@spec-wave/cli 0.5.11 → 0.7.0

package/bin/spec-wave.mjs

@@ -193,4 +193,41 @@ program
     await implement({ issue, ...options }).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('order')
+  .description('Ordena as Stories de uma Feature pelas dependências (topológica)')
+  .argument('<feature>', 'Número da issue da Feature, ex.: 12 ou #12')
+  .action(async (feature) => {
+    const { order } = await import('../src/commands/order.mjs');
+    await order({ feature }).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)')
+  .argument('<action>', 'Ação: start ou done')
+  .argument('<n>', 'Número da issue da Task, ex.: 12 ou #12')
+  .action(async (action, n) => {
+    const { task } = await import('../src/commands/task.mjs');
+    await task({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
+program
+  .command('story')
+  .description('Gerencia uma Story no board: review (move para Code Review)')
+  .argument('<action>', 'Ação: review')
+  .argument('<n>', 'Número da issue da Story, ex.: 12 ou #12')
+  .action(async (action, n) => {
+    const { story } = await import('../src/commands/story.mjs');
+    await story({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
+program
+  .command('doctor')
+  .description('Diagnostica a configuração do spec-wave no repositório atual')
+  .action(async () => {
+    const { doctor } = await import('../src/commands/doctor.mjs');
+    await doctor().catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.5.11",
+  "version": "0.7.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {
@@ -13,6 +13,9 @@
     "bin",
     "src"
   ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "engines": {
     "node": ">=20"
   },

package/src/api/github-rest.mjs

@@ -87,10 +87,12 @@ export async function upsertFile(token, owner, repo, path, content, message) {
   });
 }
 
+// `id` é o database id da issue — exigido pela API de dependências
+// (blocked_by), que não aceita number nem node id.
 export async function createIssue(token, owner, repo, title, body, labels) {
   const octokit = makeOctokit(token);
   const res = await octokit.rest.issues.create({ owner, repo, title, body, labels });
-  return { number: res.data.number, nodeId: res.data.node_id, url: res.data.html_url };
+  return { number: res.data.number, nodeId: res.data.node_id, url: res.data.html_url, id: res.data.id };
 }
 
 export async function getIssue(token, owner, repo, issueNumber) {
@@ -148,6 +150,48 @@ export async function removeLabel(token, owner, repo, issueNumber, labelName) {
   }
 }
 
+// Lista todos os comentários de uma issue/PR: [{ author, body, createdAt }].
+// Paginado — traz o histórico completo (usado pela crítica adversarial).
+export async function listIssueComments(token, owner, repo, issueNumber) {
+  const octokit = makeOctokit(token);
+  const comments = await octokit.paginate(octokit.rest.issues.listComments, {
+    owner,
+    repo,
+    issue_number: issueNumber,
+    per_page: 100,
+  });
+  return comments.map(c => ({
+    author: c.user?.login || '',
+    body: c.body || '',
+    createdAt: c.created_at,
+  }));
+}
+
+// Marca uma issue como bloqueada por outra (relação nativa do GitHub).
+// `blockingIssueId` é o DATABASE id da issue bloqueadora (não o number nem o
+// node id — ver createIssue). Erros propagam: o chamador usa como fallback.
+export async function addBlockedBy(token, owner, repo, issueNumber, blockingIssueId) {
+  const octokit = makeOctokit(token);
+  await octokit.request('POST /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by', {
+    owner,
+    repo,
+    issue_number: issueNumber,
+    issue_id: blockingIssueId,
+  });
+}
+
+// Lista as issues que bloqueiam `issueNumber`: [{ number, title, state, id }].
+export async function listBlockedBy(token, owner, repo, issueNumber) {
+  const octokit = makeOctokit(token);
+  const issues = await octokit.paginate('GET /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by', {
+    owner,
+    repo,
+    issue_number: issueNumber,
+    per_page: 100,
+  });
+  return issues.map(i => ({ number: i.number, title: i.title, state: i.state, id: i.id }));
+}
+
 export async function commentOnIssue(token, owner, repo, issueNumber, body) {
   const octokit = makeOctokit(token);
   await octokit.rest.issues.createComment({

package/src/commands/code-review.mjs

@@ -2,13 +2,17 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, getPR, commentOnIssue } from '../api/github-rest.mjs';
-import { addProjectItem, setItemSingleSelect, getSingleSelectField, getIssueParent, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
+import { addProjectItem, getIssueParent, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
-import { CONFIG_FILE, STATUS_OPTIONS, STAGE_ORDER, PROGRESS_TODO } from '../config.mjs';
+import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
+import { CONFIG_FILE, STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType } from '../config.mjs';
 
-// Campo "Etapa" (custom) → "👀 Code Review". Campo "Status" (nativo) → "Todo".
+// Ao abrir o PR: Stories/Feature → Etapa "👀 Code Review" (Status "Todo");
+// Tasks → Etapa "🎉 Done" (Status "Done"), pois a implementação da task terminou.
 const CODE_REVIEW_STAGE = STATUS_OPTIONS.find(s => s.name.includes('Code Review'))?.name;
+const DONE_STAGE = STAGE_DONE;
 const TODO_STATUS = PROGRESS_TODO;
+const DONE_STATUS = PROGRESS_DONE;
 
 // Extrai números de issues referenciadas no corpo do PR (Closes #N, Fixes #N, #N solto).
 function extractIssueNumbers(body) {
@@ -22,15 +26,6 @@ function extractIssueNumbers(body) {
   return [...nums];
 }
 
-// Resolve o campo SINGLE_SELECT pelo nome: usa .spec-wave.json, legado ou API.
-async function resolveField(token, project, name) {
-  if (project.fields?.[name]) return project.fields[name];
-  if (name === 'Etapa' && project.etapaFieldId) {
-    return { id: project.etapaFieldId, options: project.stageOptions || {} };
-  }
-  return await getSingleSelectField(token, project.id, name);
-}
-
 // A partir de qualquer issue (Feature/Story/Task), sobe a hierarquia e retorna a Feature.
 async function resolveFeatureIssue(token, owner, repo, issueNumber) {
   let issue;
@@ -54,47 +49,52 @@ async function resolveFeatureIssue(token, owner, repo, issueNumber) {
   return null;
 }
 
-// Coleta a "unidade de review" de uma issue referenciada no PR. Separa a
-// Feature dos demais itens, porque a Feature tem regra própria (só avança
-// quando TODAS as suas Stories estiverem em Code Review). Retorna
-// { feature: {number,nodeId,title}|null, items: Map(number -> {nodeId,title}) }
-// onde `items` são as Stories + Tasks que andam juntas neste PR.
+// Coleta a "unidade de review" de uma issue referenciada no PR, separando por
+// tipo porque cada um tem destino próprio: Tasks → Done, Stories → Code Review,
+// Feature → Code Review (só quando todas as Stories estiverem prontas). Retorna
+// { feature:{number,nodeId,title}|null, stories:Map, tasks:Map }.
 async function collectReviewUnit(token, owner, repo, issueNumber) {
-  const items = new Map();
-  const add = (n, nodeId, title) => { if (n && nodeId && !items.has(n)) items.set(n, { nodeId, title }); };
+  const stories = new Map();
+  const tasks = new Map();
+  const addStory = (n, nodeId, title) => { if (n && nodeId && !stories.has(n)) stories.set(n, { nodeId, title }); };
+  const addTask = (n, nodeId, title) => { if (n && nodeId && !tasks.has(n)) tasks.set(n, { nodeId, title }); };
 
   let issue;
-  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return { feature: null, items }; }
+  try { issue = await getIssue(token, owner, repo, issueNumber); } catch { return { feature: null, stories, tasks }; }
   const type = detectIssueType(issue);
-  if (type !== 'Feature' && type !== 'Story' && type !== 'Task') return { feature: null, items };
+  if (type !== 'Feature' && type !== 'Story' && type !== 'Task') return { feature: null, stories, tasks };
 
   const featureIssue = await resolveFeatureIssue(token, owner, repo, issueNumber);
   const feature = featureIssue
     ? { number: featureIssue.number, nodeId: featureIssue.node_id, title: featureIssue.title }
     : null;
 
+  // Spikes (tipos manuais) nunca são movidos automaticamente — pulados aqui.
+  const isManual = (sub) => isManualStageType(detectIssueType({ title: sub.title, labels: sub.labels }));
+
   if (type === 'Feature') {
     // Referência direta à Feature: toda a subárvore (Stories + Tasks).
-    const stories = await listSubIssues(token, issue.node_id).catch(() => []);
-    for (const st of stories) {
-      add(st.number, st.nodeId, st.title);
-      const tasks = await listSubIssues(token, st.nodeId).catch(() => []);
-      for (const t of tasks) add(t.number, t.nodeId, t.title);
+    const subs = await listSubIssues(token, issue.node_id).catch(() => []);
+    for (const st of subs) {
+      if (isManual(st)) continue;
+      addStory(st.number, st.nodeId, st.title);
+      const tks = await listSubIssues(token, st.nodeId).catch(() => []);
+      for (const t of tks) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
     }
   } else if (type === 'Story') {
-    add(issue.number, issue.node_id, issue.title);
-    const tasks = await listSubIssues(token, issue.node_id).catch(() => []);
-    for (const t of tasks) add(t.number, t.nodeId, t.title);
+    addStory(issue.number, issue.node_id, issue.title);
+    const tks = await listSubIssues(token, issue.node_id).catch(() => []);
+    for (const t of tks) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
   } else { // Task → inclui a Story pai e as Tasks irmãs.
-    add(issue.number, issue.node_id, issue.title);
+    addTask(issue.number, issue.node_id, issue.title);
     const parent = await getIssueParent(token, issue.node_id).catch(() => null);
     if (parent && detectIssueType({ title: parent.title }) === 'Story') {
-      add(parent.number, parent.nodeId, parent.title);
-      const tasks = await listSubIssues(token, parent.nodeId).catch(() => []);
-      for (const t of tasks) add(t.number, t.nodeId, t.title);
+      addStory(parent.number, parent.nodeId, parent.title);
+      const tks = await listSubIssues(token, parent.nodeId).catch(() => []);
+      for (const t of tks) { if (isManual(t)) continue; addTask(t.number, t.nodeId, t.title); }
     }
   }
-  return { feature, items };
+  return { feature, stories, tasks };
 }
 
 // A Feature só avança quando TODAS as suas Stories já estiverem em Code Review
@@ -114,31 +114,6 @@ async function allStoriesReadyForReview(readToken, projToken, project, etapaFiel
   return true;
 }
 
-// Avança um item do board para a Etapa "👀 Code Review" e reinicia o Status
-// (nativo) para "Todo". Uma issue só AVANÇA: se já estiver em Code Review ou em
-// uma etapa posterior, não é tocada (retorna false). Retorna true se avançou.
-async function setCodeReview(token, project, etapaField, statusField, nodeId) {
-  const itemId = await addProjectItem(token, project.id, nodeId);
-
-  if (etapaField?.id && CODE_REVIEW_STAGE) {
-    // Nunca retroceder: compara a etapa atual com a de destino na ordem canônica.
-    const current = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
-    const curIdx = current ? STAGE_ORDER.indexOf(current) : -1;
-    const tgtIdx = STAGE_ORDER.indexOf(CODE_REVIEW_STAGE);
-    if (curIdx !== -1 && tgtIdx !== -1 && curIdx >= tgtIdx) {
-      return false; // já está em Code Review ou adiante — não retrocede
-    }
-    const optionId = etapaField.options?.[CODE_REVIEW_STAGE];
-    if (optionId) await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
-  }
-  // Ao avançar de etapa, o Status reinicia em "Todo".
-  if (statusField?.id) {
-    const optionId = statusField.options?.[TODO_STATUS];
-    if (optionId) await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
-  }
-  return true;
-}
-
 export async function codeReview({ prNumber }) {
   const token = await resolveToken();
   const projectToken = process.env.PROJECT_TOKEN || token;
@@ -165,20 +140,9 @@ export async function codeReview({ prNumber }) {
   }
 
   // Carrega projeto do .spec-wave.json
-  const configPath = path.join(process.cwd(), CONFIG_FILE);
-  if (!existsSync(configPath)) {
-    console.warn(`${CONFIG_FILE} não encontrado — board não atualizado.`);
-    return;
-  }
-  let project;
-  try {
-    project = JSON.parse(readFileSync(configPath, 'utf-8')).project || {};
-  } catch (err) {
-    console.warn(`${CONFIG_FILE} corrompido (${err.message}) — board não atualizado.`);
-    return;
-  }
-  if (!project.id) {
-    console.warn(`Project não configurado em ${CONFIG_FILE} — board não atualizado.`);
+  const { project, error: projectError } = loadProjectConfig();
+  if (projectError) {
+    console.warn(`${projectError} — board não atualizado.`);
     return;
   }
 
@@ -190,18 +154,37 @@ export async function codeReview({ prNumber }) {
   const updated = [];
   const featuresChecked = new Set();
 
-  // Para cada issue referenciada: move a Story + Tasks para Code Review. A
-  // Feature só avança quando TODAS as suas Stories já estiverem em Code Review.
+  // Regras ao abrir o PR: Tasks → 🎉 Done (implementação concluída);
+  // Stories → 👀 Code Review; Feature → Code Review só quando TODAS as suas
+  // Stories já estiverem em Code Review.
   for (const num of issueNums) {
-    const { feature, items } = await collectReviewUnit(token, owner, repo, num);
+    const { feature, stories, tasks } = await collectReviewUnit(token, owner, repo, num);
+
+    // Tasks → Done (Status Done).
+    for (const [n, info] of tasks) {
+      if (seen.has(n)) continue;
+      seen.add(n);
+      try {
+        const moved = await advanceToStage(projectToken, project, etapaField, statusField, info.nodeId, DONE_STAGE, DONE_STATUS);
+        if (moved) {
+          updated.push(`#${n} ${info.title} → ${DONE_STAGE}`);
+          console.log(`#${n} → "${DONE_STAGE}" / Status "${DONE_STATUS}".`);
+        } else {
+          console.log(`#${n} já está em "${DONE_STAGE}" ou etapa posterior — mantido (não retrocede).`);
+        }
+      } catch (err) {
+        console.warn(`Falha ao atualizar #${n}: ${err.message}`);
+      }
+    }
 
-    for (const [n, info] of items) {
+    // Stories → Code Review (Status Todo).
+    for (const [n, info] of stories) {
       if (seen.has(n)) continue;
       seen.add(n);
       try {
-        const moved = await setCodeReview(projectToken, project, etapaField, statusField, info.nodeId);
+        const moved = await advanceToStage(projectToken, project, etapaField, statusField, info.nodeId, CODE_REVIEW_STAGE, TODO_STATUS);
         if (moved) {
-          updated.push(`#${n} ${info.title}`);
+          updated.push(`#${n} ${info.title} → ${CODE_REVIEW_STAGE}`);
           console.log(`#${n} → "${CODE_REVIEW_STAGE}" / Status "${TODO_STATUS}".`);
         } else {
           console.log(`#${n} já está em "${CODE_REVIEW_STAGE}" ou etapa posterior — mantido (não retrocede).`);
@@ -220,9 +203,9 @@ export async function codeReview({ prNumber }) {
           console.log(`Feature #${feature.number} mantida em desenvolvimento — ainda há Stories pendentes (fora de "${CODE_REVIEW_STAGE}").`);
         } else if (!seen.has(feature.number)) {
           seen.add(feature.number);
-          const moved = await setCodeReview(projectToken, project, etapaField, statusField, feature.nodeId);
+          const moved = await advanceToStage(projectToken, project, etapaField, statusField, feature.nodeId, CODE_REVIEW_STAGE, TODO_STATUS);
           if (moved) {
-            updated.push(`#${feature.number} ${feature.title} (Feature)`);
+            updated.push(`#${feature.number} ${feature.title} (Feature) → ${CODE_REVIEW_STAGE}`);
             console.log(`Feature #${feature.number} → "${CODE_REVIEW_STAGE}" (todas as Stories concluídas).`);
           } else {
             console.log(`Feature #${feature.number} já está em "${CODE_REVIEW_STAGE}" ou etapa posterior.`);
@@ -238,10 +221,10 @@ export async function codeReview({ prNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(prNumber, 10),
       `🔍 **Code Review iniciado**\n\n` +
-      `Movidos para **${CODE_REVIEW_STAGE}** (a Feature só avança quando todas as suas Stories concluírem):\n\n` +
+      `Board atualizado (Tasks → **${DONE_STAGE}**; Story → **${CODE_REVIEW_STAGE}**; Feature só avança quando todas as Stories concluírem):\n\n` +
       updated.map(f => `- ${f}`).join('\n')
     ).catch(() => {});
   }
 
-  console.log(`code-review: ${updated.length} item(ns) movido(s) para "${CODE_REVIEW_STAGE}".`);
+  console.log(`code-review: ${updated.length} item(ns) atualizado(s) no board.`);
 }