@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
@@ -0,0 +1,153 @@
1
+ // Em que linha da CLI este repositório está, de verdade? (doctor)
2
+ //
3
+ // Quatro versões convivem e podem divergir sem ninguém notar:
4
+ // • `version` do .spec-wave.json — gravada pelo init/update/refresh;
5
+ // • a fixada nos WORKFLOWS — é a que roda no Actions;
6
+ // • a CLI que está executando agora (npx/global);
7
+ // • o PLUGIN do Claude Code instalado no projeto — é o que o agente lê.
8
+ //
9
+ // Casos reais (Nuviumdigital/semseguro): config em 0.35.0 com workflows em
10
+ // 1.7.3 (o doctor mandava `@0 update`, que respondia "tudo atualizado" com o
11
+ // pr-events.yml faltando) e plugin 1.7.6 com workflows em 1.7.3.
12
+
13
+ import { existsSync, readFileSync } from 'node:fs';
14
+ import os from 'node:os';
15
+ import path from 'node:path';
16
+
17
+ import { majorOf, newerMajor } from './cli-ref.mjs';
18
+
19
+ /** Compara semver simples (função PURA): -1, 0, 1; null se ilegível. */
20
+ export function compareVersions(a, b) {
21
+ const pa = /^(\d+)\.(\d+)\.(\d+)/.exec(String(a || ''));
22
+ const pb = /^(\d+)\.(\d+)\.(\d+)/.exec(String(b || ''));
23
+ if (!pa || !pb) return null;
24
+ for (let i = 1; i <= 3; i++) {
25
+ const d = Number(pa[i]) - Number(pb[i]);
26
+ if (d) return d > 0 ? 1 : -1;
27
+ }
28
+ return 0;
29
+ }
30
+
31
+ /**
32
+ * Versão do plugin `spec-wave` do Claude Code instalada para este projeto
33
+ * (escopo de projeto vence o de usuário). Null quando não está instalado ou o
34
+ * registro não é legível. Nunca lança.
35
+ *
36
+ * @param {string} root raiz do projeto
37
+ * @param {string} [claudeDir] diretório de config do Claude Code
38
+ */
39
+ export function installedPluginVersion(root, claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude')) {
40
+ const arq = path.join(claudeDir, 'plugins', 'installed_plugins.json');
41
+ if (!existsSync(arq)) return null;
42
+ try {
43
+ const bruto = JSON.parse(readFileSync(arq, 'utf-8'));
44
+ const plugins = bruto.plugins ?? bruto;
45
+ const entradas = Object.entries(plugins)
46
+ .filter(([k]) => k.startsWith('spec-wave@'))
47
+ .flatMap(([, v]) => (Array.isArray(v) ? v : [v]));
48
+ const alvo = path.resolve(root || process.cwd());
49
+ const doProjeto = entradas.find(e => e?.projectPath && path.resolve(e.projectPath) === alvo);
50
+ const doUsuario = entradas.find(e => e?.scope === 'user');
51
+ return (doProjeto ?? doUsuario)?.version ?? null;
52
+ } catch {
53
+ return null;
54
+ }
55
+ }
56
+
57
+ /**
58
+ * Veredito da linha da CLI (função PURA).
59
+ *
60
+ * @param {object} v
61
+ * @param {string|null} [v.configVersion]
62
+ * @param {string|null} [v.workflowVersion]
63
+ * @param {string} v.cliVersion
64
+ * @param {string|null} [v.pluginVersion]
65
+ * @param {string|null} [v.latestVersion] `latest` do npm, quando consultado
66
+ * @param {string} [v.pkg]
67
+ * @returns {{status: 'ok'|'warn', notes: string[]}}
68
+ */
69
+ export function inspectCliLine({
70
+ configVersion = null, workflowVersion = null, cliVersion, pluginVersion = null,
71
+ latestVersion = null, pkg = '@spec-wave/cli',
72
+ }) {
73
+ const notes = [];
74
+ let status = 'ok';
75
+ // A referência é o que RODA: os workflows; sem eles, a CLI em execução.
76
+ const ref = workflowVersion || cliVersion;
77
+ // A LINHA do repositório é a major mais nova entre config e workflows —
78
+ // mesma regra do `pinnedMajor` (lib/cli-ref.mjs). Quem está na menor é que
79
+ // ficou para trás, e a instrução nunca pode apontar para um downgrade.
80
+ const cfgMajor = majorOf(configVersion);
81
+ const wfMajor = majorOf(workflowVersion);
82
+ const refMajor = wfMajor ? newerMajor(wfMajor, cfgMajor) : majorOf(ref);
83
+ notes.push(
84
+ `config ${configVersion ?? '—'} · workflows ${workflowVersion ?? '—'} · CLI em execução ${cliVersion}` +
85
+ (pluginVersion ? ` · plugin ${pluginVersion}` : '')
86
+ );
87
+
88
+ if (wfMajor && cfgMajor && Number(cfgMajor) < Number(wfMajor)) {
89
+ status = 'warn';
90
+ notes.push(
91
+ `O .spec-wave.json declara a linha ${cfgMajor}.x (${configVersion}), mas os workflows rodam a ${workflowVersion}: ` +
92
+ `o config ficou para trás. Atualize pela linha dos workflows — \`npx ${pkg}@${refMajor} update\` — ` +
93
+ `e NÃO pela @${cfgMajor}, que não conhece os workflows da ${refMajor}.x.`
94
+ );
95
+ } else if (wfMajor && cfgMajor && Number(cfgMajor) > Number(wfMajor)) {
96
+ // O inverso: o config já migrou e os workflows não. Mandar `@<major dos
97
+ // workflows> update` aqui seria conduzir a um downgrade.
98
+ status = 'warn';
99
+ notes.push(
100
+ `O .spec-wave.json já está na linha ${cfgMajor}.x (${configVersion}), mas os workflows ainda rodam a ${workflowVersion}: ` +
101
+ `a atualização ficou pela metade. Termine-a com \`npx ${pkg}@${refMajor} update\` — ` +
102
+ `e NÃO pela @${wfMajor}, que rebaixaria o config.`
103
+ );
104
+ }
105
+ if (workflowVersion && majorOf(cliVersion) !== refMajor) {
106
+ status = 'warn';
107
+ notes.push(
108
+ `Esta execução usa a CLI ${cliVersion}, de outra major que a deste repositório ` +
109
+ `(config ${configVersion ?? '—'}, workflows ${workflowVersion}). ` +
110
+ `Para diagnosticar e atualizar este repositório use \`npx ${pkg}@${refMajor}\`.`
111
+ );
112
+ }
113
+ if (pluginVersion) {
114
+ const c = compareVersions(pluginVersion, ref);
115
+ if (c === 1) {
116
+ status = 'warn';
117
+ notes.push(
118
+ `O plugin do Claude Code (${pluginVersion}) é mais novo que os workflows (${ref}): o agente segue ` +
119
+ `instruções de uma versão que o Actions não roda. Rode \`npx ${pkg}@${majorOf(pluginVersion)} update\`.`
120
+ );
121
+ } else if (c === -1) {
122
+ status = 'warn';
123
+ notes.push(
124
+ `O plugin do Claude Code (${pluginVersion}) é mais velho que os workflows (${ref}): ` +
125
+ 'atualize com `/plugin update spec-wave@spec-wave` no Claude Code.'
126
+ );
127
+ }
128
+ }
129
+ const latMajor = majorOf(latestVersion);
130
+ if (latMajor && refMajor && Number(latMajor) > Number(refMajor)) {
131
+ notes.push(
132
+ `Existe uma major nova: ${latestVersion}. Mudar de major é migração deliberada (a ${latMajor}.x não é ` +
133
+ `compatível com a ${refMajor}.x) — leia o CHANGELOG antes de \`npx ${pkg}@${latMajor} update\`.`
134
+ );
135
+ }
136
+ return { status, notes };
137
+ }
138
+
139
+ /**
140
+ * `latest` do pacote no npm, com teto de tempo. Null em qualquer falha —
141
+ * diagnóstico offline não pode virar erro.
142
+ */
143
+ export async function fetchLatestVersion(pkg = '@spec-wave/cli', { timeoutMs = 3000 } = {}) {
144
+ try {
145
+ const res = await fetch(`https://registry.npmjs.org/${pkg.replace('/', '%2F')}/latest`, {
146
+ signal: AbortSignal.timeout(timeoutMs),
147
+ });
148
+ if (!res.ok) return null;
149
+ return (await res.json())?.version ?? null;
150
+ } catch {
151
+ return null;
152
+ }
153
+ }
@@ -17,7 +17,8 @@
17
17
  // reprodutibilidade — uma release não pode mudar o comportamento de um pipeline
