@spec-wave/cli 0.23.0 → 0.25.0

package/src/commands/doctor.mjs

@@ -13,13 +13,16 @@ import {
   tokenMismatchWarning, parseActiveAccount,
 } from '../api/auth.mjs';
 import { getProjectSnapshot, listSubIssues } from '../api/github-graphql.mjs';
+import { getRepoVariable } from '../api/github-rest.mjs';
 import {
-  CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, STATUS_OPTIONS,
+  CONFIG_FILE, WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER, AI_PROVIDERS, STATUS_OPTIONS,
   RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, MODEL_LABEL_PREFIX,
   DEFAULT_MAX_CRITIQUE_ATTEMPTS, STAGE_TRACKS, AI_ACTIONS, recommendedModelAliases,
   modelLabels,
 } from '../config.mjs';
 import { findConfigPath } from '../lib/project-root.mjs';
+import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
+import { unguardedWorkflows } from './mode.mjs';
 import {
   DEFAULT_MAX_TOKENS, supportsStrictSchema, resolveAiConfig,
 } from '../lib/claude.mjs';
@@ -679,8 +682,9 @@ async function checkAi(ctx) {
       `${Object.entries(aliases).map(([a, m]) => `${a}=${m}`).join(', ')}.`
     );
     // Slug da OpenRouter tem "/" (anthropic/claude-…); id da Anthropic, não.
