@spec-wave/cli 0.24.0 → 0.26.0

package/src/commands/validate.mjs

@@ -5,12 +5,15 @@ import { getIssue, removeLabel, addLabel, commentOnIssue } from '../api/github-r
 import { slugify } from '../lib/slugify.mjs';
 import {
   CONFIG_FILE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_BUG, LABEL_BUG_APPROVED,
+  LABEL_READY, LABEL_PLAN_APPROVED,
   REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS, REQUIRED_BUG_SECTIONS, labelNames,
 } from '../config.mjs';
 import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
 import { bugDocPaths, describeMissingSections } from '../lib/bug-doc.mjs';
 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';
 
 /**
  * Validação do bug.md (RFC-004 §5).
@@ -55,7 +58,7 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
     }
   }
 
-  await removeLabel(token, owner, repo, n, 'spec-wave:ready');
+  await removeLabel(token, owner, repo, n, LABEL_READY);
 
   if (errors.length > 0) {
     await commentOnIssue(
@@ -65,18 +68,19 @@ async function validateBug({ token, owner, repo, issue, issueNumber, root }) {
       `\n\nCorrija os problemas e adicione novamente a label \`spec-wave:ready\`.`
     );
     console.error('Validação falhou:', errors.join(', '));
-    process.exit(1);
+    return { ok: false, errors };
   }
 
   await addLabel(token, owner, repo, n, LABEL_BUG_APPROVED);
   await commentOnIssue(
     token, owner, repo, n,
     '✅ **bug.md validado.**\n\n' +
-    `📄 [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+    `📄 [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode: executionMode(), root })})\n\n` +
     'As seis seções obrigatórias estão presentes — reprodução, causa raiz e teste de ' +
     'regressão inclusive. O bug pode ser aceito na triagem.'
   );
   console.log('bug.md validado.');
+  return { ok: true, errors: [] };
 }
 
 /**
@@ -95,6 +99,17 @@ export function renderMissingSection(doc, { section, found }) {
     : base;
 }
 
+/**
+ * Valida os documentos de uma issue.
+ *
+ * Devolve o veredito em vez de chamar `process.exit(1)` na reprova: quem
+ * encerra o processo é o wrapper do `bin` (mesmo exit code no Actions), e assim
+ * o `run` consegue tratar a reprova como o desfecho ESPERADO que ela é — sem
+ * morrer no meio da cadeia, sem pular o `finally` e sem deixar o lock para trás.
+ *
+ * @param {{issueNumber: string|number}} params
+ * @returns {Promise<{ok: boolean, errors: string[]}>}
+ */
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
   const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
@@ -174,7 +189,7 @@ export async function validate({ issueNumber }) {
   }
 
   // Remove trigger label
