@spec-wave/cli 0.26.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.26.0",
+  "version": "0.28.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

@@ -294,6 +294,33 @@ export async function createIssue(token, owner, repo, title, body, labels, { mil
   return { number: res.data.number, nodeId: res.data.node_id, url: res.data.html_url, id: res.data.id };
 }
 
+// Milestones do repositório (abertas e fechadas).
+//
+// O usuário fala o TÍTULO da milestone ("v06"), a API de issues filtra pelo
+// NÚMERO. A tradução mora aqui — e a lista completa também serve para a
+// mensagem de erro: "milestone não encontrada" sem dizer quais existem manda o
+// usuário adivinhar entre nome errado e API fora do ar.
+export async function listMilestones(token, owner, repo) {
+  const octokit = makeOctokit(token);
+  return await octokit.paginate(octokit.rest.issues.listMilestones, {
+    owner, repo, state: 'all', per_page: 100,
+  });
+}
+
+// Issues de uma milestone (pelo NÚMERO dela), abertas e fechadas.
+//
+// `state: 'all'` de propósito: uma Feature fechada continua contando para o
+// inventário — o que muda é que ela não entra na lista do que gerar.
+export async function listIssuesByMilestone(token, owner, repo, milestoneNumber) {
+  const octokit = makeOctokit(token);
+  const issues = await octokit.paginate(octokit.rest.issues.listForRepo, {
+    owner, repo, milestone: String(milestoneNumber), state: 'all', per_page: 100,
+  });
+  // `listForRepo` devolve Pull Requests junto — eles são issues para a API, e
+  // não para o fluxo.
+  return issues.filter(i => !i.pull_request);
+}
+
 export async function getIssue(token, owner, repo, issueNumber) {
   const octokit = makeOctokit(token);
   const res = await octokit.rest.issues.get({ owner, repo, issue_number: issueNumber });
@@ -311,6 +338,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;

package/src/cli.mjs

@@ -162,6 +162,16 @@ export function buildProgram() {
       await run(issue, options).catch(err => { console.error(err.message); process.exit(1); });
     });
 
+  program
+    .command('preflight')
+    .description('Confere, antes de gerar, tudo que decide uma rodada de specs de uma milestone')
+    .requiredOption('--milestone <nome>', 'Título da milestone a inventariar')
+    .option('--json', 'Imprime o relatório em JSON')
+    .action(async (options) => {
+      const { preflight } = await import('./commands/preflight.mjs');
+      await preflight(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)')
@@ -188,6 +198,8 @@ export function buildProgram() {
     .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('--skill-in-pr', 'Força incluir a skill dos agentes no Pull Request')
+    .option('--no-skill-in-pr', 'Força manter a skill dos agentes 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) => {

package/src/commands/decompose.mjs

@@ -17,11 +17,10 @@
 // edições humanas. Para regerar do zero, apague o arquivo.
 
 import { execSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import {
   getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy, listIssueComments,
+  getRepoDefaultBranch,
 } from '../api/github-rest.mjs';
 import { addSubIssue, listSubIssues, getProjectSnapshot } from '../api/github-graphql.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
@@ -37,7 +36,11 @@ import { resolveDocDir } from '../lib/doc-paths.mjs';
 import { docBlobUrl } from '../lib/repo-links.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
-import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
+import { resolveFlowContext } from '../lib/flow-run.mjs';
+import { publishArtifact } from '../lib/artifact-publish.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
+import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
+import { isAwaitingMerge } from '../lib/doc-source.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import {
   renderDecompositionDoc, parseDecompositionDoc, DECOMPOSITION_FILE,
@@ -246,11 +249,26 @@ function formatItemsLintWarning(texts) {
   return `\n\n⚠️ possíveis artefatos de idioma nos itens gerados: ${excerpts}`;
 }
 
-// Grava e commita o rascunho. O modo (actions|local) decide identidade do git e
-// o que fazer com falha de push — ver `lib/flow-run.mjs`.
-function commitFile(filePath, content, message, mode) {
-  const published = commitGenerated({ filePath, content, message, mode });
+/**
+ * Publica o documento em branch própria + Pull Request — ver lib/artifact-publish.mjs.
+ *
+ * ASSÍNCRONA, e todo chamador precisa de `await`. O `apply` chama isto dentro de
+ * um `try/catch` cuja única função é degradar a falha em aviso (as issues já
+ * existem; derrubar o run aqui mandaria o humano reaplicar o gatilho e duplicar
+ * dezenas de itens). Sem o `await`, a promise rejeitada não é capturada por esse
+ * catch: o aviso some e vira unhandled rejection.
+ */
+async function publishFile(ctx, { doc, pathRel, content, nextLabel = null }) {
+  const { token, owner, repo, issue, issueNumber, base } = ctx;
+  const published = await publishArtifact({
+    token, owner, repo, doc,
+    issueNumber: parseInt(issueNumber, 10),
+    issueTitle: issue?.title || '',
+    issueUrl: issue?.html_url || '',
+    pathRel, content, base, nextLabel,
+  });
   if (published.warning) console.warn(`⚠️  ${published.warning}`);
+  return published;
 }
 
 // Os prompts vivem em `src/plugin/skills/decompose/model-prompt.{feature,rfc}.md`
@@ -263,23 +281,67 @@ function commitFile(filePath, content, message, mode) {
 // ---------------------------------------------------------------------------
 
 async function draftDecomposition(ctx) {
-  const { token, owner, repo, issue, issueNumber, type, labels, usage, root, runMode, docDir, docPath, docRel } = ctx;
+  const {
+    token, owner, repo, issue, issueNumber, type, labels, usage, root, runMode,
+    docRel, dirRel, base,
+  } = ctx;
   const number = parseInt(issueNumber, 10);
   const kind = DECOMPOSE_TARGETS[type]; // Feature → 'stories'; RFC → 'tasks'
-  const blobUrl = docBlobUrl({ owner, repo, pathRel: docRel, mode: runMode, root });
 
-  const specPath = path.join(docDir, 'spec.md');
-  const planPath = path.join(docDir, 'plan.md');
-  const specContent = existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null;
-  const planContent = existsSync(planPath) ? readFileSync(planPath, 'utf-8') : null;
+  const ler = (doc, pathRel) => loadArtifact({
+    token, owner, repo, root, pathRel, doc, issueNumber: number, base,
+  });
+
+  // spec e plan alimentam o rascunho de Feature. Um deles preso num PR não
+  // mergeado com leitura ingênua viraria "(spec.md não encontrado)" no payload:
+  // rascunho gerado sobre o vazio, sem erro nenhum. Recusar é mais barato.
+  const spec = type === 'RFC' ? null : await ler('spec', `${dirRel}/spec.md`);
+  const plan = type === 'RFC' ? null : await ler('plan', `${dirRel}/plan.md`);
+  for (const [nome, doc] of [['spec.md', spec], ['plan.md', plan]]) {
+    if (doc && isAwaitingMerge(doc.state)) {
+      const bloqueio = awaitingMergeBlock({
+        pathRel: `${dirRel}/${nome}`, state: doc.state, pr: doc.pr, branch: doc.ref,
+      });
+      await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE).catch(() => {});
+      await commentOnIssue(token, owner, repo, number,
+        `⏸️ **decompose parado:** ${bloqueio.message}\n\n${bloqueio.unblock}\n\n` +
+        `Reaplique \`${LABEL_DECOMPOSE}\` depois do merge.`
+      ).catch(() => {});
+      throw new DecomposeBlockedError(bloqueio.message);
+    }
+  }
+  const specContent = spec?.content ?? null;
+  const planContent = plan?.content ?? null;
 
   // Rascunho existente é preservado COMO ESTÁ: o humano corrige o arquivo e
   // re-aplica a label para uma nova crítica. Regenerar aqui apagaria a correção
   // — é justamente o que fazia o ciclo não convergir.
+  //
+  // Com a publicação por Pull Request, "existente" deixou de ser `existsSync`: o
+  // rascunho que o revisor está editando mora na branch do PR. Ler só o disco
+  // aqui INVERTERIA a invariante — regeneraria por cima da revisão, e ainda
+  // pagaria a IA de novo.
+  const rascunho = await ler('decomposition', docRel);
+
   let markdown;
-  if (existsSync(docPath)) {
-    console.log(`Rascunho encontrado em ${docRel} — criticando o arquivo como está (sem regerar).`);
-    markdown = readFileSync(docPath, 'utf-8');
+  let publicado = null;
+  if (rascunho.content != null) {
+    const onde = rascunho.state === 'pending-pr'
+      ? `no PR #${rascunho.pr?.number} (ainda não mergeado)`
+      : rascunho.state === 'branch-only'
+        ? `na branch ${rascunho.ref} (sem PR aberto)`
+        : docRel;
+    console.log(`Rascunho encontrado ${onde} — criticando o arquivo como está (sem regerar).`);
+    markdown = rascunho.content;
+    // O PR que já existe é o mesmo lugar onde o revisor vai corrigir: o
+    // comentário de fecho precisa apontá-lo, senão a re-crítica sai sem link e a
+    // pessoa fica procurando onde editar.
+    if (isAwaitingMerge(rascunho.state)) {
+      // `branch-only` entra aqui de propósito: republicar reaproveita a branch e
+      // TENTA abrir o PR de novo — é o caminho de recuperação quando a abertura
+      // falhou antes. O conteúdo é o do revisor, não um regerado.
+      publicado = { pr: rascunho.pr, branch: rascunho.ref, unchanged: true };
+    }
   } else {
     console.log(`Gerando rascunho de decomposição para ${type}: ${issue.title}`);
     const userContent = type === 'RFC'
@@ -312,10 +374,22 @@ async function draftDecomposition(ctx) {
       stories: generated.stories || [],
       tasks: generated.tasks || [],
     });
-    commitFile(docPath, markdown, `docs: rascunho de decomposição de ${docRel} [spec-wave]`, runMode);
-    console.log(`Rascunho commitado em ${docRel}.`);
+    publicado = await publishFile(ctx, {
+      doc: 'decomposition', pathRel: docRel, content: markdown,
+      nextLabel: LABEL_DECOMPOSE_APPLY,
+    });
+    console.log(`Rascunho publicado em ${publicado.branch} (${docRel}).`);
   }
 
+  // O link só pode ser montado DEPOIS de saber onde o documento está: na branch
+  // do PR recém-aberto, na do PR que já existia, ou na base. Inferir a ref pelo
+  // ambiente (o que o docBlobUrl faz por padrão) daria a branch default num
+  // evento `issues: labeled` — e lá o arquivo ainda não está.
+  const refDoDocumento = publicado?.branch || rascunho.ref || undefined;
+  const blobUrl = docBlobUrl({
+    owner, repo, pathRel: docRel, mode: runMode, root, ref: refDoDocumento,
+  });
+
   // Valida a estrutura ANTES de gastar tokens com a crítica: um arquivo quebrado
   // por edição humana precisa de mensagem clara, não de uma crítica sobre nada.
   let doc;
@@ -338,7 +412,7 @@ async function draftDecomposition(ctx) {
 
   // O RFC não tem spec/plan para auditar contra — a crítica não teria referência.
   if (kind !== 'stories') {
-    await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: false });
+    return await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: false, publicado });
     return;
   }
 
@@ -422,26 +496,41 @@ async function draftDecomposition(ctx) {
   // Crítica limpa: remove o bloqueio anterior, que também zera o contador de
   // tentativas na próxima rodada (ver resolveCritiqueAttempt).
   await removeLabel(token, owner, repo, number, LABEL_CRITIQUE_FAILED).catch(() => {});
-  await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: true });
+  return await finishDraft(ctx, { doc, blobUrl, itemCount, critiqued: true, publicado });
 }
 
 // Fecho comum do rascunho aprovado: libera para revisão humana e o apply.
-async function finishDraft({ token, owner, repo, issueNumber, docRel }, { blobUrl, itemCount, critiqued }) {
+async function finishDraft(
+  { token, owner, repo, issueNumber, docRel }, { blobUrl, itemCount, critiqued, publicado }
+) {
   const number = parseInt(issueNumber, 10);
   await addLabel(token, owner, repo, number, LABEL_DECOMPOSE_READY);
   await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE);
+
+  // O apply LÊ o rascunho da branch base, então ele só roda depois do merge —
+  // dizer "crie as issues agora" sem essa ressalva manda o humano num passo que
+  // vai ser recusado.
+  const pr = publicado?.pr;
+  const revisao = pr?.number
+    ? `🔀 Pull Request: #${pr.number} — ${pr.url}\n\n` +
+      '**Nada foi criado ainda.** Revise (e edite, se quiser) o arquivo **no PR**, ' +
+      'faça o merge e então crie as issues:\n'
+    : '**Nada foi criado ainda.** Revise (e edite, se quiser) o arquivo e então crie as issues:\n';
+
   await commentOnIssue(token, owner, repo, number,
     `📝 **Rascunho de decomposição pronto para revisão** (${itemCount}).\n\n` +
     `📄 Arquivo: [\`${docRel}\`](${blobUrl})\n\n` +
     (critiqued
       ? 'A crítica adversarial não encontrou contradições graves. '
       : '') +
-    `**Nada foi criado ainda.** Revise (e edite, se quiser) o arquivo e então crie as issues:\n` +
+    revisao +
     `\`\`\`\ngh issue edit ${issueNumber} --add-label "${LABEL_DECOMPOSE_APPLY}"\n\`\`\`\n` +
     `Se preferir uma nova crítica depois de editar, reaplique \`${LABEL_DECOMPOSE}\` — ` +
-    'o arquivo é criticado como está, sem ser regerado. Para gerar outro do zero, apague-o.'
+    'o arquivo é criticado como está, sem ser regerado. Para gerar outro do zero, ' +
+    'feche o PR e apague a branch.'
   ).catch(err => console.warn(`Falha ao comentar o rascunho: ${err.message}`));
   console.log(`Rascunho liberado para revisão: ${itemCount}.`);
+  return { pr: pr || null };
 }
 
 // ---------------------------------------------------------------------------
@@ -449,14 +538,38 @@ async function finishDraft({ token, owner, repo, issueNumber, docRel }, { blobUr
 // ---------------------------------------------------------------------------
 
 async function applyDecomposition(ctx) {
-  const { token, owner, repo, issueNumber, docPath, docRel } = ctx;
+  const { token, owner, repo, issueNumber, docRel, root, base } = ctx;
   const number = parseInt(issueNumber, 10);
 
-  if (!existsSync(docPath)) {
+  const rascunho = await loadArtifact({
+    token, owner, repo, root, pathRel: docRel,
+    doc: 'decomposition', issueNumber: number, base,
+  });
+
+  // Rascunho ainda em Pull Request é recusa DURA, não aviso: aplicar criaria
+  // dezenas de issues a partir de um documento que ninguém aprovou, e o próprio
+  // arquivo passaria a afirmar `applied=<data>` enquanto o revisor ainda decide.
+  // O merge do PR É a aprovação humana.
+  // Vale para os DOIS estados fora da base. Cobrir só `pending-pr` deixaria o
+  // apply criar dezenas de issues a partir de um rascunho que está numa branch
+  // sem PR — ou seja, que ninguém teve como revisar.
+  if (isAwaitingMerge(rascunho.state)) {
+    const bloqueio = awaitingMergeBlock({
+      pathRel: docRel, state: rascunho.state, pr: rascunho.pr, branch: rascunho.ref,
+    });
+    await commentOnIssue(token, owner, repo, number,
+      `⏸️ **decompose-apply parado:** ${bloqueio.message}\n\n${bloqueio.unblock}\n\n` +
+      `Nenhuma issue foi criada. Reaplique \`${LABEL_DECOMPOSE_APPLY}\` depois do merge.`
+    ).catch(() => {});
+    await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_APPLY).catch(() => {});
+    throw new DecomposeBlockedError(bloqueio.message);
+  }
+
+  if (rascunho.content == null) {
     await commentOnIssue(token, owner, repo, number,
       `❌ **Não há rascunho de decomposição para aplicar.**\n\n` +
       `Esperava encontrar \`${docRel}\`. Gere o rascunho primeiro:\n` +
-      `\`\`\`\ngh issue edit ${issueNumber} --add-label "${LABEL_DECOMPOSE}"\n\`\`\``
+      `\`\`\`\ngh issue edit ${issueNumber} --add-label "${LABEL_DECOMPOSE}"\n\`\`\`\n`
     ).catch(() => {});
     await removeLabel(token, owner, repo, number, LABEL_DECOMPOSE_APPLY).catch(() => {});
     throw new DecomposeBlockedError(`${docRel} não encontrado — aplique ${LABEL_DECOMPOSE} primeiro.`);
@@ -464,7 +577,7 @@ async function applyDecomposition(ctx) {
 
   let doc;
   try {
-    doc = parseDecompositionDoc(readFileSync(docPath, 'utf-8'));
+    doc = parseDecompositionDoc(rascunho.content);
   } catch (err) {
     await commentOnIssue(token, owner, repo, number,
       `❌ **Não consegui ler o rascunho da decomposição.**\n\n` +
@@ -508,14 +621,19 @@ async function applyDecomposition(ctx) {
   // Depois da criação de propósito: se este commit falhar, as issues já existem
   // e o pior caso é o comportamento anterior (arquivo sem anotação), avisado no
   // log. O contrário — anotar antes e falhar na criação — inventaria issues.
+  //
+  // Vai para uma branch PRÓPRIA (`spec-wave/<n>-decompose-apply`), nunca por cima
+  // da branch do rascunho: aquela já foi mergeada (é pré-condição do apply), e
+  // reabri-la produziria um PR reintroduzindo estado antigo.
   try {
-    commitFile(
-      docPath,
-      renderDecompositionDoc({ ...doc, appliedAt: new Date().toISOString() }),
-      `docs: registra as issues criadas em ${docRel} [spec-wave]`,
-      ctx.runMode,
-    );
-    console.log(`${docRel} anotado com as issues criadas.`);
+    const anotado = await publishFile(ctx, {
+      doc: 'decomposition-apply',
+      pathRel: docRel,
+      content: renderDecompositionDoc({ ...doc, appliedAt: new Date().toISOString() }),
+    });
+    console.log(anotado.pr?.number
+      ? `${docRel} anotado com as issues criadas — PR #${anotado.pr.number}.`
+      : `${docRel} anotado com as issues criadas em ${anotado.branch}.`);
   } catch (err) {
     console.warn(
       `⚠️  Issues criadas, mas ${docRel} não foi anotado (${err.message}). ` +
@@ -992,8 +1110,12 @@ export async function decompose({ issueNumber, apply }) {
 
   // Config do repo: raiz para os caminhos de documento e escalada da crítica.
   const { config, root } = loadConfig();
-  const { rel: docRel, dir: docDir } = resolveDocDir(root, issue, type);
-  const docPath = path.join(docDir, DECOMPOSITION_FILE);
+  const { rel: docRel } = resolveDocDir(root, issue, type);
+
+  // Branch base: é dela que os documentos são lidos quando não estão no clone, e
+  // é contra ela que o PR do rascunho é aberto. Best-effort — sem ela a leitura
+  // cai para o default da API, que é o mesmo lugar.
+  const base = await getRepoDefaultBranch(token, owner, repo).catch(() => null);
 
   // Comentários só são necessários no rascunho (contador de tentativas).
   let comments = [];
@@ -1010,7 +1132,9 @@ export async function decompose({ issueNumber, apply }) {
   const usageEntries = [];
   const ctx = {
     token, projectToken, owner, repo, issue, issueNumber, type, labels, comments,
-    root, runMode, docDir, docPath, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
+    root, runMode, docRel: `${docRel}/${DECOMPOSITION_FILE}`,
+    dirRel: docRel,
+    base,
     // Números das issues já criadas por este run. Compartilhado por referência
     // com o applyCtx: o catch externo precisa saber se houve criação para não
     // aconselhar um retry que duplicaria itens.
@@ -1024,8 +1148,11 @@ export async function decompose({ issueNumber, apply }) {
   };
 
   try {
-    if (mode === 'apply') await applyDecomposition(ctx);
-    else await draftDecomposition(ctx);
+    // O desfecho volta ao chamador (o `run` usa o PR para parar a cadeia: o passo
+    // seguinte lê o documento da base, então depende do merge).
+    return mode === 'apply'
+      ? await applyDecomposition(ctx)
+      : await draftDecomposition(ctx);
   } catch (err) {
     // Paradas por decisão do fluxo já comentaram na issue; erros inesperados não.
     if (!err.blocked) {