@spec-wave/cli 0.14.0 → 0.16.0

package/src/commands/move.mjs

@@ -20,7 +20,7 @@ import { loadProjectConfig, resolveField, advanceToStage, resolveStageName } fro
 import { loadConfig } from '../lib/project-root.mjs';
 import {
   CONFIG_FILE, PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
-  isManualStageType, MANUAL_STAGE_TYPES,
+  isManualStageType, MANUAL_STAGE_TYPES, isStageInTrack, STAGE_TRACKS,
 } from '../config.mjs';
 
 const PROGRESS_VALUES = [PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE];
@@ -116,6 +116,16 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
     return;
   }
 
+  // Aviso, não bloqueio: a trilha por tipo é convenção (RFC-004 §7.1); a regra
+  // dura continua sendo "a Etapa só avança". Um caso legítimo fora da trilha
+  // (um Bug que o time decidiu homologar) não deve exigir escape hatch.
+  if (type && !isStageInTrack(type, stage)) {
+    p.log.warn(
+      `${type} normalmente não passa por ${stage} — a trilha do tipo é: ` +
+      `${STAGE_TRACKS[type].join(' → ')}.`
+    );
+  }
+
   const { project, error: projectError } = loadProjectConfig({ cwd: root || process.cwd() });
   if (projectError) {
     p.log.error(`${projectError} — board não atualizado. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);

package/src/commands/qa.mjs

@@ -78,6 +78,27 @@ export async function qa({ prNumber }) {
   const updated = [];
 
   for (const num of issueNums) {
+    // Bug é unidade própria: vai para 🧪 QA sozinho, sem arrastar a Feature-pai
+    // (que pode ter Stories ainda em desenvolvimento).
+    const issue = await getIssue(token, owner, repo, num).catch(() => null);
+    if (issue && detectIssueType(issue) === 'Bug') {
+      if (seen.has(issue.number)) continue;
+      seen.add(issue.number);
+      try {
+        const moved = await advanceToStage(
+          projectToken, project, etapaField, statusField, issue.node_id, QA_STAGE, TODO_STATUS);
+        if (moved) {
+          updated.push(`#${issue.number} ${issue.title} (bug)`);
+          console.log(`Bug #${issue.number} → "${QA_STAGE}" / Status "${TODO_STATUS}".`);
+        } else {
+          console.log(`Bug #${issue.number} já está em "${QA_STAGE}" ou etapa posterior — mantido.`);
+        }
+      } catch (err) {
+        console.warn(`Falha ao atualizar Bug #${issue.number}: ${err.message}`);
+      }
+      continue;
+    }
+
     const feature = await resolveFeatureIssue(token, owner, repo, num);
     if (!feature || seen.has(feature.number)) continue;
     seen.add(feature.number);
@@ -99,10 +120,10 @@ export async function qa({ prNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(prNumber, 10),
       `🧪 **PR aprovado — QA iniciado**\n\n` +
-      `Feature(s) movida(s) para **${QA_STAGE}**:\n\n` +
+      `Item(ns) movido(s) para **${QA_STAGE}**:\n\n` +
       updated.map(f => `- ${f}`).join('\n')
     ).catch(() => {});
   }
 
-  console.log(`qa: ${updated.length} feature(s) atualizada(s).`);
+  console.log(`qa: ${updated.length} item(ns) atualizado(s).`);
 }

package/src/commands/refresh.mjs

@@ -4,20 +4,148 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { resolveToken } from '../api/auth.mjs';
-import { CONFIG_FILE } from '../config.mjs';
+import { CONFIG_FILE, STATUS_OPTIONS } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
-import { getProjectSnapshot } from '../api/github-graphql.mjs';
+import { getProjectSnapshot, updateStatusField } from '../api/github-graphql.mjs';
 
 const __dir = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
 