18
18
  // em andamento. Instrução quer compatibilidade; pipeline quer imutabilidade.
19
19
 
20
- import { readFileSync } from 'node:fs';
20
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
21
+ import path from 'node:path';
21
22
  import { findConfigPath } from './project-root.mjs';
22
23
  import { CLI_VERSION } from './templates.mjs';
23
24
 
@@ -29,6 +30,19 @@ export function majorOf(version) {
29
30
  return m ? m[1] : null;
30
31
  }
31
32
 
33
+ /**
34
+ * A major mais nova entre duas (função PURA); a que existir, se só uma; null
35
+ * se nenhuma.
36
+ *
37
+ * @param {string|null} a
38
+ * @param {string|null} b
39
+ * @returns {string|null}
40
+ */
41
+ export function newerMajor(a, b) {
42
+ if (a == null || b == null) return a ?? b ?? null;
43
+ return Number(a) >= Number(b) ? a : b;
44
+ }
45
+
32
46
  /**
33
47
  * Major da linha em que o repositório está congelado (função PURA — `cwd`
34
48
  * injetável). Nunca lança: config ausente, ilegível ou sem `version` cai na
@@ -42,12 +56,49 @@ export function pinnedMajor(cwd = process.cwd()) {
42
56
  try {
43
57
  const configPath = findConfigPath(cwd);
44
58
  if (!configPath) return daCli;
45
- return majorOf(JSON.parse(readFileSync(configPath, 'utf-8')).version) ?? daCli;
59
+ const doConfig = majorOf(JSON.parse(readFileSync(configPath, 'utf-8')).version);
60
+ // Os WORKFLOWS são o que de fato roda. Quando a major deles é MAIOR que a
61
+ // do config, o config é que ficou para trás (caso real: config em 0.35.0,
62
+ // workflows em 1.7.3) — e mandar `@0 update` respondia "tudo atualizado"
63
+ // com o pr-events.yml faltando, porque a linha 0.x nem o conhece.
64
+ //
65
+ // Vale a MAIOR das duas, não "a dos workflows": com o config já em 2.0.0 e
66
+ // os workflows ainda em 1.x (update pela metade), preferir os workflows
67
+ // trocaria toda instrução para `@1` — um downgrade.
68
+ const doWorkflow = majorOf(workflowPinnedVersion(path.dirname(configPath)));
69
+ return newerMajor(doWorkflow, doConfig) ?? daCli;
46
70
  } catch {
47
71
  return daCli;
48
72
  }
49
73
  }
50
74
 
75
+ /**
76
+ * Versão da CLI fixada nos workflows do repositório (a mais frequente), ou
77
+ * null quando não há workflow pinado. Nunca lança.
78
+ *
79
+ * @param {string} root raiz do repositório
80
+ * @returns {string|null}
81
+ */
82
+ export function workflowPinnedVersion(root) {
83
+ const dir = path.join(root || process.cwd(), '.github', 'workflows');
84
+ if (!existsSync(dir)) return null;
85
+ const contagem = new Map();
86
+ try {
87
+ for (const f of readdirSync(dir)) {
88
+ if (!/\.ya?ml$/.test(f)) continue;
89
+ const texto = readFileSync(path.join(dir, f), 'utf-8');
90
+ for (const m of texto.matchAll(/@spec-wave\/cli@(\d+\.\d+\.\d+)/g)) {
91
+ contagem.set(m[1], (contagem.get(m[1]) || 0) + 1);
92
+ }
93
+ }
94
+ } catch {
95
+ return null;
96
+ }
97
+ let melhor = null;
98
+ for (const [v, n] of contagem) if (!melhor || n > contagem.get(melhor)) melhor = v;
99
+ return melhor;
100
+ }
101
+
51
102
  /**
52
103
  * `@spec-wave/cli@<major>` para usar em instruções — no lugar de `@latest`.
53
104
  *
@@ -0,0 +1,319 @@
1
+ // Falha de comando: classificar a causa, dizer QUAL credencial estava em uso e
2
+ // levar o diagnóstico até a issue.
3
+ //
4
+ // Três buracos medidos no uso real (Nuviumdigital/semseguro, CLI 1.7.3):
5
+ //
6
+ // 1. `GET /repos/.../issues/37 - 401 Bad credentials`, sem dizer de qual
7
+ // credencial. O `GITHUB_TOKEN` do passo era `app || GH_PROJECT_TOKEN ||
8
+ // GITHUB_TOKEN` — e o culpado era um GH_PROJECT_TOKEN expirado, herdado do
9
+ // dono anterior do repositório. O workflow agora exporta a ORIGEM de cada
10
+ // token (`SPEC_WAVE_*_SOURCE`) e é ela que nomeia o secret a trocar.
11
+ // 2. O passo da GitHub App é pulado em silêncio quando a chave não existe. O
12
+ // log de origem diz isso a cada comando.
13
+ // 3. A falha não chegava ao PM: os comandos de geração já comentavam o erro
14
+ // BRUTO quando eles mesmos falhavam, mas uma falha em passo anterior
15
+ // (`workspace prepare`, a instalação) não deixava rastro nenhum na issue.
16
+ // `exitWithFailure` grava um registro em `$RUNNER_TEMP`, e o passo
17
+ // `if: failure()` do workflow (`spec-wave report-failure`) o transforma em
18
+ // comentário — sem duplicar quando o comando já comentou.
19
+ //
20
+ // Tudo aqui é PURO exceto `exitWithFailure`/`readFailureRecord`/
21
+ // `writeFailureRecord`, que tocam disco e processo.
22
+
23
+ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
24
+ import path from 'node:path';
25
+
26
+ export const FAILURE_RECORD_FILE = 'spec-wave-failure.json';
27
+
28
+ // Variáveis de ambiente do processo → a variável que diz de onde ela veio.
29
+ // Os workflows preenchem as `*_SOURCE`; fora do Actions elas não existem.
30
+ const TOKEN_VARS = [
31
+ { env: 'GITHUB_TOKEN', source: 'SPEC_WAVE_TOKEN_SOURCE', default: 'GITHUB_TOKEN' },
32
+ { env: 'GH_PR_TOKEN', source: 'SPEC_WAVE_PR_TOKEN_SOURCE', default: 'GH_PR_TOKEN' },
33
+ { env: 'PROJECT_TOKEN', source: 'SPEC_WAVE_PROJECT_TOKEN_SOURCE', default: 'GH_PROJECT_TOKEN' },
34
+ ];
35
+
36
+ // Origens que são SECRETS trocáveis pelo usuário (o GITHUB_TOKEN automático e o
37
+ // token da App não são: o primeiro não expira, o segundo nasce a cada run).
38
+ const PAT_SECRETS = ['GH_PROJECT_TOKEN', 'GH_PR_TOKEN'];
39
+ export const APP_SOURCE = 'GitHub App (SPEC_WAVE_APP_*)';
40
+
41
+ /**
42
+ * De onde veio cada credencial do GitHub deste processo (função PURA).
43
+ *
44
+ * Só lista variável PRESENTE e não vazia — um `GH_PR_TOKEN` vazio é o
45
+ * `secrets.X` inexistente, e não é credencial em uso.
46
+ *
47
+ * @param {Record<string, string|undefined>} env
48
+ * @returns {Array<{env: string, source: string}>}
49
+ */
50
+ export function tokenSources(env = process.env) {
51
+ return TOKEN_VARS
52
+ .filter(t => env[t.env])
53
+ .map(t => ({ env: t.env, source: env[t.source] || t.default }));
54
+ }
55
+
56
+ /**
57
+ * Linha de log com as origens (função PURA). `null` fora do Actions.
58
+ *
59
+ * @param {Record<string, string|undefined>} env
60
+ * @returns {string|null}
61
+ */
62
+ export function describeTokenSources(env = process.env) {
63
+ if (env.GITHUB_ACTIONS !== 'true') return null;
64
+ const fontes = tokenSources(env);
65
+ const partes = fontes.map(f => (f.env === f.source ? f.env : `${f.env} ← ${f.source}`));
66
+ let app = '';
67
+ if (env.SPEC_WAVE_APP_PRESENT === 'false') {
68
+ app = ' · GitHub App NÃO configurada (SPEC_WAVE_APP_PRIVATE_KEY ausente) — PATs em uso';
69
+ } else if (env.SPEC_WAVE_APP_PRESENT === 'true' && !fontes.some(f => f.source === APP_SOURCE)) {
70
+ app = ' · GitHub App configurada, mas nenhum token deste passo veio dela';
71
+ }
72
+ return `Credenciais do GitHub: ${partes.length ? partes.join(', ') : '(nenhuma)'}${app}`;
73
+ }
74
+
75
+ /** Secrets trocáveis entre as origens em uso (função PURA). */
76
+ function patsEmUso(env) {
77
+ return [...new Set(tokenSources(env).map(f => f.source).filter(s => PAT_SECRETS.includes(s)))];
78
+ }
79
+
80
+ function proximoPassoAuth(env, status) {
81
+ const pats = patsEmUso(env);
82
+ const verbo = status === 401 ? 'está inválido ou expirado' : 'não tem a permissão necessária';
83
+ if (env.GITHUB_ACTIONS !== 'true') {
84
+ return `O token local ${verbo}: confira \`gh auth status\` (ou o GITHUB_TOKEN exportado no shell).`;
85
+ }
86
+ if (pats.length) {
87
+ return `Troque o(s) secret(s) ${pats.map(s => `\`${s}\``).join(' / ')} em Settings → Secrets and variables → Actions ` +
88
+ `(o token ${verbo}). Uma GitHub App da organização (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY) ` +
89
+ 'dispensa PATs pessoais.';
90
+ }
91
+ if (tokenSources(env).some(f => f.source === APP_SOURCE)) {
92
+ return 'O token veio da GitHub App: confira se ela está instalada neste repositório (e nos de código) ' +
93
+ 'com as permissões de issues, contents, pull requests e projects.';
94
+ }
95
+ return 'O GITHUB_TOKEN automático não expira — confira o bloco `permissions:` do workflow e, ' +
96
+ 'para board/outros repositórios, configure GH_PROJECT_TOKEN ou a GitHub App.';
97
+ }
98
+
99
+ // Erro HTTP do GitHub (octokit `RequestError`): só dele o `.status` é confiável.
100
+ // O SDK do provider de IA também põe `.status` no erro, e um 404 de modelo
101
+ // inexistente não é "repositório transferido".
102
+ function erroHttpDoGithub(err) {
103
+ return err?.name === 'HttpError' ||
104
+ typeof err?.request?.url === 'string' ||
105
+ /github/i.test(String(err?.response?.url ?? ''));
106
+ }
107
+
108
+ // 401/403/404 só valem como status quando o TEXTO tem forma de resposta HTTP do
109
+ // GitHub: `GET /repos/... - 401`, `HTTP 404` (gh), `returned error: 403` (git).
110
+ // Número solto não: "Story #404 não é Feature" e "docs/x.md linha 403" eram
111
+ // classificados como credencial, com conselho de trocar secret.
112
+ const STATUS_NO_TEXTO = [
113
+ /\b(?:GET|POST|PUT|PATCH|DELETE|HEAD) \/\S* - (401|403|404)\b/,
114
+ /\bHTTP (401|403|404)\b/,
115
+ /returned error: (401|403|404)\b/,
116
+ ];
117
+
118
+ function statusDe(err, msg) {
119
+ if (Number.isInteger(err?.status) && erroHttpDoGithub(err)) return err.status;
120
+ for (const re of STATUS_NO_TEXTO) {
121
+ const m = re.exec(msg);
122
+ if (m) return Number(m[1]);
123
+ }
124
+ return null;
125
+ }
126
+
127
+ /**
128
+ * Causa provável de uma falha (função PURA).
129
+ *
130
+ * A ordem importa: credencial de PROVIDER de IA também responde 401, e trocar o
131
+ * secret do GitHub por causa dela seria o conselho errado.
132
+ *
133
+ * @param {Error|{message?: string}|string} err
134
+ * @param {Record<string, string|undefined>} [env]
135
+ * @returns {{kind: string, resumo: string, proximoPasso: string}}
136
+ */
137
+ export function classifyFailure(err, env = process.env) {
138
+ const msg = typeof err === 'string' ? err : String(err?.message ?? '');
139
+ const e = typeof err === 'object' && err ? err : {};
140
+
141
+ if (e.maxTurns || /esgotou o teto de \d+ turnos|error_max_turns/i.test(msg)) {
142
+ return {
143
+ kind: 'max_turns',
144
+ resumo: 'O modelo gastou o teto de turnos explorando o repositório e não escreveu o documento.',
145
+ proximoPasso: 'Reaplique o gatilho (`spec-wave retry <issue>`). Se repetir, veja no log quais arquivos ' +
146
+ 'foram lidos e suba `maxTurns` num override em `.spec-wave/prompts/`.',
147
+ };
148
+ }
149
+ if (e.name === 'TruncatedOutputError' || /truncad|max_tokens|finish_reason: length/i.test(msg)) {
150
+ return {
151
+ kind: 'truncated',
152
+ resumo: 'A resposta do modelo foi cortada pelo limite de tokens de saída.',
153
+ proximoPasso: 'Suba `ai.maxTokens` no .spec-wave.json ou divida a Feature — repetir igual corta no mesmo ponto.',
154
+ };
155
+ }
156
+ if (/x-api-key|authentication_error|invalid api key|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN|OPENROUTER_API_KEY|credit balance|insufficient credits|Faltam credenciais/i.test(msg)) {
157
+ return {
158
+ kind: 'provider_auth',
159
+ resumo: 'A credencial do provider de IA está ausente, inválida ou sem crédito.',
160
+ proximoPasso: 'Confira o secret do provider escolhido em `.spec-wave.json` (ANTHROPIC_API_KEY, ' +
161
+ 'CLAUDE_CODE_OAUTH_TOKEN ou OPENROUTER_API_KEY) e o saldo da conta.',
162
+ };
163
+ }
164
+ // ANTES do 403: o limite de taxa do GitHub responde 403 (ou 429), e o conselho
165
+ // de "falta permissão / troque o secret" para um limite transitório é errado.
166
+ if (/API rate limit exceeded|secondary rate limit|abuse detection/i.test(msg)) {
167
+ return {
168
+ kind: 'rate_limit',
169
+ resumo: 'O GitHub limitou a taxa de requisições desta credencial.',
170
+ proximoPasso: 'Transitório: espere alguns minutos e reaplique o gatilho (`spec-wave retry <issue>`). ' +
171
+ 'Nenhum secret precisa ser trocado.',
172
+ };
173
+ }
174
+ const status = statusDe(e, msg);
175
+ if (status === 401 || /bad credentials/i.test(msg)) {
176
+ return {
177
+ kind: 'auth',
178
+ resumo: `O GitHub recusou a credencial (401).${resumoFontes(env)}`,
179
+ proximoPasso: proximoPassoAuth(env, 401),
180
+ };
181
+ }
182
+ if (status === 403 || /resource not accessible|must have admin|SAML/i.test(msg)) {
183
+ return {
184
+ kind: 'permission',
185
+ resumo: `O GitHub negou a operação (403).${resumoFontes(env)}`,
186
+ proximoPasso: proximoPassoAuth(env, 403),
187
+ };
188
+ }
189
+ if (status === 404 || /could not resolve to a (repository|projectv2)/i.test(msg)) {
190
+ return {
191
+ kind: 'not_found',
192
+ resumo: `Recurso não encontrado — ou a credencial não o enxerga (o GitHub responde 404 nos dois casos).${resumoFontes(env)}`,
193
+ proximoPasso: 'Confira owner/repo/project no `.spec-wave.json` (`spec-wave doctor`) e se o token alcança ' +
194
+ 'o repositório — repositório transferido de dono é a causa típica.',
195
+ };
196
+ }
197
+ if (/overloaded|rate.?limit|\b429\b|\b529\b|\b5\d\d\b.*(anthropic|openrouter)/i.test(msg)) {
198
+ return {
199
+ kind: 'provider',
200
+ resumo: 'O provider de IA ficou indisponível ou limitou a taxa.',
201
+ proximoPasso: 'Transitório: reaplique o gatilho em alguns minutos (`spec-wave retry <issue>`).',
202
+ };
203
+ }
204
+ if (/fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up/i.test(msg)) {
205
+ return {
206
+ kind: 'network',
207
+ resumo: 'Falha de rede.',
208
+ proximoPasso: 'Transitório: reaplique o gatilho (`spec-wave retry <issue>`).',
209
+ };
210
+ }
211
+ if (/\.spec-wave\.json|tech_context|não parseia|corrompido/i.test(msg)) {
212
+ return {
213
+ kind: 'config',
214
+ resumo: 'Configuração do repositório inválida ou incompleta.',
215
+ proximoPasso: 'Rode `spec-wave doctor` no repositório e corrija os itens ✗.',
216
+ };
217
+ }
218
+ return {
219
+ kind: 'unknown',
220
+ resumo: 'Causa não classificada.',
221
+ proximoPasso: 'Veja o log do run. Depois de corrigir, reaplique o gatilho com `spec-wave retry <issue>`.',
222
+ };
223
+ }
224
+
225
+ function resumoFontes(env) {
226
+ const fontes = tokenSources(env);
227
+ if (env.GITHUB_ACTIONS !== 'true' || !fontes.length) return '';
228
+ return ` Credenciais deste passo: ${fontes.map(f => `${f.env} ← ${f.source}`).join(', ')}.`;
229
+ }
230
+
231
+ /**
232
+ * Corpo do comentário de falha na issue (função PURA). Uma forma só para os
233
+ * comandos que comentam a própria falha e para o `report-failure` do workflow.
234
+ *
235
+ * @param {object} p
236
+ * @param {string} p.titulo ex.: "Falha ao gerar a spec.md"
237
+ * @param {string} p.message mensagem do erro
238
+ * @param {{kind: string, resumo: string, proximoPasso: string}} p.causa
239
+ * @param {string|null} [p.trigger] label de gatilho removida
240
+ * @param {string|null} [p.runUrl]
241
+ * @param {string|null} [p.issueNumber]
242
+ * @returns {string}
243
+ */
244
+ export function renderFailureComment({ titulo, message, causa, trigger = null, runUrl = null, issueNumber = null }) {
245
+ const linhas = [
246
+ `❌ **${titulo}**`,
247
+ '',
248
+ `**Causa provável (${causa.kind}):** ${causa.resumo}`,
249
+ `**Próximo passo:** ${causa.proximoPasso.replace('<issue>', issueNumber ?? '<issue>')}`,
250
+ '',
251
+ ];
252
+ if (message) linhas.push('```', String(message).slice(0, 6000), '```', '');
253
+ if (runUrl) linhas.push(`Log do run: ${runUrl}`, '');
254
+ if (trigger) {
255
+ linhas.push(`A label \`${trigger}\` foi removida para destravar o gatilho — ` +
256
+ `adicione-a de novo (ou \`spec-wave retry ${issueNumber ?? '<issue>'}\`) para tentar outra vez.`);
257
+ }
258
+ return linhas.join('\n').trimEnd();
259
+ }
260
+
261
+ /** URL do run do Actions em curso, ou null fora dele (função PURA). */
262
+ export function actionsRunUrl(env = process.env) {
263
+ const { GITHUB_SERVER_URL: srv, GITHUB_REPOSITORY: repo, GITHUB_RUN_ID: id } = env;
264
+ return srv && repo && id ? `${srv}/${repo}/actions/runs/${id}` : null;
265
+ }
266
+
267
+ /** Caminho do registro de falha, ou null fora do Actions (função PURA). */
268
+ export function failureRecordPath(env = process.env) {
269
+ return env.RUNNER_TEMP ? path.join(env.RUNNER_TEMP, FAILURE_RECORD_FILE) : null;
270
+ }
271
+
272
+ /** Grava o registro. Nunca lança — diagnóstico não pode virar a falha. */
273
+ export function writeFailureRecord(err, env = process.env) {
274
+ const alvo = failureRecordPath(env);
275
+ if (!alvo) return;
276
+ try {
277
+ // A causa é gravada INTEIRA, classificada com o `env` DESTE passo — o único
278
+ // que sabe de onde veio cada token (`SPEC_WAVE_*_SOURCE`) e que ainda tem o
279
+ // objeto do erro (`status`). O `report-failure` roda com outro `env`.
280
+ const causa = classifyFailure(err, env);
281
+ writeFileSync(alvo, JSON.stringify({
282
+ message: String(err?.message ?? err ?? ''),
283
+ kind: causa.kind,
284
+ resumo: causa.resumo,
285
+ proximoPasso: causa.proximoPasso,
286
+ // O comando já comentou na issue (generate-*, decompose): o passo de
287
+ // relatório não repete.
288
+ notified: Boolean(err?.issueNotified),
289
+ at: new Date().toISOString(),
290
+ }, null, 2));
291
+ } catch {
292
+ // RUNNER_TEMP ilegível — o log continua tendo a mensagem
293
+ }
294
+ }
295
+
296
+ /** Lê o registro. `null` quando não existe (a falha foi antes da CLI). */
297
+ export function readFailureRecord(env = process.env) {
298
+ const alvo = failureRecordPath(env);
299
+ if (!alvo || !existsSync(alvo)) return null;
300
+ try {
301
+ return JSON.parse(readFileSync(alvo, 'utf-8'));
302
+ } catch {
303
+ return null;
304
+ }
305
+ }
306
+
307
+ /**
308
+ * Fim de comando que falhou: mensagem, causa provável, registro para o passo
309
+ * de relatório, exit 1. É o que o `cli.mjs` chama em todo `.catch`.
310
+ */
311
+ export function exitWithFailure(err) {
312
+ console.error(err?.message ?? String(err));
313
+ const causa = classifyFailure(err);
314
+ if (causa.kind !== 'unknown') {
315
+ console.error(`\nCausa provável (${causa.kind}): ${causa.resumo}\nPróximo passo: ${causa.proximoPasso}`);
316
+ }
317
+ writeFailureRecord(err);
318
+ process.exit(1);
319
+ }
@@ -0,0 +1,46 @@
1
+ // Eventos de progresso por Task para o spec-wave-agent (RFC-008).
2
+ //
3
+ // A tela Development mostra o andamento de uma Feature como barra de
4
+ // progresso, e a unidade dela é a TASK. O dev-agent não tem como saber que uma
5
+ // Task terminou olhando para o executor: quem sabe é a CLI, no `task done` e
6
+ // no fim de um `implement <story>`. Então, sob o agente (que define
7
+ // SPEC_WAVE_STREAM_DIR), a CLI acrescenta uma linha JSON por acontecimento em
8
+ // `<dir>/progress.jsonl`, e o agente acompanha o arquivo e reporta.
9
+ //
10
+ // O arquivo é só um SINAL: o retrato completo (quantas Tasks a Feature tem e
11
+ // quais já estão concluídas) vem do `spec-wave progress <feature> --json`.
12
+ // Repetir um evento é inofensivo — o agente guarda o conjunto de Tasks
13
+ // concluídas, não um contador.
14
+ //
15
+ // Sem SPEC_WAVE_STREAM_DIR, nada acontece.
16
+
17
+ import { appendFileSync, mkdirSync } from 'node:fs';
18
+ import path from 'node:path';
19
+ import { STREAM_DIR_ENV } from './implement-stream.mjs';
20
+
21
+ export const PROGRESS_FILE = 'progress.jsonl';
22
+
23
+ export function progressFileFor(dir) {
24
+ return path.join(dir, PROGRESS_FILE);
25
+ }
26
+
27
+ /**
28
+ * Acrescenta um evento ao arquivo de progresso. Melhor esforço: falha de disco
29
+ * não pode derrubar a implementação nem o `task done` — só atrasa a barra.
30
+ *
31
+ * @param {{event: 'task_done'|'story_done', task?: number, story?: number, tasks?: number[]}} event
32
+ * @param {Record<string, string|undefined>} [env]
33
+ * @returns {boolean} true quando a linha foi gravada
34
+ */
35
+ export function emitProgress(event, env = process.env) {
36
+ const dir = env[STREAM_DIR_ENV];
37
+ if (!dir) return false;
38
+ try {
39
+ mkdirSync(dir, { recursive: true });
40
+ // Uma escrita por linha (O_APPEND): stories em paralelo não se intercalam.
41
+ appendFileSync(progressFileFor(dir), `${JSON.stringify(event)}\n`);
42
+ return true;
43
+ } catch {
44
+ return false;
45
+ }
46
+ }
@@ -0,0 +1,55 @@
1
+ // O repositório do config ainda é ESTE repositório?
2
+ //
3
+ // Caso real (Nuviumdigital/semseguro): o repo foi transferido de uma conta
4
+ // pessoal para a org. O `.spec-wave.json` seguiu apontando para o dono antigo
5
+ // (owner, repo e o Project pessoal dele) e o doctor mostrou, em linhas
6
+ // separadas, "Token enxerga Nuviumdigital/semseguro" e "Owner renatolinux é
7
+ // conta pessoal" — os dois sintomas, sem nunca cruzá-los. A API do GitHub
8
+ // SEGUE o redirecionamento de repo transferido, então o nome que ela devolve
9
+ // é o atual. Basta comparar.
10
+ //
11
+ // O `git remote origin` NÃO é evidência de transferência: num fork ele aponta
12
+ // para `alice/hub` com o config (correto) em `acme/hub`. Acusar isso mandava o
13
+ // contribuidor rodar o `relink`, que reescreveria owner/repo para o fork. O
14
+ // remote divergente é só observação (`remoteDiffers`).
15
+
16
+ import { execSync } from 'node:child_process';
17
+
18
+ /** `owner/repo` de uma URL de remote do GitHub (função PURA); null se não for. */
19
+ export function parseGithubRemote(url) {
20
+ const m = /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(String(url || '').trim());
21
+ return m ? `${m[1]}/${m[2]}` : null;
22
+ }
23
+
24
+ /** `owner/repo` do `origin` do clone em `cwd`, ou null. Nunca lança. */
25
+ export function gitRemoteRepo(cwd = process.cwd()) {
26
+ try {
27
+ const url = execSync('git remote get-url origin', { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
28
+ .toString().trim();
29
+ return parseGithubRemote(url);
30
+ } catch {
31
+ return null;
32
+ }
33
+ }
34
+
35
+ /**
36
+ * Divergência entre o config e o repositório real (função PURA).
37
+ *
38
+ * Compara sem caixa: o GitHub trata `SemSeguro` e `semseguro` como o mesmo
39
+ * repositório, e acusar isso seria ruído.
40
+ *
41
+ * @param {object} p
42
+ * @param {string} p.configured `owner/repo` do .spec-wave.json
43
+ * @param {string|null} [p.apiName] nome que a API devolveu (segue transferência)
44
+ * @param {string|null} [p.remote] `owner/repo` do git remote
45
+ * @returns {{moved: boolean, actual: string|null, via: string[], remoteDiffers: boolean}}
46
+ * `moved` só pela API: o repo CONFIGURADO resolveu para outro nome.
47
+ * `remoteDiffers`: o `origin` não é o repo que a API devolveu (ou, sem a
48
+ * resposta dela, o do config) — fork ou clone de outro lugar; nunca `moved`.
49
+ */
50
+ export function detectRepoMove({ configured, apiName = null, remote = null }) {
51
+ const norm = s => String(s || '').toLowerCase();
52
+ const moved = Boolean(apiName) && norm(apiName) !== norm(configured);
53
+ const remoteDiffers = Boolean(remote) && norm(remote) !== norm(apiName || configured);
54
+ return { moved, actual: moved ? apiName : null, via: moved ? ['api'] : [], remoteDiffers };
55
+ }