71 lines
5.3 KiB
Markdown
71 lines
5.3 KiB
Markdown
# Worktree CLI: `--go` vira o padrão (escape `--stay`) e `kill` volta ao main
|
|
|
|
Status: rascunho
|
|
Atualizado em: 2026-08-10
|
|
Issue: #569
|
|
Priority: P2
|
|
Model: composer-2.5
|
|
model-local: deepseek-v4-flash-high
|
|
Impeccable: A — N/A (CLI de dev; sem superfície de usuário de produto)
|
|
Canvas UI: N/A — sem UI
|
|
Appetite: ~0,5 dia eng; um outcome verificável (o terminal sempre termina no lugar certo)
|
|
|
|
## Intenção
|
|
|
|
Hoje `pnpm worktree next` / `plan` só aplicam o `cd` com `--go` explícito — mas **quase toda** invocação quer ir para o worktree; o raro é ficar. O usuário lança `worktree next --go` e `worktree plan --go` todo dia, e o caso incomum (automação, olhar sem entrar, rodar de dentro do opencode) é o que deveria pedir o flag. Além disso, `worktree kill` destrói o worktree em que o shell está e deixa o terminal órfão num diretório que não existe mais — o output até imprime "Volte ao main: cd …", mas ninguém aplica esse cd, então o prompt do shell fica num cwd morto até o usuário sair manualmente.
|
|
|
|
## Persona e fluxo
|
|
|
|
- **Persona / contexto:** Francisco no terminal (bash), fluxo diário de abrir/fechar worktrees; e o agente opencode rodando o comando `/worktree`.
|
|
- **Job principal:** um comando `worktree` que termina me deixando no lugar certo — dentro do worktree quando crio, no repo principal quando destruo.
|
|
- **Fluxo desejado:** `pnpm worktree next` (sem flags) cria/reusa e provisiona o worktree **e** aplica `cd <dir>` no shell; `pnpm worktree plan` idem; `pnpm worktree kill` destrói, remove os bancos **e** aplica `cd <main>` (`~/Code/teqo`); quem não quer entrar usa `--stay`.
|
|
- **Anti-goals de produto:** não criar um sistema de flags complexo (um escape só); não mudar a lógica determinística de branch/slot/provisionamento; não alterar o que `kill` destrói.
|
|
|
|
## Objetivo e aceite
|
|
|
|
- `pnpm worktree next` e `pnpm worktree plan` sem flags aplicam o `cd` no shell do terminal (hoje exigem `--go`).
|
|
- `--stay` suprime o `cd` (e a futura abertura de opencode — ver OPS26): o script imprime o caminho sem aplicar.
|
|
- `--go` explícito continua aceito como no-op — não quebra hábito, script de automação ou a doc existente.
|
|
- `pnpm worktree kill` termina com o shell no main repo; o cwd nunca fica num diretório destruído.
|
|
- O comportamento vale nas duas superfícies que aplicam o cd: função `worktree()` do `.agents/shell/worktree.sh` (terminal) e comando `/worktree` do opencode (`.opencode/commands/worktree.md`).
|
|
- **O comando `/worktree` no TUI do opencode continua criando/reutilizando o worktree (roda o script completo, com provisionamento) — o cd é consequência, não a função dele.** Com default-go, `/worktree next` cria + provisiona + aplica o cd na sessão; `/worktree plan` idem; `/worktree kill` destrói + aplica `cd <main>`.
|
|
- `AGENTS.md` (seção "Per-worktree environments") reflete a nova semântica default-go/`--stay`.
|
|
|
|
## Dados (intenção)
|
|
|
|
- **Vou apresentar dados?** Não — sem superfície de dados; é ergonomia de CLI de dev.
|
|
|
|
## Direção no codebase (hipótese)
|
|
|
|
- **Áreas prováveis:** `scripts/worktree.mjs` (cmdNext/cmdPlan imprimem `cd <dir>` por default; flag `--stay` no parseArgs; cmdKill imprime `cd <mainRoot>` no mesmo formato máquina que `next`/`plan` já usam); `.agents/shell/worktree.sh` (aplica o cd por default, suprime com `--stay`, aplica também no `kill`); `.opencode/commands/worktree.md` (texto de uso das três formas).
|
|
- **Precedente a olhar:** o formato `cd <dir>` já é o contrato entre o script e a função shell (sed parse na última linha); o kill já resolve `mainRoot` como `entries[0]?.path`.
|
|
- **Risco de acoplamento:** o opencode command (`/worktree`) e a função shell dividem a mesma saída do script — qualquer mudança de formato quebra os dois; manter UMA linha `cd …` no fim, sempre.
|
|
|
|
## Dependências
|
|
|
|
- Nenhuma. (Base de semântica para OPS26 e OPS27.)
|
|
|
|
## Fora de escopo
|
|
|
|
- Abertura do opencode ao "go" — item próprio (OPS26).
|
|
- O subcomando `worktree new` — item próprio (OPS27).
|
|
- Mudanças no provisionamento (porta/bancos/env) — pré-existente, não é o alvo.
|
|
|
|
## Rabbit holes de produto
|
|
|
|
- **"Vários escapes":** `--no-go`, `--here`, `--cd`… um só, com nome claro.
|
|
- **"O script deve detectar terminal vs opencode":** não — o script imprime o `cd`; quem aplica (shell function vs opencode command) decide o que fazer com ele. Manter o contrato de saída simples.
|
|
|
|
## Questões em aberto (produto)
|
|
|
|
- **Nome do escape?** **Opções:** A) `--stay` | B) `--no-go` | C) `--here`. **Recomendação:** A — curto, lê como o oposto de "go" e não parece flag de modo. _(confirmado no gate — `--stay`)_
|
|
- **`kill` deve suportar `--stay` (não voltar ao main)?** **Opções:** A) não — kill sempre volta ao main | B) sim, por simetria. **Recomendação:** A — ficar num cwd destruído é exatamente o bug que estamos corrigindo; quem roda kill por automação não depende do cwd do terminal pai.
|
|
|
|
## Referências
|
|
|
|
- GitHub Issue #569
|
|
- `scripts/worktree.mjs:444-481` — `cmdKill` já imprime "Volte ao main: cd ${mainRoot}"; nada aplica
|
|
- `scripts/worktree.mjs:329` e `400` — `if (go) console.log(\`cd ${dir}\`)`em`next`/`plan`
|
|
- `.agents/shell/worktree.sh:36-39` — cd só quando `--go` presente
|
|
- `.opencode/commands/worktree.md` — instrui o agente a aplicar o `cd` quando `--go`
|
|
- `AGENTS.md` seção "Per-worktree environments" — documenta `worktree next [--go]` etc.
|