@spec-wave/cli 0.10.0 → 0.11.1

package/README.md

@@ -85,6 +85,14 @@ Ferramenta Node.js que configura e opera o fluxo via linha de comando.
 | `code-review.yml` | PR aberto/reaberto | Move Feature para `👀 Code Review` |
 | `qa.yml` | PR aprovado | Move Feature para `🧪 QA` |
 
+**Re-executar uma etapa (`spec-wave:force`).** Adicionada *junto* de uma label de gatilho, a label `spec-wave:force` manda o comando re-executar a etapa ignorando os guards; ela é consumida pelo run (vale uma vez). Sozinha não dispara nada.
+
+```bash
+gh issue edit 12 --add-label "spec-wave:force" --add-label "spec-wave:decompose"
+```
+
+No `decompose` ela **fecha as sub-issues da decomposição anterior** (Stories e suas Tasks) antes de gerar as novas — operação destrutiva, com aviso no comentário da issue quando alguma já saiu de `✅ Ready`. Em `generate-spec`/`generate-plan` não muda nada: essas etapas já sobrescrevem o documento a cada acionamento. A flag equivalente para execução local é `--force`.
+
 ### Skill (`src/templates/skill/SKILL.md`)
 
 Skill que guia o usuário pelo fluxo via comandos como `/spec-wave spec 42`, `/spec-wave plan 42`, `/spec-wave decompose 42`. A skill lê o `.spec-wave.json` local, detecta o estado atual e executa os comandos corretos sem abrir wizards interativos. Instale-a no seu agente com `install-skill` (ver abaixo).

package/bin/spec-wave.mjs