-  await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:ready');
+  await removeLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_READY);
 
   if (errors.length > 0) {
     await commentOnIssue(
@@ -199,11 +214,11 @@ export async function validate({ issueNumber }) {
     //
     // Regenerar é decisão humana, e o comentário acima diz como e o que custa.
     console.error('Validação falhou:', errors.join(', '));
-    process.exit(1);
+    return { ok: false, errors };
   }
 
   // Validação passou: adiciona label plan-approved.
-  await addLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:plan-approved');
+  await addLabel(token, owner, repo, parseInt(issueNumber, 10), LABEL_PLAN_APPROVED);
 
   await commentOnIssue(
     token, owner, repo, parseInt(issueNumber, 10),
@@ -216,4 +231,5 @@ export async function validate({ issueNumber }) {
   );
 
   console.log('Validação OK. Feature pronta para decomposição.');
+  return { ok: true, errors: [] };
 }

package/src/config.mjs

@@ -407,6 +407,9 @@ export const LABEL_NEEDS_HUMAN = 'spec-wave:needs-human';
 // pronta de uma que só foi movida à mão para ✅ Ready.
 export const LABEL_PLAN_APPROVED = 'spec-wave:plan-approved';
 // Gatilhos que REGERAM documento: presentes na issue, indicam etapa pendente.
+// `spec-wave:ready` era o único gatilho sem constante — e por isso aparecia como
+// string literal no validate, no YAML e em toda tabela que precisasse citá-lo.
+export const LABEL_READY = 'spec-wave:ready';
 export const LABEL_SPEC = 'spec-wave:spec';
 export const LABEL_PLAN = 'spec-wave:plan';
 // Achado GRAVE que o Tech Leader aceitou como risco conhecido. Fica na issue
@@ -422,7 +425,7 @@ export const TRIGGER_LABELS = [
   { name: LABEL_SPEC,                color: 'BFD4F2', description: 'Gerar spec.md via GitHub Action'      },
   { name: LABEL_PLAN,                color: 'BFD4F2', description: 'Gerar plan.md via GitHub Action'      },
   { name: LABEL_CRITIQUE,            color: 'BFD4F2', description: 'Re-criticar o plan.md COMO ESTÁ, sem regerar' },
-  { name: 'spec-wave:ready',         color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
+  { name: LABEL_READY,               color: '0E8A16', description: 'Validar spec+plan e mover para Ready'  },
   { name: LABEL_PLAN_APPROVED,       color: '0E8A16', description: 'Spec+plan validados com sucesso'       },
   { name: LABEL_DECOMPOSE,           color: 'BFD4F2', description: 'Gerar/re-criticar o rascunho da decomposição (decomposition.md)' },
   { name: LABEL_DECOMPOSE_APPLY,     color: 'BFD4F2', description: 'Aplicar o decomposition.md revisado: criar Stories e Tasks' },

package/src/lib/config-file.mjs

@@ -0,0 +1,62 @@
+// Escrita do `.spec-wave.json` — um lugar só.
+//
+// Havia três escritores, cada um com a sua lógica: `init` monta o objeto do zero
+// (e por isso descarta campos custom como `codeReview.linkMode` e `specKit`),
+// `refresh` faz merge preservando o resto, e `update` tem a mesma lógica do
+// refresh duplicada. Quem só precisa mexer em UM campo — o caso do `mode` — não
+// tinha por onde.
+//
+// A serialização é parte do contrato, não detalhe: `update` compara o config
+// byte a byte com o remoto para decidir se ele entra no PR (`lib/pr-branch.mjs`),
+// então um `\n` a mais no fim faria o arquivo entrar em toda execução.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+import { CONFIG_FILE } from '../config.mjs';
+import { findConfigPath } from './project-root.mjs';
+
+/**
+ * Serialização canônica do config (função PURA).
+ *
+ * @param {object} config
+ * @returns {string}
+ */
+export function serializeConfig(config) {
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+/**
+ * Aplica uma mutação ao `.spec-wave.json` preservando todo o resto.
+ *
+ * O mutator recebe uma CÓPIA e pode alterá-la no lugar ou devolver outro objeto.
+ * Gravação idempotente: conteúdo idêntico não reescreve o arquivo (não suja o
+ * mtime nem o `git status` de quem só consultou).
+ *
+ * @param {(config: object) => object|void} mutator
+ * @param {{cwd?: string}} [options]
+ * @returns {{configPath: string, config: object, changed: boolean}}
+ */
+export function updateConfig(mutator, { cwd = process.cwd() } = {}) {
+  const configPath = findConfigPath(cwd);
+  if (!configPath) {
+    throw new Error(
+      `${CONFIG_FILE} não encontrado — rode \`npx @spec-wave/cli@latest init\` neste repositório.`,
+    );
+  }
+
+  const raw = readFileSync(configPath, 'utf-8');
+  let current;
+  try {
+    current = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${CONFIG_FILE} está corrompido (${err.message}) — corrija-o à mão antes.`);
+  }
+
+  const draft = structuredClone(current);
+  const next = mutator(draft) ?? draft;
+  const content = serializeConfig(next);
+  if (content === raw) return { configPath, config: next, changed: false };
+
+  writeFileSync(configPath, content);
+  return { configPath, config: next, changed: true };
+}

package/src/lib/doc-paths.mjs

@@ -0,0 +1,51 @@
+// Onde mora cada documento do fluxo, a partir do TÍTULO da issue.
+//
+// O slug vem do título (`slugify`), então renomear a issue muda o diretório —
+// motivo pelo qual o `run` compara o que as labels afirmam com o que existe no
+// clone antes de decidir qualquer coisa.
+//
+// Funções PURAS: montam caminhos, não tocam o filesystem.
+
+import path from 'node:path';
+
+import { slugify } from './slugify.mjs';
+
+export { bugDocPaths } from './bug-doc.mjs';
+
+/**
+ * Diretório do documento por tipo de issue.
+ *
+ * Feature usa o mesmo `docs/features/<slug>` da spec/plan; RFC ganha o seu, já
+ * que não passa por spec/plan.
+ *
+ * @param {string|null} root raiz do repositório (ausente = process.cwd())
+ * @param {{title?: string}} issue
+ * @param {string|null} [type] tipo canônico ('Feature', 'RFC', ...)
+ * @returns {{slug: string, rel: string, dir: string}}
+ */
+export function resolveDocDir(root, issue, type) {
+  const slug = slugify(issue?.title || '');
+  const rel = type === 'RFC' ? `docs/rfcs/${slug}` : `docs/features/${slug}`;
+  return { slug, rel, dir: path.resolve(root || process.cwd(), rel) };
+}
+
+/**
+ * Caminhos dos três documentos de uma Feature/RFC (função PURA).
+ *
+ * @param {string|null} root
+ * @param {{title?: string}} issue
+ * @param {string|null} [type]
+ * @returns {{slug, dirRel, dirAbs, spec, plan, decomposition}} cada documento com {rel, abs}
+ */
+export function featureDocPaths(root, issue, type) {
+  const { slug, rel, dir } = resolveDocDir(root, issue, type);
+  const doc = name => ({ rel: `${rel}/${name}`, abs: path.join(dir, name) });
+  return {
+    slug,
+    dirRel: rel,
+    dirAbs: dir,
+    spec: doc('spec.md'),
+    plan: doc('plan.md'),
+    decomposition: doc('decomposition.md'),
+  };
+}

package/src/lib/execution-mode.mjs

@@ -0,0 +1,132 @@
+// Onde o fluxo roda: no GitHub Actions ou nesta máquina.
+//
+// Duas fontes, de propósito, porque são dois leitores diferentes:
+//
+//  • `.spec-wave.json` → `execution.mode` — é o que a CLI e a skill leem para
+//    saber se devem aplicar a label (Actions) ou chamar `spec-wave run` (local);
+//  • variável de repositório `SPEC_WAVE_EXECUTION` — é o que o GitHub avalia no
+//    `if:` de cada job. Sem ela, o workflow roda mesmo com o config dizendo
+//    "local", e o minuto é cobrado do mesmo jeito.
+//
+// Divergir é o estado perigoso, não um detalhe: o usuário acha que desligou e
+// não desligou. Por isso a comparação vira função PURA aqui, e tanto o comando
+// `mode` quanto o `doctor` dizem a mesma coisa.
+//
+// NÃO confundir com `executionMode()` de `lib/flow-run.mjs`: aquele responde
+// "onde este processo está rodando AGORA" (GITHUB_ACTIONS); este responde "onde
+// o repositório decidiu que o fluxo roda".
+
+export const EXECUTION_MODES = ['actions', 'local'];
+export const DEFAULT_EXECUTION_MODE = 'actions';
+
+/** Nome da variável de repositório consultada pelo `if:` dos workflows. */
+export const EXECUTION_VARIABLE = 'SPEC_WAVE_EXECUTION';
+
+/** Expressão que os templates de workflow carregam — usada pelo doctor e pelos testes. */
+export const EXECUTION_GUARD = `vars.${EXECUTION_VARIABLE} != 'local'`;
+
+/**
+ * Modo declarado no `.spec-wave.json` (função PURA).
+ *
+ * @param {object|null} config
+ * @returns {'actions'|'local'}
+ */
+export function configuredMode(config) {
+  const mode = String(config?.execution?.mode || '').toLowerCase();
+  return EXECUTION_MODES.includes(mode) ? mode : DEFAULT_EXECUTION_MODE;
+}
+
+/**
+ * Valor que a variável de repositório deve ter para um modo (função PURA).
+ *
+ * `null` significa "a variável não deve existir" — ausência é o estado default
+ * de qualquer repo, e é o que mantém os workflows armados sem depender de nada.
+ *
+ * @param {'actions'|'local'} mode
+ * @returns {string|null}
+ */
+export function variableValueFor(mode) {
+  return mode === 'local' ? 'local' : null;
+}
+
+/**
+ * A variável do repositório precisa ser escrita? (função PURA)
+ *
+ * Três estados entram, não dois: `string` (valor lido), `null` (lida, e não
+ * existe) e `undefined` (NÃO deu para ler — 403, a variável exige admin).
+ *
+ * `undefined` conta como "precisa escrever". Tratá-lo como "já está certo"
+ * fazia o comando pular a escrita e ainda anunciar que config e variável
+ * coincidiam — o usuário saía achando que desligou o CI, com os workflows
+ * armados. Não conseguir ler quase sempre significa não conseguir escrever;
+ * tentar e falhar com a mensagem certa é honesto, não tentar e declarar
+ * sucesso não é.
+ *
+ * @param {object} params
+ * @param {string|null|undefined} params.variable valor remoto
+ * @param {string|null} params.expected valor que o modo-alvo exige (null = ausente)
+ * @returns {boolean}
+ */
+export function shouldWriteVariable({ variable, expected }) {
+  return variable !== expected;
+}
+
+/**
+ * Diagnóstico do modo de execução (função PURA).
+ *
+ * @param {object} params
+ * @param {'actions'|'local'} params.configured modo no .spec-wave.json
+ * @param {string|null|undefined} params.variable valor remoto (undefined = não verificável)
+ * @param {string[]} [params.unguardedWorkflows] workflows instalados SEM a guarda
+ * @returns {{status: 'ok'|'warn'|'problem', summary: string, notes: string[], fixes: string[]}}
+ */
+export function describeModeState({ configured, variable, unguardedWorkflows = [] }) {
+  const esperado = variableValueFor(configured);
+  const notes = [];
+  const fixes = [];
+  let status = 'ok';
+
+  notes.push(`Modo declarado no .spec-wave.json: **${configured}**.`);
+
+  if (variable === undefined) {
+    status = 'warn';
+    notes.push(
+      `Variável \`${EXECUTION_VARIABLE}\` não verificável (requer admin no repo) — ` +
+      'não dá para afirmar daqui se os workflows estão armados.'
+    );
+  } else if (variable === esperado) {
+    notes.push(esperado === null
+      ? `Variável \`${EXECUTION_VARIABLE}\` ausente, como deve ser no modo actions.`
+      : `Variável \`${EXECUTION_VARIABLE}\`=${variable} no repositório.`);
+  } else if (configured === 'local') {
+    // O caso que custa dinheiro: config diz local, GitHub continua disparando.
+    status = 'problem';
+    notes.push(
+      `Modo local, mas \`${EXECUTION_VARIABLE}\` ${variable === null ? 'não existe' : `vale "${variable}"`} ` +
+      'no repositório — os workflows CONTINUAM disparando e consumindo minutos.'
+    );
+    fixes.push('Rode `npx @spec-wave/cli@latest mode local` (ou defina a variável em Settings → Actions → Variables).');
+  } else {
+    status = 'problem';
+    notes.push(
+      `Modo actions, mas \`${EXECUTION_VARIABLE}\`="${variable}" está setada — os workflows ` +
+      'são pulados e nada roda até alguém rodar o comando local.'
+    );
+    fixes.push('Rode `npx @spec-wave/cli@latest mode actions` para remover a variável.');
+  }
+
+  if (configured === 'local' && unguardedWorkflows.length > 0) {
+    status = 'problem';
+    notes.push(
+      `Workflows instalados sem a guarda \`${EXECUTION_GUARD}\`: ${unguardedWorkflows.join(', ')} — ` +
+      'esses vão rodar de qualquer jeito.'
+    );
+    fixes.push('Rode `npx @spec-wave/cli@latest update` para publicar os workflows com a guarda.');
+  }
+
+  const summary = configured === 'local'
+    ? 'Execução local: os comandos rodam nesta máquina (`spec-wave run <issue>`).'
+    : 'Execução no GitHub Actions: as labels de gatilho disparam os workflows.';
+
+  return { status, summary, notes, fixes };
+}