@spec-wave/cli 0.4.0 → 0.5.0

package/bin/spec-wave.mjs

@@ -136,6 +136,24 @@ program
     await decompose(options).catch(err => { console.error(err.message); process.exit(1); });
   });
 
+program
+  .command('code-review')
+  .description('Move Feature para Code Review ao abrir um PR (usado pelo GitHub Action)')
+  .requiredOption('--pr-number <n>', 'Número do Pull Request')
+  .action(async (options) => {
+    const { codeReview } = await import('../src/commands/code-review.mjs');
+    await codeReview(options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
+program
+  .command('qa')
+  .description('Move Feature para QA ao aprovar um PR (usado pelo GitHub Action)')
+  .requiredOption('--pr-number <n>', 'Número do Pull Request')
+  .action(async (options) => {
+    const { qa } = await import('../src/commands/qa.mjs');
+    await qa(options).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program
   .command('implement')
   .description('Aciona o spec-kit implement para uma Story (todas as tasks) ou uma Task')

package/package.json

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

@@ -145,6 +145,12 @@ export async function isRepoInitialized(token, owner, repo) {
   }
 }
 
+export async function getPR(token, owner, repo, prNumber) {
+  const octokit = makeOctokit(token);
+  const res = await octokit.rest.pulls.get({ owner, repo, pull_number: prNumber });
+  return res.data;
+}
+
 export async function getFileContent(token, owner, repo, path) {
   const octokit = makeOctokit(token);
   try {

package/src/commands/code-review.mjs

@@ -0,0 +1,138 @@
+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 } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { CONFIG_FILE, STATUS_OPTIONS } from '../config.mjs';
+
+// Campo "Etapa" (custom) → "👀 Code Review". Campo "Status" (nativo) → "Todo".
+const CODE_REVIEW_STAGE = STATUS_OPTIONS.find(s => s.name.includes('Code Review'))?.name;
+const TODO_STATUS = 'Todo';
+
+// Extrai números de issues referenciadas no corpo do PR (Closes #N, Fixes #N, #N solto).
+function extractIssueNumbers(body) {
+  if (!body) return [];
+  const nums = new Set();
+  const re = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
+  for (const m of body.matchAll(re)) {
+    const n = parseInt(m[1] || m[2], 10);
+    if (n) nums.add(n);
+  }
+  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;
+  try {
+    issue = await getIssue(token, owner, repo, issueNumber);
+  } catch {
+    return null;
+  }
+  const type = detectIssueType(issue);
+  if (type === 'Feature') return issue;
+  if (type !== 'Story' && type !== 'Task') return null;
+  let currentNodeId = issue.node_id;
+  for (let depth = 0; depth < 5; depth++) {
+    const parent = await getIssueParent(token, currentNodeId);
+    if (!parent) return null;
+    if (detectIssueType({ title: parent.title }) === 'Feature') {
+      return await getIssue(token, owner, repo, parent.number).catch(() => null);
+    }
+    currentNodeId = parent.nodeId;
+  }
+  return null;
+}
+
+// Move um item do board para Etapa "👀 Code Review" e Status "Todo".
+async function setCodeReview(token, project, etapaField, statusField, nodeId) {
+  const itemId = await addProjectItem(token, project.id, nodeId);
+  if (etapaField?.id && CODE_REVIEW_STAGE) {
+    const optionId = etapaField.options?.[CODE_REVIEW_STAGE];
+    if (optionId) await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
+  }
+  if (statusField?.id) {
+    const optionId = statusField.options?.[TODO_STATUS];
+    if (optionId) await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+  }
+}
+
+export async function codeReview({ prNumber }) {
+  const token = await resolveToken();
+  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+
+  if (!owner || !repo) {
+    throw new Error(
+      'GITHUB_REPOSITORY env var não definida.\n' +
+      'Este comando roda no GitHub Actions. Para testar localmente:\n' +
+      `  GITHUB_REPOSITORY=owner/repo spec-wave code-review --pr-number ${prNumber}`
+    );
+  }
+
+  const pr = await getPR(token, owner, repo, parseInt(prNumber, 10));
+  const issueNums = extractIssueNumbers(pr.body || '');
+
+  if (issueNums.length === 0) {
+    console.log('PR sem referências a issues — nenhuma Feature atualizada.');
+    return;
+  }
+
+  // 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.`);
+    return;
+  }
+
+  // Resolve campos uma vez, reutiliza em todas as Features.
+  const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+  const statusField = await resolveField(token, project, 'Status').catch(() => null);
+
+  const seen = new Set();
+  const updated = [];
+
+  for (const num of issueNums) {
+    const feature = await resolveFeatureIssue(token, owner, repo, num);
+    if (!feature || seen.has(feature.number)) continue;
+    seen.add(feature.number);
+    try {
+      await setCodeReview(token, project, etapaField, statusField, feature.node_id);
+      updated.push(`#${feature.number} ${feature.title}`);
+      console.log(`Feature #${feature.number} → "${CODE_REVIEW_STAGE}" / Status "${TODO_STATUS}".`);
+    } catch (err) {
+      console.warn(`Falha ao atualizar Feature #${feature.number}: ${err.message}`);
+    }
+  }
+
+  if (updated.length > 0) {
+    await commentOnIssue(
+      token, owner, repo, parseInt(prNumber, 10),
+      `🔍 **Code Review iniciado**\n\n` +
+      `Feature(s) movida(s) para **${CODE_REVIEW_STAGE}**:\n\n` +
+      updated.map(f => `- ${f}`).join('\n')
+    ).catch(() => {});
+  }
+
+  console.log(`code-review: ${updated.length} feature(s) atualizada(s).`);
+}

package/src/commands/decompose.mjs

@@ -1,9 +1,39 @@
 import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
 import { getIssue, createIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
-import { addSubIssue } from '../api/github-graphql.mjs';
+import { addSubIssue, addProjectItem, setItemSingleSelect, getSingleSelectField } from '../api/github-graphql.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { slugify } from '../lib/slugify.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+
+const READY_STAGE = 'Todo';
+
+// Carrega o projeto do .spec-wave.json. Retorna null se ausente ou sem project.id.
+function loadProject() {
+  const configPath = path.join(process.cwd(), CONFIG_FILE);
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf-8')).project || null;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve o campo Status do Project: usa .spec-wave.json ou consulta API.
+async function resolveStatusField(token, project) {
+  if (project.fields?.Status) return project.fields.Status;
+  return await getSingleSelectField(token, project.id, 'Status');
+}
+
+// Adiciona issue ao board e move para a etapa informada. Best-effort.
+async function moveToStage(token, project, statusField, nodeId, stageName) {
+  if (!project?.id || !statusField) return;
+  const optionId = statusField.options?.[stageName];
+  if (!statusField.id || !optionId) return;
+  const itemId = await addProjectItem(token, project.id, nodeId);
+  await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+}
 
 const SYSTEM_PROMPT = `Você é um Tech Lead experiente em decomposição de trabalho ágil.
 A partir da Feature fornecida (com spec.md e plan.md), gere uma lista de Stories e Tasks.
@@ -47,6 +77,17 @@ export async function decompose({ issueNumber }) {
 
   const issue = await getIssue(token, owner, repo, parseInt(issueNumber, 10));
   const slug = slugify(issue.title);
+
+  // Carrega projeto e resolve campo Status uma vez (reutilizado em todos os itens).
+  const project = loadProject();
+  let statusField = null;
+  if (project?.id && READY_STAGE) {
+    try {
+      statusField = await resolveStatusField(token, project);
+    } catch (err) {
+      console.warn(`Não foi possível resolver campo Status do board: ${err.message}`);
+    }
+  }
   const featureDir = `docs/features/${slug}`;
 
   const planContent = existsSync(`${featureDir}/plan.md`)
@@ -101,6 +142,13 @@ export async function decompose({ issueNumber }) {
       console.warn(`  Story #${createdStory.number} criada, mas falhou ao vincular à Feature: ${err.message}`);
     }
 
+    // Move story para Ready no board.
+    try {
+      await moveToStage(token, project, statusField, createdStory.nodeId, READY_STAGE);
+    } catch (err) {
+      console.warn(`  Falha ao mover story #${createdStory.number} para "${READY_STAGE}": ${err.message}`);
+    }
+
     for (const task of story.tasks || []) {
       console.log(`  Criando task: ${task.title}`);
       const taskTitle = `[TASK] ${task.title}`;
@@ -113,9 +161,24 @@ export async function decompose({ issueNumber }) {
       } catch (err) {
         console.warn(`    Task #${createdTask.number} criada, mas falhou ao vincular à Story: ${err.message}`);
       }
+
+      // Move task para Ready no board.
+      try {
+        await moveToStage(token, project, statusField, createdTask.nodeId, READY_STAGE);
+      } catch (err) {
+        console.warn(`    Falha ao mover task #${createdTask.number} para "${READY_STAGE}": ${err.message}`);
+      }
     }
   }
 
+  // Move a própria Feature para Ready no board.
+  try {
+    await moveToStage(token, project, statusField, featureNodeId, READY_STAGE);
+    if (project?.id && statusField) console.log(`Feature movida para "${READY_STAGE}" no board.`);
+  } catch (err) {
+    console.warn(`Falha ao mover Feature para "${READY_STAGE}": ${err.message}`);
+  }
+
   // Remove trigger label
   await removeLabel(token, owner, repo, parseInt(issueNumber, 10), 'spec-wave:decompose');
 

package/src/commands/qa.mjs

@@ -0,0 +1,131 @@
+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 } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { CONFIG_FILE, STATUS_OPTIONS } from '../config.mjs';
+
+const QA_STAGE = STATUS_OPTIONS.find(s => s.name.includes('QA'))?.name;
+const TODO_STATUS = 'Todo';
+
+function extractIssueNumbers(body) {
+  if (!body) return [];
+  const nums = new Set();
+  const re = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
+  for (const m of body.matchAll(re)) {
+    const n = parseInt(m[1] || m[2], 10);
+    if (n) nums.add(n);
+  }
+  return [...nums];
+}
+
+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);
+}
+
+async function resolveFeatureIssue(token, owner, repo, issueNumber) {
+  let issue;
+  try {
+    issue = await getIssue(token, owner, repo, issueNumber);
+  } catch {
+    return null;
+  }
+  const type = detectIssueType(issue);
+  if (type === 'Feature') return issue;
+  if (type !== 'Story' && type !== 'Task') return null;
+  let currentNodeId = issue.node_id;
+  for (let depth = 0; depth < 5; depth++) {
+    const parent = await getIssueParent(token, currentNodeId);
+    if (!parent) return null;
+    if (detectIssueType({ title: parent.title }) === 'Feature') {
+      return await getIssue(token, owner, repo, parent.number).catch(() => null);
+    }
+    currentNodeId = parent.nodeId;
+  }
+  return null;
+}
+
+async function setQA(token, project, etapaField, statusField, nodeId) {
+  const itemId = await addProjectItem(token, project.id, nodeId);
+  if (etapaField?.id && QA_STAGE) {
+    const optionId = etapaField.options?.[QA_STAGE];
+    if (optionId) await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
+  }
+  if (statusField?.id) {
+    const optionId = statusField.options?.[TODO_STATUS];
+    if (optionId) await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
+  }
+}
+
+export async function qa({ prNumber }) {
+  const token = await resolveToken();
+  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+
+  if (!owner || !repo) {
+    throw new Error(
+      'GITHUB_REPOSITORY env var não definida.\n' +
+      'Este comando roda no GitHub Actions. Para testar localmente:\n' +
+      `  GITHUB_REPOSITORY=owner/repo spec-wave qa --pr-number ${prNumber}`
+    );
+  }
+
+  const pr = await getPR(token, owner, repo, parseInt(prNumber, 10));
+  const issueNums = extractIssueNumbers(pr.body || '');
+
+  if (issueNums.length === 0) {
+    console.log('PR sem referências a issues — nenhuma Feature atualizada.');
+    return;
+  }
+
+  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.`);
+    return;
+  }
+
+  const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+  const statusField = await resolveField(token, project, 'Status').catch(() => null);
+
+  const seen = new Set();
+  const updated = [];
+
+  for (const num of issueNums) {
+    const feature = await resolveFeatureIssue(token, owner, repo, num);
+    if (!feature || seen.has(feature.number)) continue;
+    seen.add(feature.number);
+    try {
+      await setQA(token, project, etapaField, statusField, feature.node_id);
+      updated.push(`#${feature.number} ${feature.title}`);
+      console.log(`Feature #${feature.number} → "${QA_STAGE}" / Status "${TODO_STATUS}".`);
+    } catch (err) {
+      console.warn(`Falha ao atualizar Feature #${feature.number}: ${err.message}`);
+    }
+  }
+
+  if (updated.length > 0) {
+    await commentOnIssue(
+      token, owner, repo, parseInt(prNumber, 10),
+      `🧪 **PR aprovado — QA iniciado**\n\n` +
+      `Feature(s) movida(s) para **${QA_STAGE}**:\n\n` +
+      updated.map(f => `- ${f}`).join('\n')
+    ).catch(() => {});
+  }
+
+  console.log(`qa: ${updated.length} feature(s) atualizada(s).`);
+}

