@spec-wave/cli 1.7.5 → 1.8.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 (52) 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 +93 -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/init.mjs +2 -2
  16. package/src/commands/preflight.mjs +38 -2
  17. package/src/commands/relink.mjs +105 -0
  18. package/src/commands/report-failure.mjs +99 -0
  19. package/src/commands/retry.mjs +91 -0
  20. package/src/commands/update.mjs +70 -0
  21. package/src/config.mjs +8 -8
  22. package/src/lib/cited-paths.mjs +89 -0
  23. package/src/lib/claude.mjs +4 -2
  24. package/src/lib/cli-line.mjs +153 -0
  25. package/src/lib/cli-ref.mjs +53 -2
  26. package/src/lib/failure-report.mjs +319 -0
  27. package/src/lib/repo-identity.mjs +55 -0
  28. package/src/lib/spec-index.mjs +114 -0
  29. package/src/lib/tech-context.mjs +144 -5
  30. package/src/plugin/.claude-plugin/plugin.json +1 -1
  31. package/src/plugin/skills/plan/SKILL.md +1 -1
  32. package/src/plugin/skills/plan/reference/tech-context.md +12 -4
  33. package/src/plugin/skills/setup/SKILL.md +1 -1
  34. package/src/plugin/skills/spec/model-prompt.md +8 -1
  35. package/src/plugins/scm-github/index.mjs +8 -1
  36. package/src/plugins/tracker-github-projects/index.mjs +11 -4
  37. package/src/ports/tracker.mjs +2 -1
  38. package/src/setup/labels.mjs +5 -3
  39. package/src/setup/project.mjs +5 -3
  40. package/src/templates/config/tech_context.yml +29 -25
  41. package/src/templates/skill/SKILL.md +27 -9
  42. package/src/templates/skill/core.md +25 -7
  43. package/src/templates/workflows/code-review.yml +1 -0
  44. package/src/templates/workflows/critique.yml +11 -0
  45. package/src/templates/workflows/decompose.yml +27 -0
  46. package/src/templates/workflows/generate-bug.yml +26 -0
  47. package/src/templates/workflows/generate-plan.yml +26 -0
  48. package/src/templates/workflows/generate-qa-plan.yml +27 -0
  49. package/src/templates/workflows/generate-spec.yml +26 -0
  50. package/src/templates/workflows/pr-events.yml +11 -1
  51. package/src/templates/workflows/qa.yml +1 -0
  52. package/src/templates/workflows/validate.yml +11 -0
