iara-pwa/AGENTS.md
Francisco Solla 8d4a944127 feat(ci): CI/PR no GitHub Actions — tracker de Issues permanece no Forgejo (Closes #17)
- .github/workflows: ci.yml (job único checks hosted), deploy.yml (verify
  hosted full → deploy self-hosted no homeserver), flips pós-merge via API
  (FORGEJO_API_TOKEN/PR_BODY, fail-loud), auto-merge nativo (GraphQL)
- scripts: github-api/pr-flow/branch-protection (plain Node zero-dep),
  pr.mjs reescrito (GitHub + auto-merge), configure-branch-protection,
  deploy-iara.sh (local, sem SSH, idempotente), forgejo-issue-transition
  com PR_BODY + fail-loud (I10 absorvida)
- AGENTS.md/runbook: seção CI GitHub, branch protection REAL em main,
  passos manuais do cutover
2026-08-19 23:06:23 -03:00

8.1 KiB

Iara — convenções de trabalho para agentes

Iara é um chat PWA local-first para falar com assistentes de IA (gateways compatíveis com o protocolo ZeroClaw). Vite + React + TypeScript + assistant-ui

  • Tailwind v4 + vite-plugin-pwa. Sem backend próprio: o estado do cliente vive no dispositivo (localStorage); o único servidor externo é o gateway WS do usuário.

Stack e scripts

  • Runtime: bun (também há node para os scripts de agente — são ESM puros).
  • bun run dev — dev server; bun run build — tsc -b && vite build (build de produção em dist/); bun run preview — servir o build.
  • bun run gate — gate local: lint (oxlint) + build (typecheck + build). Rode antes de push.
  • bun run test:e2e — e2e Playwright; roda SÓ no CI, nunca local (decisão do fluxo: não rodar e2e local para não divergir do CI).

Arquitetura do código

  • src/lib/ws.ts — protocolo WebSocket zeroclaw.v1 (tipos de mensagens, conecta em <gateway>/ws/chat?token=&agent=&name=). Contrato: mudar tipos de protocolo é breaking.
  • src/lib/messages.ts — normalização/montagem de mensagens.
  • src/lib/settings.ts — config local (URL/key/agente/STT/TTS) em localStorage.
  • src/lib/voice.ts — STT/TTS opcional (Web Speech + endpoints configuráveis).
  • src/components/Chat.tsx — thread + composer (assistant-ui primitives).
  • src/components/Settings.tsx — tela de configuração.
  • src/components/ApprovalCard.tsx — card de aprovação (approval_request → approval_response).
  • vite.config.ts — base /_app/ (servido pelo gateway do ZeroClaw), PWA manifest + service worker, background sync do WS.

Invariantes: local-first (nada de servidor para estado do cliente); token nunca logado/commitado; aprovações nunca auto-aprovadas; copy pt-BR / identificadores em inglês; assets offline em globPatterns do PWA.

Harness do agente

  • Skills: .agents/skills/ — fluxo custom + pack de engenharia (fonte de verdade: skills-lock.json; detalhes no Workflow de trabalho).
  • MCPs: contrato em opencode.jsonc na raiz — seleção sobre os globais (~/.config/opencode/opencode.jsonc). Em uso: forgejo, playwright, jina. Desligados no repo: postgres (sem backend; global aponta pro banco do teqo) e stalwart (e-mail pessoal). penpot/secrets do teqo nunca entram. MCP novo ou re-habilitado passa por lá, com comentário registrando o porquê.

Workflow de trabalho (fluxo tipo teqo)

Pack de skills de engenharia: em .agents/skills/ (além das 5 de fluxo custom), com proveniência/hashes em skills-lock.json na raiz — fonte de verdade; upgrade deliberado via npx skills update -y.

Issues do Forgejo (git.solla.dev/amana/iara-pwa) são a fonte canônica de spec/status/deps/prio. Estado em labels: ready | in-progress | blocked | done (+ in-prod). Frontmatter no body da Issue:

---
id: I7
depends: [I3]
serializes: []
priority: P1
---
Plano: [`docs/plans/<slug>.md`](docs/plans/<slug>.md)

Ciclo completo (detalhes nas skills plan-issue / work-issue):

  1. /plan-issue (num worktree bun run worktree plan) → plano de intenção em docs/plans/<slug>.md + Issue blocked (bun run agent:register --plan) → PR Related #N → merge → bun run agent:ready -- --issue N (ou o CI promove sozinho).
  2. bun run worktree next → claima a próxima Issue ready (label in-progress), cria worktree ~/.worktrees/iara/<code>-<slug> de origin/main, roda bun install e abre o opencode com /work-issue --issue N.
  3. /work-issue → plano de implementação (docs/plans/<slug>-impl.md), pausa para aprovação humana, execução.
  4. /simplify (skill code-simplification) → 3 reviews locais paralelos no diff.
  5. capture-review-debts → triagem + débitos (bun run agent:register / agent:file-miss).
  6. PR Ready Closes #N com auto-merge (bun run pr -- --automerge) → CI (lint+build+e2e) → merge → done/in-prod → deploy (manual, workflow_dispatch).

Comandos de agente (bun)

Comando O que faz
bun run worktree next/plan/new/kill fila → worktree da Issue / planejamento / neutro / destruir
bun run issue next|all próxima claimável / overview (read-only)
bun run agent:claim claima a próxima ready (não usar em sessão — worktree next já claima)
bun run agent:register cria Issue rastreável (com --plan nasce blocked)
bun run agent:ready promove blocked → ready (plano em main)
bun run agent:file-miss registra défice do fluxo de agentes
bun run agent:status grafo/overview read-only
bun run pr -- --head <b> --body "Closes #N" --automerge cria PR no GitHub (Ready) e arma o auto-merge nativo — o servidor mergea quando checks ficar green (requer GITHUB_TOKEN env)
bun run configure:branch-protection (re)aplica a proteção de main no GitHub (required check checks + enforce admins; idempotente)

O comando de terminal worktree é o roteador global (~/.config/shell/worktree.sh): descobre o projeto pelo diretório atual (git rev-parse) e roda o script do projeto; config por projeto em .forgejo/worktree.env (commitado, sem secrets).

CI (GitHub Actions — .github/workflows/)

O código/PR/CI vive no GitHub (github.com/fsolla/iara-pwa, público; o origin local aponta para ele após o cutover); o tracker de Issues permanece no Forgejo (git.solla.dev/amana/iara-pwa — labels, claims, bun run issue/agent:* e os flips pós-merge continuam falando com a API do Forgejo; GitHub é só o host do Actions).

  • ci.yml — PR gate: job único checks em ubuntu-latest (lint + build + unit + e2e Playwright); seu check-run CI / checks é o required check de main — literal de match na proteção: checks (o GitHub casa pelo nome do check-run/job; a UI exibe CI / checks). Sem verificador de main — publicar é ato manual (deploy.yml).
  • deploy.yml — manual (workflow_dispatch): verify (hosted, suíte full) → deploy (needs: [verify], runner self-hosted no homeserver) executando scripts/deploy-iara.sh localmente (sem SSH; idempotente via marker do SHA).
  • issue-done-on-main-merge.yml — PRs mergeadas com Closes #N flipam a Issue para done/in-prod no Forgejo via API (scripts/forgejo-issue-transition.mjs, fail-loud).
  • plan-issue-ready-on-main-merge.yml — PRs com Related #N promovem blocked → ready (scripts/agent-promote-related-on-merge.mjs).
  • agent-pr-ready-automerge.yml — safety net: arma o auto-merge nativo do GitHub (GraphQL enablePullRequestAutoMerge, rebase) para todo PR same-repo não-draft (scripts/github-pr-automerge.mjs). O servidor só mergeia com o required check checks verde — nada de poll.

Branch protection REAL em main (era Forgejo não tinha): required check checks + enforce_admins: true (nem admin mergeia com CI vermelho). Configurado via bun run configure:branch-protection (idempotente). O merge automático é o nativo do GitHub — a semântica de "cria e mergea quando os checks passarem" (bun run pr -- --automerge) é preservada pela garantia do servidor (o --automerge local arma o auto-merge; sem poll local).

Deploy: manual via workflow_dispatch no GitHub (job Deploy (manual)), só após verify full green. Nada de deploy automático em push.

e2e só no CI — nunca rode bun run test:e2e local como parte do fluxo normal.

Arquivos do fluxo Forgejo (.forgejo/workflows/, forgejo-pr-automerge.mjs) permanecem dormentes como via de rollback até a remoção na entrega sucessora (Fase 2); o runner do Forgejo fica desligado após o cutover.

Regras de entrega

  • Gate antes de push: bun run gate limpo. CI roda lint+build+e2e de novo no PR.
  • PR nunca draft para entrega; Closes #N no body; auto-merge armado.
  • Nunca editar Issue in-progress de outra sessão; débito vira Issue nova com depends no pai.
  • Planos imutáveis para Issues in-progress/done/in-prod — refino = sucessor.
  • Sem git push nu com o fluxo de agente — use o fluxo do PR (a branch é do worktree).