Francisco Solla 8125334401 feat(worktree): ambientes isolados por worktree — porta própria, bancos próprios, migrations no provision

pnpm worktree next [--go] [--no-migrate] agora provisiona um ambiente
determinístico por worktree: slot = parte numérica do código da Issue
(C15→15; hash sem dígitos; bump em colisão entre worktrees vivos), dev
server em 3100+slot, bancos teqo_wt<slot> / teqo_wt<slot>_test no
container compartilhado (-p teqo) com a cadeia de migrations aplicada;
escreve .env.local + .env.test.local (gitignored, marcador gerado; envs
manuais nunca sobrescritos) e copia PAYLOAD_SECRET/Blob/VAPID do main.
kill remove o worktree e dropa os bancos gerados (WITH FORCE, best-effort).

Suites leem .env.test.local depois de .env.test (vitest.setup /
playwright / db-doctor / gate-ci espelham o layering) e
assertTestDatabase aceita teqo_test ou teqo_<worktree>_test em localhost
só (fail-closed preservado). db:start/db:stop fixam -p teqo (um
container de qualquer diretório); max_connections 200→400. Sem Docker
(Cursor Cloud): degrada ao compartilhado com aviso.

Derivação pura em scripts/lib/worktree-env.mjs (unit-tested); fluxo
validado end-to-end: provision → migrate → 598/598 int no banco do
worktree → kill sem resíduo.

2026-08-08 11:33:07 -03:00

4.3 KiB

Raw Blame History

name	description
worktree-next-issue	Cria um worktree git a partir de main para a próxima Issue claimável da fila do projeto, com branch legível no formato <código>-<slug> (ex. C15-fullcalendar-em-campanha-agenda, slug pt-BR do título sem acentos). Read-only no GitHub — NÃO claima, NÃO altera Issues. Usar quando o usuário pedir "worktree da próxima issue", "cria o worktree para o próximo da fila", "prepara o ambiente do próximo item", ou quiser começar a trabalhar a próxima Issue sem abrir o pool/Cursor.

name

description

worktree-next-issue

Cria um worktree git a partir de main para a próxima Issue claimável da fila do projeto, com branch legível no formato <código>-<slug> (ex. C15-fullcalendar-em-campanha-agenda, slug pt-BR do título sem acentos). Read-only no GitHub — NÃO claima, NÃO altera Issues. Usar quando o usuário pedir "worktree da próxima issue", "cria o worktree para o próximo da fila", "prepara o ambiente do próximo item", ou quiser começar a trabalhar a próxima Issue sem abrir o pool/Cursor.

Worktree da próxima Issue claimável

Prepara o ambiente git para a próxima Issue da fila de claim, sem tocá-la no GitHub (read-only por contrato — claim continua sendo pnpm agent:claim, feito à parte).

Fonte canônica: `pnpm worktree` (script)

A lógica determinística (fila → código+slug → branch → worktree) vive em scripts/worktree.mjs — fonte única, coberta por tests/unit/worktree.unit.spec.ts. Não a reescreva à mão aqui.

pnpm worktree next [--go] [--no-migrate]  # cria worktree de origin/main + provisiona o ambiente
pnpm worktree kill [--force]              # destrói o worktree atual + remove seus bancos gerados

No opencode, isso é o comando /worktree next / /worktree kill (.opencode/commands/worktree.md), que só repassa $ARGUMENTS para o script.

No terminal interativo, para --go trocar de diretório de verdade, use a função worktree() de .agents/shell/worktree.sh (uma linha de source no profile): o script imprime cd <dir> e a função o aplica no shell que te chamou — node não consegue mudar o cwd do shell pai.

Fluxo quando invocado como skill (agentes que não têm opencode)

Rode pnpm worktree next e leia a saída inteira. Se a fila estiver vazia, ele para sozinho — não crie worktree sem Issue.
Se a saída reclamar de conflito (worktree/branch já existentes), o script já reporta o que reutilizar.
Reporte ao usuário: código, #<N>, branch (<code>-<slug>), path — e que a Issue não foi claimada.

O que o script garante (contrato)

Fila = pnpm agent:claim --dry-run (ready + desbloqueadas, por prio:P* e mais antiga primeiro — mesma ordenação do pool e de project-status).
Branch <code>-<slug>: code = id do frontmatter; slug = título pt-BR via src/lib/slug.ts (acentos fora, não-alfanumérico → hífen); truncamento só no slug, nunca no código; valida com git check-ref-format --allow-onelevel.
Base origin/main (com git fetch antes); dir em ~/.cursor/worktrees/teqo/<branch>.
Provisiona o ambiente isolado do worktree (determinístico, ver "Ambiente provisionado"): dev server na porta 3100+slot e bancos próprios teqo_wt<slot> / teqo_wt<slot>_test no container compartilhado (-p teqo), com migrations aplicadas — agentes em paralelo não disputam porta 3000 nem o teqo_test. --no-migrate pula as migrations (bancos criados, envs escritos).
kill: recusa destruir o worktree principal (main); recusa worktree sujo sem --force; remove e apaga o branch; remove os bancos gerados do worktree (best-effort).
NUNCA usa --force no add, não inventa código de Issue, e é read-only no GitHub.

Ambiente provisionado (leia a saída do script)

Cada worktree gerado ganha um ambiente próprio — reporte ao agente/humano os valores que o script imprime ao final:

dev: http://localhost:<porta> (pnpm dev), banco teqo_wt<slot>.
test: banco teqo_wt<slot>_test (as suites leem .env.test.local, que sobrepõe o .env.test commitado; pnpm test:int / test:e2e / gate:push rodam isolados).
Sem Docker (Cursor Cloud): o script degrada para o compartilhado teqo/teqo_test com aviso — comportamento antigo.
Envs geradas têm o marcador # teqo worktree env (generated by pnpm worktree next); .env.local/.env.test.local manuais nunca são sobrescritos (o script pula o provisionamento com aviso).
Detalhes e derivarão pura: scripts/lib/worktree-env.mjs; skill local-database.

NÃO faz

Não roda pnpm agent:claim (mudaria labels no GitHub).
Não usa git worktree add --force nem destrói worktrees existentes (isso é kill, explícito).
Não duplica a lógica: se o script falhar ou faltar (gh fora do ar), reporte e pare.

4.3 KiB Raw Blame History