@@ -0,0 +1,99 @@
1
+ // `spec-wave report-failure` — o passo `if: failure()` dos workflows de fluxo.
2
+ //
3
+ // Leva a falha até a issue quando o comando que falhou NÃO a comentou: falha
4
+ // antes da CLI (instalação, checkout) ou num passo que não é de geração (o
5
+ // `workspace prepare`, que foi o caso do 401 no semseguro). Quando o comando já
6
+ // comentou, o registro em `$RUNNER_TEMP` diz isso e aqui não se repete nada.
7
+ //
8
+ // Também remove a label de gatilho: com ela aplicada, reaplicá-la não emite
9
+ // evento `labeled`, e a issue vira beco sem saída — mesmo motivo do `catch`
10
+ // dos generate-*.
11
+ //
12
+ // NUNCA falha: o job já está vermelho, e um relatório que derruba o relatório
13
+ // esconde a causa original atrás de um erro novo.
14
+
15
+ import { resolveToken } from '../api/auth.mjs';
16
+ import { resolveFlowContext } from '../lib/flow-run.mjs';
17
+ import {
18
+ actionsRunUrl, classifyFailure, readFailureRecord, renderFailureComment,
19
+ } from '../lib/failure-report.mjs';
20
+ import { requireTracker } from '../ports/index.mjs';
21
+
22
+ /**
23
+ * A causa que o PASSO QUE FALHOU registrou, ou — só para registro sem ela — a
24
+ * reclassificação da mensagem (função PURA).
25
+ *
26
+ * O registro vence porque o `env` deste passo NÃO é o do passo que falhou: o
27
+ * `report-failure` roda com o GITHUB_TOKEN automático e sem `SPEC_WAVE_*_SOURCE`.
28
+ * Reclassificar aqui trocava o diagnóstico — um GH_PROJECT_TOKEN expirado virava
29
+ * "o GITHUB_TOKEN automático não expira", que é o conselho oposto.
30
+ */
31
+ function causaDoRegistro(record, env) {
32
+ if (record?.resumo && record?.proximoPasso) {
33
+ return { kind: record.kind ?? 'unknown', resumo: record.resumo, proximoPasso: record.proximoPasso };
34
+ }
35
+ return classifyFailure(record?.message ?? '', env);
36
+ }
37
+
38
+ /**
39
+ * O que fazer com o registro (função PURA).
40
+ *
41
+ * @param {{message?: string, kind?: string, resumo?: string, proximoPasso?: string, notified?: boolean}|null} record
42
+ * @param {Record<string,string|undefined>} [env] só para o registro sem causa gravada
43
+ * @returns {{comentar: boolean, message: string|null, causa: object}}
44
+ */
45
+ export function planFailureReport(record, env = process.env) {
46
+ if (record?.notified) return { comentar: false, message: record.message ?? null, causa: causaDoRegistro(record, env) };
47
+ if (!record) {
48
+ return {
49
+ comentar: true,
50
+ message: null,
51
+ causa: {
52
+ kind: 'workflow',
53
+ resumo: 'O workflow falhou antes de a CLI registrar um erro (instalação, checkout ou passo intermediário).',
54
+ proximoPasso: 'Veja o passo vermelho no log do run. Depois de corrigir, reaplique o gatilho com ' +
55
+ '`spec-wave retry <issue>`.',
56
+ },
57
+ };
58
+ }
59
+ return { comentar: true, message: record.message ?? null, causa: causaDoRegistro(record, env) };
60
+ }
61
+
62
+ /**
63
+ * @param {object} params
64
+ * @param {string|number} params.issue
65
+ * @param {string} [params.label] label de gatilho do run (removida para destravar)
66
+ * @param {string} [params.step] nome da etapa, para o título ("Falha no generate-spec")
67
+ * @param {object} [params.deps] `tracker`, `readRecord`, `env`
68
+ */
69
+ export async function reportFailure({ issue, label = null, step = null, deps = {} }) {
70
+ const env = deps.env ?? process.env;
71
+ try {
72
+ const plano = planFailureReport((deps.readRecord ?? readFailureRecord)(env), env);
73
+ if (!plano.comentar) {
74
+ console.log('A falha já foi comentada na issue pelo próprio comando — nada a repetir.');
75
+ return { commented: false };
76
+ }
77
+ const token = await resolveToken({ quiet: true });
78
+ const { owner, repo } = resolveFlowContext({ command: 'report-failure', env });
79
+ const tracker = await requireTracker({ token, owner, repo, deps });
80
+ const ref = { key: String(issue) };
81
+ if (label) await tracker.removeTag({ ref, tag: label }).catch(() => {});
82
+ await tracker.addComment({
83
+ ref,
84
+ body: renderFailureComment({
85
+ titulo: step ? `Falha no ${step}` : 'Falha no workflow do spec-wave',
86
+ message: plano.message,
87
+ causa: plano.causa,
88
+ trigger: label,
89
+ runUrl: actionsRunUrl(env),
90
+ issueNumber: String(issue),
91
+ }),
92
+ });
93
+ console.log(`Falha comentada na issue #${issue} (causa: ${plano.causa.kind}).`);
94
+ return { commented: true, kind: plano.causa.kind };
95
+ } catch (err) {
96
+ console.warn(`⚠️ Não consegui comentar a falha na issue #${issue}: ${err.message}`);
97
+ return { commented: false, error: err.message };
98
+ }
99
+ }
@@ -0,0 +1,91 @@
1
+ // `spec-wave retry <issue>` — dispara de novo a etapa atual de uma issue.
2
+ //
3
+ // `gh run rerun` não serve: ele reexecuta o COMMIT ORIGINAL do run, então
4
+ // correções já mergeadas (um override de prompt, um workflow atualizado) ficam
5
+ // de fora — foi o que aconteceu no semseguro. O gatilho do fluxo é a label, e o
6
+ // evento `labeled` só sai quando a label ENTRA: com ela ainda aplicada (falha
7
+ // antes do comando, que é quem a remove), reaplicar não faz nada. Aqui a label
8
+ // sai e volta, e o run novo pega o estado atual da branch default.
9
+ //
10
+ // Recusa no Actions: label aplicada com o GITHUB_TOKEN não dispara workflow
11
+ // (regra do GitHub contra recursão), então o retry "funcionaria" sem efeito.
12
+ // Recusa no modo local: ali as labels não disparam nada — o caminho é `run`.
13
+
14
+ import chalk from 'chalk';
15
+
16
+ import { resolveToken } from '../api/auth.mjs';
17
+ import { LABEL_DECOMPOSE_APPLY, labelNames } from '../config.mjs';
18
+ import { configuredMode } from '../lib/execution-mode.mjs';
19
+ import { isActionsRun, resolveFlowContext } from '../lib/flow-run.mjs';
20
+ import { STEPS } from '../lib/next-step.mjs';
21
+ import { requireTracker } from '../ports/index.mjs';
22
+
23
+ export const RETRY_TRIGGERS = [...new Set(Object.values(STEPS).map(s => s.trigger).filter(Boolean))];
24
+
25
+ /**
26
+ * Qual label reaplicar (função PURA).
27
+ *
28
+ * @param {object} p
29
+ * @param {string[]} p.labels labels atuais da issue
30
+ * @param {string|null} [p.label] label pedida explicitamente
31
+ * @param {boolean} [p.force] aceita o `decompose-apply`
32
+ * @returns {{label: string|null, present: boolean, error: string|null}}
33
+ */
34
+ export function planRetry({ labels = [], label = null, force = false }) {
35
+ const presentes = labels.filter(l => RETRY_TRIGGERS.includes(l));
36
+ let alvo = label;
37
+ if (alvo && !RETRY_TRIGGERS.includes(alvo)) {
38
+ return { label: null, present: false, error: `"${alvo}" não é label de gatilho. Use uma de: ${RETRY_TRIGGERS.join(', ')}.` };
39
+ }
40
+ if (!alvo) {
41
+ if (presentes.length > 1) {
42
+ return { label: null, present: false, error: `A issue tem ${presentes.length} labels de gatilho (${presentes.join(', ')}) — escolha com --label.` };
43
+ }
44
+ if (presentes.length === 0) {
45
+ return {
46
+ label: null, present: false,
47
+ error: 'A issue não tem label de gatilho aplicada (o comando que falhou a removeu). ' +
48
+ `Diga qual etapa repetir com --label: ${RETRY_TRIGGERS.join(', ')}.`,
49
+ };
50
+ }
51
+ alvo = presentes[0];
52
+ }
53
+ if (alvo === LABEL_DECOMPOSE_APPLY && !force) {
54
+ return {
55
+ label: null, present: false,
56
+ error: `\`${LABEL_DECOMPOSE_APPLY}\` cria issues: se o run anterior criou parte delas e o guard de ` +
57
+ 'idempotência não pegou, repetir DUPLICA. Confira as sub-issues e rode de novo com --force.',
58
+ };
59
+ }
60
+ return { label: alvo, present: labels.includes(alvo), error: null };
61
+ }
62
+
63
+ /**
64
+ * @param {string|number} issue
65
+ * @param {{label?: string, force?: boolean, deps?: object}} [options]
66
+ */
67
+ export async function retry(issue, { label = null, force = false, deps = {} } = {}) {
68
+ if (isActionsRun()) {
69
+ throw new Error('`spec-wave retry` não roda no GitHub Actions: label aplicada pelo GITHUB_TOKEN não dispara workflow.');
70
+ }
71
+ const { owner, repo, config } = resolveFlowContext({ command: 'retry' });
72
+ if (configuredMode(config) === 'local') {
73
+ throw new Error(`Modo local: as labels não disparam workflow. Use \`spec-wave run ${issue}\`.`);
74
+ }
75
+ const token = await resolveToken();
76
+ const tracker = await requireTracker({ token, owner, repo, deps });
77
+ const ref = { key: String(issue) };
78
+ const item = await tracker.getWorkItem({ ref });
79
+
80
+ const plano = planRetry({ labels: labelNames(item), label, force });
81
+ if (plano.error) throw new Error(`#${issue}: ${plano.error}`);
82
+
83
+ // Sai e volta: é a ENTRADA da label que emite `labeled`.
84
+ if (plano.present) await tracker.removeTag({ ref, tag: plano.label });
85
+ await tracker.addTag({ ref, tag: plano.label });
86
+ console.log(
87
+ `${chalk.green('✓')} #${issue}: \`${plano.label}\` ${plano.present ? 'removida e reaplicada' : 'aplicada'} — ` +
88
+ `o workflow roda sobre o estado atual da branch default de ${owner}/${repo}.`
89
+ );
90
+ return { label: plano.label };
91
+ }
@@ -333,6 +333,62 @@ async function applyLabels(token, owner, repo, labelDiff, forceLabels = false) {
333
333
  return done;
334
334
  }