@@ -132,6 +132,7 @@ program
   .command('generate-plan')
   .description('Gera plan.md para uma Feature (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .option('--force', 'Re-executa a etapa ignorando os guards (equivale à label spec-wave:force)')
   .action(async (options) => {
     const { generatePlan } = await import('../src/commands/generate-plan.mjs');
     await generatePlan(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -141,6 +142,7 @@ program
   .command('generate-spec')
   .description('Gera spec.md para uma Feature (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .option('--force', 'Re-executa a etapa ignorando os guards (equivale à label spec-wave:force)')
   .action(async (options) => {
     const { generateSpec } = await import('../src/commands/generate-spec.mjs');
     await generateSpec(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -159,6 +161,7 @@ program
   .command('decompose')
   .description('Decompõe uma Feature em Stories e Tasks (usado pelo GitHub Action)')
   .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
+  .option('--force', 'Re-executa a etapa ignorando os guards (equivale à label spec-wave:force)')
   .action(async (options) => {
     const { decompose } = await import('../src/commands/decompose.mjs');
     await decompose(options).catch(err => { console.error(err.message); process.exit(1); });
@@ -222,6 +225,23 @@ program
     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')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {
@@ -28,4 +28,4 @@
     "commander": "^13.1.0",
     "js-yaml": "^4.1.0"
   }
-}
+}

package/src/api/github-graphql.mjs

@@ -198,6 +198,7 @@ export async function listSubIssues(token, issueNodeId) {
               number
               title
               body
+              state
               labels(first: 20) { nodes { name } }
             }
           }
@@ -211,6 +212,9 @@ export async function listSubIssues(token, issueNodeId) {
     title: n.title,
     body: n.body || '',
     nodeId: n.id,
+    // 'OPEN' | 'CLOSED' (GraphQL) normalizado para o vocabulário do REST, que
+    // é o que o resto do código compara (issue.state === 'closed').
+    state: n.state === 'CLOSED' ? 'closed' : 'open',
     labels: (n.labels?.nodes || []).map(l => l.name),
   }));
 }

package/src/api/github-rest.mjs

@@ -101,6 +101,19 @@ export async function getIssue(token, owner, repo, issueNumber) {
   return res.data;
 }
 
+// Fecha uma issue. Usado pelo re-decompose forçado para limpar as sub-issues
+// da decomposição anterior antes de gerar as novas.
+export async function closeIssue(token, owner, repo, issueNumber, reason = 'not_planned') {
+  const octokit = makeOctokit(token);
+  await octokit.rest.issues.update({
+    owner,
+    repo,
+    issue_number: issueNumber,
+    state: 'closed',
+    state_reason: reason,
+  });
+}
+
 export async function deleteLabel(token, owner, repo, name) {
   const octokit = makeOctokit(token);
   try {

package/src/commands/decompose.mjs

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolveToken } from '../api/auth.mjs';
-import { getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy } from '../api/github-rest.mjs';
-import { addSubIssue, listSubIssues } from '../api/github-graphql.mjs';
+import { getIssue, createIssue, removeLabel, addLabel, commentOnIssue, addBlockedBy, closeIssue } from '../api/github-rest.mjs';
+import { addSubIssue, listSubIssues, addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
+import { isForced, consumeForceLabel } from '../lib/force.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { runCritique } from '../lib/critique.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
@@ -10,7 +11,10 @@ import { formatDependencyLine } from '../lib/dependencies.mjs';
 import { lintLanguage } from '../lib/output-lint.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { DECOMPOSE_TARGETS, LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, TARGET_LANGUAGE, STAGE_READY, PROGRESS_TODO } from '../config.mjs';
+import {
+  DECOMPOSE_TARGETS, LABEL_DECOMPOSED, LABEL_CRITIQUE_FAILED, LABEL_FORCE,
+  TARGET_LANGUAGE, STAGE_READY, STAGE_DEVELOPMENT, STAGE_ORDER, PROGRESS_TODO,
+} from '../config.mjs';
 
 // Adiciona a issue ao board na Etapa ✅ Ready / Status Todo. Best-effort; a
 // Etapa nunca retrocede (advanceToStage não toca itens já adiante).
@@ -19,15 +23,61 @@ async function moveToReady(token, project, etapaField, statusField, nodeId) {
   await advanceToStage(token, project, etapaField, statusField, nodeId, STAGE_READY, PROGRESS_TODO);
 }
 
-// Extrai JSON da resposta do modelo (tolera texto em volta).
-function parseJson(raw) {
-  try {
-    return JSON.parse(raw);
-  } catch {
-    const jsonMatch = raw.match(/\{[\s\S]*\}/);
-    if (!jsonMatch) throw new Error('Claude did not return valid JSON');
-    return JSON.parse(jsonMatch[0]);
+// Dobra as barras invertidas que NÃO iniciam um escape válido de JSON. O corpo
+// das tasks costuma trazer trecho de shell/YAML/regex ("\d+", "gradlew \" no fim
+// da linha) e o modelo emite a barra crua: `JSON.parse` morre com "Bad escaped
+// character". Escapes válidos são consumidos inteiros pela regex, então `\\`,
+// `\n` e `\uXXXX` passam intactos.
+function repairEscapes(text) {
+  return text.replace(/\\(u[0-9a-fA-F]{4}|["\\/bfnrt])?/g, (match, valid) => (valid ? match : '\\\\'));
+}
+
+// Trecho ao redor da posição que o V8 reporta ("... at position 18321"), para o
+// log da Action mostrar O QUE quebrou em vez de só um offset.
+function excerptAt(text, message) {
+  const at = /position (\d+)/.exec(message || '');
+  if (!at) return '';
+  const pos = Number(at[1]);
+  const excerpt = text.slice(Math.max(0, pos - 60), pos + 60).replace(/\s+/g, ' ').trim();
+  return excerpt ? ` Trecho: …${excerpt}…` : '';
+}
+
+/**
+ * Extrai o JSON da resposta do modelo (função PURA — testável).
+ *
+ * Tenta, em ordem: conteúdo de fence de código, resposta inteira e o primeiro
+ * objeto `{...}` do texto; cada candidato é parseado cru e, se falhar, com os
+ * escapes reparados. Sem candidato válido, lança com o motivo e o trecho.
+ *
+ * @param {string} raw resposta bruta do modelo
+ * @returns {object} objeto decodificado
+ */
+export function parseModelJson(raw) {
+  const text = String(raw ?? '');
+  const candidates = [];
+  const fence = text.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+  if (fence) candidates.push(fence[1]);
+  candidates.push(text);
+  const obj = text.match(/\{[\s\S]*\}/);
+  if (obj) candidates.push(obj[0]);
+
+  let failure = null;
+  for (const candidate of candidates) {
+    const trimmed = candidate.trim();
+    if (!trimmed) continue;
+    for (const attempt of [trimmed, repairEscapes(trimmed)]) {
+      try {
+        return JSON.parse(attempt);
+      } catch (err) {
+        failure = { message: err.message, text: attempt };
+      }
+    }
   }
+
+  throw new Error(
+    `O modelo não devolveu JSON válido: ${failure?.message ?? 'nenhum objeto encontrado na resposta'}.` +
+    (failure ? excerptAt(failure.text, failure.message) : '')
+  );
 }
 
 // Prefixo de título das sub-issues geradas por cada tipo decompoível.
@@ -40,13 +90,19 @@ const CHILD_PREFIX = { Feature: '[STORY]', RFC: '[TASK]' };
  * sub-issues já contêm um item do tipo-alvo (Feature → algum `[STORY]` no
  * título; RFC → algum `[TASK]`). Sub-issues de outro tipo não contam.
  *
+ * Com `force` (flag `--force` ou label `spec-wave:force`) nada é pulado — o
+ * chamador é quem limpa a decomposição anterior antes de gerar a nova.
+ *
  * @param {object} params
  * @param {Array<string|{name: string}>} [params.labels] labels da issue
  * @param {Array<{ number?: number, title?: string }>} [params.subIssues] sub-issues existentes
  * @param {string} params.type tipo da issue ('Feature' | 'RFC')
+ * @param {boolean} [params.force] re-executa ignorando os guards
  * @returns {{ skip: boolean, reason: string }}
  */
-export function shouldSkipDecompose({ labels = [], subIssues = [], type } = {}) {
+export function shouldSkipDecompose({ labels = [], subIssues = [], type, force = false } = {}) {
+  if (force) return { skip: false, reason: '' };
+
   const names = labels
     .map(l => (typeof l === 'string' ? l : l?.name))
     .filter(Boolean);
@@ -66,6 +122,103 @@ export function shouldSkipDecompose({ labels = [], subIssues = [], type } = {})
   return { skip: false, reason: '' };
 }
 
+/**
+ * Planeja a limpeza de um re-decompose forçado (função PURA — testável).
+ *
+ * Só entram as sub-issues do tipo-alvo (Feature → `[STORY]`, RFC → `[TASK]`)
+ * que ainda estão abertas — as já fechadas não precisam de nada. Separa as que
+ * já saíram de ✅ Ready (Etapa ≥ 🚧 Desenvolvimento): fechá-las descarta
+ * trabalho em andamento, então elas são destacadas no aviso.
+ *
+ * @param {object} params
+ * @param {Array<{number:number, title?:string, nodeId?:string, state?:string}>} [params.subIssues]
+ * @param {string} params.type tipo da issue pai ('Feature' | 'RFC')
+ * @param {Record<number, string|null>} [params.stages] Etapa atual por número de issue
+ * @returns {{ close: object[], started: object[] }} close: a fechar (com `stage`);
+ *          started: subconjunto de close que já passou de Ready.
+ */
+export function planForcedCleanup({ subIssues = [], type, stages = {} } = {}) {
+  const prefix = CHILD_PREFIX[type];
+  if (!prefix) return { close: [], started: [] };
+
+  const devIdx = STAGE_ORDER.indexOf(STAGE_DEVELOPMENT);
+  const close = subIssues
+    .filter(s => (s.title || '').includes(prefix) && s.state !== 'closed')
+    .map(s => ({ ...s, stage: stages[s.number] ?? null }));
+  const started = close.filter(s => {
+    const idx = s.stage ? STAGE_ORDER.indexOf(s.stage) : -1;
+    return idx !== -1 && devIdx !== -1 && idx >= devIdx;
+  });
+  return { close, started };
+}
+
+// Fecha a decomposição anterior (sub-issues do tipo-alvo e os filhos delas) e
+// comenta o que foi fechado. Best-effort item a item: uma falha vira warn e o
+// re-decompose segue — melhor uma issue órfã do que abortar no meio.
+async function closeStaleSubIssues(ctx, subIssues) {
+  const { token, projectToken, owner, repo, issueNumber, project, etapaField, type } = ctx;
+
+  // Etapa de cada sub-issue (best-effort) — só para avisar o que já saiu de Ready.
+  const stages = {};
+  if (project?.id && etapaField?.id) {
+    await Promise.all(subIssues.map(async (s) => {
+      if (!s.nodeId) return;
+      try {
+        const itemId = await addProjectItem(projectToken, project.id, s.nodeId);
+        stages[s.number] = await getItemSingleSelectValue(projectToken, itemId, etapaField.id);
+      } catch {
+        stages[s.number] = null;
+      }
+    }));
+  }
+
+  const { close, started } = planForcedCleanup({ subIssues, type, stages });
+  if (close.length === 0) {
+    console.log('Re-decompose forçado: nenhuma sub-issue anterior aberta para fechar.');
+    return;
+  }
+
+  console.log(`Re-decompose forçado: fechando ${close.length} sub-issue(s) anterior(es)...`);
+  const closed = [];
+  for (const s of close) {
+    // Filhos primeiro (Tasks de uma Story): fechar só a Story deixaria as Tasks
+    // órfãs e abertas no board.
+    const children = s.nodeId ? await listSubIssues(token, s.nodeId).catch(() => []) : [];
+    for (const child of children.filter(c => c.state !== 'closed')) {
+      try {
+        await closeIssue(token, owner, repo, child.number);
+      } catch (err) {
+        console.warn(`  Falha ao fechar #${child.number}: ${err.message}`);
+      }
+    }
+    try {
+      await closeIssue(token, owner, repo, s.number);
+      closed.push({ ...s, children: children.length });
+      console.log(`  #${s.number} fechada${children.length ? ` (+${children.length} filha(s))` : ''}.`);
+    } catch (err) {
+      console.warn(`  Falha ao fechar #${s.number}: ${err.message}`);
+    }
+  }
+
+  if (closed.length === 0) return;
+  const lines = closed.map(s =>
+    `- #${s.number} ${s.title}${s.stage ? ` — Etapa ${s.stage}` : ''}` +
+    (s.children ? ` _(+${s.children} sub-issue(s))_` : '')
+  );
+  const startedWarning = started.length > 0
+    ? `\n\n⚠️ ${started.length} delas já tinha(m) saído de **${STAGE_READY}**: ` +
+      `${started.map(s => `#${s.number} (${s.stage})`).join(', ')} — ` +
+      'confira se algum trabalho em andamento foi descartado.'
+    : '';
+  await commentOnIssue(
+    token, owner, repo, parseInt(issueNumber, 10),
+    `🔀 **Re-decompose forçado** (label \`${LABEL_FORCE}\`)\n\n` +
+    `Fechadas ${closed.length} sub-issue(s) da decomposição anterior:\n\n${lines.join('\n')}` +
+    startedWarning +
+    '\n\nGerando a nova decomposição…'
+  ).catch(() => {});
+}
+
 // Lint de idioma sobre títulos+corpos gerados; retorna aviso pronto para
 // anexar ao comentário final ('' se limpo).
 function formatItemsLintWarning(texts) {
@@ -147,7 +300,7 @@ async function decomposeFeature(ctx) {
     `\n## plan.md\n${planContent}`,
   ].join('\n');
 
-  const decomposition = parseJson(await generateDocument(FEATURE_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
+  const decomposition = parseModelJson(await generateDocument(FEATURE_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
 
   // Crítica adversarial ANTES de criar qualquer issue: stories que contradizem
   // a spec/plan não devem virar trabalho. Crítica indisponível → só avisa.
@@ -283,7 +436,7 @@ async function decomposeRFC(ctx) {
     `\n## Descrição\n${issue.body || '(sem descrição)'}`,
   ].join('\n');
 
-  const decomposition = parseJson(await generateDocument(RFC_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
+  const decomposition = parseModelJson(await generateDocument(RFC_SYSTEM_PROMPT, userContent, { action: 'decompose', usage }));
   const rfcNodeId = issue.node_id;
   const tasks = decomposition.tasks || [];
   const created = [];
@@ -327,7 +480,7 @@ async function decomposeRFC(ctx) {
   console.log(`Decomposição concluída: ${created.length} tasks criadas.`);
 }
 
-export async function decompose({ issueNumber }) {
+export async function decompose({ issueNumber, force = false }) {
   const token = await resolveToken();
   // PROJECT_TOKEN deve ter scope "project" para atualizar GitHub Projects v2.
   // Fallback para GITHUB_TOKEN (só funciona em repos pessoais sem org restrictions).
@@ -366,17 +519,25 @@ export async function decompose({ issueNumber }) {
     console.warn(`Não foi possível listar sub-issues: ${err.message} — seguindo sem o guard de sub-issues.`);
     subIssues = [];
   }
-  const guard = shouldSkipDecompose({ labels: issue.labels || [], subIssues, type });
+  // Force (flag --force ou label spec-wave:force): ignora o guard e limpa a
+  // decomposição anterior antes de gerar a nova.
+  const forced = isForced({ labels: issue.labels || [], flag: force });
+  const guard = shouldSkipDecompose({ labels: issue.labels || [], subIssues, type, force: forced });
   if (guard.skip) {
     console.log(`Decompose ignorado: ${guard.reason}.`);
     await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:decompose');
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
-      `⏭️ **decompose ignorado:** ${guard.reason}. Para forçar, remova a label ` +
-      `\`${LABEL_DECOMPOSED}\` (e apague as sub-issues antigas se quiser re-gerar).`
+      `⏭️ **decompose ignorado:** ${guard.reason}.\n\n` +
+      `Para re-decompor, adicione a label \`${LABEL_FORCE}\` junto com \`spec-wave:decompose\` — ` +
+      'as sub-issues da decomposição anterior serão **fechadas** e novas serão geradas.'
     ).catch(() => {});
     return;
   }
+  // Consome a label assim que ela é lida — se o run for cancelado/morto mais
+  // adiante, ela não fica pendurada forçando silenciosamente os runs seguintes.
+  await consumeForceLabel(token, owner, repo, parseInt(issueNumber, 10));
+  if (forced) console.log(`Modo forçado ativo (${force ? 'flag --force' : `label ${LABEL_FORCE}`}).`);
 
   // Projeto + campos Etapa/Status do board (reutilizados em todos os itens).
   const { project, error: projectError } = loadProjectConfig();
@@ -399,8 +560,11 @@ export async function decompose({ issueNumber }) {
   // Coletor de uso de IA — o finally registra o custo já incorrido mesmo nos
   // fluxos que retornam cedo (ex.: abort da crítica grave) ou que falham.
   const usageEntries = [];
-  const ctx = { token, projectToken, owner, repo, issue, issueNumber, project, etapaField, statusField, usage: usageEntries };
+  const ctx = { token, projectToken, owner, repo, issue, issueNumber, type, project, etapaField, statusField, usage: usageEntries };
   try {
+    // Limpeza do re-decompose forçado ANTES de gerar: fecha as sub-issues da
+    // decomposição anterior para o board não ficar com dois conjuntos.
+    if (forced) await closeStaleSubIssues(ctx, subIssues);
     if (type === 'Feature') await decomposeFeature(ctx);
     else if (type === 'RFC') await decomposeRFC(ctx);
   } finally {