@spec-wave/cli 0.2.0 → 0.2.1

package/bin/spec-wave.mjs

@@ -124,4 +124,15 @@ program
     await decompose(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')
+  .argument('<issue>', 'Número da issue (Story ou Task), ex.: 12 ou #12')
+  .option('--feature-dir <path>', 'Caminho do docs/features/<slug> (sobrescreve a resolução automática)')
+  .option('--dry-run', 'Monta o contexto e imprime o comando sem executar o spec-kit')
+  .action(async (issue, options) => {
+    const { implement } = await import('../src/commands/implement.mjs');
+    await implement({ issue, ...options }).catch(err => { console.error(err.message); process.exit(1); });
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-graphql.mjs

@@ -183,6 +183,56 @@ export async function addSubIssue(token, parentIssueId, childIssueId) {
   `, { issueId: parentIssueId, subIssueId: childIssueId });
 }
 
+// Lista as sub-issues de uma issue (pelo node id da issue pai). Retorna
+// [{ number, title, body, nodeId, labels: [nome...] }]. Usado pelo comando
+// `implement` para coletar as Tasks de uma Story.
+export async function listSubIssues(token, issueNodeId) {
+  const client = makeClient(token);
+  const result = await client(`
+    query SubIssues($id: ID!) {
+      node(id: $id) {
+        ... on Issue {
+          subIssues(first: 100) {
+            nodes {
+              id
+              number
+              title
+              body
+              labels(first: 20) { nodes { name } }
+            }
+          }
+        }
+      }
+    }
+  `, { id: issueNodeId });
+  const nodes = result.node?.subIssues?.nodes || [];
+  return nodes.map(n => ({
+    number: n.number,
+    title: n.title,
+    body: n.body || '',
+    nodeId: n.id,
+    labels: (n.labels?.nodes || []).map(l => l.name),
+  }));
+}
+
+// Lê o parent (issue pai) de uma sub-issue. Retorna { number, title, nodeId }
+// ou null se a issue não tiver pai. Usado para subir a cadeia Task→Story→Feature.
+export async function getIssueParent(token, issueNodeId) {
+  const client = makeClient(token);
+  const result = await client(`
+    query IssueParent($id: ID!) {
+      node(id: $id) {
+        ... on Issue {
+          parent { id number title }
+        }
+      }
+    }
+  `, { id: issueNodeId });
+  const parent = result.node?.parent;
+  if (!parent) return null;
+  return { number: parent.number, title: parent.title, nodeId: parent.id };
+}
+
 // Define o valor de um campo SINGLE_SELECT para um item do Project.
 export async function setItemSingleSelect(token, projectId, itemId, fieldId, optionId) {
   const client = makeClient(token);

package/src/commands/decompose.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { execFileSync } from 'node:child_process';
 import { resolveToken } from '../api/auth.mjs';
-import { getIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
+import { getIssue, createIssue, removeLabel, commentOnIssue } from '../api/github-rest.mjs';
+import { addSubIssue } from '../api/github-graphql.mjs';
 import { generateDocument } from '../lib/claude.mjs';
 import { slugify } from '../lib/slugify.mjs';
 
@@ -12,11 +12,12 @@ Responda APENAS com JSON válido neste formato:
 {
   "stories": [
     {
-      "title": "[STORY] Título da story no formato 'Como <perfil>, quero <objetivo>, para <benefício>'",
-      "body": "Descrição da story com contexto e critérios de aceite relevantes",
+      "title": "Título curto da story (apenas a parte 'quero', sem prefixo)",
+      "userStory": "Como <perfil>, quero <objetivo>, para <benefício>",
+      "body": "Descrição complementar da story com contexto e critérios de aceite relevantes",
       "tasks": [
         {
-          "title": "[TASK] Título técnico da task",
+          "title": "Título técnico curto da task (sem prefixo)",
           "body": "Descrição técnica detalhada"
         }
       ]
@@ -25,9 +26,11 @@ Responda APENAS com JSON válido neste formato:
 }
 
 Regras:
+- "title" deve ser CURTO (máx. ~60 caracteres): apenas a parte "quero" da user story, sem o "Como" nem o "para", e sem prefixo. Ex.: "visualizar meus repositórios em layout responsivo"
+- "userStory" deve trazer a user story completa no formato "Como <perfil>, quero <objetivo>, para <benefício>"
+- "body" é texto complementar (contexto, critérios de aceite); não repita o título
 - Cada Story deve ter 2–5 Tasks associadas
-- Stories devem seguir o formato de User Story
-- Tasks devem ser atividades técnicas concretas
+- Tasks devem ser atividades técnicas concretas, com "title" curto e "body" detalhado
 - Gere entre 3 e 7 Stories por Feature`;
 
 export async function decompose({ issueNumber }) {
@@ -75,26 +78,41 @@ export async function decompose({ issueNumber }) {
     decomposition = JSON.parse(jsonMatch[0]);
   }
 
+  // node id da Feature — necessário para vincular as stories como sub-issues.
+  const featureNodeId = issue.node_id;
+
   const created = [];
 
   for (const story of decomposition.stories) {
     console.log(`Criando story: ${story.title}`);
-    const storyOutput = execFileSync(
-      'gh',
-      ['issue', 'create', '--title', story.title, '--body', story.body, '--label', '[STORY]'],
-      { encoding: 'utf-8' }
-    ).trim();
-    const storyUrl = storyOutput.trim();
-    created.push({ type: 'story', title: story.title, url: storyUrl });
+    const storyTitle = `[STORY] ${story.title}`;
+    // Corpo: user story completa (Como/quero/para) + texto complementar.
+    const storyBody = [story.userStory, story.body]
+      .map(s => (s || '').trim())
+      .filter(Boolean)
+      .join('\n\n') || '_(sem descrição)_';
+    const createdStory = await createIssue(token, owner, repo, storyTitle, storyBody, ['[STORY]']);
+    created.push({ type: 'story', title: storyTitle, url: createdStory.url });
+
+    // Vincula a story como sub-issue da Feature (relação nativa do GitHub).
+    try {
+      await addSubIssue(token, featureNodeId, createdStory.nodeId);
+    } catch (err) {
+      console.warn(`  Story #${createdStory.number} criada, mas falhou ao vincular à Feature: ${err.message}`);
+    }
 
     for (const task of story.tasks || []) {
       console.log(`  Criando task: ${task.title}`);
-      const taskBody = `${task.body}\n\n_Story pai: ${storyUrl}_`;
-      execFileSync(
-        'gh',
-        ['issue', 'create', '--title', task.title, '--body', taskBody, '--label', '[TASK]'],
-        { encoding: 'utf-8' }
-      );
+      const taskTitle = `[TASK] ${task.title}`;
+      const taskBody = `${task.body}\n\n_Story pai: ${createdStory.url}_`;
+      const createdTask = await createIssue(token, owner, repo, taskTitle, taskBody, ['[TASK]']);
+
+      // Vincula a task como sub-issue da Story.
+      try {
+        await addSubIssue(token, createdStory.nodeId, createdTask.nodeId);
+      } catch (err) {
+        console.warn(`    Task #${createdTask.number} criada, mas falhou ao vincular à Story: ${err.message}`);
+      }
     }
   }
 

package/src/commands/implement.mjs

@@ -0,0 +1,222 @@
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+import { resolveToken } from '../api/auth.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+import { getIssue } from '../api/github-rest.mjs';
+import { listSubIssues, getIssueParent } from '../api/github-graphql.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { slugify } from '../lib/slugify.mjs';
+
+// Diretório onde montamos o arquivo de contexto entregue ao spec-kit.
+const WORK_DIR = '.spec-wave';
+
+// Sobe a cadeia de pais (Task → Story → Feature) até achar uma issue do tipo
+// "Feature" e devolve seu título (para resolver docs/features/<slug>). Limita a
+// profundidade para evitar loops em dados inconsistentes.
+async function resolveFeatureTitle(token, startNodeId) {
+  let current = startNodeId;
+  for (let depth = 0; depth < 5 && current; depth++) {
+    const parent = await getIssueParent(token, current);
+    if (!parent) return null;
+    if (detectIssueType({ title: parent.title }) === 'Feature') return parent.title;
+    current = parent.nodeId;
+  }
+  return null;
+}
+
+// Lê spec.md/plan.md de um docs/features/<slug> se existirem.
+function readSpecPlan(featureDir) {
+  const specPath = path.join(featureDir, 'spec.md');
+  const planPath = path.join(featureDir, 'plan.md');
+  return {
+    specPath,
+    planPath,
+    spec: existsSync(specPath) ? readFileSync(specPath, 'utf-8') : null,
+    plan: existsSync(planPath) ? readFileSync(planPath, 'utf-8') : null,
+  };
+}
+
+// Monta o markdown de contexto que será entregue ao spec-kit implement.
+function buildContext({ type, issue, tasks, spec, plan, specPath, planPath }) {
+  const lines = [];
+  lines.push(`# Contexto de implementação — ${type} #${issue.number}`);
+  lines.push('');
+  lines.push(`**${type}:** ${issue.title}`);
+  if (issue.body && issue.body.trim()) {
+    lines.push('');
+    lines.push(issue.body.trim());
+  }
+
+  lines.push('');
+  lines.push(`## Tasks a implementar (${tasks.length})`);
+  for (const t of tasks) {
+    lines.push('');
+    lines.push(`### #${t.number} ${t.title}`);
+    if (t.body && t.body.trim()) lines.push(t.body.trim());
+  }
+
+  if (spec) {
+    lines.push('');
+    lines.push(`## spec.md (${specPath})`);
+    lines.push(spec.trim());
+  }
+  if (plan) {
+    lines.push('');
+    lines.push(`## plan.md (${planPath})`);
+    lines.push(plan.trim());
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+// Substitui os placeholders do template de comando do spec-kit.
+function renderCommand(template, vars) {
+  return template.replace(/\{(\w+)\}/g, (m, key) => (key in vars ? vars[key] : m));
+}
+
+export async function implement({ issue: issueArg, featureDir: featureDirOpt, dryRun }) {
+  const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
+  if (!Number.isInteger(issueNumber)) {
+    p.log.error(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 12 ou #12.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // 1. Config local (.spec-wave.json) — owner/repo e bloco opcional specKit.
+  const configPath = path.join(process.cwd(), CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    p.log.error(`Repositório não inicializado (sem ${CONFIG_FILE}). Rode \`spec-wave init\` primeiro.`);
+    process.exitCode = 1;
+    return;
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf-8'));
+  } catch (err) {
+    p.log.error(`${CONFIG_FILE} corrompido: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const { owner, repo } = config;
+  if (!owner || !repo) {
+    p.log.error(`${CONFIG_FILE} não contém owner/repo. Rode \`spec-wave init\` novamente.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let token;
+  try {
+    token = await resolveToken();
+  } catch (err) {
+    p.log.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.intro(chalk.bold(`spec-wave implement #${issueNumber}`));
+
+  // 2. Lê a issue alvo.
+  let issue;
+  try {
+    issue = await getIssue(token, owner, repo, issueNumber);
+  } catch (err) {
+    p.log.error(`Não foi possível ler a issue #${issueNumber}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // 3. Detecta o tipo e monta a lista de tasks.
+  const type = detectIssueType(issue);
+  let tasks;
+  if (type === 'Story') {
+    const subs = await listSubIssues(token, issue.node_id);
+    tasks = subs.filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Task');
+    if (tasks.length === 0) {
+      p.log.error(`Story #${issueNumber} não tem Tasks (sub-issues) para implementar.`);
+      process.exitCode = 1;
+      return;
+    }
+    p.log.info(`Story com ${tasks.length} task(s): ${tasks.map(t => `#${t.number}`).join(', ')}`);
+  } else if (type === 'Task') {
+    tasks = [{ number: issue.number, title: issue.title, body: issue.body || '' }];
+    p.log.info(`Task única #${issueNumber}.`);
+  } else {
+    p.log.error(
+      `implement só aceita Story ou Task. Issue #${issueNumber} é do tipo ${type || 'desconhecido'}.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // 4. Resolve spec.md/plan.md da Feature (enriquecimento opcional).
+  let featureDir = featureDirOpt;
+  if (!featureDir) {
+    const featureTitle = await resolveFeatureTitle(token, issue.node_id);
+    if (featureTitle) featureDir = path.join('docs', 'features', slugify(featureTitle));
+  }
+  let specPlan = { spec: null, plan: null, specPath: null, planPath: null };
+  if (featureDir && existsSync(featureDir)) {
+    specPlan = readSpecPlan(featureDir);
+  } else if (featureDir) {
+    p.log.warn(`Diretório da feature não encontrado (${featureDir}); seguindo só com as tasks.`);
+  } else {
+    p.log.warn('Não foi possível resolver a Feature; seguindo só com as tasks (use --feature-dir).');
+  }
+
+  // 5. Monta e grava o arquivo de contexto.
+  const context = buildContext({ type, issue, tasks, ...specPlan });
+  mkdirSync(WORK_DIR, { recursive: true });
+  const tasksFile = path.join(WORK_DIR, `implement-${issueNumber}.md`);
+  writeFileSync(tasksFile, context);
+  p.log.success(`Contexto montado em ${chalk.cyan(tasksFile)}.`);
+
+  // 6. Aciona o spec-kit (comando configurável).
+  const template = process.env.SPEC_WAVE_IMPLEMENT_CMD || config.specKit?.command;
+  const vars = {
+    tasksFile,
+    specFile: specPlan.specPath || '',
+    planFile: specPlan.planPath || '',
+    issue: String(issueNumber),
+    type,
+    title: issue.title,
+  };
+
+  if (!template) {
+    p.log.warn('Comando do spec-kit não configurado.');
+    p.note(
+      `Configure em ${CONFIG_FILE}:\n` +
+      `  "specKit": { "command": "<comando do spec-kit com placeholders>" }\n` +
+      'ou defina a env SPEC_WAVE_IMPLEMENT_CMD.\n\n' +
+      'Placeholders: {tasksFile} {specFile} {planFile} {issue} {type} {title}',
+      'Como acionar o spec-kit'
+    );
+    p.outro(`Contexto pronto em ${tasksFile}. Acione o spec-kit manualmente com esse arquivo.`);
+    return;
+  }
+
+  const command = renderCommand(template, vars);
+
+  if (dryRun) {
+    p.note(command, 'Comando que seria executado (--dry-run)');
+    p.outro(`Dry-run: nada executado. Contexto em ${tasksFile}.`);
+    return;
+  }
+
+  p.log.step(`Executando: ${chalk.dim(command)}`);
+  try {
+    execSync(command, { stdio: 'inherit' });
+  } catch (err) {
+    p.log.error(`spec-kit implement falhou: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  p.outro(
+    `${chalk.green('✓')} Implementação acionada para ${type} #${issueNumber}.\n` +
+    '  Próximo: revise as mudanças, abra o PR e mova o card para 👀 Code Review.'
+  );
+}

package/src/lib/issue-type.mjs

@@ -0,0 +1,37 @@
+import { TYPE_LABELS } from '../config.mjs';
+
+// Mapa de prefixo de label (ex.: "[STORY]") → nome canônico do tipo ("Story").
+// Derivado de TYPE_LABELS para manter uma única fonte da verdade.
+const TAG_TO_TYPE = Object.fromEntries(
+  TYPE_LABELS.map(l => [l.name.toUpperCase(), capitalize(l.name.replace(/[[\]]/g, ''))])
+);
+
+function capitalize(s) {
+  const lower = s.toLowerCase();
+  // RFC fica em caixa alta; os demais tipos seguem Capitalizado (Story, Task...).
+  return lower === 'rfc' ? 'RFC' : lower.charAt(0).toUpperCase() + lower.slice(1);
+}
+
+// Detecta o tipo canônico de uma issue ('Story', 'Task', 'Feature', ...) a partir
+// do prefixo do título ([STORY], [TASK], ...) com fallback nas labels. Retorna
+// null quando não é possível determinar.
+export function detectIssueType(issue) {
+  if (!issue) return null;
+
+  // 1. Prefixo do título: "[STORY] ..." → "Story".
+  const titleMatch = String(issue.title || '').match(/^\s*(\[[^\]]+\])/);
+  if (titleMatch) {
+    const type = TAG_TO_TYPE[titleMatch[1].toUpperCase()];
+    if (type) return type;
+  }
+
+  // 2. Fallback: varrer as labels da issue procurando um dos prefixos de tipo.
+  const labels = Array.isArray(issue.labels) ? issue.labels : [];
+  for (const label of labels) {
+    const name = (typeof label === 'string' ? label : label?.name) || '';
+    const type = TAG_TO_TYPE[name.toUpperCase()];
+    if (type) return type;
+  }
+
+  return null;
+}