@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,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,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
+ }
@@ -0,0 +1,114 @@
1
+ // Índice das specs vizinhas, entregue PRONTO ao modelo do `generate-spec`.
2
+ //
3
+ // Existe por causa de um padrão medido: num hub com ~24 specs em
4
+ // `docs/features/`, três Features falharam 12 vezes com `error_max_turns`
5
+ // (Read×27–29, Glob×5–12, nenhuma escrita). O prompt mandava "procurar specs
6
+ // vizinhas" e o modelo tentava ler TODAS antes de escrever a primeira linha.
7
+ // O que ele procurava em cada uma era quase sempre o mesmo: do que aquela
8
+ // Feature trata e de quem ela depende. Isso cabe num índice — e o índice custa
9
+ // zero turnos.
10
+ //
11
+ // O índice NÃO substitui a leitura: é o mapa para o modelo escolher as poucas
12
+ // specs que valem um `Read` inteiro.
13
+
14
+ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
15
+ import path from 'node:path';
16
+
17
+ import { dependencySection } from './spec-audit.mjs';
18
+
19
+ export const SPEC_INDEX_DIR = 'docs/features';
20
+
21
+ // Tetos: o índice é para caber no prompt sem competir com a issue.
22
+ const MAX_ENTRIES = 80;
23
+ const MAX_OBJETIVO = 240;
24
+ const MAX_DEPS = 600;
25
+
26
+ /**
27
+ * Objetivo declarado na Visão Geral (função PURA): a linha do bullet
28
+ * "Objetivo", ou o primeiro parágrafo da seção quando o bullet não existe.
29
+ *
30
+ * @param {string} markdown
31
+ * @returns {string}
32
+ */
33
+ export function specObjective(markdown = '') {
34
+ const linhas = String(markdown).split('\n');
35
+ const bullet = linhas.find(l => /^\s*[-*]\s*\**objetivo\**\s*:?/i.test(l));
36
+ if (bullet) return compactar(bullet.replace(/^\s*[-*]\s*\**objetivo\**\s*:?\**\s*/i, ''), MAX_OBJETIVO);
37
+ const inicio = linhas.findIndex(l => /^#\s+vis[aã]o geral/i.test(l.trim()));
38
+ if (inicio === -1) return '';
39
+ const corpo = [];
40
+ for (const l of linhas.slice(inicio + 1)) {
41
+ if (/^#{1,6}\s/.test(l)) break;
42
+ if (!l.trim()) { if (corpo.length) break; continue; }
43
+ corpo.push(l.trim());
44
+ }
45
+ return compactar(corpo.join(' '), MAX_OBJETIVO);
46
+ }
47
+
48
+ function compactar(texto, max) {
49
+ const limpo = String(texto).replace(/\s+/g, ' ').trim();
50
+ return limpo.length > max ? `${limpo.slice(0, max - 1)}…` : limpo;
51
+ }
52
+
53
+ /**
54
+ * Entradas do índice a partir do disco. Nunca lança: diretório ausente ou
55
+ * arquivo ilegível somem do índice (o modelo ainda tem `Glob` para achar).
56
+ *
57
+ * @param {string} root raiz do hub
58
+ * @param {{excludeSlug?: string}} [opts] a própria Feature fica de fora
59
+ * @returns {Array<{path: string, objetivo: string, dependencias: string}>}
60
+ */
61
+ export function collectSpecIndex(root, { excludeSlug = null } = {}) {
62
+ const base = path.join(root || process.cwd(), SPEC_INDEX_DIR);
63
+ if (!existsSync(base)) return [];
64
+ let slugs;
65
+ try {
66
+ slugs = readdirSync(base).filter(s => s !== excludeSlug).sort();
67
+ } catch {
68
+ return [];
69
+ }
70
+ const entradas = [];
71
+ for (const slug of slugs) {
72
+ const abs = path.join(base, slug, 'spec.md');
73
+ try {
74
+ if (!statSync(abs).isFile()) continue;
75
+ const md = readFileSync(abs, 'utf-8');
76
+ const deps = dependencySection(md);
77
+ entradas.push({
78
+ path: `${SPEC_INDEX_DIR}/${slug}/spec.md`,
79
+ objetivo: specObjective(md),
80
+ dependencias: deps == null ? '' : compactar(deps.replace(/^#{1,6}\s+/gm, ''), MAX_DEPS),
81
+ });
82
+ } catch {
83
+ // spec.md ausente ou ilegível nesta Feature — segue sem ela
84
+ }
85
+ }
86
+ return entradas;
87
+ }
88
+
89
+ /**
90
+ * Seção markdown do índice para o prompt (função PURA). Vazio quando não há
91
+ * spec vizinha — aí a seção nem aparece.
92
+ *
93
+ * @param {Array<{path: string, objetivo: string, dependencias: string}>} entradas
94
+ * @returns {string}
95
+ */
96
+ export function renderSpecIndex(entradas = []) {
97
+ if (!entradas.length) return '';
98
+ const mostradas = entradas.slice(0, MAX_ENTRIES);
99
+ const linhas = [
100
+ '## Índice das specs existentes',
101
+ '',
102
+ `${entradas.length} spec(s) em \`${SPEC_INDEX_DIR}/\`. Use este índice para decidir quais ` +
103
+ 'poucas valem um `Read` — não abra todas.',
104
+ '',
105
+ ];
106
+ for (const e of mostradas) {
107
+ linhas.push(`- \`${e.path}\` — ${e.objetivo || '(sem objetivo declarado)'}`);
108
+ if (e.dependencias) linhas.push(` - Dependências: ${e.dependencias}`);
109
+ }
110
+ if (entradas.length > mostradas.length) {
111
+ linhas.push('', `(+${entradas.length - mostradas.length} spec(s) fora do índice — use \`Grep\` para achá-las.)`);
112
+ }
113
+ return linhas.join('\n');
114
+ }
@@ -21,6 +21,135 @@ const MIGRATION_DIRS = [
21
21
 
22
22
  const MAX_MIGRATIONS = 10;
23
23
 
24
+ // Marcador do scaffold. O `init` grava o template com ele na primeira linha, e
25
+ // enquanto ele existir o arquivo é um FORMULÁRIO, não a descrição do sistema.
26
+ export const TECH_CONTEXT_TEMPLATE_MARKER = 'spec-wave:template';
27
+
28
+ // O marcador só vale ONDE o scaffold o grava: como comentário que abre o
29
+ // arquivo. Casar a string em qualquer lugar bloqueava um arquivo preenchido que
30
+ // apenas a citasse ("# removi o spec-wave:template em 03/11").
31
+ const MARKER_LINE = new RegExp(`^#\\s*${TECH_CONTEXT_TEMPLATE_MARKER}(?![\\w-])`);
32
+
33
+ function hasTemplateMarker(raw) {
34
+ const primeira = String(raw).replace(/^/, '').split(/\r?\n/)
35
+ .find((l) => l.trim() !== '' && l.trim() !== '---');
36
+ return primeira !== undefined && MARKER_LINE.test(primeira.trim());
37
+ }
38
+
39
+ // Algum valor de verdade no YAML? String em branco, lista vazia e null não
40
+ // contam. `system_info.name` também não: o nome do sistema sozinho não descreve
41
+ // stack nenhum, e é o primeiro (às vezes o único) campo que alguém preenche.
42
+ function hasContent(value, caminho = '') {
43
+ if (value == null) return false;
44
+ if (typeof value === 'string') return value.trim() !== '';
45
+ if (Array.isArray(value)) return value.some((v) => hasContent(v, `${caminho}[]`));
46
+ if (typeof value === 'object') {
47
+ return Object.entries(value).some(([k, v]) => {
48
+ const filho = caminho ? `${caminho}.${k}` : k;
49
+ return filho !== 'system_info.name' && hasContent(v, filho);
50
+ });
51
+ }
52
+ return true; // número, booleano, data
53
+ }
54
+
55
+ /**
56
+ * Por que o tech_context não conta como preenchido — ou `null` se conta.
57
+ * (função PURA)
58
+ *
59
+ * Três formas de não estar preenchido, e as três aconteceram ou são um passo
60
+ * óbvio de quem segue a instrução do próprio scaffold:
61
+ * • `marker` — a linha `# spec-wave:template` ainda abre o arquivo;
62
+ * • `legacy-example` — o EXEMPLO dos scaffolds anteriores, "Order Management
63
+ * System" em NestJS, PostgreSQL e Redis. Ele era sintaticamente perfeito, e
64
+ * foi lido como verdade: num cliente cujo stack é Kotlin Multiplatform +
65
+ * Amplify, as specs e os planos saíram falando de Postgres, Redis e
66
+ * microsserviços, porque ninguém editou o arquivo e nada avisou;
67
+ * • `empty` — nenhum campo além do nome tem valor. É o que sobra quando só a
68
+ * linha do marcador é apagada: sem este critério, `backend: ""` e
69
+ * `rbac_roles: []` entravam no prompt como contexto com autoridade.
70
+ *
71
+ * Um arquivo PREENCHIDO pelo time que por acaso mantenha um valor do exemplo
72
+ * não é template: o critério do exemplo é o par nome + backend, que só
73
+ * coincide se ninguém tocou na seção.
74
+ *
75
+ * @param {string|null} raw texto do arquivo
76
+ * @param {object|null} [parsed] o YAML já parseado (evita parsear duas vezes)
77
+ * @returns {'marker'|'legacy-example'|'empty'|null}
78
+ */
79
+ export function techContextTemplateReason(raw, parsed = undefined) {
80
+ if (raw == null) return null;
81
+ if (hasTemplateMarker(raw)) return 'marker';
82
+ let ctx = parsed;
83
+ if (ctx === undefined) {
84
+ try { ctx = yaml.load(String(raw)); } catch { return null; }
85
+ }
86
+ const info = ctx?.system_info;
87
+ if (info?.name === 'Order Management System' &&
88
+ info?.stack?.backend === 'Node.js (NestJS v10)') return 'legacy-example';
89
+ return hasContent(ctx) ? null : 'empty';
90
+ }
91
+
92
+ /** O tech_context ainda é o template do scaffold? Ver `techContextTemplateReason`. */
93
+ export function isTechContextTemplate(raw, parsed = undefined) {
94
+ return techContextTemplateReason(raw, parsed) !== null;
95
+ }
96
+
97
+ // Uma leitura, um parse: estado + conteúdo. `inspectTechContext` devolve só o
98
+ // estado; `readStaticContext` aproveita o `context` em vez de reler o arquivo.
99
+ function readTechContext(cwd) {
100
+ const base = { path: TECH_CONTEXT_PATH, reason: null, error: null, context: null };
101
+ const filePath = path.join(cwd, TECH_CONTEXT_PATH);
102
+ if (!existsSync(filePath)) return { ...base, state: 'missing' };
103
+ let raw;
104
+ let parsed;
105
+ try {
106
+ raw = readFileSync(filePath, 'utf-8');
107
+ parsed = yaml.load(raw);
108
+ } catch (err) {
109
+ return { ...base, state: 'invalid', error: err.message };
110
+ }
111
+ const reason = techContextTemplateReason(raw, parsed);
112
+ if (reason) return { ...base, state: 'template', reason };
113
+ return { ...base, state: 'filled', context: parsed };
114
+ }
115
+
116
+ /**
117
+ * Estado do tech_context no disco: `missing` | `invalid` | `template` | `filled`.
118
+ * `reason` só vem em `template` (ver `techContextTemplateReason`). Nunca lança.
119
+ *
120
+ * @param {string} [cwd]
121
+ * @returns {{state: 'missing'|'invalid'|'template'|'filled', path: string,
122
+ * reason: 'marker'|'legacy-example'|'empty'|null, error: string|null}}
123
+ */
124
+ export function inspectTechContext(cwd = process.cwd()) {
125
+ const { state, path: p, reason, error } = readTechContext(cwd);
126
+ return { state, path: p, reason, error };
127
+ }
128
+
129
+ /**
130
+ * Texto de orientação quando o arquivo não está preenchido (uma fonte só).
131
+ * O que fazer depende do motivo: mandar apagar a linha do marcador num arquivo
132
+ * antigo, que nunca a teve, deixa o usuário procurando o que não existe.
133
+ *
134
+ * @param {'marker'|'legacy-example'|'empty'|null} [reason]
135
+ */
136
+ export function techContextTemplateHint(reason = 'marker') {
137
+ const stack = 'o stack REAL do sistema (backend, frontend, banco, infra, autenticação)';
138
+ const fim = ' Enquanto isso, spec e plan são gerados SEM contexto técnico estático — ' +
139
+ 'o conteúdo do template nunca é injetado.';
140
+ if (reason === 'legacy-example') {
141
+ return `${TECH_CONTEXT_PATH} ainda traz o EXEMPLO dos scaffolds antigos ` +
142
+ `("Order Management System" em NestJS) (não preenchido): substitua-o por ${stack}.` + fim;
143
+ }
144
+ if (reason === 'empty') {
145
+ return `${TECH_CONTEXT_PATH} está com os campos em branco (não preenchido): ` +
146
+ `descreva ${stack} — só o nome do sistema não basta.` + fim;
147
+ }
148
+ return `${TECH_CONTEXT_PATH} ainda é o template do scaffold (não preenchido): ` +
149
+ `descreva ${stack} e apague a linha \`# ${TECH_CONTEXT_TEMPLATE_MARKER}\` ` +
150
+ 'que abre o arquivo.' + fim;
151
+ }
152
+
24
153
  // Leitura SILENCIOSA da fonte estática — para quem só consulta (o `audit` lê
25
154
  // as decisões de modelagem e ausência não é problema dele). `context: null`
26
155
  // distingue "não existe" de "existe vazio"; `error` só em falha de parse.
@@ -35,15 +164,21 @@ export function loadStaticTechContext(cwd = process.cwd()) {
35
164
  }
36
165
 
37
166
  // §4.1 — Fonte de verdade estática. Ausência não é erro: segue com {} e avisa.
167
+ // Template não preenchido também vira {} — injetar o exemplo é pior que nada.
168
+ // Devolve também o motivo, para quem monta o aviso na issue.
38
169
  function readStaticContext(cwd) {
39
- const { context, error } = loadStaticTechContext(cwd);
40
- if (context) return context;
41
- console.warn(error
170
+ const { state, reason, error, context } = readTechContext(cwd);
171
+ if (state === 'filled') return { context, reason: null };
172
+ if (state === 'template') {
173
+ console.warn(`⚠️ ${techContextTemplateHint(reason)}`);
174
+ return { context: {}, reason };
175
+ }
176
+ console.warn(state === 'invalid'
42
177
  ? `⚠️ Falha ao parsear ${TECH_CONTEXT_PATH}: ${error}. Ignorando.`
43
178
  : `⚠️ ${TECH_CONTEXT_PATH} não encontrado. ` +
44
179
  `O plano será gerado sem contexto técnico estático. ` +
45
180
  `Rode \`spec-wave init\` para gerar o scaffold.`);
46
- return {};
181
+ return { context: {}, reason: null };
47
182
  }
48
183
 
49
184
  // §4.2 — Augmentação dinâmica: migrations recentes + versões exatas de pacotes.
@@ -132,7 +267,7 @@ function isPlainObject(v) {
132
267
 
133
268
  // Monta o tech context completo. `cwd` default = process.cwd() (checkout do Action).
134
269
  export function buildTechContext({ issueBody = '', cwd = process.cwd() } = {}) {
135
- const staticContext = readStaticContext(cwd);
270
+ const { context: staticContext, reason: unfilledReason } = readStaticContext(cwd);
136
271
  const dynamic = readDynamicContext(cwd);
137
272
  const overrides = parseTechOverride(issueBody);
138
273
  const merged = deepMerge(staticContext, overrides);
@@ -142,6 +277,10 @@ export function buildTechContext({ issueBody = '', cwd = process.cwd() } = {}) {
142
277
  dynamic,
143
278
  overrides,
144
279
  merged,
280
+ // O arquivo existe mas é o template: quem gera o documento avisa na issue.
281
+ // `unfilledReason` diz por quê (marcador, exemplo antigo ou campos em branco).
282
+ unfilled: unfilledReason !== null,
283
+ unfilledReason,
145
284
  // String pronta para injetar no prompt: contexto efetivo + efêmeros.
146
285
  yaml: yaml.dump({ ...merged, _dynamic: dynamic }, { lineWidth: 120 }),
147
286
  };
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.7.5",
4
+ "version": "1.8.0",
5
5
  "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
6
6
  "author": {
7
7
  "name": "Astratech",