@spec-wave/cli 0.25.0 → 0.27.0

package/src/commands/run.mjs

@@ -20,13 +20,13 @@ import path from 'node:path';
 import chalk from 'chalk';
 
 import { resolveToken } from '../api/auth.mjs';
-import { getIssue, getPR, getFileContent, listPullRequestReviews } from '../api/github-rest.mjs';
+import { getIssue, getPR, listPullRequestReviews } from '../api/github-rest.mjs';
 import { loadProjectConfig } from '../lib/board.mjs';
-import { existsOnRemote } from '../lib/doc-availability.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
 import { featureDocPaths, bugDocPaths } from '../lib/doc-paths.mjs';
 import { isActionsRun, resolveFlowContext } from '../lib/flow-run.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { nextStep, resolveForcedStep, STEPS } from '../lib/next-step.mjs';
+import { nextStep, resolveForcedStep, stepDocs, docsForType, STEPS } from '../lib/next-step.mjs';
 import { nextPrStep, reviewVerdict } from '../lib/pr-step.mjs';
 import { configuredMode } from '../lib/execution-mode.mjs';
 import { labelNames } from '../config.mjs';
@@ -41,8 +41,44 @@ const LOCK_STALE_MS = 30 * 60 * 1000;
 // comentário de uso. Fica em .git/ porque já é ignorado e é por clone.
 // ---------------------------------------------------------------------------
 
