@spec-wave/cli 1.7.6 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +1 -1
  2. package/package.json +1 -1
  3. package/src/agent/errors.mjs +31 -1
  4. package/src/agent/openrouter-agent.mjs +25 -2
  5. package/src/api/github-graphql.mjs +31 -0
  6. package/src/api/github-rest.mjs +20 -0
  7. package/src/cli.mjs +103 -36
  8. package/src/commands/auth-check.mjs +72 -0
  9. package/src/commands/decompose.mjs +14 -2
  10. package/src/commands/doctor.mjs +139 -2
  11. package/src/commands/generate-bug.mjs +6 -6
  12. package/src/commands/generate-plan.mjs +9 -8
  13. package/src/commands/generate-qa-plan.mjs +9 -6
  14. package/src/commands/generate-spec.mjs +12 -7
  15. package/src/commands/implement.mjs +21 -0
  16. package/src/commands/init.mjs +2 -2
  17. package/src/commands/preflight.mjs +38 -2
  18. package/src/commands/progress.mjs +144 -0
  19. package/src/commands/relink.mjs +105 -0
  20. package/src/commands/report-failure.mjs +99 -0
  21. package/src/commands/retry.mjs +91 -0
  22. package/src/commands/task.mjs +5 -0
  23. package/src/commands/update.mjs +70 -0
  24. package/src/config.mjs +8 -8
  25. package/src/lib/cited-paths.mjs +89 -0
  26. package/src/lib/claude.mjs +4 -2
  27. package/src/lib/cli-line.mjs +153 -0
  28. package/src/lib/cli-ref.mjs +53 -2
  29. package/src/lib/failure-report.mjs +319 -0
  30. package/src/lib/progress-events.mjs +46 -0
  31. package/src/lib/repo-identity.mjs +55 -0
  32. package/src/lib/spec-index.mjs +114 -0
  33. package/src/lib/tech-context.mjs +144 -5
  34. package/src/plugin/.claude-plugin/plugin.json +1 -1
  35. package/src/plugin/skills/plan/SKILL.md +1 -1
  36. package/src/plugin/skills/plan/reference/tech-context.md +12 -4
  37. package/src/plugin/skills/setup/SKILL.md +1 -1
  38. package/src/plugin/skills/spec/model-prompt.md +8 -1
  39. package/src/plugins/scm-github/index.mjs +8 -1
  40. package/src/plugins/tracker-github-projects/index.mjs +11 -4
  41. package/src/ports/tracker.mjs +2 -1
  42. package/src/setup/labels.mjs +5 -3
  43. package/src/setup/project.mjs +5 -3
  44. package/src/templates/config/tech_context.yml +29 -25
  45. package/src/templates/skill/SKILL.md +27 -9
  46. package/src/templates/skill/core.md +25 -7
  47. package/src/templates/workflows/code-review.yml +1 -0
  48. package/src/templates/workflows/critique.yml +11 -0
  49. package/src/templates/workflows/decompose.yml +27 -0
  50. package/src/templates/workflows/generate-bug.yml +26 -0
  51. package/src/templates/workflows/generate-plan.yml +26 -0
  52. package/src/templates/workflows/generate-qa-plan.yml +27 -0
  53. package/src/templates/workflows/generate-spec.yml +26 -0
  54. package/src/templates/workflows/pr-events.yml +5 -0
  55. package/src/templates/workflows/qa.yml +1 -0
  56. package/src/templates/workflows/validate.yml +11 -0
package/README.md CHANGED
@@ -299,7 +299,7 @@ A issue #12 recebe um comentário com o link para o arquivo.
299
299
 
300
300
  ### 4. Gerar o plano técnico
301
301
 
302
- Antes de gerar o plano, garanta que `.github/config/tech_context.yml` existe e reflete a stack real. O `init` cria um scaffold — edite-o:
302
+ Antes de gerar o plano, garanta que `.github/config/tech_context.yml` existe e reflete a stack real. O `init` cria um scaffold **em branco**, aberto pela linha `# spec-wave:template` — preencha-o com o stack real e apague essa linha (enquanto ela existir, ou os campos estiverem vazios, o `doctor` reprova, o `preflight` bloqueia e o plano sai sem contexto técnico):
303
303
 