335
335
 
336
+ /**
337
+ * O config sem o que o próprio `update` regrava (função PURA). `null` quando
338
+ * não é JSON — aí quem chama compara o texto cru.
339
+ */
340
+ function configSemVersao(raw) {
341
+ try {
342
+ const { version: _v, ...resto } = JSON.parse(raw);
343
+ return JSON.stringify(resto);
344
+ } catch {
345
+ return null;
346
+ }
347
+ }
348
+
349
+ /**
350
+ * PRs abertos contra `base` que MEXEM no `.spec-wave.json`. Só usa operações
351
+ * da porta (listar PRs, ler arquivo numa ref, comparar branches); best-effort:
352
+ * qualquer falha vira lista vazia, e o teto evita pagar uma leitura por PR num
353
+ * repositório com dezenas abertos.
354
+ *
355
+ * "O config da head difere do da PONTA da base" não basta: toda branch apenas
356
+ * ATRASADA difere, porque cada `update` regrava `version` na base — e o aviso
357
+ * listaria quase todo PR antigo. A porta não expõe o merge-base nem os
358
+ * arquivos do PR, então a decisão sai do `compare`:
359
+ * • `ahead` — a head contém a ponta da base; diferença é mudança do PR. Exato.
360
+ * • `diverged` (ou comparação indisponível) — a diferença pode ser só atraso.
361
+ * Conta apenas o que difere ALÉM de `version`, o campo que o `update`
362
+ * regrava. Perde o PR atrasado que só mexe em `version`; em troca, não
363
+ * acusa todo PR antigo.
364
+ * • `behind`/`identical` — a head não tem commit próprio: não mexe em nada.
365
+ *
366
+ * @returns {Promise<Array<{number: string, headRef: string}>>}
367
+ */
368
+ export async function openPrsTouchingConfig({ scm, base, baseContent, branch, limit = 20 }) {
369
+ try {
370
+ const abertos = (await scm.listOpenPullRequests())
371
+ .filter(pr => pr.headRef && pr.headRef !== branch && (!pr.baseRef || pr.baseRef === base))
372
+ .slice(0, limit);
373
+ const semVersaoDaBase = configSemVersao(baseContent);
374
+ // Em paralelo: são leituras independentes, e o teto (`limit`) já limita o
375
+ // leque. `Promise.all` preserva a ordem da listagem.
376
+ const mexe = await Promise.all(abertos.map(async (pr) => {
377
+ const conteudo = await scm.readFile({ path: CONFIG_FILE, ref: pr.headRef }).catch(() => null);
378
+ if (conteudo == null || conteudo === baseContent) return false;
379
+ // `async` em volta: um `compare` que lance SINCRONAMENTE não passaria pelo `.catch`.
380
+ const status = await (async () => scm.compare({ base, head: pr.headRef }))().catch(() => null);
381
+ if (status === 'ahead') return true;
382
+ if (status === 'behind' || status === 'identical') return false;
383
+ const semVersao = configSemVersao(conteudo);
384
+ return semVersao == null || semVersaoDaBase == null || semVersao !== semVersaoDaBase;
385
+ }));
386
+ return abertos.filter((_, i) => mexe[i]).map(pr => ({ number: pr.number, headRef: pr.headRef }));
387
+ } catch {
388
+ return [];
389
+ }
390
+ }
391
+
336
392
  export async function update(options = {}) {
337
393
  p.intro(chalk.bold(`spec-wave update (CLI v${CLI_VERSION})`));
338
394
 
@@ -483,6 +539,20 @@ export async function update(options = {}) {
483
539
  );
484
540
  prMode = false;
485
541
  }