package/src/commands/validate.mjs

@@ -1,8 +1,54 @@
 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 { addProjectItem, setItemSingleSelect, getSingleSelectField } from '../api/github-graphql.mjs';
 import { slugify } from '../lib/slugify.mjs';
-import { REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS } from '../config.mjs';
+import { CONFIG_FILE, REQUIRED_PLAN_SECTIONS, REQUIRED_SPEC_SECTIONS } from '../config.mjs';
+
+// Opção nativa do campo Status do GitHub Projects (Todo / In Progress / Done).
+const DONE_STAGE = 'Done';
+
+// Resolve um campo SINGLE_SELECT pelo nome: usa o .spec-wave.json, cai para o
+// formato legado (etapaFieldId/stageOptions) e, por fim, consulta o Project.
+async function resolveField(token, project, name) {
+  if (project.fields && 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);
+}
+
+// Move o item da issue para a Etapa "🎉 Done" no board. Best-effort: loga e
+// segue se o .spec-wave.json não tiver o Project ou o campo não for encontrado.
+async function moveToDone(token, issue) {
+  const configPath = path.join(process.cwd(), CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    console.warn(`${CONFIG_FILE} não encontrado — status do 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}) — status do board não atualizado.`);
+    return;
+  }
+  if (!project.id) {
+    console.warn(`Project não configurado no ${CONFIG_FILE} — status do board não atualizado.`);
+    return;
+  }
+  // addProjectItem é idempotente: retorna o item existente se a issue já está no board.
+  const itemId = await addProjectItem(token, project.id, issue.node_id);
+  const field = await resolveField(token, project, 'Status');
+  const optionId = field?.options?.[DONE_STAGE];
+  if (field?.id && optionId) {
+    await setItemSingleSelect(token, project.id, itemId, field.id, optionId);
+    console.log(`Status do board atualizado para "${DONE_STAGE}".`);
+  } else {
+    console.warn(`Etapa "${DONE_STAGE}" não encontrada no Project — status do board não atualizado.`);
+  }
+}
 
 export async function validate({ issueNumber }) {
   const token = await resolveToken();
@@ -64,12 +110,22 @@ export async function validate({ issueNumber }) {
     process.exit(1);
   }
 
+  // Validação passou: move a issue para "🎉 Done" no board (best-effort).
+  let doneOk = false;
+  try {
+    await moveToDone(token, issue);
+    doneOk = !!DONE_STAGE;
+  } catch (err) {
+    console.warn(`Falha ao atualizar status do board: ${err.message}`);
+  }
+
   await commentOnIssue(
     token, owner, repo, parseInt(issueNumber, 10),
     `✅ **Validação concluída com sucesso!**\n\n` +
     `- [\`${specPath}\`](${specPath}) ✓\n` +
     `- [\`${planPath}\`](${planPath}) ✓\n\n` +
-    `A Feature está pronta para decomposição. Mova o card para **📋 Backlog Técnico** ou use:\n` +
+    (doneOk ? `Status movido para **${DONE_STAGE}**. ` : '') +
+    `A Feature está pronta para decomposição. Use:\n` +
     `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:decompose"\n\`\`\``
   );
 

package/src/config.mjs

@@ -142,6 +142,8 @@ export const WORKFLOW_FILES = [
   'generate-spec.yml',
   'validate.yml',
   'decompose.yml',
+  'code-review.yml',
+  'qa.yml',
 ];
 
 export const ISSUE_TEMPLATE_FILES = [

package/src/templates/workflows/code-review.yml

@@ -0,0 +1,26 @@
+name: Code Review
+
+on:
+  pull_request:
+    types: [opened, reopened]
+
+jobs:
+  code-review:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Move Feature to Code Review
+        run: npx @spec-wave/cli code-review --pr-number ${{ github.event.pull_request.number }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}

package/src/templates/workflows/qa.yml

@@ -0,0 +1,27 @@
+name: QA
+
+on:
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  qa:
+    if: github.event.review.state == 'approved'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Move Feature to QA
+        run: npx @spec-wave/cli qa --pr-number ${{ github.event.pull_request.number }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}