@spec-wave/cli 0.25.0 → 0.27.0

package/bin/spec-wave.mjs

@@ -1,378 +1,8 @@
 #!/usr/bin/env node
 
-import { program } from 'commander';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-import { readFileSync } from 'node:fs';
+// Ponto de entrada: a montagem do programa vive em ../src/cli.mjs para que ela
+// possa ser importada (doc gerada, testes de superfície) sem executar a CLI.
 
-const __dir = path.dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(path.join(__dir, '..', 'package.json'), 'utf-8'));
+import { buildProgram } from '../src/cli.mjs';
 
-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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/commands/mode.mjs');
-    await mode({ target, ...options }).catch(err => { console.error(err.message); 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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/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('../src/commands/doctor.mjs');
-    await doctor().catch(err => { console.error(err.message); process.exit(1); });
-  });
-
-program.parse();
+buildProgram().parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-rest.mjs

@@ -311,6 +311,31 @@ export async function deleteLabel(token, owner, repo, name) {
   }
 }
 
+/**
+ * Apaga a ref de uma branch.
+ *
+ * Existe para UM caso, e só ele: a branch de artefato que sobrou de um PR
+ * mergeado com squash. Nesse merge a ponta da branch não é ancestral da base, e
+ * empilhar o próximo commit nela produziria um PR que reintroduz estado antigo.
+ * Sem PR aberto e sem commits à frente da base, a branch não guarda nada — pode
+ * ser recriada a partir da base.
+ *
+ * NUNCA use isto para resolver conflito: apagar uma branch com PR aberto
+ * descartaria revisão humana.
+ *
+ * @returns {Promise<boolean>} false quando a branch já não existia
+ */
+export async function deleteBranch(token, owner, repo, branch) {
+  const octokit = makeQuietOctokit(token); // 404 = já não existe, não é erro
+  try {
+    await octokit.rest.git.deleteRef({ owner, repo, ref: `heads/${branch}` });
+    return true;
+  } catch (err) {
+    if (err.status === 404 || err.status === 422) return false;
+    throw err;
+  }
+}
+
 export async function deleteFile(token, owner, repo, filePath, message) {
   const octokit = makeOctokit(token);
   let sha;