-function lockPath(root, key) {
-  return path.join(root || process.cwd(), '.git', 'spec-wave', `run-${key}.lock`);
+/**
+ * Diretório .git COMPARTILHADO do clone (função com I/O, isolada para teste).
+ *
+ * Montar `<root>/.git` à mão assume que `.git` é um diretório — e num git
+ * worktree ele é um ARQUIVO com `gitdir: <caminho real>`. O `mkdirSync` do
+ * acquireLock estourava ENOTDIR ali, derrubando TODO `spec-wave run` de dentro
+ * de um worktree, inclusive `--dry-run`, antes de qualquer trabalho.
+ *
+ * `--git-common-dir` e não `--git-dir`: num worktree o `--git-dir` é
+ * `.git/worktrees/<nome>`, o que tornaria o lock por WORKTREE. Dois `run` na
+ * mesma issue em worktrees diferentes rodariam em paralelo commitando na mesma
+ * branch — exatamente o que este lock existe para impedir. O comum preserva o
+ * "é por clone" que o comentário acima declara.
+ *
+ * O caminho devolvido é RELATIVO ao cwd quando se está no clone principal
+ * (`.git` na raiz, `../../.git` num subdiretório) e absoluto de dentro de um
+ * worktree — daí o `path.resolve`. Sem ele, rodar de um subdiretório criaria um
+ * `.git/` novo ali dentro, que é um estrago pior e mais silencioso que o ENOTDIR.
+ *
+ * @param {string} [root] raiz do projeto (a do .spec-wave.json)
+ * @returns {string} caminho absoluto do diretório .git compartilhado
+ */
+export function gitCommonDir(root) {
+  const cwd = root || process.cwd();
+  try {
+    const out = execSync('git rev-parse --git-common-dir', {
+      cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (out) return path.resolve(cwd, out);
+  } catch {
+    // Fora de um repositório git: cai no palpite antigo. O `run` vai falhar
+    // adiante de qualquer forma (ele commita e faz push), e com mensagem melhor.
+  }
+  return path.join(cwd, '.git');
+}
+
+export function lockPath(root, key) {
+  return path.join(gitCommonDir(root), 'spec-wave', `run-${key}.lock`);
 }
 
 function acquireLock(root, key) {
@@ -78,19 +114,6 @@ function releaseLock(file) {
   } catch { /* já removido */ }
 }
 
-// Commits locais ainda não publicados: gerar o próximo documento por cima de um
-// anterior que ficou só no clone é execução parcial disfarçada de sucesso.
-function unpushedCommits(root) {
-  try {
-    const out = execSync('git rev-list --count @{u}..HEAD', {
-      cwd: root || process.cwd(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    return Number.parseInt(out, 10) || 0;
-  } catch {
-    return 0; // sem upstream configurado: não dá para afirmar nada
-  }
-}
-
 function assertNotInActions() {
   if (!isActionsRun()) return;
   throw new Error(
@@ -126,23 +149,69 @@ function localDocStates(issue, type, root) {
  * clone. É a diferença entre "ainda não foi gerado" e "foi gerado e você não
  * puxou" — a segunda leva a sobrescrever trabalho publicado.
  */
-async function probeRemote({ decision, docs, docPaths, token, owner, repo }) {
-  const step = STEPS[decision.action];
-  if (!step) return docs;
-  const alvos = [step.writes, ...step.reads]
-    .filter(Boolean)
-    .filter(doc => docs[doc] === 'missing');
-  if (alvos.length === 0) return docs;
+/**
+ * Documentos que vale sondar no remoto antes de acreditar na decisão (PURA).
+ *
+ * O G5 ("as labels afirmam um documento que não existe aqui") diz, com todas as
+ * letras, que o arquivo *não está no clone nem no remoto* — e manda renomear o
+ * diretório ou REGERAR. Enquanto a sonda só rodava para decisão não-bloqueada,
+ * essa frase era afirmada sem nunca ter perguntado ao remoto: num clone que
+ * está apenas atrás, o conselho levava a regerar por cima de um documento
+ * publicado, gastando uma chamada de IA para destruir o artefato bom. A
+ * correção certa era `git pull`.
+ *
+ * Nesse caso o passo é `none` e não há `writes`/`reads` de onde tirar a lista —
+ * sondamos os documentos do tipo.
+ *
+ * @param {{action: string, blocked: object|null}} decision
+ * @param {string|null} type
+ * @returns {string[]}
+ */
+export function docsToProbe(decision, type) {
+  if (decision.blocked?.code === 'inconsistent-state') return docsForType(type);
+  if (decision.blocked || !STEPS[decision.action]) return [];
+  // stepDocs e não `[writes, ...reads]`: `validate` e `decompose` leem
+  // documentos diferentes conforme o tipo, e sondar a lista errada devolve um
+  // `docs` que o G6 aprova por engano.
+  return stepDocs(decision.action, type);
+}
+
+/**
+ * Resolve o estado remoto dos documentos que faltam no clone.
+ *
+ * Duas camadas, não uma: além da branch base, o documento pode estar num Pull
+ * Request ainda não mergeado — é onde ele NASCE agora. Sem essa segunda camada,
+ * o `run` concluiria "não existe" e regeraria a spec a cada execução até alguém
+ * mergear, pagando a IA de novo toda vez e descartando as edições do revisor.
+ *
+ * `doc` do resolvedor usa 'decomposition' com o mesmo nome do fluxo, então o
+ * mapeamento é direto.
+ */
+async function probeRemote({ alvos, docs, docPaths, token, owner, repo, root, issueNumber }) {
+  if (alvos.length === 0) return { docs, docPrs: {} };
 
   const atualizado = { ...docs };
+  const docPrs = {};
   for (const doc of alvos) {
-    const onRemote = await existsOnRemote({
-      getFileContent, token, owner, repo, pathRel: docPaths[doc],
-    });
-    if (onRemote === true) atualizado[doc] = 'remote';
-    else if (onRemote === null) atualizado[doc] = 'unknown';
+    const achado = await loadArtifact({
+      token, owner, repo, root, pathRel: docPaths[doc], doc, issueNumber,
+    }).catch(() => null);
+
+    if (!achado) {
+      atualizado[doc] = 'unknown';
+      continue;
+    }
+    // 'local' aqui só aconteceria se o arquivo tivesse aparecido no meio da
+    // execução; manter o estado que a sonda local já apurou é mais previsível.
+    if (achado.state === 'local') continue;
+    atualizado[doc] = achado.state;
+    // Guarda PR e branch: o bloqueio de `branch-only` cita a branch, porque não
+    // há PR nenhum a citar.
+    if (achado.state === 'pending-pr' || achado.state === 'branch-only') {
+      docPrs[doc] = { pr: achado.pr || null, branch: achado.ref || null };
+    }
   }
-  return atualizado;
+  return { docs: atualizado, docPrs };
 }
 
 // ---------------------------------------------------------------------------
@@ -180,6 +249,32 @@ function parityWarnings(issue, type) {
 // Despacho
 // ---------------------------------------------------------------------------
 
+/**
+ * Saída de `--json` (função PURA — devolve o texto, não imprime).
+ *
+ * UM documento, sempre. A impressão morava dentro do laço de passos, então
+ * `--max-steps N` emitia N documentos JSON concatenados — saída que nenhum
+ * parser aceita, numa flag que a skill anuncia justamente para ramificar
+ * programaticamente.
+ *
+ * O desfecho fica no TOPO, e não só dentro de `steps`: é o que quase todo
+ * consumidor lê, e é exatamente o formato que a execução de um passo só já
+ * produzia. Assim a correção não quebra quem já lia `.action`.
+ *
+ * @param {object} params
+ * @param {string|number} params.issueNumber
+ * @param {string|null} params.type
+ * @param {object|null} params.ultimaDecisao
+ * @param {object[]} [params.passos]
+ * @returns {string} JSON indentado
+ */
+export function renderRunJson({ issueNumber, type, ultimaDecisao, passos = [] }) {
+  return JSON.stringify(
+    { issue: Number(issueNumber), type: type ?? null, ...ultimaDecisao, steps: passos },
+    null, 2,
+  );
+}
+
 async function dispatch(action, { issueNumber }) {
   switch (action) {
     case 'generate-spec': {
@@ -315,6 +410,9 @@ export async function run(issueArg, options = {}) {
   const exitCodeAntes = process.exitCode;
   try {
     let ultimaDecisao = null;
+    // `--json` acumula e imprime UMA vez no fim (ver renderRunJson).
+    const passos = [];
+    let ultimoTipo = null;
 
     for (let i = 0; i < teto; i++) {
       const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
@@ -342,9 +440,14 @@ export async function run(issueArg, options = {}) {
       };
 
       let decision = nextStep({ ...entrada, docs });
-      if (remoteCheck && decision.action !== 'none' && !decision.blocked) {
-        const docsRemotos = await probeRemote({ decision, docs, docPaths, token, owner, repo });
-        decision = nextStep({ ...entrada, docs: docsRemotos });
+      if (remoteCheck) {
+        const alvos = docsToProbe(decision, type).filter(doc => docs[doc] === 'missing');
+        if (alvos.length > 0) {
+          const sondado = await probeRemote({
+            alvos, docs, docPaths, token, owner, repo, root, issueNumber,
+          });
+          decision = nextStep({ ...entrada, docs: sondado.docs, docPrs: sondado.docPrs });
+        }
       }
       ultimaDecisao = decision;
 
@@ -357,7 +460,8 @@ export async function run(issueArg, options = {}) {
         );
       }
 
-      if (json) console.log(JSON.stringify({ issue: Number(issueNumber), type, ...decision }, null, 2));
+      ultimoTipo = type;
+      if (json) passos.push(decision);
       else reportDecision(decision, { issueNumber, type, title: issue.title, warnings: parityWarnings(issue, type) });
 
       if (decision.blocked) { process.exitCode = 2; break; }
@@ -379,16 +483,28 @@ export async function run(issueArg, options = {}) {
         break;
       }
 
-      const pendentes = unpushedCommits(root);
-      if (pendentes > 0) {
-        console.warn(chalk.yellow(
-          `\n⚠️  ${pendentes} commit(s) ainda não publicado(s). O próximo passo leria um documento ` +
-          'que só existe no seu clone — publique antes de continuar.'
+      // O passo publicou um documento em Pull Request? Então o próximo depende do
+      // merge, e encadear agora só produziria um bloqueio `pr-pending` uma volta
+      // depois — com uma mensagem menos direta e uma consulta à API a mais.
+      //
+      // Substitui o antigo guard de commits não publicados, que ficou
+      // permanentemente em zero: a publicação deixou de passar por git local.
+      const publicado = resultado?.pr || resultado?.published?.pr;
+      if (publicado?.number) {
+        console.log(chalk.yellow(
+          `\n⏸️  O documento foi publicado no PR #${publicado.number}` +
+          `${publicado.url ? ` (${publicado.url})` : ''}.\n` +
+          '   O próximo passo do fluxo lê esse documento da branch base — ' +
+          'revise e faça o merge para continuar.'
         ));
         break;
       }
     }
 
+    if (json) {
+      console.log(renderRunJson({ issueNumber, type: ultimoTipo, ultimaDecisao, passos }));
+    }
+
     return ultimaDecisao;
   } finally {
     releaseLock(lock);

package/src/commands/validate.mjs

@@ -1,5 +1,3 @@
-import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-rest.mjs';
 import { slugify } from '../lib/slugify.mjs';
@@ -14,6 +12,48 @@ import { detectIssueType } from '../lib/issue-type.mjs';
 import { loadConfig } from '../lib/project-root.mjs';
 import { executionMode } from '../lib/flow-run.mjs';
 import { docBlobUrl } from '../lib/repo-links.mjs';
+import { loadArtifact } from '../lib/doc-source.mjs';
+import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
+import { isAwaitingMerge } from '../lib/doc-source.mjs';
+import { getRepoDefaultBranch } from '../api/github-rest.mjs';
+
+/**
+ * Aborto por documento ainda em Pull Request.
+ *
+ * Este é o portão mais importante do `validate`, e existe por um motivo
+ * assimétrico: a reprova NÃO é inócua. Ela remove `spec-wave:ready` (o gatilho,
+ * que `issues: [labeled]` não redispara sozinho) e comenta a falha na issue —
+ * ou seja, danifica estado COMPARTILHADO. Fazer isso porque o documento está num
+ * PR não mergeado seria reprovar por uma condição que não é do documento.
+ *
+ * É exatamente o incidente que o comentário do `readsByType` em
+ * lib/next-step.mjs já registra ter acontecido antes, com clone desatualizado.
+ *
+ * Aborta ANTES do removeLabel: a label fica, e reaplicá-la depois do merge
+ * simplesmente funciona.
+ */
+async function abortIfPendingPr({ token, owner, repo, n, docs }) {
+  const pendentes = docs.filter(d => isAwaitingMerge(d.state));
+  if (pendentes.length === 0) return null;
+
+  // Cada documento carrega o SEU desbloqueio: um está esperando merge, outro
+  // esperando alguém abrir o PR. Um texto único ("faça o merge do PR") mandaria
+  // metade dos casos procurar uma tela que não existe.
+  const blocos = pendentes.map(d => awaitingMergeBlock({
+    pathRel: d.pathRel, state: d.state, pr: d.pr, branch: d.ref,
+  }));
+  const linhas = blocos.map(b => `- ${b.message}\n  ${b.unblock}`);
+
+  await commentOnIssue(token, owner, repo, n,
+    '⏸️ **Validação adiada — documento ainda não está na branch base.**\n\n' +
+    `${linhas.join('\n')}\n\n` +
+    'Resolvido isso, reaplique `spec-wave:ready` — a label foi **mantida** na issue, ' +
+    'e nada foi reprovado.'
+  ).catch(() => {});
+
+  console.error(`Validação adiada: ${pendentes.map(d => d.pathRel).join(', ')} fora da base.`);
+  return { ok: false, errors: linhas, awaitingMerge: true };
+}
 
 /**
  * Validação do bug.md (RFC-004 §5).
@@ -23,11 +63,19 @@ import { docBlobUrl } from '../lib/repo-links.mjs';
  * um único arquivo, e a falha NÃO devolve o item para a etapa de spec (Bug não
  * tem etapa de spec). Reaplicar `spec-wave:bug` é o caminho de retomada.
  */
-async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
+async function validateBug({ token, owner, repo, issue, issueNumber, root, base }) {
   const n = parseInt(issueNumber, 10);
-  const { fileRel, fileAbs } = bugDocPaths(issue.title, root);
+  const { fileRel } = bugDocPaths(issue.title, root);
   const errors = [];
 
+  const bug = await loadArtifact({
+    token, owner, repo, root, pathRel: fileRel, doc: 'bug', issueNumber: n, base,
+  });
+  const adiado = await abortIfPendingPr({
+    token, owner, repo, n, docs: [{ ...bug, pathRel: fileRel }],
+  });
+  if (adiado) return adiado;
+
   const names = labelNames(issue);
   const critiqueFailed = names.includes(LABEL_CRITIQUE_FAILED);
   const needsHuman = names.includes(LABEL_NEEDS_HUMAN);
@@ -44,12 +92,12 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
     );
   }
 
-  if (!existsSync(fileAbs)) {
+  if (bug.content == null) {
     errors.push(
       `❌ \`bug.md\` não encontrado em \`${fileRel}\` — aplique \`${LABEL_BUG}\` para gerá-lo.`
     );
   } else {
-    const content = readFileSync(fileAbs, 'utf-8');
+    const content = bug.content;
     for (const faltante of describeMissingSections(content, REQUIRED_BUG_SECTIONS)) {
       errors.push(renderMissingSection('bug.md', faltante));
     }
@@ -124,19 +172,23 @@ export async function validate({ issueNumber }) {
     );
   }
 
-  const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
+  const n = parseInt(issueNumber, 10);
+  const issue = await getIssue(token, owner, repo, n);
+
+  // Branch base para a leitura em camadas. Best-effort: sem ela o resolvedor cai
+  // no default da API, que é a mesma branch.
+  const base = await getRepoDefaultBranch(token, owner, repo).catch(() => null);
 
   // Bug tem artefato próprio (bug.md) e caminho próprio de validação — não passa
   // pelo par spec.md + plan.md, que é exclusivo de Feature.
   if (detectIssueType(issue) === 'Bug') {
-    return await validateBug({ token, owner, repo, issue, issueNumber, root });
+    return await validateBug({ token, owner, repo, issue, issueNumber, root, base });
   }
 
   const slug = slugify(issue.title);
   // Ancorado na RAIZ do repo, não no cwd: rodar de um subdiretório encontra o
   // config subindo na árvore e precisa encontrar os documentos no mesmo lugar.
   const featureRel = `docs/features/${slug}`;
-  const featureDir = path.resolve(root || process.cwd(), featureRel);
 
   const errors = [];
 
@@ -158,12 +210,28 @@ export async function validate({ issueNumber }) {
     );
   }
 
+  // Os dois documentos vêm do resolvedor em camadas (disco → base → PR aberto):
+  // ler só o disco reprovaria uma Feature cujo plan.md está publicado, o que
+  // custa a label de gatilho e um comentário de falha na issue.
+  const planRel = `${featureRel}/plan.md`;
+  const specRel = `${featureRel}/spec.md`;
+  const ler = (doc, pathRel) => loadArtifact({
+    token, owner, repo, root, pathRel, doc, issueNumber: n, base,
+  });
+  const plan = await ler('plan', planRel);
+  const spec = await ler('spec', specRel);
+
+  const adiado = await abortIfPendingPr({
+    token, owner, repo, n,
+    docs: [{ ...plan, pathRel: planRel }, { ...spec, pathRel: specRel }],
+  });
+  if (adiado) return adiado;
+
   // Check plan.md
-  const planPath = path.join(featureDir, 'plan.md');
-  if (!existsSync(planPath)) {
-    errors.push('❌ `plan.md` não encontrado em `' + `${featureRel}/plan.md` + '`');
+  if (plan.content == null) {
+    errors.push('❌ `plan.md` não encontrado em `' + planRel + '`');
   } else {
-    const planContent = readFileSync(planPath, 'utf-8');
+    const planContent = plan.content;
     for (const faltante of describeMissingSections(planContent, REQUIRED_PLAN_SECTIONS)) {
       errors.push(renderMissingSection('plan.md', faltante));
     }
@@ -173,11 +241,10 @@ export async function validate({ issueNumber }) {
   }
 
   // Check spec.md
-  const specPath = path.join(featureDir, 'spec.md');
-  if (!existsSync(specPath)) {
-    errors.push('❌ `spec.md` não encontrado em `' + `${featureRel}/spec.md` + '`');
+  if (spec.content == null) {
+    errors.push('❌ `spec.md` não encontrado em `' + specRel + '`');
   } else {
-    const specContent = readFileSync(specPath, 'utf-8');
+    const specContent = spec.content;
     for (const faltante of describeMissingSections(specContent, REQUIRED_SPEC_SECTIONS)) {
       errors.push(renderMissingSection('spec.md', faltante));
     }

package/src/config.mjs

@@ -519,6 +519,24 @@ export const WORKFLOW_FILES = [
   'qa.yml',
 ];
 
+/**
+ * Workflows que PUBLICAM um documento gerado (branch própria + Pull Request).
+ *
+ * Lista explícita de propósito. O teste que verifica permissões selecionava os
+ * workflows por `content.includes('contents: write')` — um predicado que passa
+ * VACUAMENTE se o marcador sumir do YAML: nenhum arquivo é selecionado, o laço
+ * não roda, e o teste fica verde justamente no cenário que ele deveria pegar.
+ *
+ * Estes quatro precisam de `contents: write` (o commit vai por Git Data API) E
+ * de `pull-requests: write` (sem ela o commit existe e o PR não).
+ */
+export const ARTIFACT_WORKFLOW_FILES = [
+  'generate-spec.yml',
+  'generate-plan.yml',
+  'generate-bug.yml',
+  'decompose.yml',
+];
+
 export const ISSUE_TEMPLATE_FILES = [
   'plan-template.md',
   'spec-template.md',