+    // O critério é o BACKEND: `claude-oauth` fala com a mesma API do `anthropic`.
     const wrongShape = Object.entries(aliases).filter(([, m]) => (
-      provider.value === 'openrouter' ? !String(m).includes('/') : String(m).includes('/')
+      provider.backend === 'openrouter' ? !String(m).includes('/') : String(m).includes('/')
     ));
     if (wrongShape.length > 0) {
       status = 'warn';
@@ -700,7 +704,7 @@ async function checkAi(ctx) {
 
   // Saída estruturada da crítica: sem structured output confiável, a validação
   // do schema queima os retries antes de falhar.
-  if (provider.value === 'openrouter' && !fileAi.models?.critique) {
+  if (provider.backend === 'openrouter' && !fileAi.models?.critique) {
     status = 'warn';
     notes.push(
       `Saída estruturada da crítica: o provider é openrouter e \`ai.models.critique\` não está ` +
@@ -708,21 +712,27 @@ async function checkAi(ctx) {
       'e a crítica falha na primeira execução. Aponte `ai.models.critique` para um modelo com ' +
       'saída estruturada.'
     );
+  } else if (provider.backend === 'anthropic') {
+    // No backend anthropic quem garante o schema é o próprio Claude Code
+    // (`outputFormat: json_schema`), repetindo o turno até casar — não há
+    // tool call forçado nem `strict` de endpoint para reportar.
+    notes.push(
+      `Saída estruturada da crítica: json_schema do Claude Code (${provider.value}) ` +
+      '— o CLI repete o turno até a resposta casar com o schema.'
+    );
   } else {
     notes.push(
       `Saída estruturada da crítica: tool call forçado (${provider.value}) ` +
       `· strict=${supportsStrictSchema(critiqueModel) ? 'sim' : 'não'} neste modelo.`
     );
   }
-  // O backend anthropic não chama a API — sobe o Claude Code CLI como
-  // subprocesso, que não existe no runner dos workflows (só há setup-node).
-  if (provider.value === 'anthropic') {
-    problems.push(
-      'O provider `anthropic` NÃO roda nos GitHub Actions: ele sobe o Claude Code CLI como ' +
-      'subprocesso, ausente no runner. As Actions de spec/plan/decompose vão falhar. ' +
-      'Troque para `"provider": "openrouter"` no .spec-wave.json (e adicione o secret ' +
-      'OPENROUTER_API_KEY), ou instale o Claude Code no workflow e defina ' +
-      'SPEC_WAVE_ALLOW_ANTHROPIC_IN_CI=1. Localmente o anthropic funciona.'
+  // O backend anthropic sobe o Claude Code CLI como subprocesso — e o binário
+  // vem embarcado no SDK, então o runner não precisa de instalação extra.
+  if (provider.backend === 'anthropic') {
+    notes.push(
+      `Backend anthropic (${provider.value}): o Claude Code sobe como subprocesso a partir do ` +
+      'binário embarcado no @anthropic-ai/claude-agent-sdk — nada a instalar no runner além do ' +
+      'próprio CLI. Só falha se o pacote for instalado com `--omit=optional`.'
     );
   }
 
@@ -929,6 +939,34 @@ export function checkSpecKit(ctx) {
   };
 }
 
+// Modo de execução: o config e a variável do repositório precisam concordar.
+// Discordar não é detalhe — é o usuário achando que desligou os workflows e
+// continuando a pagar minutos (ou o contrário: tudo pulado e nada rodando).
+async function checkExecutionMode(ctx) {
+  const name = 'Modo de execução (Actions × local)';
+  const configured = configuredMode(ctx.cfg);
+
+  let variable; // undefined = não verificável
+  if (ctx.token && ctx.cfg?.owner && ctx.cfg?.repo) {
+    try {
+      variable = await getRepoVariable(ctx.token, ctx.cfg.owner, ctx.cfg.repo, EXECUTION_VARIABLE);
+    } catch (err) {
+      variable = undefined;
+      if (err.status !== 403 && err.status !== 404) {
+        return { name, status: 'warn', detail: `Variável não verificável agora: ${err.message}` };
+      }
+    }
+  }
+
+  const estado = describeModeState({
+    configured,
+    variable,
+    unguardedWorkflows: unguardedWorkflows(ctx.root || ctx.cwd),
+  });
+  const status = estado.status === 'problem' ? 'fail' : estado.status;
+  return { name, status, detail: [estado.summary, ...estado.notes, ...estado.fixes].join('\n') };
+}
+
 async function checkWorkflows(ctx) {
   const name = 'Workflows do Actions';
   // Ancorado na raiz do projeto, não no cwd: rodar o doctor de um subdiretório
@@ -955,10 +993,19 @@ async function checkWorkflows(ctx) {
   // comportamento de pipelines já em andamento.
   const unpinned = [];
   const otherVersion = [];
+  // O secret do provider escolhido chega ao runner? A YAML é que decide: um
+  // repo configurado com um provider cujo secret o workflow não encaminha morre
+  // com "Faltam credenciais" no meio do fluxo, e o único conserto é `update`.
+  const provider = getProvider(ctx.cfg?.ai?.provider) || getProvider(DEFAULT_PROVIDER);
+  const missingSecret = [];
   for (const file of WORKFLOW_FILES) {
     const content = readFileSync(path.join(dir, file), 'utf-8');
     if (/@spec-wave\/cli@latest/.test(content)) unpinned.push(file);
     else if (!content.includes(`@spec-wave/cli@${CLI_VERSION}`)) otherVersion.push(file);
+    // Identifica os workflows de IA pelo que eles próprios declaram, em vez de
+    // manter uma segunda lista para sair de sincronia com WORKFLOW_FILES.
+    const usesAi = AI_PROVIDERS.some(pr => content.includes(`secrets.${pr.secret}`));
+    if (usesAi && !content.includes(`secrets.${provider.secret}`)) missingSecret.push(file);
   }
   const notes = [`Os ${WORKFLOW_FILES.length} workflows do spec-wave estão presentes.`];
   let status = 'ok';
@@ -976,6 +1023,16 @@ async function checkWorkflows(ctx) {
       'para fazer o bump explícito.'
     );
   }
+  if (missingSecret.length > 0) {
+    status = 'fail';
+    notes.push(
+      `Não encaminham \`${provider.secret}\` (secret do provider ${provider.value}): ` +
+      `${missingSecret.join(', ')}. Esses workflows vão falhar com "Faltam credenciais" — ` +
+      'rode `npx @spec-wave/cli@latest update`.'
+    );
+  } else {
+    notes.push(`Todos encaminham \`${provider.secret}\` (provider ${provider.value}).`);
+  }
   return { name, status, detail: notes.join('\n') };
 }
 
@@ -1011,6 +1068,7 @@ export async function doctor() {
     checkDecompositions,
     checkSpecKit,
     checkWorkflows,
+    checkExecutionMode,
   ];
   const results = [];
   const spinner = p.spinner();

package/src/commands/generate-bug.mjs

@@ -15,11 +15,11 @@ import {
 import { generateDocument } from '../lib/claude.mjs';
 import { unwrapGeneratedDoc } from '../lib/unwrap-doc.mjs';
 import { recordUsage } from '../lib/usage-report.mjs';
-import { loadConfig } from '../lib/project-root.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import { bugDocPaths } from '../lib/bug-doc.mjs';
-import { commitGenerated, executionMode } from '../lib/flow-run.mjs';
+import { commitGenerated, resolveFlowContext } from '../lib/flow-run.mjs';
+import { docBlobUrl } from '../lib/repo-links.mjs';
 import {
   runCritique, resolveCritiqueAttempt, renderNeedsHumanComment,
 } from '../lib/critique.mjs';
@@ -48,18 +48,12 @@ function isSpecWaveComment(body) {
 
 export async function generateBug({ issueNumber }) {
   const token = await resolveToken();
-  const [owner, repo] = (process.env.GITHUB_REPOSITORY || '').split('/');
-  const { root } = loadConfig();
+  // Mesmo contexto dos outros geradores: GITHUB_REPOSITORY quando existe, o
+  // `.spec-wave.json` quando não. Este comando exigia a env crua e morria fora
+  // do runner mandando exportá-la — dentro de um repo que já sabe seu owner/repo.
+  const { owner, repo, root, config, mode } = resolveFlowContext({ command: 'generate-bug' });
   const n = parseInt(issueNumber, 10);
 
-  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 generate-bug --issue-number 1'
-    );
-  }
-
   console.log(`Buscando issue #${n}...`);
   const issue = await getIssue(token, owner, repo, n);
 
@@ -126,7 +120,7 @@ export async function generateBug({ issueNumber }) {
       filePath: fileAbs,
       content,
       message: `docs: generate bug.md for ${slug} [spec-wave]`,
-      mode: executionMode(),
+      mode,
     });
     if (published.warning) console.warn(`⚠️  ${published.warning}`);
 
@@ -142,7 +136,7 @@ export async function generateBug({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, n,
       '🐞 **bug.md gerado automaticamente!**\n\n' +
-      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+      `📄 Arquivo: [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode, root, config })})\n\n` +
       'Revise a **causa raiz** e o **teste de regressão** — são as duas seções que decidem se ' +
       'a correção ataca o defeito ou o sintoma. Quando estiver pronto, valide com:\n' +
       `\`\`\`\ngh issue edit ${n} --add-label "spec-wave:ready"\n\`\`\`` +

package/src/commands/generate-plan.mjs

@@ -20,6 +20,7 @@ import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { resolveFromRoot } from '../lib/project-root.mjs';
 import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
+import { docBlobUrl } from '../lib/repo-links.mjs';
 import { buildTechContext } from '../lib/tech-context.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 
@@ -213,7 +214,7 @@ export async function generatePlan({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
       `📋 **plan.md gerado automaticamente!**\n\n` +
-      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+      `📄 Arquivo: [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode, root, config })})\n\n` +
       `Revise o plano e, quando estiver pronto, valide a Feature: mova o card para **✅ Ready** ou use:\n` +
       `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:ready"\n\`\`\`` +
       formatLintWarning(lintFindings)

package/src/commands/generate-spec.mjs

@@ -7,6 +7,7 @@ import { recordUsage } from '../lib/usage-report.mjs';
 import { slugify } from '../lib/slugify.mjs';
 import { resolveFromRoot } from '../lib/project-root.mjs';
 import { resolveFlowContext, commitGenerated } from '../lib/flow-run.mjs';
+import { docBlobUrl } from '../lib/repo-links.mjs';
 import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
 import { detectIssueType } from '../lib/issue-type.mjs';
 import {
@@ -110,7 +111,7 @@ export async function generateSpec({ issueNumber }) {
     await commentOnIssue(
       token, owner, repo, parseInt(issueNumber, 10),
       `📋 **spec.md gerado automaticamente!**\n\n` +
-      `📄 Arquivo: [\`${fileRel}\`](https://github.com/${owner}/${repo}/blob/main/${fileRel})\n\n` +
+      `📄 Arquivo: [\`${fileRel}\`](${docBlobUrl({ owner, repo, pathRel: fileRel, mode, root })})\n\n` +
       `Revise a especificação e, quando estiver pronto, gere o plano técnico: mova o card para **📋 Plan** ou use:\n` +
       `\`\`\`\ngh issue edit ${issueNumber} --add-label "spec-wave:plan"\n\`\`\`` +
       formatLintWarning(lintFindings)

package/src/commands/init.mjs

@@ -220,6 +220,11 @@ export async function init(options) {
       ? `  1. Commite o ${CONFIG_FILE} quando quiser (git add ${CONFIG_FILE} && git commit)\n`
       : '') +
     `  ${configWritten ? '2' : '1'}. Adicione ${providerMeta.secret} como secret no repositório (provider: ${providerMeta.label})\n` +
+    // O valor do token da assinatura não é copiável de lugar nenhum: só existe
+    // depois de rodar o comando que o gera.
+    (providerMeta.secret === 'CLAUDE_CODE_OAUTH_TOKEN'
+      ? `     ${chalk.dim('Gere o valor com: claude setup-token')}\n`
+      : '') +
     `  ${configWritten ? '3' : '2'}. Configure o board view para agrupar por "Etapa"\n` +
     `  ${configWritten ? '4' : '3'}. Crie uma Feature com o prefixo [FEATURE] no título\n` +
     `  ${configWritten ? '5' : '4'}. Use a skill spec-wave para guiar o fluxo\n\n` +

package/src/commands/mode.mjs

@@ -0,0 +1,169 @@
+// Alterna entre rodar o fluxo no GitHub Actions e rodar nesta máquina.
+//
+// O comando escreve os DOIS lados do interruptor — o `.spec-wave.json`, que a
+// CLI e a skill leem, e a variável de repositório, que o `if:` de cada job
+// avalia. Escrever só um deles é o defeito que o comando existe para evitar:
+// config em "local" com a variável ausente significa workflow disparando e
+// minuto sendo cobrado enquanto o usuário acha que desligou.
+//
+// A variável exige permissão de administração. Sem ela o comando NÃO finge que
+// deu certo: grava o config, diz o que falta e aponta a alternativa manual.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+
+import { resolveToken } from '../api/auth.mjs';
+import { getRepoVariable, setRepoVariable, deleteRepoVariable } from '../api/github-rest.mjs';
+import { CONFIG_FILE, WORKFLOW_FILES } from '../config.mjs';
+import { updateConfig } from '../lib/config-file.mjs';
+import {
+  EXECUTION_MODES, EXECUTION_VARIABLE, EXECUTION_GUARD,
+  configuredMode, variableValueFor, describeModeState,
+} from '../lib/execution-mode.mjs';
+import { loadConfig } from '../lib/project-root.mjs';
+
+/**
+ * Workflows instalados que NÃO carregam a guarda (função quase pura — só lê o fs).
+ *
+ * @param {string|null} root
+ * @returns {string[]}
+ */
+export function unguardedWorkflows(root) {
+  const dir = path.join(root || process.cwd(), '.github', 'workflows');
+  if (!existsSync(dir)) return [];
+  const presentes = new Set(readdirSync(dir));
+  return WORKFLOW_FILES
+    .filter(file => presentes.has(file))
+    .filter(file => !readFileSync(path.join(dir, file), 'utf-8').includes(EXECUTION_GUARD));
+}
+
+// A variável só é legível por quem administra o repo. 403 não é falha: é "não
+// verificável", e quem chama distingue isso de "não existe" (null).
+async function readVariable(token, owner, repo) {
+  try {
+    return await getRepoVariable(token, owner, repo, EXECUTION_VARIABLE);
+  } catch (err) {
+    if (err.status === 403 || err.status === 404) return undefined;
+    throw err;
+  }
+}
+
+export async function mode({ target, dryRun = false } = {}) {
+  p.intro(chalk.bold('spec-wave mode'));
+
+  const { config, root, configPath } = loadConfig();
+  if (!config) {
+    p.log.error(`${CONFIG_FILE} não encontrado — rode \`npx @spec-wave/cli@latest init\` antes.`);
+    process.exit(1);
+  }
+
+  const alvo = target ? String(target).toLowerCase() : null;
+  if (alvo && !EXECUTION_MODES.includes(alvo)) {
+    p.log.error(`Modo inválido: ${alvo}. Use um de: ${EXECUTION_MODES.join(', ')}.`);
+    process.exit(1);
+  }
+
+  const atual = configuredMode(config);
+  const owner = config.owner;
+  const repo = config.repo;
+
+  let token = null;
+  let variavel;
+  if (owner && repo) {
+    try {
+      token = await resolveToken();
+      variavel = await readVariable(token, owner, repo);
+    } catch (err) {
+      p.log.warn(`Não foi possível consultar a variável do repositório: ${err.message}`);
+      variavel = undefined;
+    }
+  }
+
+  // Sem argumento: só relatório.
+  if (!alvo) {
+    const estado = describeModeState({
+      configured: atual, variable: variavel, unguardedWorkflows: unguardedWorkflows(root),
+    });
+    p.log.info(estado.summary);
+    for (const nota of estado.notes) p.log.message(`• ${nota}`);
+    for (const fix of estado.fixes) p.log.warn(fix);
+    p.outro(
+      atual === 'local'
+        ? `Próximo passo de uma issue: ${chalk.cyan('spec-wave run <issue>')}`
+        : `Para desligar o CI: ${chalk.cyan('spec-wave mode local')}`
+    );
+    return { mode: atual, variable: variavel, changed: false };
+  }
+
+  const esperado = variableValueFor(alvo);
+  const mudaConfig = atual !== alvo;
+  const mudaVariavel = variavel !== undefined && variavel !== esperado;
+
+  if (!mudaConfig && !mudaVariavel) {
+    p.log.success(`Já está em ${chalk.bold(alvo)} — config e variável do repositório coincidem.`);
+    p.outro('Nada a fazer.');
+    return { mode: alvo, variable: variavel, changed: false };
+  }
+
+  if (dryRun) {
+    if (mudaConfig) p.log.info(`${CONFIG_FILE}: execution.mode ${atual} → ${alvo}`);
+    if (mudaVariavel) {
+      p.log.info(esperado === null
+        ? `Variável ${EXECUTION_VARIABLE}: remover (valor atual: ${variavel})`
+        : `Variável ${EXECUTION_VARIABLE}: definir como "${esperado}"`);
+    }
+    p.outro('Dry-run: nada foi alterado.');
+    return { mode: atual, variable: variavel, changed: false };
+  }
+
+  if (mudaConfig) {
+    const { changed } = updateConfig(cfg => {
+      cfg.execution = { ...(cfg.execution || {}), mode: alvo };
+    }, { cwd: root || process.cwd() });
+    if (changed) p.log.success(`${CONFIG_FILE} atualizado: execution.mode = ${alvo}`);
+  }
+
+  let variavelOk = true;
+  if (token && owner && repo) {
+    try {
+      if (esperado === null) {
+        const removida = await deleteRepoVariable(token, owner, repo, EXECUTION_VARIABLE);
+        p.log.success(removida
+          ? `Variável ${EXECUTION_VARIABLE} removida — os workflows voltam a disparar.`
+          : `Variável ${EXECUTION_VARIABLE} já não existia.`);
+      } else {
+        await setRepoVariable(token, owner, repo, EXECUTION_VARIABLE, esperado);
+        p.log.success(`Variável ${EXECUTION_VARIABLE}=${esperado} — os jobs passam a ser pulados (0 minutos).`);
+      }
+    } catch (err) {
+      variavelOk = false;
+      p.log.error(
+        `Não foi possível escrever a variável ${EXECUTION_VARIABLE} (${err.status || ''} ${err.message}).\n` +
+        'Ela exige administração no repositório — peça a um admin, ou defina em ' +
+        'Settings → Secrets and variables → Actions → Variables.'
+      );
+    }
+  } else {
+    variavelOk = false;
+    p.log.warn(`Sem owner/repo ou token: só o ${CONFIG_FILE} foi atualizado.`);
+  }
+
+  const semGuarda = unguardedWorkflows(root);
+  if (alvo === 'local' && semGuarda.length > 0) {
+    p.log.warn(
+      `Estes workflows instalados ainda não têm a guarda \`${EXECUTION_GUARD}\` e vão rodar mesmo assim: ` +
+      `${semGuarda.join(', ')}. Rode \`npx @spec-wave/cli@latest update\`.`
+    );
+  }
+
+  p.log.message(chalk.dim(`Commite o ${configPath ? path.basename(configPath) : CONFIG_FILE} — quem clona o repo lê a versão versionada.`));
+  p.outro(
+    alvo === 'local'
+      ? `Modo local. Conduza o fluxo com ${chalk.cyan('spec-wave run <issue>')}.`
+      : 'Modo actions. As labels de gatilho voltam a disparar os workflows.'
+  );
+  return { mode: alvo, variable: esperado, changed: true, variableApplied: variavelOk };
+}