@spec-wave/cli 0.28.0 → 0.29.0

package/package.json

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

package/src/api/github-graphql.mjs

@@ -343,6 +343,7 @@ export async function listSubIssues(token, issueNodeId) {
               createdAt
               state
               stateReason
+              milestone { number title }
               labels(first: 20) { nodes { name } }
             }
           }
@@ -363,10 +364,46 @@ export async function listSubIssues(token, issueNodeId) {
     // distinguir "entregue" de "descartada no rescopo".
     state: (n.state || '').toLowerCase() || null,
     stateReason: (n.stateReason || '').toLowerCase() || null,
+    // O `order` compara com o milestone do pai: sub-issue sem milestone (ou em
+    // outro) é tão invisível numa visão de release quanto Etapa vazia no board.
+    milestone: n.milestone ? { number: n.milestone.number, title: n.milestone.title } : null,
     labels: (n.labels?.nodes || []).map(l => l.name),
   }));
 }
 
+/**
+ * Os PRs que o GitHub reconhece como fechadores DESTA issue — o inverso de
+ * listLinkedIssuesForPR, pela mesma fonte de vínculo (`Closes #N` + UI). É como
+ * o `merge` descobre o PR de cada Story sem depender de convenção de nome de
+ * branch. `includeClosedPrs` de propósito: PR já mergeado é o que diz que a
+ * Story está entregue.
+ *
+ * @returns {Promise<Array<{number, state, merged, isDraft, baseRefName, headRefName}>>}
+ */
+export async function listIssuePullRequests(token, issueNodeId) {
+  const client = makeClient(token);
+  const result = await client(`
+    query IssuePRs($id: ID!) {
+      node(id: $id) {
+        ... on Issue {
+          closedByPullRequestsReferences(first: 20, includeClosedPrs: true) {
+            nodes { number state merged isDraft baseRefName headRefName }
+          }
+        }
+      }
+    }
+  `, { id: issueNodeId });
+  const nodes = result.node?.closedByPullRequestsReferences?.nodes || [];
+  return nodes.map(n => ({
+    number: n.number,
+    state: (n.state || '').toLowerCase(), // open | closed | merged
+    merged: Boolean(n.merged),
+    isDraft: Boolean(n.isDraft),
+    baseRefName: n.baseRefName || null,
+    headRefName: n.headRefName || null,
+  }));
+}
+
 /**
  * Issues que o GitHub reconhece como fechadas por este PR
  * (`Closes #N` e o vínculo feito pela UI). É a MESMA lista que fecha as issues

package/src/api/github-rest.mjs

@@ -511,6 +511,27 @@ export async function getFileContent(token, owner, repo, path, ref) {
   }
 }
 
+// Reaponta a BASE de um PR aberto. Usado pelo `merge` numa pilha de Stories:
+// depois que o PR anterior mergeia, o dependente é reapontado para a default
+// ANTES de qualquer branch ser apagada — apagar primeiro foi o que fechou um
+// PR empilhado sem volta.
+export async function updatePRBase(token, owner, repo, prNumber, base) {
+  const octokit = makeOctokit(token);
+  await octokit.rest.pulls.update({ owner, repo, pull_number: prNumber, base });
+}
+
+// Mergeia um PR. `merge` (commit de merge) é o método da pilha de Stories:
+// squash reescreveria o merge-base dos dependentes e o retarget deixaria de
+// ser limpo. O GitHub recusa (405) draft, check obrigatório pendente e
+// conflito — o chamador decide o que fazer com a fila.
+export async function mergePR(token, owner, repo, prNumber, { method = 'merge' } = {}) {
+  const octokit = makeOctokit(token);
+  const res = await octokit.rest.pulls.merge({
+    owner, repo, pull_number: prNumber, merge_method: method,
+  });
+  return { merged: Boolean(res.data.merged), sha: res.data.sha || null };
+}
+
 export async function listPullRequestReviews(token, owner, repo, prNumber) {
   const octokit = makeOctokit(token);
   return await octokit.paginate(octokit.rest.pulls.listReviews, {

package/src/cli.mjs

@@ -147,7 +147,7 @@ export function buildProgram() {
     .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('--pr <n>', 'Modo PR: decide entre code-review e qa pelo estado das reviews e do merge')
     .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)')
@@ -172,6 +172,17 @@ export function buildProgram() {
       await preflight(options).catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  program
+    .command('audit')
+    .description('Cruza as specs de uma milestone: dependência órfã, bloqueante em milestone posterior, sobreposição com código')
+    .requiredOption('--milestone <nome>', 'Título da milestone a auditar')
+    .option('--critique', 'Roda também a crítica adversarial de conjunto (uma chamada de modelo por milestone)')
+    .option('--json', 'Imprime o relatório em JSON')
+    .action(async (options) => {
+      const { audit } = await import('./commands/audit.mjs');
+      await audit(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)')
@@ -309,7 +320,7 @@ export function buildProgram() {
 
   program
     .command('qa')
-    .description('Move Feature para QA ao aprovar um PR (usado pelo GitHub Action)')
+    .description('Move Feature para QA ao aprovar ou mergear 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');
@@ -336,6 +347,18 @@ export function buildProgram() {
       await order({ feature }).catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  program
+    .command('merge')
+    .description('Mergeia os PRs empilhados das Stories de uma Feature na ordem topológica e move o board até QA')
+    .argument('<feature>', 'Número da issue da Feature, ex.: 12 ou #12')
+    .option('--yes', 'Executa os merges (sem isso, só mostra o plano)')
+    .option('--dry-run', 'Mostra o plano e sai')
+    .option('--keep-branches', 'Não apaga as branches das Stories depois do merge')
+    .action(async (feature, options) => {
+      const { merge } = await import('./commands/merge.mjs');
+      await merge({ feature, ...options }).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)')
@@ -408,5 +431,19 @@ export function buildProgram() {
       await doctor().catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  // O mapa por tema no fim do --help: 29 comandos em lista plana dizem O QUE
+  // cada um faz, mas não POR ONDE começar nem em que ordem o fluxo anda.
+  program.addHelpText('after', `
+Fluxo típico (cada tema, na ordem):
+  configurar     init · doctor · mode <actions|local> · update
+  especificar    preflight --milestone → specs (label ou run) → audit --milestone [--critique]
+  planejar       run <issue> (plan → critique → validate) → move <n> ready
+  decompor       run <issue> (decompose → --apply) → order <feature>
+  implementar    implement <issue> · task start/done · story review
+  entregar       merge <feature> (PRs empilhados, na ordem) · run --pr <n> (board até QA)
+  acompanhar     info · order · move · repair-stage
+
+Docs: https://astratech-net-br.github.io/spec-wave-cli/  ·  spec-wave <comando> --help`);
+
   return program;
 }

package/src/commands/audit.mjs

@@ -0,0 +1,280 @@
+// Auditoria de dependências de uma milestone — o passo entre "as specs estão
+// mergeadas" e "vamos gerar os planos".
+//
+// A crítica adversarial roda por Feature; este comando cruza as specs COMO
+// CONJUNTO e responde as três perguntas que hoje só apareciam se alguém lesse
+// as dez juntas: alguma dependência declarada não é criada por ninguém? Alguma
+// bloqueante vive em milestone posterior à de quem depende dela? Alguma spec
+// descreve o que já existe em código?
+//
+// Toda a decisão mora em `lib/spec-audit.mjs` (puro); aqui é só coleta: as
+// Features de todas as milestones (o catálogo do que uma spec pode citar), o
+// conteúdo da spec de cada Feature-alvo nas quatro camadas (loadArtifact — uma
+// spec em PR aberto também é auditável), e a lista de arquivos do repositório
+// para a heurística de código.
+//
+// Comando LOCAL, fora da tabela STEPS de propósito: ele é por milestone, não
+// por issue — não há label que o dispare nem lugar para ela no fluxo.
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, getRepoDefaultBranch, listMilestones, listIssuesByMilestone,
+} from '../api/github-rest.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { featureDocPaths } from '../lib/doc-paths.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { runCritique } from '../lib/critique.mjs';
+import { slugify } from '../lib/slugify.mjs';
+import { loadStaticTechContext, TECH_CONTEXT_PATH } from '../lib/tech-context.mjs';
+import {
+  auditMilestone, auditVerdict, dependencySection, issueRefs,
+} from '../lib/spec-audit.mjs';
+import { resolveMilestone } from './preflight.mjs';
+
+// A heurística de código procura componente/rota, não texto: docs/ casaria com
+// o próprio slug da spec, e um README citando a feature não é implementação.
+const IGNORED_DIRS = new Set([
+  'node_modules', 'dist', 'build', 'coverage', 'vendor', 'target', 'tmp', 'docs',
+]);
+const IGNORED_EXTS = new Set(['.md', '.txt', '.lock', '.log', '.svg', '.png', '.jpg']);
+const MAX_FILES = 20000;
+
+/**
+ * Caminhos relativos dos arquivos do repositório (I/O — nunca lança).
+ * Profundidade e volume limitados: é insumo de heurística, não um índice.
+ */
+export function listRepoFiles(root, { maxFiles = MAX_FILES, maxDepth = 8 } = {}) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > maxDepth || out.length >= maxFiles) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (out.length >= maxFiles) return;
+      if (e.name.startsWith('.') || IGNORED_DIRS.has(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) walk(abs, depth + 1);
+      else if (e.isFile() && !IGNORED_EXTS.has(path.extname(e.name).toLowerCase())) {
+        out.push(path.relative(root, abs));
+      }
+    }
+  };
+  walk(root, 0);
+  return out;
+}
+
+export async function audit({ milestone: milestoneArg, critique = false, json = false } = {}) {
+  const falhar = (msg) => {
+    if (json) console.log(JSON.stringify({ erro: msg }, null, 2));
+    else p.log.error(msg);
+    process.exitCode = 1;
+  };
+
+  if (!json) p.intro(chalk.bold('spec-wave audit — dependências da milestone'));
+
+  const { config, root, error: configError } = loadConfig();
+  if (configError || !config?.owner || !config?.repo) {
+    return falhar(`${configError || `${CONFIG_FILE} sem owner/repo`} — rode \`spec-wave init\` antes.`);
+  }
+  const { owner, repo } = config;
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    return falhar(`Sem token utilizável para ${owner}/${repo}: ${err.message}`);
+  }
+
+  const s = json ? null : p.spinner();
+  s?.start('Montando o catálogo de Features...');
+
+  let base;
+  let milestones;
+  try {
+    base = await getRepoDefaultBranch(token, owner, repo);
+    milestones = await listMilestones(token, owner, repo);
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível ler o repositório ${owner}/${repo}: ${err.message}`);
+  }
+  const { milestone, error: msError } = resolveMilestone(milestones, milestoneArg);
+  if (msError) {
+    s?.stop('');
+    return falhar(msError);
+  }
+
+  // O catálogo vem de TODAS as milestones: a inversão de sequenciamento é
+  // exatamente uma dependência que resolve para FORA da milestone-alvo.
+  const catalog = [];
+  let targetIssues = [];
+  try {
+    for (const m of milestones) {
+      const issues = await listIssuesByMilestone(token, owner, repo, m.number);
+      if (m.number === milestone.number) targetIssues = issues;
+      for (const i of issues) {
+        if (detectIssueType(i) !== 'Feature') continue;
+        catalog.push({
+          number: i.number,
+          title: i.title,
+          slug: slugify(i.title),
+          closed: i.state === 'closed',
+          milestone: { number: m.number, title: m.title, due_on: m.due_on ?? null },
+        });
+      }
+    }
+  } catch (err) {
+    s?.stop('');
+    return falhar(`Não foi possível listar as issues por milestone: ${err.message}`);
+  }
+
+  // A spec de cada Feature-alvo, nas quatro camadas (disco, base, branch, PR) —
+  // em série pelo mesmo motivo do preflight: rate limit secundário.
+  const features = [];
+  for (const issue of targetIssues) {
+    if (detectIssueType(issue) !== 'Feature' || issue.state === 'closed') continue;
+    const docs = featureDocPaths(root, issue, 'Feature');
+    const { content } = await loadArtifact({
+      token, owner, repo, root, base,
+      pathRel: docs.spec.rel, doc: 'spec', issueNumber: issue.number,
+    });
+    features.push({
+      number: issue.number,
+      title: issue.title,
+      slug: slugify(issue.title),
+      milestone: { number: milestone.number, title: milestone.title, due_on: milestone.due_on ?? null },
+      spec: content,
+    });
+  }
+
+  if (features.length === 0) {
+    s?.stop('');
+    return falhar(`Nenhuma Feature aberta na milestone "${milestone.title}".`);
+  }
+
+  // Referências `#N` que o catálogo não conhece: issue sem milestone, Story de
+  // outra Feature, ou número que não existe. A API é quem diferencia.
+  const conhecidas = new Set(catalog.map(f => f.number));
+  const desconhecidas = new Set();
+  for (const f of features) {
+    const section = f.spec ? dependencySection(f.spec) : null;
+    for (const n of issueRefs(section || '')) {
+      if (!conhecidas.has(n)) desconhecidas.add(n);
+    }
+  }
+  const missingRefs = [];
+  for (const n of desconhecidas) {
+    const issue = await getIssue(token, owner, repo, n).catch(() => null);
+    if (!issue) { missingRefs.push(n); continue; }
+    catalog.push({
+      number: issue.number,
+      title: issue.title,
+      slug: slugify(issue.title),
+      closed: issue.state === 'closed',
+      milestone: issue.milestone
+        ? { number: issue.milestone.number, title: issue.milestone.title, due_on: issue.milestone.due_on ?? null }
+        : null,
+    });
+  }
+
+  // As decisões de modelagem do tech_context entram na auditoria: recurso
+  // compartilhado com `criada_por: SEM DONO` é pendência de planejamento, não
+  // nota perdida num YAML. Falha de parse é aviso — o arquivo é do usuário.
+  const { context: techContext, error: techError } = loadStaticTechContext(root);
+  if (techError && !json) {
+    p.log.warn(`${TECH_CONTEXT_PATH} não parseou (${techError}) — decisões de modelagem fora da auditoria.`);
+  }
+
+  const resultado = auditMilestone({
+    features, catalog, missingRefs, files: listRepoFiles(root), techContext,
+  });
+  const veredito = auditVerdict(resultado);
+  s?.stop(`Milestone "${milestone.title}": ${features.length} Feature(s) auditada(s).`);
+
+  // A crítica de conjunto: UMA chamada de modelo sobre todas as specs juntas,
+  // atrás do que o determinístico não pega — a mesma regra contada de dois
+  // jeitos. Grave é material (é contradição entre requisitos, por definição);
+  // e falhar aqui falha o comando: quem pediu --critique não pode receber um
+  // "ok" que só cobriu a metade barata.
+  let critica = null;
+  if (critique) {
+    const comSpec = features.filter(f => f.spec);
+    if (comSpec.length < 2) {
+      veredito.avisos.push(
+        `Crítica de conjunto não rodou: ${comSpec.length} spec(s) disponível(is) — conjunto de um não tem par.`
+      );
+    } else {
+      const sc = json ? null : p.spinner();
+      sc?.start(`Crítica de conjunto sobre ${comSpec.length} specs...`);
+      try {
+        critica = await runCritique({
+          kind: 'conjunto',
+          specs: comSpec.map(f => ({ number: f.number, title: f.title, content: f.spec })),
+          cwd: root,
+          standalone: true,
+        });
+      } catch (err) {
+        sc?.stop('');
+        return falhar(`A crítica de conjunto falhou: ${err.message}`);
+      }
+      sc?.stop(`Crítica de conjunto: ${critica.findings.length} finding(s) (modelo ${critica.model}).`);
+      for (const f of critica.findings) {
+        const onde = (f.features || []).map(n => `#${n}`).join(' × ');
+        const linha = `crítica de conjunto${onde ? ` [${onde}]` : ''}: ${f.text}`;
+        if (f.severity === 'grave') veredito.materiais.push(linha);
+        else veredito.avisos.push(linha);
+      }
+      if (veredito.materiais.length) veredito.status = 'problema';
+      else if (veredito.avisos.length) veredito.status = 'aviso';
+    }
+  }
+
+  const saida = {
+    milestone: { title: milestone.title, number: milestone.number },
+    features: features.map(f => ({ number: f.number, title: f.title, temSpec: !!f.spec })),
+    auditoria: resultado,
+    // `markdown` é o comentário pronto para a issue — quem posta (nas DUAS
+    // pontas de cada finding) é o agente que dirige o comando, não a CLI.
+    critica: critica
+      ? { model: critica.model, findings: critica.findings, markdown: critica.markdown }
+      : null,
+    veredito,
+  };
+
+  if (json) {
+    console.log(JSON.stringify(saida, null, 2));
+    if (veredito.status === 'problema') process.exitCode = 1;
+    return saida;
+  }
+
+  const grafoLinhas = resultado.grafo.map(g => {
+    const deps = g.dependsOn.length ? ` ← depende de ${g.dependsOn.map(d => `#${d}`).join(', ')}` : '';
+    return `  #${g.number}${deps}`;
+  });
+  if (grafoLinhas.length) {
+    p.note(grafoLinhas.join('\n'), 'Dependências entre Features (extraídas das specs)');
+  }
+
+  for (const a of veredito.avisos) p.log.warn(a);
+  for (const m of veredito.materiais) p.log.error(m);
+
+  if (veredito.status === 'problema') {
+    p.outro(`${veredito.materiais.length} achado(s) material(is). Decida antes de gerar os planos.`);
+    process.exitCode = 1;
+    return saida;
+  }
+  p.outro(veredito.status === 'aviso'
+    ? 'Nada material — confira os avisos antes de seguir.'
+    : 'Dependências da milestone fecham. Siga para os planos.');
+  return saida;
+}

