@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.
- package/README.md +1 -1
- package/package.json +1 -1
- package/src/agent/errors.mjs +31 -1
- package/src/agent/openrouter-agent.mjs +25 -2
- package/src/api/github-graphql.mjs +31 -0
- package/src/api/github-rest.mjs +20 -0
- package/src/cli.mjs +93 -36
- package/src/commands/auth-check.mjs +72 -0
- package/src/commands/decompose.mjs +14 -2
- package/src/commands/doctor.mjs +139 -2
- package/src/commands/generate-bug.mjs +6 -6
- package/src/commands/generate-plan.mjs +9 -8
- package/src/commands/generate-qa-plan.mjs +9 -6
- package/src/commands/generate-spec.mjs +12 -7
- package/src/commands/init.mjs +2 -2
- package/src/commands/preflight.mjs +38 -2
- package/src/commands/relink.mjs +105 -0
- package/src/commands/report-failure.mjs +99 -0
- package/src/commands/retry.mjs +91 -0
- package/src/commands/update.mjs +70 -0
- package/src/config.mjs +8 -8
- package/src/lib/cited-paths.mjs +89 -0
- package/src/lib/claude.mjs +4 -2
- package/src/lib/cli-line.mjs +153 -0
- package/src/lib/cli-ref.mjs +53 -2
- package/src/lib/failure-report.mjs +319 -0
- package/src/lib/repo-identity.mjs +55 -0
- package/src/lib/spec-index.mjs +114 -0
- package/src/lib/tech-context.mjs +144 -5
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugin/skills/plan/SKILL.md +1 -1
- package/src/plugin/skills/plan/reference/tech-context.md +12 -4
- package/src/plugin/skills/setup/SKILL.md +1 -1
- package/src/plugin/skills/spec/model-prompt.md +8 -1
- package/src/plugins/scm-github/index.mjs +8 -1
- package/src/plugins/tracker-github-projects/index.mjs +11 -4
- package/src/ports/tracker.mjs +2 -1
- package/src/setup/labels.mjs +5 -3
- package/src/setup/project.mjs +5 -3
- package/src/templates/config/tech_context.yml +29 -25
- package/src/templates/skill/SKILL.md +27 -9
- package/src/templates/skill/core.md +25 -7
- package/src/templates/workflows/code-review.yml +1 -0
- package/src/templates/workflows/critique.yml +11 -0
- package/src/templates/workflows/decompose.yml +27 -0
- package/src/templates/workflows/generate-bug.yml +26 -0
- package/src/templates/workflows/generate-plan.yml +26 -0
- package/src/templates/workflows/generate-qa-plan.yml +27 -0
- package/src/templates/workflows/generate-spec.yml +26 -0
- package/src/templates/workflows/pr-events.yml +11 -1
- package/src/templates/workflows/qa.yml +1 -0
- 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
|
+
}
|
package/src/commands/update.mjs
CHANGED
|
@@ -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-
|
|
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-
|
|
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
|
+
}
|
package/src/lib/claude.mjs
CHANGED
|
@@ -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
|
+
}
|
package/src/lib/cli-ref.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
*
|