+/**
+ * Plano de sincronização das opções do campo "Etapa" (função PURA).
+ *
+ * A operação é DELIBERADAMENTE aditiva: `ordered` contém tudo que já existe no
+ * board mais as etapas canônicas que faltam, cada uma na posição canônica. Nada
+ * é removido — nem coluna inventada, nem etapa descontinuada.
+ *
+ * O motivo é o contrato da API: `updateProjectV2Field` SUBSTITUI o conjunto de
+ * opções do single-select, e a preservação do valor de cada item do board
+ * depende de a opção continuar existindo com o mesmo nome. Uma opção que some
+ * leva junto a Etapa de todo item que estava nela — silenciosamente. Remover
+ * coluna continua sendo trabalho manual, feito com os itens já esvaziados.
+ *
+ * @param {string[]} current nomes das opções hoje no board, na ordem atual
+ * @param {Array<{name: string, color: string}>} canonical STATUS_OPTIONS
+ * @returns {{ missing: string[], preserved: string[], ordered: Array<{name: string, color: string}> }}
+ */
+export function planStageSync(current, canonical) {
+  const have = new Set(current || []);
+  const canonicalNames = new Set(canonical.map(o => o.name));
+
+  const missing = canonical.filter(o => !have.has(o.name)).map(o => o.name);
+  // Colunas que o board tem e o fluxo canônico não conhece (inventadas ou
+  // descontinuadas). Vão para o fim, preservando a ordem relativa que tinham.
+  const preserved = (current || []).filter(name => !canonicalNames.has(name));
+
+  const ordered = [
+    ...canonical.map(o => ({ name: o.name, color: o.color })),
+    ...preserved.map(name => ({ name, color: 'GRAY' })),
+  ];
+  return { missing, preserved, ordered };
+}
+
+/**
+ * Aplica o plano de `planStageSync` no campo "Etapa" do Project.
+ *
+ * Escreve só quando há etapa canônica faltando, e verifica o resultado relendo
+ * o Project: se alguma opção que existia antes sumiu, grita — é o único jeito
+ * de o usuário descobrir a tempo que itens perderam a Etapa.
+ *
+ * @returns {Promise<boolean>} true se o comando deve continuar
+ */
+async function syncStages(token, snapshot, options) {
+  const etapa = snapshot.fields?.['Etapa'];
+  if (!etapa?.id) {
+    p.log.error('Campo "Etapa" não encontrado no Project — nada a sincronizar.');
+    process.exitCode = 1;
+    return false;
+  }
+
+  const current = Object.keys(etapa.options || {});
+  const { missing, preserved, ordered } = planStageSync(current, STATUS_OPTIONS);
+
+  if (missing.length === 0) {
+    p.log.success(`Campo "Etapa" já tem as ${STATUS_OPTIONS.length} etapas canônicas.`);
+    return true;
+  }
+
+  p.note(
+    `${chalk.green('+')} acrescentar: ${missing.join(', ')}\n` +
+    (preserved.length
+      ? `${chalk.dim('=')} preservar (fora do fluxo canônico): ${preserved.join(', ')}\n`
+      : '') +
+    `${chalk.dim('=')} preservar (canônicas já presentes): ${current.length - preserved.length}\n\n` +
+    chalk.dim(`Resultado: ${ordered.length} opções. Nenhuma é removida.`),
+    'Plano para o campo "Etapa"'
+  );
+
+  if (options.dryRun) {
+    p.outro('Dry-run: nada foi enviado ao GitHub.');
+    return false;
+  }
+
+  if (!options.yes) {
+    const go = await p.confirm({
+      message: 'Reescrever as opções do campo "Etapa" com esse conjunto?',
+      initialValue: false,
+    });
+    if (p.isCancel(go) || !go) {
+      p.outro('Cancelado — nada foi alterado.');
+      return false;
+    }
+  }
+
+  const spinner = p.spinner();
+  spinner.start('Atualizando o campo "Etapa"...');
+  try {
+    await updateStatusField(token, etapa.id, ordered);
+  } catch (err) {
+    spinner.stop('');
+    p.log.error(`Falha ao atualizar o campo "Etapa": ${err.message}`);
+    process.exitCode = 1;
+    return false;
+  }
+
+  // Verificação pós-escrita: releitura, não confiança na mutação.
+  let after;
+  try {
+    after = await getProjectSnapshot(token, snapshot.id);
+  } catch (err) {
+    spinner.stop('');
+    p.log.warn(`Campo atualizado, mas a verificação falhou: ${err.message}`);
+    return true;
+  }
+  const now = Object.keys(after?.fields?.['Etapa']?.options || {});
+  const lost = current.filter(name => !now.includes(name));
+  const stillMissing = STATUS_OPTIONS.map(o => o.name).filter(name => !now.includes(name));
+  spinner.stop(`Campo "Etapa" com ${now.length} opções.`);
+
+  if (lost.length > 0) {
+    p.log.error(
+      `Opções que existiam SUMIRAM: ${lost.join(', ')}. Os itens que estavam nelas ficaram ` +
+      'sem Etapa — recrie a coluna com o mesmo nome e reposicione os itens.'
+    );
+    process.exitCode = 1;
+    return false;
+  }
+  if (stillMissing.length > 0) {
+    p.log.warn(`Etapas canônicas ainda ausentes: ${stillMissing.join(', ')}.`);
+    return true;
+  }
+  p.log.success(`Etapas acrescentadas: ${missing.join(', ')}.`);
+  return true;
+}
+
 // Re-consulta o GitHub Project e reescreve o .spec-wave.json local com os dados
 // atuais (id/number/url/title do Project, IDs do campo Etapa e das opções, e a
 // versão da CLI). Útil para repositórios inicializados antes do enriquecimento,
 // ou quando o Project foi renomeado/teve campos alterados.
 export async function refresh(options = {}) {
-  if (!options.config) {
-    p.log.error('Nada a fazer. Use `spec-wave refresh --config` para atualizar o .spec-wave.json.');
+  if (!options.config && !options.stages) {
+    p.log.error(
+      'Nada a fazer. Use `spec-wave refresh --config` para atualizar o .spec-wave.json, ' +
+      'ou `--stages` para acrescentar as colunas canônicas que faltam no campo "Etapa".'
+    );
     process.exitCode = 1;
     return;
   }
@@ -57,7 +185,7 @@ export async function refresh(options = {}) {
     return;
   }
 
-  p.intro(chalk.bold('spec-wave refresh --config'));
+  p.intro(chalk.bold(`spec-wave refresh${options.stages ? ' --stages' : ' --config'}`));
 
   const spinner = p.spinner();
   spinner.start('Consultando o GitHub Project...');
@@ -78,6 +206,18 @@ export async function refresh(options = {}) {
   }
   spinner.stop('Project consultado.');
 
+  if (options.stages) {
+    const ok = await syncStages(token, snapshot, options);
+    if (!ok) return;
+    // Depois de mexer no board, o .spec-wave.json guarda ids de opção velhos —
+    // relê o Project para que o resto do comando grave o estado novo.
+    snapshot = await getProjectSnapshot(token, projectId);
+    if (!options.config) {
+      p.outro('Campo "Etapa" sincronizado. Rode `spec-wave refresh --config` para atualizar o .spec-wave.json.');
+      return;
+    }
+  }
+
   // Remove campos legados (versões anteriores gravavam etapaFieldId/stageOptions soltos).
   const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
   const updated = {

package/src/commands/triage.mjs

@@ -0,0 +1,174 @@
+// Triagem de Bug pela CLI (RFC-004 §4.1) — o mesmo desfecho que a tela do PM
+// oferece, para quem trabalha no terminal ou automatiza.
+//
+// Três saídas, e nenhuma delas é "editar": aceitar (→ ✅ Ready), rejeitar
+// (fecha) e duplicar (fecha, apontando a original). Corrigir o relato é
+// conversa na issue.
+//
+// Rejeitar e duplicar NÃO mexem na Etapa: ela nunca retrocede, e um bug
+// rejeitado não avançou para lugar nenhum — quem o tira das filas é o estado
+// `closed` da issue.
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { resolveToken } from '../api/auth.mjs';
+import {
+  getIssue, addLabel, removeLabel, commentOnIssue, setIssueState,
+} from '../api/github-rest.mjs';
+import { detectIssueType } from '../lib/issue-type.mjs';
+import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+import { resolveTriageAction, canAcceptBug } from '../lib/bug-triage.mjs';
+import {
+  CONFIG_FILE, STAGE_READY, PROGRESS_TODO, PRIORITY_LABELS,
+  LABEL_TRIAGED, LABEL_DUPLICATE, LABEL_WONT_FIX, labelNames,
+} from '../config.mjs';
+
+const PRIORITIES = PRIORITY_LABELS.map(l => l.name);
+
+export async function triage({ action: actionArg, issue: issueArg, reason, of, severity }) {
+  const { action, error: actionError } = resolveTriageAction(actionArg);
+  if (actionError) {
+    p.log.error(actionError);
+    process.exitCode = 1;
+    return;
+  }
+
+  const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+    p.log.error(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 42 ou #42.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (severity && !PRIORITIES.includes(severity)) {
+    p.log.error(`Severidade inválida: ${severity}. Use uma de: ${PRIORITIES.join(', ')}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
+  const { config, root } = loadConfig();
+  const owner = envOwner || config?.owner;
+  const repo = envRepo || config?.repo;
+  if (!owner || !repo) {
+    p.log.error(
+      'Não foi possível determinar owner/repo.\n' +
+      `Rode dentro de um repositório com ${CONFIG_FILE} ou defina GITHUB_REPOSITORY=owner/repo.`
+    );
+    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 triage ${action} #${issueNumber}`));
+
+  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;
+  }
+
+  if (detectIssueType(issue) !== 'Bug') {
+    p.log.error(`#${issueNumber} não é um Bug — a triagem só se aplica a defeitos.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const labels = labelNames(issue);
+  const severidadeAtual = severity || labels.find(n => PRIORITIES.includes(n)) || null;
+
+  if (action === 'accept') {
+    const { ok, error } = canAcceptBug({ severity: severidadeAtual, labels });
+    if (!ok) {
+      p.log.error(error);
+      process.exitCode = 1;
+      return;
+    }
+
+    // Reclassificação: troca a label em vez de acumular. Duas prioridades na
+    // mesma issue tornam a ordem da fila indefinida.
+    if (severity) {
+      for (const outra of PRIORITIES) {
+        if (outra !== severity) await removeLabel(token, owner, repo, issueNumber, outra).catch(() => {});
+      }
+      await addLabel(token, owner, repo, issueNumber, severity);
+      p.log.info(`Severidade → ${severity}.`);
+    }
+
+    await addLabel(token, owner, repo, issueNumber, LABEL_TRIAGED);
+    await commentOnIssue(token, owner, repo, issueNumber,
+      '**Triado:** aceito para a fila técnica.').catch(() => {});
+    await moveToReady({ token, issueNumber, issue, root });
+
+    p.outro(`${chalk.green('✓')} Bug #${issueNumber} aceito → ${STAGE_READY}.`);
+    return;
+  }
+
+  if (action === 'reject') {
+    if (!reason || !reason.trim()) {
+      p.log.error('Rejeitar exige --reason "<motivo>".');
+      process.exitCode = 1;
+      return;
+    }
+    await addLabel(token, owner, repo, issueNumber, LABEL_WONT_FIX);
+    await addLabel(token, owner, repo, issueNumber, LABEL_TRIAGED);
+    await commentOnIssue(token, owner, repo, issueNumber,
+      `**Rejeitado na triagem:** ${reason.trim()}`).catch(() => {});
+    await setIssueState(token, owner, repo, issueNumber, 'closed');
+    p.outro(`${chalk.green('✓')} Bug #${issueNumber} rejeitado e fechado.`);
+    return;
+  }
+
+  // duplicate
+  const original = parseInt(String(of || '').replace('#', ''), 10);
+  if (!Number.isInteger(original) || original <= 0) {
+    p.log.error('Marcar como duplicata exige --of <número da issue original>.');
+    process.exitCode = 1;
+    return;
+  }
+  if (original === issueNumber) {
+    p.log.error('Uma issue não pode ser duplicata de si mesma.');
+    process.exitCode = 1;
+    return;
+  }
+
+  await addLabel(token, owner, repo, issueNumber, LABEL_DUPLICATE);
+  await addLabel(token, owner, repo, issueNumber, LABEL_TRIAGED);
+  await commentOnIssue(token, owner, repo, issueNumber, `**Duplicata de #${original}.**`).catch(() => {});
+  // Comentar também na original: sem isso, quem acompanha #original não fica
+  // sabendo que há outro relato do mesmo defeito — e o contexto extra está lá.
+  await commentOnIssue(token, owner, repo, original,
+    `#${issueNumber} foi marcada como duplicata desta issue.`).catch(() => {});
+  await setIssueState(token, owner, repo, issueNumber, 'closed');
+
+  p.outro(`${chalk.green('✓')} Bug #${issueNumber} marcado como duplicata de #${original} e fechado.`);
+}
+
+async function moveToReady({ token, issueNumber, issue, root }) {
+  const { project, error } = loadProjectConfig({ cwd: root || process.cwd() });
+  if (error) {
+    p.log.warn(`${error} — board não atualizado.`);
+    return;
+  }
+  try {
+    const etapaField = await resolveField(token, project, 'Etapa').catch(() => null);
+    const statusField = await resolveField(token, project, 'Status').catch(() => null);
+    const moved = await advanceToStage(
+      token, project, etapaField, statusField, issue.node_id, STAGE_READY, PROGRESS_TODO);
+    if (!moved) {
+      p.log.info(`#${issueNumber} já está em ${STAGE_READY} ou etapa posterior — mantido.`);
+    }
+  } catch (err) {
+    p.log.warn(`Falha ao mover no board: ${err.message}`);
+  }
+}