package/src/commands/implement.mjs

@@ -412,6 +412,18 @@ export function buildFeatureContext({
     `Enquanto houver Story pendente, a Feature permanece em ${STAGE_DEVELOPMENT}.`
   );
   lines.push('');
+  // O trecho pós-implementação era o único do fluxo inteiramente manual — e o
+  // merge de PRs empilhados é ordem-dependente (apagar a branch do primeiro já
+  // fechou o segundo). O contexto termina apontando o comando que encapsula a
+  // sequência segura, em vez de deixar a mecânica por conta de quem mergeia.
+  lines.push(
+    '**Ao terminar, informe no relatório final:** os PRs ficam **empilhados** (cada um baseado no anterior) — ' +
+    'o merge é **ordem-dependente**. Depois da revisão humana (marcar cada PR como pronto), o merge é ' +
+    `\`npx @spec-wave/cli@latest merge ${feature.number}\`: ele mergeia na ordem das dependências, ` +
+    'reaponta as bases, move o board até 🧪 QA e só apaga as branches no fim. ' +
+    '**NUNCA** mergeie um PR da pilha com `--delete-branch` à mão — apagar a branch antes de reapontar o dependente fecha o PR seguinte.'
+  );
+  lines.push('');
   lines.push(boardRuleBlockquote());
 
   if (skipped.length > 0) {