542
+ // Outro PR aberto mexendo no .spec-wave.json: as linhas de `version` e de
543
+ // `owner` são adjacentes, e os dois PRs conflitam no merge (caso real).
544
+ if (prMode) {
545
+ const outros = await openPrsTouchingConfig({
546
+ scm: await scmDe(tk, owner, repo), base, baseContent: remoteConfigRaw, branch,
547
+ });
548
+ if (outros.length > 0) {
549
+ p.log.warn(
550
+ `PR(s) aberto(s) que também alteram o ${CONFIG_FILE}: ` +
551
+ `${outros.map(pr => `#${pr.number} (${pr.headRef})`).join(', ')}. ` +
552
+ 'Mergeie esse(s) antes — ou espere conflito no merge deste.'
553
+ );
554
+ }
555
+ }
486
556
  }
487
557
 
488
558
  // 2d) Skill: a BASE versiona alguma destas cópias?
package/src/config.mjs CHANGED
@@ -69,16 +69,16 @@ export const MODEL_LABEL_PREFIX = 'spec-wave:model:';
69
69
  // obrigar cada projeto a inventar a própria nomenclatura.
70
70
  //
71
71
  // O mapa é POR BACKEND, não por provider, porque o que ele distingue é o
72
- // formato do id: a OpenRouter usa slug com "/" (anthropic/claude-opus-5) e a
73
- // Anthropic usa o id nu (claude-opus-5). Sugerir o formato errado geraria
72
+ // formato do id: a OpenRouter usa slug com "/" (anthropic/claude-opus-5.5) e a
73
+ // Anthropic usa o id nu (claude-opus-5-5). Sugerir o formato errado geraria
74
74
  // exatamente o aviso de "apelido com formato incompatível" que o doctor emite
