@spec-wave/cli 0.25.0 → 0.27.0

package/src/cli.mjs

@@ -0,0 +1,400 @@
+// Superfície da CLI: monta o programa do Commander e o devolve SEM executá-lo.
+//
+// Vive aqui, e não no `bin/`, porque o `bin/` executa (`parse()`) — importá-lo
+// para introspecção dispararia a CLI. Com a montagem separada, o gerador da
+// documentação (`apps/docs/scripts/generate-reference.mjs`) e os testes leem
+// `program.commands` diretamente, em vez de parsear o texto do `--help`.
+
+import { Command } from 'commander';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dir, '..', 'package.json'), 'utf-8'));
+
+/**
+ * Monta o programa do Commander com todos os comandos (função sem efeito).
+ *
+ * NÃO chama `.parse()` — quem executa é o `bin/spec-wave.mjs`.
+ *
+ * @returns {Command}
+ */
+export function buildProgram() {
+  const program = new Command();
+
+  program
+    .name('spec-wave')
+    .description('Setup spec-driven GitHub workflow with Projects v2')
+    .version(pkg.version)
+    // Conta do `gh` a usar nesta execução. Existe porque um GH_TOKEN exportado no
+    // shell (um `.envrc` na raiz de um diretório de projetos, por exemplo) vale
+    // para repositórios de QUALQUER org abaixo dele — e o GraphQL do GitHub
+    // mascara o 403 resultante como "Could not resolve to a Repository".
+    .option('--account <login>', 'Conta do gh a usar (vence GITHUB_TOKEN/GH_TOKEN fora do CI)')
+    .hook('preAction', async (thisCommand) => {
+      const { account } = thisCommand.opts();
+      if (account) {
+        const { setAccountOverride } = await import('./api/auth.mjs');
+        setAccountOverride(account);
+      }
+    });
+
+  program
+    .command('init')
+    .description('Configura spec-wave em um repositório GitHub')
+    .option('--dry-run', 'Simula a configuração sem fazer alterações')
+    .option('--repo <owner/repo>', 'Repositório GitHub (ignora o wizard interativo)')
+    .option('--project-title <title>', 'Nome do GitHub Project (padrão: "<repo> — Spec Wave")')
+    .option('--skip-project', 'Pula a criação do GitHub Project (use se já foi criado)')
+    .option('--skip-labels', 'Pula a criação das labels')
+    .option('--skip-files', 'Pula a criação dos arquivos de workflow')
+    .option('--provider <provider>', 'Provider de IA dos workflows: anthropic ou openrouter')
+    .option('--model <model>', 'Modelo de IA usado pelos workflows (ex.: anthropic/claude-3.7-sonnet)')
+    .action(async (options) => {
+      const { init } = await import('./commands/init.mjs');
+      await init(options);
+    });
+
+  program
+    .command('info')
+    .description('Mostra se o repositório atual foi inicializado e os dados do .spec-wave.json')
+    .option('--json', 'Saída em JSON (para uso programático)')
+    .action(async (options) => {
+      const { info } = await import('./commands/info.mjs');
+      await info(options);
+    });
+
+  program
+    .command('refresh')
+    .description('Atualiza o .spec-wave.json local com os dados atuais do GitHub Project')
+    .option('--config', 'Re-consulta o Project e reescreve o .spec-wave.json')
+    .option('--stages', 'Acrescenta ao campo "Etapa" as colunas canônicas que faltam (nunca remove)')
+    .option('--dry-run', 'Com --stages: mostra o que seria enviado e não escreve nada')
+    .option('--yes', 'Com --stages: não pede confirmação')
+    .action(async (options) => {
+      const { refresh } = await import('./commands/refresh.mjs');
+      await refresh(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('issue')
+    .description('Cria um work item (initiative/epic/feature/story/task...), opcionalmente como sub-issue, e adiciona ao board')
+    .requiredOption('--title <title>', 'Título (sem o prefixo de tipo, ex.: [FEATURE])')
+    .option('--type <type>', 'Tipo: initiative, epic, feature, story, task, bug, spike ou rfc', 'feature')
+    .option('--parent <n>', 'Número da issue pai (cria como sub-issue dela)')
+    .option('--body <text>', 'Descrição')
+    .option('--priority <p>', 'Prioridade: P0, P1, P2 ou P3')
+    .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
+    .action(async (options) => {
+      const { issue } = await import('./commands/issue.mjs');
+      await issue(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('initiative')
+    .description('Atalho de `issue --type initiative` (nó raiz que agrupa Epics)')
+    .requiredOption('--title <title>', 'Título da initiative (sem o prefixo [INITIATIVE])')
+    .option('--body <text>', 'Descrição da initiative')
+    .option('--priority <p>', 'Prioridade: P0, P1, P2 ou P3 (adiciona label)')
+    .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
+    .action(async (options) => {
+      const { initiative } = await import('./commands/initiative.mjs');
+      await initiative(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('feature')
+    .description('Atalho de `issue --type feature`')
+    .requiredOption('--title <title>', 'Título da feature (sem o prefixo [FEATURE])')
+    .option('--parent <n>', 'Número da Epic pai (cria como sub-issue dela)')
+    .option('--body <text>', 'Descrição da feature')
+    .option('--priority <p>', 'Prioridade: P0, P1, P2 ou P3 (adiciona label)')
+    .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
+    .action(async (options) => {
+      const { feature } = await import('./commands/feature.mjs');
+      await feature(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('bug')
+    .description('Cria um Bug (atalho de `issue --type bug`) — nasce em 🐞 Triagem, ou ✅ Ready se P0')
+    .requiredOption('--title <title>', 'Título (sem o prefixo [BUG])')
+    .option('--parent <n>', 'Feature ou Story afetada (cria como sub-issue dela)')
+    .option('--body <text>', 'Descrição: passos, esperado e obtido')
+    .option('--priority <p>', 'Severidade: P0, P1, P2 ou P3')
+    .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
+    .action(async (options) => {
+      const { bug } = await import('./commands/bug.mjs');
+      await bug(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('triage')
+    .description('Tria um Bug: accept (→ ✅ Ready), reject (fecha) ou duplicate (fecha)')
+    .argument('<action>', 'accept | reject | duplicate')
+    .argument('<issue>', 'Número da issue do Bug')
+    .option('--reason <texto>', 'Motivo da rejeição (obrigatório em reject)')
+    .option('--of <n>', 'Número da issue original (obrigatório em duplicate)')
+    .option('--severity <p>', 'Reclassifica a severidade ao aceitar: P0–P3')
+    .action(async (action, issue, options) => {
+      const { triage } = await import('./commands/triage.mjs');
+      await triage({ action, issue, ...options })
+        .catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('run')
+    .description('Executa LOCALMENTE o próximo passo do fluxo (o que a label dispararia no Actions)')
+    .argument('[issue]', 'Número da issue (Feature, Bug ou RFC)')
+    .option('--pr <n>', 'Modo PR: decide entre code-review e qa pelo estado das reviews')
+    .option('--dry-run', 'Decide e explica sem executar nada')
+    .option('--yes', 'Confirma o passo que exige confirmação')
+    .option('--apply', 'Autoriza especificamente o decompose-apply (erra se o passo pendente for outro)')
+    .option('--step <nome>', 'Força um passo: spec | plan | critique | validate | decompose | decompose-apply | bug')
+    .option('--max-steps <n>', 'Encadeia até N passos (padrão: 1)', '1')
+    .option('--force', 'Ignora o portão de label de gatilho pendente')
+    .option('--no-remote-check', 'Não consulta o remoto pelos documentos ausentes (offline)')
+    .option('--only <passo>', 'No modo --pr: roda só code-review ou só qa')
+    .option('--json', 'Imprime a decisão em JSON')
+    .action(async (issue, options) => {
+      const { run } = await import('./commands/run.mjs');
+      await run(issue, options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('mode')
+    .description('Mostra ou alterna o modo de execução: `actions` (workflows) ou `local` (esta máquina)')
+    .argument('[modo]', 'actions | local (sem argumento: só mostra o estado)')
+    .option('--dry-run', 'Mostra o que mudaria sem alterar nada')
+    .action(async (target, options) => {
+      const { mode } = await import('./commands/mode.mjs');
+      const result = await mode({ target, ...options })
+        .catch(err => { console.error(err.message); process.exit(1); });
+      // Escrever só o config é meio-interruptor: a CLI passa a agir como local
+      // e os workflows continuam disparando. O comando já avisa em vermelho,
+      // mas sair 0 fazia qualquer script (ou agente) que o encadeasse ler
+      // sucesso — e seguir em frente achando que o CI estava desligado.
+      if (result?.variableApplied === false) process.exit(1);
+    });
+
+  program
+    .command('update')
+    .description('Detecta o que está desatualizado (skill, .spec-wave.json, workflows/labels do repo) e atualiza só o que mudou')
+    .option('--global', 'Verifica a skill no escopo do usuário (padrão: projeto)')
+    .option('--skip-skill', 'Não verifica/atualiza a skill instalada')
+    .option('--skip-config', 'Não verifica/atualiza o .spec-wave.json local')
+    .option('--skip-repo', 'Não verifica/atualiza workflows e labels do repo')
+    .option('--branch [nome]', 'Envia os arquivos do repo como Pull Request numa branch, em um único commit (sem valor: spec-wave/update-v<versão>)')
+    .option('--config-in-pr', 'Força incluir o .spec-wave.json no Pull Request')
+    .option('--no-config-in-pr', 'Força manter o .spec-wave.json fora do Pull Request')
+    .option('--dry-run', 'Mostra o que seria atualizado sem alterar nada')
+    .option('--yes', 'Aplica sem pedir confirmação')
+    .action(async (options) => {
+      const { update } = await import('./commands/update.mjs');
+      await update(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('install-skill')
+    .description('Instala a skill spec-wave no(s) agente(s) detectado(s): Claude Code, Codex, Cursor, opencode, Cline, Kilo, Antigravity, AGENTS.md')
+    .option('--agent <names>', 'Agente(s) alvo, separados por vírgula (pula a detecção)')
+    .option('--all', 'Instala em todos os agentes detectados')
+    .option('--global', 'Instala no escopo do usuário (padrão: projeto)')
+    .option('--dry-run', 'Mostra o que seria instalado sem gravar')
+    .option('--force', 'Sobrescreve arquivos existentes sem confirmar')
+    .option('--yes', 'Modo não-interativo')
+    .action(async (options) => {
+      const { installSkill } = await import('./commands/install-skill.mjs');
+      await installSkill(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('uninstall')
+    .description('Remove labels, arquivos .github e o .spec-wave.json (mantém o GitHub Project)')
+    .option('--repo <owner/repo>', 'Repositório (padrão: lê do .spec-wave.json)')
+    .option('--skip-labels', 'Não remove as labels')
+    .option('--skip-files', 'Não remove os arquivos .github')
+    .option('--keep-config', 'Mantém o .spec-wave.json local')
+    .option('--dry-run', 'Mostra o que seria removido sem alterar nada')
+    .option('--yes', 'Não pede confirmação')
+    .action(async (options) => {
+      const { uninstall } = await import('./commands/uninstall.mjs');
+      await uninstall(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('generate-plan')
+    .description('Gera plan.md para uma Feature — roda no GitHub Action ou localmente')
+    .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+    .action(async (options) => {
+      const { generatePlan } = await import('./commands/generate-plan.mjs');
+      await generatePlan(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('critique')
+    .description('Critica um documento COMO ESTÁ, sem regerar — para depois de corrigi-lo à mão')
+    .option('--issue-number <n>', 'Número da issue: critica o plan.md dela e comenta (fluxo canônico)')
+    .option('--file <caminho>', 'Critica ESTE arquivo e imprime o resultado — sem issue, sem label, sem contar tentativa')
+    .option('--kind <tipo>', 'plan | spec | stories | bug (default: inferido do nome do arquivo)')
+    .option('--fail-on-grave', 'Sai com código 1 se houver finding grave (útil em script)')
+    .action(async (options) => {
+      const { critique } = await import('./commands/generate-plan.mjs');
+      await critique(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('generate-spec')
+    .description('Gera spec.md para uma Feature — roda no GitHub Action ou localmente')
+    .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+    .action(async (options) => {
+      const { generateSpec } = await import('./commands/generate-spec.mjs');
+      await generateSpec(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('generate-bug')
+    .description('Gera bug.md para um Bug — roda no GitHub Action ou localmente')
+    .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+    .action(async (options) => {
+      const { generateBug } = await import('./commands/generate-bug.mjs');
+      await generateBug(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('validate')
+    .description('Valida os documentos de uma issue: spec.md+plan.md de Feature, bug.md de Bug (usado pelo GitHub Action)')
+    .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+    .action(async (options) => {
+      const { validate } = await import('./commands/validate.mjs');
+      // A reprova é um desfecho esperado do comando, não uma exceção — mas o exit
+      // code precisa continuar 1 para o job do Actions ficar vermelho.
+      const result = await validate(options)
+        .catch(err => { console.error(err.message); process.exit(1); });
+      if (result?.ok === false) process.exit(1);
+    });
+
+  program
+    .command('decompose')
+    .description('Gera o rascunho da decomposição em decomposition.md; com --apply, cria as Stories/Tasks a partir do rascunho revisado — roda no Action ou localmente')
+    .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+    .option('--apply', 'Aplica o decomposition.md já revisado: cria as issues (sem esta flag, apenas gera/critica o rascunho)')
+    .action(async (options) => {
+      const { decompose } = await import('./commands/decompose.mjs');
+      await decompose(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('code-review')
+    .description('Move Feature para Code Review ao abrir um PR (usado pelo GitHub Action)')
+    .requiredOption('--pr-number <n>', 'Número do Pull Request')
+    .option('--resolve-only', 'Só descobre a Feature-alvo e imprime feature=<n>, sem tocar no board')
+    .action(async (options) => {
+      const { codeReview } = await import('./commands/code-review.mjs');
+      await codeReview(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('qa')
+    .description('Move Feature para QA ao aprovar um PR (usado pelo GitHub Action)')
+    .requiredOption('--pr-number <n>', 'Número do Pull Request')
+    .action(async (options) => {
+      const { qa } = await import('./commands/qa.mjs');
+      await qa(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('implement')
+    .description('Aciona o spec-kit implement para uma Feature (Stories pendentes em ordem de dependência), uma Story (todas as tasks) ou uma Task')
+    .argument('<issue>', 'Número da issue (Feature, Story ou Task), ex.: 12 ou #12')
+    .option('--feature-dir <path>', 'Caminho do docs/features/<slug> (sobrescreve a resolução automática)')
+    .option('--dry-run', 'Monta o contexto e imprime o comando sem executar o spec-kit')
+    .action(async (issue, options) => {
+      const { implement } = await import('./commands/implement.mjs');
+      await implement({ issue, ...options }).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('order')
+    .description('Ordena as Stories pelas dependências (topológica). Sem argumento, o mapa de todas as Features com trabalho')
+    .argument('[feature]', 'Número da issue da Feature, ex.: 12 ou #12. Omitido: todas as Features abertas fora de 🎉 Done')
+    .action(async (feature) => {
+      const { order } = await import('./commands/order.mjs');
+      await order({ feature }).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('task')
+    .description('Gerencia uma Task no board: start (Status "In Progress") ou done (Done)')
+    .argument('<action>', 'Ação: start ou done')
+    .argument('<n>', 'Número da issue da Task, ex.: 12 ou #12')
+    .action(async (action, n) => {
+      const { task } = await import('./commands/task.mjs');
+      await task({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('move')
+    .description('Move qualquer item do board (Feature, Story, Task, Bug, RFC) para uma Etapa — a Etapa nunca retrocede')
+    .argument('<n>', 'Número da issue, ex.: 8 ou #8')
+    .argument('<etapa>', 'Etapa de destino, com ou sem emoji, ex.: "code review", "Homologação", "🎉 Done"')
+    .option('--status <valor>', 'Valor do campo Status no destino: Todo, In Progress ou Done (default: Todo)')
+    .action(async (n, etapa, options) => {
+      const { move } = await import('./commands/move.mjs');
+      await move({ issue: n, stage: etapa, ...options })
+        .catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('repair-stage')
+    .description('Corrige a Etapa de itens que a automação errou — inclusive retrocedendo. Exige --yes e --reason, e registra o reparo na issue')
+    .argument('<issues>', 'Número(s) da(s) issue(s), ex.: 529 ou 529,530,531')
+    .argument('<etapa>', 'Etapa correta, com ou sem emoji, ex.: "ready", "✅ Ready"')
+    .option('--reason <motivo>', 'Por que o reparo é necessário (vai para o comentário de auditoria)')
+    .option('--status <valor>', 'Também corrige o Status: Todo, In Progress ou Done (default: não mexe)')
+    .option('--yes', 'Confirma o reparo (obrigatório)')
+    .option('--dry-run', 'Mostra o que seria reparado sem alterar nada')
+    .action(async (issues, etapa, options) => {
+      const { repairStage } = await import('./commands/repair-stage.mjs');
+      await repairStage(issues, etapa, options)
+        .catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('story')
+    .description('Gerencia uma Story no board: review (move para Code Review)')
+    .argument('<action>', 'Ação: review')
+    .argument('<n>', 'Número da issue da Story, ex.: 12 ou #12')
+    .action(async (action, n) => {
+      const { story } = await import('./commands/story.mjs');
+      await story({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('dev-agent')
+    .description('Instala (--install/--build) ou executa (--run) o spec-wave-agent nesta máquina')
+    .option('--install', 'Baixa o binário da release, gera a config e (com --service) o serviço')
+    .option('--build', 'Clona o repo do agente e compila com cargo (alternativa ao --install)')
+    .option('--run', 'Executa o agente em foreground (Ctrl+C encerra com checkpoint)')
+    .option('--service', 'No --install/--build: também instala e habilita systemd/launchd')
+    .option('--tag <tag>', 'Release (--install) ou branch/tag (--build); padrão: última release / main')
+    .option('--debug', 'No --run: RUST_LOG=debug')
+    .option('--dry-run', 'Mostra o que seria instalado sem gravar')
+    .option('--force', 'Reinstala o binário e regrava a config')
+    .option('--yes', 'Modo não-interativo')
+    .action(async (options) => {
+      const { devAgent } = await import('./commands/dev-agent.mjs');
+      await devAgent(options).catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  program
+    .command('doctor')
+    .description('Diagnostica a configuração do spec-wave no repositório atual')
+    .action(async () => {
+      const { doctor } = await import('./commands/doctor.mjs');
+      await doctor().catch(err => { console.error(err.message); process.exit(1); });
+    });
+
+  return program;
+}