304
304
  ```yaml
305
305
  system_info:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spec-wave/cli",
3
- "version": "1.7.6",
3
+ "version": "1.9.0",
4
4
  "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
5
5
  "type": "module",
6
6
  "bin": {
@@ -105,10 +105,11 @@ export class MaxTurnsError extends Error {
105
105
  : 'As chamadas se REPETEM — é loop degenerado, e repetir reproduz a mesma perambulação ' +
106
106
  'mais cara. Troque o modelo (por `ai.models` ou pela label ' +
107
107
  '`spec-wave:model:<apelido>`) ou suba o teto de turnos.';
108
+ const lidos = filesReadFrom(toolSignatures);
108
109
  super(
109
110
  `O modelo esgotou o teto de ${turns} turnos sem produzir o documento ` +
110
111
  `(${provider} · ${model}${action ? ` · ação=${action}` : ''}): respondeu com chamadas de ` +
111
- `ferramenta em todos eles.${resumo} ${remedio}`
112
+ `ferramenta em todos eles.${resumo} ${remedio}${renderFilesRead(lidos)}`
112
113
  );
113
114
  this.name = 'MaxTurnsError';
114
115
  this.maxTurns = true;
@@ -119,9 +120,38 @@ export class MaxTurnsError extends Error {
119
120
  this.action = action || null;
120
121
  this.toolCalls = toolCalls;
121
122
  this.toolSignatures = toolSignatures;
123
+ this.filesRead = lidos;
122
124
  }
123
125
  }
124
126
 
127
+ /**
128
+ * Arquivos lidos com `Read`, sem repetição e na ordem da primeira leitura
129
+ * (função PURA). As contagens sozinhas ("Read×29") não dizem ONDE o orçamento
130
+ * foi gasto — e é isso que decide entre subir o teto, encurtar o prompt ou
131
+ * entregar um índice ao modelo.
132
+ *
133
+ * @param {string[]} signatures saídas de `toolSignature`
134
+ * @returns {string[]}
135
+ */
136
+ export function filesReadFrom(signatures = []) {
137
+ const vistos = [];
138
+ for (const sig of signatures || []) {
139
+ const m = /^Read:(.+)$/.exec(String(sig));
140
+ if (m && !vistos.includes(m[1])) vistos.push(m[1]);
141
+ }
142
+ return vistos;
143
+ }
144
+
145
+ const MAX_FILES_IN_MESSAGE = 40;
146
+
147
+ function renderFilesRead(lidos) {
148
+ if (!lidos.length) return '';
149
+ const mostrados = lidos.slice(0, MAX_FILES_IN_MESSAGE);
150
+ const resto = lidos.length - mostrados.length;
151
+ return `\nArquivos lidos (${lidos.length}): ${mostrados.join(', ')}` +
152
+ (resto > 0 ? ` (+${resto})` : '') + '.';
153
+ }
154
+
125
155
  /** Contagem por nome de ferramenta, da mais chamada para a menos (função PURA). */
126
156
  export function summarizeToolCalls(toolCalls) {
127
157
  const counts = new Map();
@@ -108,6 +108,28 @@ async function postChatCompletion(body, apiKey, verbose) {
108
108
  throw lastError instanceof Error ? lastError : new Error(String(lastError));
109
109
  }
110
110
 
111
+ // Modelos que RECUSAM `tool_choice` forçado (`{type:'function'}`/`any`) com
112
+ // 400: Claude Fable 5.1, Mythos 5.1, Opus 5.5 e Sonnet 5.5. Neles a saída
113
+ // estruturada vai com `tool_choice: 'auto'` + instrução explícita de chamar a
114
+ // ferramenta; se o modelo ainda responder em texto, o ramo "não chamou a
115
+ // ferramenta" (transitório) repete. Aceita o slug da OpenRouter
116
+ // (`anthropic/claude-opus-5.5`) e o id nu (`claude-opus-5-5`).
117
+ const MODELS_WITHOUT_FORCED_TOOL_CHOICE =
118
+ /claude-(?:fable-5[.-]1|mythos-5[.-]1|opus-5[.-]5|sonnet-5[.-]5)/i;
119
+
120
+ /** O modelo aceita `tool_choice` forçado? (função PURA) */
121
+ export function supportsForcedToolChoice(model) {
122
+ return !MODELS_WITHOUT_FORCED_TOOL_CHOICE.test(model || '');
123
+ }
124
+
125
+ // Sem tool_choice forçado, a instrução é o que sobra para pedir a chamada.
126
+ function comInstrucaoDeFerramenta(messages, toolName) {
127
+ const instrucao = `Responda EXCLUSIVAMENTE chamando a ferramenta "${toolName}" — nunca em texto livre.`;
128
+ const i = messages.findIndex(m => m.role === 'system');
129
+ if (i === -1) return [{ role: 'system', content: instrucao }, ...messages];
130
+ return messages.map((m, j) => (j === i ? { ...m, content: `${m.content}\n\n${instrucao}` } : m));
131
+ }
132
+
111
133
  /**
112
134
  * Corpo EXATO de POST /chat/completions (função PURA — testável sem HTTP).
113
135
  *
@@ -121,9 +143,10 @@ async function postChatCompletion(body, apiKey, verbose) {
121
143
  export function buildChatCompletionBody({
122
144
  model, messages, tools = [], schema = null, maxTokens, temperature,
123
145
  }) {
146
+ const forcar = Boolean(schema) && supportsForcedToolChoice(model);
124
147
  return {
125
148
  model,
126
- messages,
149
+ messages: schema && !forcar ? comInstrucaoDeFerramenta(messages, schema.name) : messages,
127
150
  ...(maxTokens ? { max_tokens: maxTokens } : {}),
128
151
  ...(temperature !== undefined ? { temperature } : {}),
129
152
  ...(schema
@@ -137,7 +160,7 @@ export function buildChatCompletionBody({
137
160
  ...(schema.strict ? { strict: true } : {}),
138
161
  },
139
162
  }],
140
- tool_choice: { type: 'function', function: { name: schema.name } },
163
+ tool_choice: forcar ? { type: 'function', function: { name: schema.name } } : 'auto',
141
164
  }
142
165
  : tools.length > 0
143
166
  ? { tools, tool_choice: 'auto' }
@@ -135,6 +135,37 @@ export async function getSingleSelectField(token, projectId, fieldName) {
135
135
  return { id: field.id, options: optionIds };
136
136
  }
137
137
 
138
+ /**
139
+ * `https://github.com/orgs/<login>/projects/<n>` (ou `/users/`) → partes
140
+ * (função PURA). `null` quando a URL não é de Project v2.
141
+ *
142
+ * Aceita o sufixo `/views/<n>`: é a URL que o navegador MOSTRA ao abrir um
143
+ * Project, e portanto a que a pessoa cola no `relink --project`.
144
+ */
145
+ export function parseProjectUrl(url) {
146
+ const m = /^https?:\/\/github\.com\/(orgs|users)\/([^/]+)\/projects\/(\d+)(?:\/views\/\d+)?\/?(?:[?#].*)?$/.exec(String(url || '').trim());
147
+ return m ? { kind: m[1] === 'orgs' ? 'organization' : 'user', login: m[2], number: Number(m[3]) } : null;
148
+ }
149
+
150
+ /**
151
+ * Id do Project v2 a partir da URL. Lança em URL inválida; `null` quando o
152
+ * Project não existe ou o token não o enxerga.
153
+ */
154
+ export async function getProjectIdByUrl(token, url) {
155
+ const partes = parseProjectUrl(url);
156
+ if (!partes) throw new Error(`URL de Project inválida: ${url} (esperado https://github.com/orgs/<org>/projects/<n>)`);
157
+ const client = makeClient(token);
158
+ const result = await client(`
159
+ query ProjectByNumber($login: String!, $number: Int!) {
160
+ ${partes.kind}(login: $login) { projectV2(number: $number) { id } }
161
+ }
162
+ `, { login: partes.login, number: partes.number }).catch((err) => {
163
+ if (/Could not resolve/i.test(err.message)) return null;
164
+ throw err;
165
+ });
166
+ return result?.[partes.kind]?.projectV2?.id ?? null;
167
+ }
168
+
138
169
  // Lê os metadados atuais de um Project (id, number, url, title) + o campo "Etapa"
139
170
  // (id e opções), em uma única query. Usado pelo comando `refresh`.
140
171
  export async function getProjectSnapshot(token, projectId) {
@@ -783,6 +783,26 @@ export async function listActionsSecretNames(token, owner, repo) {
783
783
  return names;
784
784
  }
785
785
 
786
+ /**
787
+ * Plano do GitHub da ORGANIZAÇÃO dona do repositório (`free`, `team`,
788
+ * `enterprise`…). `null` quando o owner não é organização ou quando o token não
789
+ * vê o campo (o GitHub só o expõe a quem administra a org).
790
+ *
791
+ * Existe por um caso real: no plano Free, secrets de organização NÃO chegam a
792
+ * repositórios privados — `organization-secrets` do repo volta vazio, e a
793
+ * GitHub App configurada na org fica inutilizável sem nenhum erro explícito.
794
+ */
795
+ export async function getOwnerPlan(token, owner) {
796
+ const octokit = makeQuietOctokit(token);
797
+ try {
798
+ const res = await octokit.request('GET /orgs/{org}', { org: owner });
799
+ return res.data?.plan?.name ?? null;
800
+ } catch (err) {
801
+ if (err.status === 404) return null;
802
+ throw err;
803
+ }
804
+ }
805
+
786
806
  /**
787
807
  * "Allow GitHub Actions to create and approve pull requests" está ligado?
788
808
  *
package/src/cli.mjs CHANGED
@@ -10,6 +10,9 @@ import { Command } from 'commander';
10
10
  // (SPEC_WAVE_CLI_VERSION) — antes este arquivo lia o package.json por conta
11
11
  // própria, e um bundle precisava reproduzir a árvore só por causa disto.
12
12
  import { CLI_VERSION } from './lib/templates.mjs';
13
+ // Leve e sem I/O no import: classifica a falha, diz qual credencial estava em
14
+ // uso e deixa o registro para o passo `report-failure` do workflow.
15
+ import { exitWithFailure, describeTokenSources, writeFailureRecord } from './lib/failure-report.mjs';
13
16
 
14
17
  /**
15
18
  * Monta o programa do Commander com todos os comandos (função sem efeito).
@@ -32,6 +35,11 @@ export function buildProgram() {
32
35
  .option('--account <login>', 'Conta do gh a usar (vence GITHUB_TOKEN/GH_TOKEN fora do CI)')
33
36
  .hook('preAction', async (thisCommand) => {
34
37
  const { account } = thisCommand.opts();
38
+ // No Actions, toda execução diz de onde veio cada credencial — um 401
39
+ // sem isso não aponta o secret a trocar (ver lib/failure-report.mjs).
40
+ const origens = describeTokenSources();
41
+ // stderr: comandos com --json têm o stdout parseado pelo workflow.
42
+ if (origens) console.error(origens);
35
43
  if (account) {
36
44
  const { setAccountOverride } = await import('./api/auth.mjs');
37
45
  setAccountOverride(account);
@@ -65,6 +73,17 @@ export function buildProgram() {
65
73
  await info(options);
66
74
  });
67
75
 
76
+ program
77
+ .command('relink')
78
+ .description('Reaponta o .spec-wave.json para o repositório e o Project atuais (repo transferido ou renomeado): reescreve owner/repo e os ids do board')
79
+ .requiredOption('--project <url>', 'URL do Project v2 do dono atual (https://github.com/orgs/<org>/projects/<n>)')
80
+ .option('--repo <owner/repo>', 'Repositório atual (padrão: o git remote origin)')
81
+ .option('--dry-run', 'Mostra o que mudaria sem gravar')
82
+ .action(async (options) => {
83
+ const { relink } = await import('./commands/relink.mjs');
84
+ await relink(options).catch(err => exitWithFailure(err));
85
+ });
86
+
68
87
  program
69
88
  .command('refresh')
70
89
  .description('Atualiza o .spec-wave.json local com os dados atuais do GitHub Project')
@@ -74,7 +93,7 @@ export function buildProgram() {
74
93
  .option('--yes', 'Com --stages: não pede confirmação')
75
94
  .action(async (options) => {
76
95
  const { refresh } = await import('./commands/refresh.mjs');
77
- await refresh(options).catch(err => { console.error(err.message); process.exit(1); });
96
+ await refresh(options).catch(err => exitWithFailure(err));
78
97
  });
79
98
 
80
99
  program
@@ -88,7 +107,7 @@ export function buildProgram() {
88
107
  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
89
108
  .action(async (options) => {
90
109
  const { issue } = await import('./commands/issue.mjs');
91
- await issue(options).catch(err => { console.error(err.message); process.exit(1); });
110
+ await issue(options).catch(err => exitWithFailure(err));
92
111
  });
93
112
 
94
113
  program
@@ -100,7 +119,7 @@ export function buildProgram() {
100
119
  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
101
120
  .action(async (options) => {
102
121
  const { initiative } = await import('./commands/initiative.mjs');
103
- await initiative(options).catch(err => { console.error(err.message); process.exit(1); });
122
+ await initiative(options).catch(err => exitWithFailure(err));
104
123
  });
105
124
 
106
125
  program
@@ -113,7 +132,7 @@ export function buildProgram() {
113
132
  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
114
133
  .action(async (options) => {
115
134
  const { feature } = await import('./commands/feature.mjs');
116
- await feature(options).catch(err => { console.error(err.message); process.exit(1); });
135
+ await feature(options).catch(err => exitWithFailure(err));
117
136
  });
118
137
 
119
138
  program
@@ -126,7 +145,7 @@ export function buildProgram() {
126
145
  .option('--area <area>', 'Área: Frontend, Backend, Mobile, Infra, DevOps ou Data')
127
146
  .action(async (options) => {
128
147
  const { bug } = await import('./commands/bug.mjs');
129
- await bug(options).catch(err => { console.error(err.message); process.exit(1); });
148
+ await bug(options).catch(err => exitWithFailure(err));
130
149
  });
131
150
 
132
151
  program
@@ -140,7 +159,40 @@ export function buildProgram() {
140
159
  .action(async (action, issue, options) => {
141
160
  const { triage } = await import('./commands/triage.mjs');
142
161
  await triage({ action, issue, ...options })
143
- .catch(err => { console.error(err.message); process.exit(1); });
162
+ .catch(err => exitWithFailure(err));
163
+ });
164
+
165
+ program
166
+ .command('retry')
167
+ .description('Dispara de novo a etapa atual de uma issue: remove e reaplica a label de gatilho (ao contrário de `gh run rerun`, usa o estado atual da branch default)')
168
+ .argument('<issue>', 'Número da issue')
169
+ .option('--label <label>', 'Label de gatilho a reaplicar (obrigatória quando a issue não tem nenhuma aplicada)')
170
+ .option('--force', 'Aceita reaplicar spec-wave:decompose-apply (pode duplicar issues já criadas)')
171
+ .action(async (issue, options) => {
172
+ const { retry } = await import('./commands/retry.mjs');
173
+ await retry(issue, options).catch(err => exitWithFailure(err));
174
+ });
175
+
176
+ program
177
+ .command('auth')
178
+ .description('Primeiro passo dos workflows de geração: testa as credenciais de verdade (lê a issue e o Project) e falha cedo dizendo qual secret trocar')
179
+ .argument('<acao>', 'check')
180
+ .requiredOption('--issue <n>', 'Issue que o run vai processar')
181
+ .action(async (acao, options) => {
182
+ if (acao !== 'check') exitWithFailure(new Error(`Ação desconhecida: ${acao} (use \`auth check\`).`));
183
+ const { authCheck } = await import('./commands/auth-check.mjs');
184
+ await authCheck(options).catch(err => exitWithFailure(err));
185
+ });
186
+
187
+ program
188
+ .command('report-failure')
189
+ .description('Passo `if: failure()` dos workflows: comenta na issue a causa classificada e o próximo passo, e remove a label de gatilho')
190
+ .requiredOption('--issue <n>', 'Número da issue do run')
191
+ .option('--label <label>', 'Label de gatilho do run (removida para destravar)')
192
+ .option('--step <nome>', 'Etapa que falhou, para o título do comentário')
193
+ .action(async (options) => {
194
+ const { reportFailure } = await import('./commands/report-failure.mjs');
195
+ await reportFailure(options);
144
196
  });
145
197
 
146
198
  program
@@ -159,7 +211,7 @@ export function buildProgram() {
159
211
  .option('--json', 'Imprime a decisão em JSON')
160
212
  .action(async (issue, options) => {
161
213
  const { run } = await import('./commands/run.mjs');
162
- await run(issue, options).catch(err => { console.error(err.message); process.exit(1); });
214
+ await run(issue, options).catch(err => exitWithFailure(err));
163
215
  });
164
216
 
165
217
  program
@@ -169,7 +221,7 @@ export function buildProgram() {
169
221
  .option('--json', 'Imprime o relatório em JSON')
170
222
  .action(async (options) => {
171
223
  const { preflight } = await import('./commands/preflight.mjs');
172
- await preflight(options).catch(err => { console.error(err.message); process.exit(1); });
224
+ await preflight(options).catch(err => exitWithFailure(err));
173
225
  });
174
226
 
175
227
  program
@@ -180,7 +232,7 @@ export function buildProgram() {
180
232
  .option('--json', 'Imprime o relatório em JSON')
181
233
  .action(async (options) => {
182
234
  const { audit } = await import('./commands/audit.mjs');
183
- await audit(options).catch(err => { console.error(err.message); process.exit(1); });
235
+ await audit(options).catch(err => exitWithFailure(err));
184
236
  });
185
237
 
186
238
  program
@@ -191,7 +243,7 @@ export function buildProgram() {
191
243
  .action(async (target, options) => {
192
244
  const { mode } = await import('./commands/mode.mjs');
193
245
  const result = await mode({ target, ...options })
194
- .catch(err => { console.error(err.message); process.exit(1); });
246
+ .catch(err => exitWithFailure(err));
195
247
  // Escrever só o config é meio-interruptor: a CLI passa a agir como local
196
248
  // e os workflows continuam disparando. O comando já avisa em vermelho,
197
249
  // mas sair 0 fazia qualquer script (ou agente) que o encadeasse ler
@@ -216,7 +268,7 @@ export function buildProgram() {
216
268
  .option('--force-labels', 'Remove labels spec-wave:* órfãs mesmo com issues abertas usando-as (padrão: mantém)')
217
269
  .action(async (options) => {
218
270
  const { update } = await import('./commands/update.mjs');
219
- await update(options).catch(err => { console.error(err.message); process.exit(1); });
271
+ await update(options).catch(err => exitWithFailure(err));
220
272
  });
221
273
 
222
274
  program
@@ -230,7 +282,7 @@ export function buildProgram() {
230
282
  .option('--yes', 'Modo não-interativo')
231
283
  .action(async (options) => {
232
284
  const { installSkill } = await import('./commands/install-skill.mjs');
233
- await installSkill(options).catch(err => { console.error(err.message); process.exit(1); });
285
+ await installSkill(options).catch(err => exitWithFailure(err));
234
286
  });
235
287
 
236
288
  program
@@ -244,7 +296,7 @@ export function buildProgram() {
244
296
  .option('--yes', 'Não pede confirmação')
245
297
  .action(async (options) => {
246
298
  const { uninstall } = await import('./commands/uninstall.mjs');
247
- await uninstall(options).catch(err => { console.error(err.message); process.exit(1); });
299
+ await uninstall(options).catch(err => exitWithFailure(err));
248
300
  });
249
301
 
250
302
  program
@@ -253,7 +305,7 @@ export function buildProgram() {
253
305
  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
254
306
  .action(async (options) => {
255
307
  const { generatePlan } = await import('./commands/generate-plan.mjs');
256
- await generatePlan(options).catch(err => { console.error(err.message); process.exit(1); });
308
+ await generatePlan(options).catch(err => exitWithFailure(err));
257
309
  });
258
310
 
259
311
  program
@@ -265,7 +317,7 @@ export function buildProgram() {
265
317
  .option('--fail-on-grave', 'Sai com código 1 se houver finding grave (útil em script)')
266
318
  .action(async (options) => {
267
319
  const { critique } = await import('./commands/generate-plan.mjs');
268
- await critique(options).catch(err => { console.error(err.message); process.exit(1); });
320
+ await critique(options).catch(err => exitWithFailure(err));
269
321
  });
270
322
 
271
323
  program
@@ -274,7 +326,7 @@ export function buildProgram() {
274
326
  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
275
327
  .action(async (options) => {
276
328
  const { generateSpec } = await import('./commands/generate-spec.mjs');
277
- await generateSpec(options).catch(err => { console.error(err.message); process.exit(1); });
329
+ await generateSpec(options).catch(err => exitWithFailure(err));
278
330
  });
279
331
 
280
332
  program
@@ -283,7 +335,7 @@ export function buildProgram() {
283
335
  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
284
336
  .action(async (options) => {
285
337
  const { generateBug } = await import('./commands/generate-bug.mjs');
286
- await generateBug(options).catch(err => { console.error(err.message); process.exit(1); });
338
+ await generateBug(options).catch(err => exitWithFailure(err));
287
339
  });
288
340
 
289
341
  program
@@ -295,8 +347,13 @@ export function buildProgram() {
295
347
  // A reprova é um desfecho esperado do comando, não uma exceção — mas o exit
296
348
  // code precisa continuar 1 para o job do Actions ficar vermelho.
297
349
  const result = await validate(options)
298
- .catch(err => { console.error(err.message); process.exit(1); });
299
- if (result?.ok === false) process.exit(1);
350
+ .catch(err => exitWithFailure(err));
351
+ if (result?.ok === false) {
352
+ // A reprova já foi comentada pelo validate: o `report-failure` do
353
+ // workflow não pode tratá-la como falha desconhecida.
354
+ writeFailureRecord(Object.assign(new Error('Validação reprovada.'), { issueNotified: true }));
355
+ process.exit(1);
356
+ }
300
357
  });
301
358
 
302
359
  program
@@ -306,7 +363,7 @@ export function buildProgram() {
306
363
  .option('--apply', 'Aplica o decomposition.md já revisado: cria as issues (sem esta flag, apenas gera/critica o rascunho)')
307
364
  .action(async (options) => {
308
365
  const { decompose } = await import('./commands/decompose.mjs');
309
- await decompose(options).catch(err => { console.error(err.message); process.exit(1); });
366
+ await decompose(options).catch(err => exitWithFailure(err));
310
367
  });
311
368
 
312
369
  program
@@ -317,7 +374,7 @@ export function buildProgram() {
317
374
  .option('--resolve-only', 'Só descobre a Feature-alvo e imprime feature=<n>, sem tocar no board')
318
375
  .action(async (options) => {
319
376
  const { codeReview } = await import('./commands/code-review.mjs');
320
- await codeReview(options).catch(err => { console.error(err.message); process.exit(1); });
377
+ await codeReview(options).catch(err => exitWithFailure(err));
321
378
  });
322
379
 
323
380
  program
@@ -342,12 +399,12 @@ export function buildProgram() {
342
399
  }
343
400
  if (options.prNumber) {
344
401
  const { qa } = await import('./commands/qa.mjs');
345
- await qa(options).catch(err => { console.error(err.message); process.exit(1); });
402
+ await qa(options).catch(err => exitWithFailure(err));
346
403
  return;
347
404
  }
348
405
  const { qaRun } = await import('./commands/qa-run.mjs');
349
406
  await qaRun({ issue: issueArg, ...options })
350
- .catch(err => { console.error(err.message); process.exit(1); });
407
+ .catch(err => exitWithFailure(err));
351
408
  })
352
409
  .addHelpText('after', `
353
410
  A fase de QA em duas metades (a ordem é obrigatória):
@@ -381,7 +438,7 @@ Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
381
438
  .action(async (acao, slug, repo, options) => {
382
439
  const { repoCommand } = await import('./commands/repo.mjs');
383
440
  await repoCommand({ action: acao, slug, repo, ...options })
384
- .catch(err => { console.error(err.message); process.exit(1); });
441
+ .catch(err => exitWithFailure(err));
385
442
  })
386
443
  .addHelpText('after', `
387
444
  Edita só o .spec-wave.json LOCAL do hub (commite depois — os workflows leem a branch default) e cria a
@@ -400,7 +457,7 @@ aplicadas. A UI grava o mesmo repositories[] — este comando é o caminho de qu
400
457
  .action(async (acao, options) => {
401
458
  const { workspace } = await import('./commands/workspace.mjs');
402
459
  await workspace({ action: acao, ...options })
403
- .catch(err => { console.error(err.message); process.exit(1); });
460
+ .catch(err => exitWithFailure(err));
404
461
  })
405
462
  .addHelpText('after', `
406
463
  Ordem de resolução por slug: override em .spec-wave/workspace.json ({ "dirs": { "<slug>": "<caminho>" } })
@@ -448,7 +505,7 @@ dos artefatos (SPEC_WAVE_PR_TOKEN / GH_PR_TOKEN, senão o da execução).`);
448
505
  .action(async (acao, milestone, options) => {
449
506
  const { qaLead } = await import('./commands/qa-lead.mjs');
450
507
  await qaLead({ action: acao, milestone, ...options })
451
- .catch(err => { console.error(err.message); process.exit(1); });
508
+ .catch(err => exitWithFailure(err));
452
509
  })
453
510
  .addHelpText('after', `
454
511
  Trilha = milestone (D-QAL1), na ordem do \`spec-wave order\` sem argumento. Duas fases (D-QAL2):
@@ -473,7 +530,7 @@ Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
473
530
  .requiredOption('--issue-number <n>', 'Número da issue no GitHub')
474
531
  .action(async (options) => {
475
532
  const { generateQaPlan } = await import('./commands/generate-qa-plan.mjs');
476
- await generateQaPlan(options).catch(err => { console.error(err.message); process.exit(1); });
533
+ await generateQaPlan(options).catch(err => exitWithFailure(err));
477
534
  })
478
535
  .addHelpText('after', `
479
536
  Só em FEATURE (o plano é um arquivo por Feature, com seções "## Cenário N — Story #X").
@@ -494,7 +551,7 @@ Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
494
551
  .option('--verify-commits', 'Confere se os commits recentes trazem o trailer Spec-Wave-Story/Tasks (best-effort, nunca bloqueia)')
495
552
  .action(async (issue, options) => {
496
553
  const { implement } = await import('./commands/implement.mjs');
497
- await implement({ issue, ...options }).catch(err => { console.error(err.message); process.exit(1); });
554
+ await implement({ issue, ...options }).catch(err => exitWithFailure(err));
498
555
  });
499
556
 
500
557
  program
@@ -508,7 +565,7 @@ Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
508
565
  .option('--sync', 'Grava as dependências VIVAS (body + blocked_by) de volta no decomposition.md e regenera o dependency-map.json')
509
566
  .action(async (feature, options) => {
510
567
  const { order } = await import('./commands/order.mjs');
511
- await order({ feature, ...options }).catch(err => { console.error(err.message); process.exit(1); });
568
+ await order({ feature, ...options }).catch(err => exitWithFailure(err));
512
569
  })
513
570
  .addHelpText('after', `
514
571
  As ARESTAS vêm de fontes locais (dependency-map.json do decompose --apply, decomposition.md,
@@ -517,6 +574,16 @@ cacheado por ${'`cache.ttlSec`'} (default 600s; SPEC_WAVE_CACHE_TTL na env; 0 de
517
574
  staleness sempre visível. blocked_by criado SÓ pela UI não está nas fontes locais: use --remote
518
575
  para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefatos.`);
519
576
 
577
+ program
578
+ .command('progress')
579
+ .description('Andamento de uma Feature: Stories e Tasks concluídas — a base da barra de progresso do dev-agent')
580
+ .argument('<feature>', 'Número da issue da Feature, ex.: 12 ou #12')
581
+ .option('--json', 'Saída em JSON estável (para o spec-wave-agent/scripts), sem ANSI')
582
+ .action(async (feature, options) => {
583
+ const { progress } = await import('./commands/progress.mjs');
584
+ await progress({ feature, ...options }).catch(err => exitWithFailure(err));
585
+ });
586
+
520
587
  program
521
588
  .command('merge')
522
589
  .description('Mergeia os PRs empilhados das Stories de uma Feature na ordem topológica e move o board até QA')
@@ -528,7 +595,7 @@ para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefato
528
595
  .option('--refresh', 'Ignora o cache local e reconsulta a API')
529
596
  .action(async (feature, options) => {
530
597
  const { merge } = await import('./commands/merge.mjs');
531
- await merge({ feature, ...options }).catch(err => { console.error(err.message); process.exit(1); });
598
+ await merge({ feature, ...options }).catch(err => exitWithFailure(err));
532
599
  });
533
600
 
534
601
  program
@@ -538,7 +605,7 @@ para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefato
538
605
  .argument('<n>', 'Número da issue da Task, ex.: 12 ou #12')
539
606
  .action(async (action, n) => {
540
607
  const { task } = await import('./commands/task.mjs');
541
- await task({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
608
+ await task({ action, issue: n }).catch(err => exitWithFailure(err));
542
609
  });
543
610
 
544
611
  program
@@ -550,7 +617,7 @@ para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefato
550
617
  .action(async (n, etapa, options) => {
551
618
  const { move } = await import('./commands/move.mjs');
552
619
  await move({ issue: n, stage: etapa, ...options })
553
- .catch(err => { console.error(err.message); process.exit(1); });
620
+ .catch(err => exitWithFailure(err));
554
621
  });
555
622
 
556
623
  program
@@ -565,7 +632,7 @@ para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefato
565
632
  .action(async (issues, etapa, options) => {
566
633
  const { repairStage } = await import('./commands/repair-stage.mjs');
567
634
  await repairStage(issues, etapa, options)
568
- .catch(err => { console.error(err.message); process.exit(1); });
635
+ .catch(err => exitWithFailure(err));
569
636
  });
570
637
 
571
638
  program
@@ -575,7 +642,7 @@ para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefato
575
642
  .argument('<n>', 'Número da issue da Story, ex.: 12 ou #12')
576
643
  .action(async (action, n) => {
577
644
  const { story } = await import('./commands/story.mjs');
578
- await story({ action, issue: n }).catch(err => { console.error(err.message); process.exit(1); });
645
+ await story({ action, issue: n }).catch(err => exitWithFailure(err));
579
646
  });
580
647
 
581
648
  program
@@ -593,7 +660,7 @@ para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefato
593
660
  .option('--queue <nome>', 'No --install/--build: fila deste daemon (padrão: dev-agent). Para uma trilha extra, declare-a em devAgent.queues do .spec-wave.json antes — senão update/doctor não reconhecem a label')
594
661
  .action(async (options) => {
595
662
  const { devAgent } = await import('./commands/dev-agent.mjs');
596
- await devAgent(options).catch(err => { console.error(err.message); process.exit(1); });
663
+ await devAgent(options).catch(err => exitWithFailure(err));
597
664
  });
598
665
 
599
666
  program
@@ -602,7 +669,7 @@ para incluí-lo na consulta, ou --sync para gravá-lo em definitivo nos artefato
602
669
  .option('--deep', 'Confere também as Tasks de cada decomposição aplicada (1 chamada GraphQL a mais por Story; padrão: só Stories)')
603
670
  .action(async (options) => {
604
671
  const { doctor } = await import('./commands/doctor.mjs');
605
- await doctor(options).catch(err => { console.error(err.message); process.exit(1); });
672
+ await doctor(options).catch(err => exitWithFailure(err));
606
673
  });
607
674
 
608
675
  // O mapa por tema no fim do --help: 29 comandos em lista plana dizem O QUE
@@ -0,0 +1,72 @@
1
+ // `spec-wave auth check --issue <n>` — primeiro passo dos workflows de geração.
2
+ //
3
+ // Testa as credenciais DE VERDADE, dentro do Actions, antes de qualquer
4
+ // trabalho: lê a issue com o GITHUB_TOKEN do passo e, havendo board, lê o
5
+ // Project com o PROJECT_TOKEN. O `doctor` só confere o NOME dos secrets (a API
6
+ // nunca expõe o valor), e foi assim que um GH_PROJECT_TOKEN expirado passou por
7
+ // "presente" e só apareceu como `401 Bad credentials` no meio do run, sem dizer
8
+ // qual token era. Aqui a falha sai classificada (lib/failure-report.mjs), com o
9
+ // secret a trocar, e o passo `report-failure` a leva até a issue.
10
+ //
11
+ // Duas leituras baratas (uma REST, uma GraphQL); nenhuma escrita.
12
+
13
+ import { resolveToken } from '../api/auth.mjs';
14
+ import { openTracker, trackerAvailable } from '../lib/board.mjs';
15
+ import { tokenSources } from '../lib/failure-report.mjs';
16
+ import { resolveFlowContext } from '../lib/flow-run.mjs';
17
+ import { requireTracker } from '../ports/index.mjs';
18
+
19
+ function origemDe(env, nome) {
20
+ return tokenSources(env).find(f => f.env === nome)?.source ?? nome;
21
+ }
22
+
23
+ /**
24
+ * @param {object} params
25
+ * @param {string|number} params.issue
26
+ * @param {object} [params.deps] `tracker`, `boardTracker`, `env`
27
+ * @returns {Promise<{issue: boolean, board: boolean|null}>}
28
+ */
29
+ export async function authCheck({ issue, deps = {} }) {
30
+ const env = deps.env ?? process.env;
31
+ const { owner, repo } = resolveFlowContext({ command: 'auth check', env });
32
+ const token = await resolveToken({ quiet: true });
33
+
34
+ // 1) Issue — a credencial do passo (GITHUB_TOKEN, que pode vir de PAT/App).
35
+ const tracker = await requireTracker({ token, owner, repo, deps });
36
+ try {
37
+ await tracker.getWorkItem({ ref: { key: String(issue) } });
38
+ } catch (err) {
39
+ err.message = `Credencial ${origemDe(env, 'GITHUB_TOKEN')} não leu a issue #${issue} de ${owner}/${repo}: ${err.message}`;
40
+ throw err;
41
+ }
42
+ console.log(`✓ ${origemDe(env, 'GITHUB_TOKEN')} lê a issue #${issue} de ${owner}/${repo}.`);
43
+
44
+ // 2) Board — só quando o repositório tem um e há credencial própria para ele.
45
+ const projectToken = env.PROJECT_TOKEN || null;
46
+ if (!projectToken || !(deps.boardTracker || trackerAvailable().ok)) {
47
+ return { issue: true, board: null };
48
+ }
49
+ // `openTracker` devolve `{ tracker, root, error }` — a PORTA é o `tracker`.
50
+ // Usar o retorno direto como porta dava `board.setup is not a function` em
51
+ // todo hub com board, e o teste não via porque injetava `deps.boardTracker`
52
+ // por fora desta chamada. Agora a injeção passa POR ela, e a forma é uma só.
53
+ const { tracker: board, error } = await openTracker({
54
+ token, projectToken, owner, repo, tracker: deps.boardTracker ?? null,
55
+ });
56
+ if (error || !board) {
57
+ throw new Error(`Não consegui montar o tracker do board para testar ${origemDe(env, 'PROJECT_TOKEN')}: ${error ?? 'porta ausente'}`);
58
+ }
59
+ const { config, warnings } = await board.setup({ provision: false }).catch((err) => {
60
+ err.message = `Credencial ${origemDe(env, 'PROJECT_TOKEN')} não leu o Project: ${err.message}`;
61
+ throw err;
62
+ });
63
+ if (!config) {
64
+ throw new Error(
65
+ `Credencial ${origemDe(env, 'PROJECT_TOKEN')} não enxerga o Project do .spec-wave.json ` +
66
+ `(${warnings?.[0] ?? 'sem detalhe'}). 404 de Project é quase sempre token sem acesso ao board ` +
67
+ '(ou repositório transferido — `spec-wave doctor`).'
68
+ );
69
+ }
70
+ console.log(`✓ ${origemDe(env, 'PROJECT_TOKEN')} lê o Project "${config.projectTitle}".`);
71
+ return { issue: true, board: true };
72
+ }