75
75
  // na linha seguinte. `anthropic` e `claude-oauth` compartilham o mesmo mapa
76
76
  // porque compartilham o backend.
77
77
  export const RECOMMENDED_MODEL_ALIASES = {
78
78
  openrouter: {
79
- opus: 'anthropic/claude-opus-5',
80
- sonnet: 'anthropic/claude-sonnet-5',
81
- haiku: 'anthropic/claude-haiku-4.5',
79
+ opus: 'anthropic/claude-opus-5.5',
80
+ sonnet: 'anthropic/claude-sonnet-5.5',
81
+ haiku: 'anthropic/claude-haiku-5.5',
82
82
  glm: 'z-ai/glm-5.2',
83
83
  'kimi-k3': 'moonshotai/kimi-k3',
84
84
  'gpt-sol': 'openai/gpt-5.6-sol',
@@ -86,9 +86,9 @@ export const RECOMMENDED_MODEL_ALIASES = {
86
86
  },
87
87
  // Só os modelos da própria Anthropic — os demais não existem nessa API.
88
88
  anthropic: {
89
- opus: 'claude-opus-5',
90
- sonnet: 'claude-sonnet-5',
91
- haiku: 'claude-haiku-4-5',
89
+ opus: 'claude-opus-5-5',
90
+ sonnet: 'claude-sonnet-5-5',
91
+ haiku: 'claude-haiku-5-5',
92
92
  },
93
93
  };
94
94
 
@@ -0,0 +1,89 @@
1
+ // Caminhos de arquivo citados no corpo de uma issue que NÃO existem no repo.
2
+ //
3
+ // Caso real (Nuviumdigital/semseguro): todas as issues citavam
4
+ // "Fonte: docs/sem-seguro.md", e o arquivo nunca foi commitado. O modelo
5
+ // recebia a referência, procurava, não achava — e escrevia a spec sem a fonte,
6
+ // sem que ninguém soubesse. O preflight avisa antes de a rodada pagar modelo.
7
+
8
+ import { existsSync } from 'node:fs';
9
+ import path from 'node:path';
10
+
11
+ // Caminho relativo com ao menos um diretório OU precedido de "Fonte:", sempre
12
+ // com extensão. URL fica de fora (o lookbehind barra `://` e domínio).
13
+ //
14
+ // A extensão COMEÇA por letra: `1.0/2.0` e "Fonte: 14.5px" não são arquivos.
15
+ const EXT = '[A-Za-z][A-Za-z0-9]{0,5}';
16
+ const COM_DIR = new RegExp(`(?<![\\w/:.@-])((?:\\.\\/)?[\\w.-]+(?:\\/[\\w.-]+)+\\.${EXT})(?![\\w/])`, 'g');
17
+ const FONTE = new RegExp(`\\bfontes?\\s*:\\s*\`?((?:\\.\\/)?[\\w./-]+\\.${EXT})\`?(?![\\w/])`, 'gi');
18
+
19
+ // Segmento de DIRETÓRIO com cara de arquivo ou de domínio (`Node.js`,
20
+ // `api.example.com`): o token é "Node.js/React.js" ou uma URL sem esquema, não
21
+ // um caminho. `.github` e `v1.2` passam — começam por ponto ou têm "extensão"
22
+ // numérica. O custo é não avisar sobre um `conf.d/x.md`; o viés é deliberado:
23
+ // aviso falso muda o veredito do preflight, aviso que faltou não muda nada.
24
+ const DIR_COM_EXTENSAO = /^[\w-][\w.-]*\.[A-Za-z]{2,}$/;
25
+
26
+ /** O token tem forma de caminho de arquivo do repositório? (função PURA) */
27
+ function pareceCaminho(p) {
28
+ const partes = p.split('/');
29
+ const arquivo = partes.pop();
30
+ if (partes.some(d => DIR_COM_EXTENSAO.test(d))) return false;
31
+ // Nome sem letra antes da extensão é medida ou versão: `14.5px`, `1.2.x`.
32
+ return /[A-Za-z_]/.test(arquivo.slice(0, arquivo.lastIndexOf('.')));
33
+ }
34
+
35
+ /**
36
+ * Caminhos citados (função PURA), sem repetição, na ordem do texto.
37
+ *
38
+ * @param {string} body
39
+ * @returns {string[]}
40
+ */
41
+ export function citedPaths(body = '') {
42
+ const texto = String(body || '').replace(/https?:\/\/\S+/g, ' ');
43
+ const achados = [];
44
+ const add = (p) => {
45
+ const limpo = p.replace(/^\.\//, '').replace(/[.,;:]+$/, '');
46
+ if (pareceCaminho(limpo) && !achados.includes(limpo)) achados.push(limpo);
47
+ };
48
+ for (const m of texto.matchAll(FONTE)) add(m[1]);
49
+ for (const m of texto.matchAll(COM_DIR)) add(m[1]);
50
+ return achados;
51
+ }
52
+
53
+ /**
54
+ * Caminhos citados que não existem sob `root`.
55
+ *
56
+ * `multiRepo`: o hub tem repositórios de CÓDIGO vinculados, e a Feature pode
57
+ * citar um arquivo que mora num deles (`src/a/b.kt`) — que daqui não dá para
58
+ * conferir. Aí só é "ausente" o caminho cujo diretório de topo EXISTE no hub
59
+ * (ou que fica na raiz dele): `docs/sem-seguro.md` com `docs/` presente é falta
60
+ * de verdade; `src/…` sem `src/` no hub é, quase sempre, do repo de código.
61
+ *
62
+ * @param {string} body
63
+ * @param {string} root
64
+ * @param {(abs: string) => boolean} [exists]
65
+ * @param {{multiRepo?: boolean}} [opts]
66
+ * @returns {string[]}
67
+ */
68
+ export function missingCitedPaths(body, root, exists = existsSync, { multiRepo = false } = {}) {
69
+ const base = root || process.cwd();
70
+ return citedPaths(body).filter((rel) => {
71
+ if (exists(path.join(base, rel))) return false;
72
+ if (!multiRepo || !rel.includes('/')) return true;
73
+ return exists(path.join(base, rel.split('/')[0]));
74
+ });
75
+ }
76
+
77
+ /**
78
+ * Agrupa por caminho (função PURA): `{ 'docs/x.md': [37, 38] }`.
79
+ *
80
+ * @param {Array<{number: number, missing: string[]}>} porIssue
81
+ * @returns {Record<string, number[]>}
82
+ */
83
+ export function groupMissingPaths(porIssue = []) {
84
+ const out = {};
85
+ for (const { number, missing } of porIssue) {
86
+ for (const p of missing || []) (out[p] ||= []).push(number);
87
+ }
88
+ return out;
89
+ }
@@ -245,8 +245,10 @@ export { TruncatedOutputError, MaxTurnsError, isTruncationReason };
245
245
  // da Anthropic quebraria em toda requisição — daí a checagem no modelo, não no
246
246
  // provider. Aceita tanto o id primário (`claude-opus-4-8`) quanto o slug da
247
247
  // OpenRouter (`anthropic/claude-opus-4.8`).
248
+ // Haiku 5.5 também (o Haiku 4.5 ainda aceita). `opus-5`/`sonnet-5`/`fable-5`
249
+ // cobrem as 5.5 e 5.1 por prefixo.
248
250
  const MODELS_WITHOUT_SAMPLING_PARAMS =
249
- /claude-(?:opus-(?:4[.-]7|4[.-]8|5)|sonnet-5|fable-5|mythos-5)/i;
251
+ /claude-(?:opus-(?:4[.-]7|4[.-]8|5)|sonnet-5|haiku-5|fable-5|mythos-5)/i;
250
252
 
251
253
  /** O modelo ainda aceita `temperature`? (função PURA) */
252
254
  export function supportsTemperature(model) {
@@ -258,7 +260,7 @@ export function supportsTemperature(model) {
258
260
  // devolve 400. Sem strict, o tool_choice forçado ainda garante um bloco tool_use
259
261
  // com input JSON; quem fecha o contrato é o validador do schema.
260
262
  const MODELS_WITH_STRICT_SCHEMA =
261
- /claude-(?:fable-5|mythos-5|opus-5|opus-4[.-](?:1|5|8)|sonnet-5|haiku-4[.-]5)/i;
263
+ /claude-(?:fable-5|mythos-5|opus-5|opus-4[.-](?:1|5|8)|sonnet-5|haiku-4[.-]5|haiku-5)/i;
262
264
 
263
265
  /** O modelo aceita `strict: true` na definição de tool? (função PURA) */
264
266
  export function supportsStrictSchema(model) {
@@ -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
  *