@spec-wave/cli 1.3.0 → 1.5.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 (59) hide show
  1. package/package.json +1 -1
  2. package/protocol/scm.v1.json +154 -0
  3. package/protocol/tracker.v1.json +175 -0
  4. package/src/api/github-rest.mjs +109 -0
  5. package/src/commands/audit.mjs +3 -4
  6. package/src/commands/code-review.mjs +11 -6
  7. package/src/commands/decompose.mjs +29 -9
  8. package/src/commands/doctor.mjs +389 -220
  9. package/src/commands/generate-bug.mjs +17 -7
  10. package/src/commands/generate-plan.mjs +21 -13
  11. package/src/commands/generate-qa-plan.mjs +19 -11
  12. package/src/commands/generate-spec.mjs +19 -6
  13. package/src/commands/implement.mjs +105 -49
  14. package/src/commands/init.mjs +36 -6
  15. package/src/commands/issue.mjs +6 -2
  16. package/src/commands/merge.mjs +31 -18
  17. package/src/commands/mode.mjs +18 -10
  18. package/src/commands/move.mjs +3 -3
  19. package/src/commands/order.mjs +30 -20
  20. package/src/commands/preflight.mjs +10 -5
  21. package/src/commands/qa-lead.mjs +41 -31
  22. package/src/commands/qa-run.mjs +83 -55
  23. package/src/commands/qa.mjs +10 -6
  24. package/src/commands/refresh.mjs +6 -3
  25. package/src/commands/repair-stage.mjs +1 -1
  26. package/src/commands/repo.mjs +7 -7
  27. package/src/commands/run.mjs +7 -4
  28. package/src/commands/story.mjs +3 -3
  29. package/src/commands/task.mjs +3 -3
  30. package/src/commands/triage.mjs +3 -3
  31. package/src/commands/uninstall.mjs +14 -5
  32. package/src/commands/update.mjs +47 -19
  33. package/src/commands/validate.mjs +3 -4
  34. package/src/commands/workspace.mjs +2 -2
  35. package/src/lib/artifact-publish.mjs +4 -3
  36. package/src/lib/board.mjs +22 -24
  37. package/src/lib/config-ports.mjs +114 -0
  38. package/src/lib/critique.mjs +11 -1
  39. package/src/lib/doc-source.mjs +16 -2
  40. package/src/lib/doctor-capabilities.mjs +168 -0
  41. package/src/lib/implement-board.mjs +6 -1
  42. package/src/lib/implement-stream.mjs +87 -0
  43. package/src/lib/pr-ready.mjs +24 -11
  44. package/src/lib/story-graph.mjs +26 -6
  45. package/src/lib/tag-registry.mjs +58 -0
  46. package/src/lib/usage-report.mjs +15 -2
  47. package/src/plugin/.claude-plugin/plugin.json +1 -1
  48. package/src/plugins/load.mjs +427 -0
  49. package/src/plugins/scm-github/index.mjs +71 -2
  50. package/src/plugins/tracker-github-projects/index.mjs +52 -10
  51. package/src/ports/capabilities.mjs +47 -0
  52. package/src/ports/index.mjs +347 -0
  53. package/src/ports/scm.mjs +39 -2
  54. package/src/ports/tracker.mjs +94 -3
  55. package/src/ports/types.mjs +59 -6
  56. package/src/setup/files.mjs +2 -2
  57. package/src/setup/labels.mjs +2 -2
  58. package/src/setup/project.mjs +2 -2
  59. package/src/ui/wizard.mjs +76 -1
@@ -0,0 +1,427 @@
1
+ // O loader de plugins — RFC-006 §9.2, Fase 2 bloco A.
2
+ //
3
+ // Este é o único arquivo que sabe DE ONDE um plugin vem. Mora em
4
+ // `src/plugins/` de propósito: `test/ports-boundary.test.mjs` isenta esse
5
+ // diretório das duas regras de barreira, e é aqui que o nome de um fornecedor
6
+ // pode aparecer sem ser acoplamento.
7
+ //
8
+ // ── O plugin embutido percorre o MESMO caminho ───────────────────────────────
9
+ //
10
+ // `github-projects` e `github` entram por uma tabela de embutidos e daí seguem
11
+ // pela mesma validação de um plugin de terceiro. Curto-circuitá-los faria todo
12
+ // este arquivo ser código morto até o primeiro plugin publicado — a classe de
13
+ // coisa que quebra em silêncio, e que os 1424 testes de hoje não exercitariam.
14
+ // Com a tabela, a suíte inteira passa por aqui.
15
+ //
16
+ // ── "não instalado" × "instalado e QUEBRADO" ─────────────────────────────────
17
+ //
18
+ // Os dois dão `ERR_MODULE_NOT_FOUND`, e só a MENSAGEM diz qual pacote faltou
19
+ // (medido, não suposto: um plugin que importa um pacote ausente reporta o pacote
20
+ // DELE). Ler o código do erro e seguir para o próximo candidato mandaria o
21
+ // usuário instalar algo que ele já tem.
22
+ //
23
+ // A separação é feita sem parsear mensagem: RESOLVER é uma etapa, CARREGAR é
24
+ // outra. Resolver falhou = não instalado, próximo candidato. Resolveu e carregar
25
+ // falhou = existe e está quebrado, PARA e reporta.
26
+ //
27
+ // ── E a resolução parte da RAIZ DO PROJETO ───────────────────────────────────
28
+ //
29
+ // `import.meta.resolve` resolve relativo a ESTE módulo. Rodando por `npx`, este
30
+ // módulo está num diretório temporário e o plugin que o usuário instalou está no
31
+ // `node_modules` dele — nunca seria encontrado. `createRequire(<root>/package.json)`
32
+ // resolve a partir do projeto, é estável, e honra `exports` inclusive de pacote
33
+ // ESM-only, porque resolver não é carregar.
34
+
35
+ import { createRequire } from 'node:module';
36
+ import { existsSync, readdirSync } from 'node:fs';
37
+ import path from 'node:path';
38
+ import { pathToFileURL } from 'node:url';
39
+
40
+ // Namespace do MÓDULO, não os símbolos soltos: é o módulo real que a validação
41
+ // tem de conferir. Montar aqui um objeto `{specWaveTrackerApi: 1, …}` a partir
42
+ // dos símbolos seria um falso que passa por construção — o mesmo defeito da
43
+ // porta falsa escrita à mão, e o embutido deixaria de exercitar o loader.
44
+ import * as trackerGithubProjects from './tracker-github-projects/index.mjs';
45
+ import * as scmGithub from './scm-github/index.mjs';
46
+ import { checkTrackerPort } from '../ports/tracker.mjs';
47
+ import { checkScmPort } from '../ports/scm.mjs';
48
+
49
+ /**
50
+ * A versão do contrato que este core fala.
51
+ *
52
+ * Um plugin publicado independentemente **vai** ficar para trás, e descobrir
53
+ * isso na primeira chamada de rede — no meio de um `decompose` que já gastou uma
54
+ * geração de IA — é o pior momento possível. Por isso a checagem é na carga.
55
+ */
56
+ export const TRACKER_API_VERSION = 1;
57
+ export const SCM_API_VERSION = 1;
58
+
59
+ /**
60
+ * O que um módulo de plugin exporta. O embutido declara o mesmo — ver o bloco
61
+ * "O que o LOADER lê" no fim de cada `index.mjs` de plugin.
62
+ */
63
+ const FORMA = Object.freeze({
64
+ tracker: Object.freeze({
65
+ versao: 'specWaveTrackerApi', esperada: TRACKER_API_VERSION,
66
+ kind: 'trackerKind', fabrica: 'createTracker', conferir: checkTrackerPort,
67
+ // Convenção de pacote da §9.2, nível 2.
68
+ escopado: k => `@spec-wave/tracker-${k}`,
69
+ }),
70
+ scm: Object.freeze({
71
+ versao: 'specWaveScmApi', esperada: SCM_API_VERSION,
72
+ kind: 'scmKind', fabrica: 'createScm', conferir: checkScmPort,
73
+ escopado: k => `@spec-wave/scm-${k}`,
74
+ }),
75
+ });
76
+
77
+ /** Os embutidos, indexados pelo `kind` que o próprio módulo declara. */
78
+ const EMBUTIDOS = Object.freeze({
79
+ tracker: Object.freeze({ [trackerGithubProjects.trackerKind]: trackerGithubProjects }),
80
+ scm: Object.freeze({ [scmGithub.scmKind]: scmGithub }),
81
+ });
82
+
83
+ /**
84
+ * O `kind` que o core assume enquanto o bloco D não o deriva do config legado.
85
+ *
86
+ * Exportados DAQUI para que `src/ports/index.mjs` não escreva um nome de
87
+ * fornecedor: o core não ramifica nem defaulta por fornecedor, e este arquivo é
88
+ * o único lugar onde esse nome pode aparecer (a barreira isenta `src/plugins/`).
89
+ */
90
+ export const DEFAULT_TRACKER_KIND = trackerGithubProjects.trackerKind;
91
+ export const DEFAULT_SCM_KIND = scmGithub.scmKind;
92
+
93
+ /**
94
+ * Os `kind` de plugin DISPONÍVEIS neste projeto — RFC-006 §9.3, Fase 2 bloco F.
95
+ *
96
+ * O embutido sempre entra. Os demais são descobertos pelas mesmas convenções da
97
+ * §9.2, na ordem inversa: em vez de resolver um `kind` conhecido, varre-se o que
98
+ * está instalado e deduz-se o `kind` do NOME.
99
+ *
100
+ * ── Por que o `init` precisa disto ──────────────────────────────────────────
101
+ *
102
+ * As duas perguntas da §9.3 só fazem sentido com mais de uma resposta. Com um
103
+ * fornecedor só — o caso de hoje — perguntar "qual tracker?" é ruído, e pior:
104
+ * sugere que os outros existem e que a escolha tem consequência. O `init` chama
105
+ * isto e **só pergunta quando há o que escolher**.
106
+ *
107
+ * Varredura de diretório, não `import()`: descobrir o que existe não pode custar
108
+ * carregar código de terceiro. A validação acontece na CARGA, depois da escolha.
109
+ *
110
+ * @param {object} params
111
+ * @param {'tracker'|'scm'} params.port
112
+ * @param {string} [params.root] raiz do projeto
113
+ * @returns {Array<{kind: string, origem: 'embutido'|'pacote'|'local', spec: string|null}>}
114
+ */
115
+ export function listPluginKinds({ port, root = process.cwd() }) {
116
+ const forma = FORMA[port];
117
+ if (!forma) return [];
118
+
119
+ const achados = Object.keys(EMBUTIDOS[port])
120
+ .map(kind => ({ kind, origem: 'embutido', spec: null }));
121
+ const vistos = new Set(achados.map(a => a.kind));
122
+
123
+ const acrescentar = (kind, origem, spec) => {
124
+ if (!kind || vistos.has(kind)) return;
125
+ vistos.add(kind);
126
+ achados.push({ kind, origem, spec });
127
+ };
128
+
129
+ // Nível 2: `@spec-wave/<porta>-<kind>` no escopo instalado.
130
+ const escopo = path.join(root, 'node_modules', '@spec-wave');
131
+ const prefixoEscopado = `${port}-`;
132
+ for (const nome of lerDir(escopo)) {
133
+ if (nome.startsWith(prefixoEscopado)) {
134
+ acrescentar(nome.slice(prefixoEscopado.length), 'pacote', `@spec-wave/${nome}`);
135
+ }
136
+ }
137
+
138
+ // Nível 3: `spec-wave-<kind>-plugin`. Ambíguo entre as portas por construção
139
+ // (o nome não diz a porta), então entra só se AINDA não houver esse `kind` —
140
+ // é o mesmo motivo pelo qual ele é o terceiro na resolução.
141
+ for (const nome of lerDir(path.join(root, 'node_modules'))) {
142
+ const m = /^spec-wave-(.+)-plugin$/.exec(nome);
143
+ if (m) acrescentar(m[1], 'pacote', nome);
144
+ }
145
+
146
+ // Nível 4: a fenda de desenvolvimento.
147
+ const fenda = path.join(root, '.spec-wave', 'plugins');
148
+ for (const nome of lerDir(fenda)) {
149
+ if (nome.startsWith(prefixoEscopado)) {
150
+ acrescentar(nome.slice(prefixoEscopado.length), 'local',
151
+ `./.spec-wave/plugins/${nome}/index.mjs`);
152
+ }
153
+ }
154
+
155
+ return achados;
156
+ }
157
+
158
+ /** `readdirSync` que devolve `[]` em vez de lançar — diretório ausente é normal. */
159
+ function lerDir(dir) {
160
+ try {
161
+ return readdirSync(dir);
162
+ } catch {
163
+ return [];
164
+ }
165
+ }
166
+
167
+ /**
168
+ * Os especificadores a tentar, em ordem (§9.2) — função PURA.
169
+ *
170
+ * **`package` explícito NÃO tem fallback.** Quem nomeia um pacote quer aquele
171
+ * pacote: cair na convenção em silêncio entrega uma porta diferente da pedida, e
172
+ * o sintoma aparece longe da causa. Falhar dizendo o nome é uma linha; descobrir
173
+ * que o fork não estava sendo usado é uma hora.
174
+ *
175
+ * O nível 3 (`spec-wave-<kind>-plugin`) vem DEPOIS do nível 2 porque não tem o
176
+ * nome da porta dentro: um `kind` que sirva às duas portas resolveria para o
177
+ * mesmo pacote nas duas. O nível 2 é o que desambigua, então é o preferido.
178
+ *
179
+ * O nível 4 é a fenda de desenvolvimento do plugin, dentro do projeto —
180
+ * `.spec-wave/plugins/<porta>-<kind>/index.mjs`. Fica sob `.spec-wave/` porque
181
+ * é onde já vivem o cache e os prompts do projeto.
182
+ *
183
+ * @param {object} params
184
+ * @param {'tracker'|'scm'} params.port
185
+ * @param {string} params.kind
186
+ * @param {string} [params.pkg] `tracker.package` / `scm.package` do config
187
+ * @returns {string[]}
188
+ */
189
+ export function candidateSpecifiers({ port, kind, pkg }) {
190
+ if (pkg) return [pkg];
191
+ if (!kind) return [];
192
+ return [
193
+ FORMA[port].escopado(kind),
194
+ `spec-wave-${kind}-plugin`,
195
+ `./.spec-wave/plugins/${port}-${kind}/index.mjs`,
196
+ ];
197
+ }
198
+
199
+ /** Especificador de CAMINHO (`.` ou `/`) em vez de nome de pacote. */
200
+ const eCaminho = spec => spec.startsWith('.') || spec.startsWith('/');
201
+
202
+ /**
203
+ * O módulo tem a forma que o loader exige? — função PURA.
204
+ *
205
+ * Quatro coisas, e a ordem importa: sem a versão do contrato não há garantia
206
+ * nenhuma sobre o resto, então ela vem primeiro.
207
+ *
208
+ * @param {object} params
209
+ * @param {'tracker'|'scm'} params.port
210
+ * @param {object} params.mod o módulo importado
211
+ * @param {string} params.kind o `kind` que o config pediu
212
+ * @param {string} [params.origem] para a mensagem
213
+ * @returns {string[]} problemas; vazio = conforme
214
+ */
215
+ export function checkPluginModule({ port, mod, kind, origem = 'plugin' }) {
216
+ const forma = FORMA[port];
217
+ if (!mod || typeof mod !== 'object') return [`${origem}: não exporta nada`];
218
+ const problemas = [];
219
+
220
+ const versao = mod[forma.versao];
221
+ if (versao === undefined) {
222
+ problemas.push(
223
+ `${origem}: não exporta \`${forma.versao}\` — não é um plugin de ${port} da spec-wave `
224
+ + '(ou é de uma versão anterior ao contrato versionado)'
225
+ );
226
+ // Sem a versão, cobrar o resto é adivinhação: um módulo qualquer não tem por
227
+ // que ter `createTracker`, e listar cinco problemas esconde o único que é o
228
+ // problema.
229
+ return problemas;
230
+ }
231
+ if (versao !== forma.esperada) {
232
+ problemas.push(
233
+ `${origem}: fala a versão ${versao} do contrato de ${port} e este core fala a `
234
+ + `${forma.esperada}. ${versao > forma.esperada
235
+ ? 'Atualize a spec-wave (`spec-wave update`).'
236
+ : 'Atualize o plugin.'}`
237
+ );
238
+ // Também para aqui: cobrar a forma da v1 de um módulo que declara outra
239
+ // versão produziria uma lista de problemas que não são o problema.
240
+ return problemas;
241
+ }
242
+
243
+ if (typeof mod[forma.fabrica] !== 'function') {
244
+ problemas.push(`${origem}: não exporta a fábrica \`${forma.fabrica}\``);
245
+ }
246
+ const declarado = mod[forma.kind];
247
+ if (!declarado) {
248
+ problemas.push(`${origem}: não exporta \`${forma.kind}\``);
249
+ } else if (kind && declarado !== kind) {
250
+ // Divergência silenciosa com efeito máximo: o config pede `jira`, o pacote
251
+ // instalado é de outro tracker, e tudo "funciona" contra o site errado.
252
+ problemas.push(
253
+ `${origem}: declara \`${forma.kind}\` = "${declarado}" e o config pede "${kind}"`
254
+ );
255
+ }
256
+ if (!mod.capabilities || typeof mod.capabilities !== 'object') {
257
+ problemas.push(`${origem}: não exporta \`capabilities\``);
258
+ }
259
+ return problemas;
260
+ }
261
+
262
+ /**
263
+ * Memo da RESOLUÇÃO, não da porta.
264
+ *
265
+ * `import()` já é cacheado pelo runtime, mas o LAÇO de candidatos não é: dois
266
+ * dos três candidatos de convenção normalmente não existem, e pagar duas falhas
267
+ * de resolução por comando é desperdício puro. A porta continua sendo construída
268
+ * a cada chamada — "nada de reuso de instância" (CLAUDE.md) é sobre contagem de
269
+ * chamadas e rate limit, e não muda aqui.
270
+ */
271
+ const memo = new Map();
272
+
273
+ /** Para os testes: o memo é global ao processo. */
274
+ export function resetPluginCache() {
275
+ memo.clear();
276
+ }
277
+
278
+ /**
279
+ * Resolve e carrega o módulo do plugin.
280
+ *
281
+ * @param {object} params
282
+ * @param {'tracker'|'scm'} params.port
283
+ * @param {string} params.kind
284
+ * @param {string} [params.pkg]
285
+ * @param {string} [params.root] raiz do projeto — de onde a resolução parte
286
+ * @returns {Promise<{mod: object|null, origem: string|null, error: string|null}>}
287
+ */
288
+ export async function loadPluginModule({ port, kind, pkg, root = process.cwd() }) {
289
+ if (!FORMA[port]) return { mod: null, origem: null, error: `porta desconhecida: "${port}"` };
290
+
291
+ const chave = `${port}|${kind || ''}|${pkg || ''}|${root}`;
292
+ if (memo.has(chave)) return memo.get(chave);
293
+
294
+ const guardar = (r) => { memo.set(chave, r); return r; };
295
+
296
+ // Embutido — mas só quando o config não nomeou um pacote. `package` explícito
297
+ // vence até para um `kind` embutido: é assim que se usa um fork.
298
+ if (!pkg && EMBUTIDOS[port][kind]) {
299
+ const mod = EMBUTIDOS[port][kind];
300
+ const problemas = checkPluginModule({ port, mod, kind, origem: `embutido "${kind}"` });
301
+ // Um embutido que não passe é defeito NOSSO, não do usuário — daí a
302
+ // mensagem diferente. A suíte reprova antes de chegar aqui.
303
+ if (problemas.length) {
304
+ return guardar({ mod: null, origem: null, error: `plugin embutido inconsistente: ${problemas.join('; ')}` });
305
+ }
306
+ return guardar({ mod, origem: `embutido "${kind}"`, error: null });
307
+ }
308
+
309
+ const candidatos = candidateSpecifiers({ port, kind, pkg });
310
+ if (candidatos.length === 0) {
311
+ return guardar({ mod: null, origem: null, error: `${port}: nem \`kind\` nem \`package\` no config` });
312
+ }
313
+
314
+ const req = createRequire(path.join(root, 'package.json'));
315
+ const naoAchados = [];
316
+
317
+ for (const spec of candidatos) {
318
+ // Etapa 1 — RESOLVER. Falha aqui = não instalado, próximo candidato.
319
+ let url;
320
+ try {
321
+ if (eCaminho(spec)) {
322
+ const abs = path.resolve(root, spec);
323
+ // `import.meta.resolve` NÃO confere existência de caminho (medido), então
324
+ // para caminho a sonda é o disco.
325
+ if (!existsSync(abs)) { naoAchados.push(spec); continue; }
326
+ url = pathToFileURL(abs).href;
327
+ } else {
328
+ url = pathToFileURL(req.resolve(spec)).href;
329
+ }
330
+ } catch {
331
+ naoAchados.push(spec);
332
+ continue;
333
+ }
334
+
335
+ // Etapa 2 — CARREGAR. Falha aqui é outro bicho: o plugin EXISTE e está
336
+ // quebrado. Seguir para o próximo candidato esconderia o defeito e mandaria
337
+ // o usuário instalar o que ele já tem.
338
+ let mod;
339
+ try {
340
+ mod = await import(url);
341
+ } catch (err) {
342
+ return guardar({
343
+ mod: null,
344
+ origem: spec,
345
+ error: `plugin de ${port} "${spec}" está instalado mas não carrega: ${err.message.split('\n')[0]}`,
346
+ });
347
+ }
348
+
349
+ const problemas = checkPluginModule({ port, mod, kind, origem: `plugin de ${port} "${spec}"` });
350
+ // Forma errada também PARA: achamos o pacote que o usuário pediu, e mandá-lo
351
+ // procurar outro seria mentir sobre o que aconteceu.
352
+ if (problemas.length) {
353
+ return guardar({ mod: null, origem: spec, error: problemas.join('\n ') });
354
+ }
355
+ return guardar({ mod, origem: spec, error: null });
356
+ }
357
+
358
+ // Nada resolveu. A mensagem LISTA o que foi tentado — sem isso, "plugin não
359
+ // encontrado" manda o usuário adivinhar qual nome a spec-wave esperava.
360
+ return guardar({
361
+ mod: null,
362
+ origem: null,
363
+ error: pkg
364
+ ? `plugin de ${port} "${pkg}" não encontrado a partir de ${root}. `
365
+ + 'Instale-o no projeto (`npm i -D ' + pkg + '`) ou corrija o `package` no config.'
366
+ : `nenhum plugin de ${port} para \`kind: "${kind}"\`. Tentei, nesta ordem:\n `
367
+ + naoAchados.join('\n ')
368
+ + '\nInstale um deles, ou nomeie o pacote em `'
369
+ + port + '.package` no config.',
370
+ });
371
+ }
372
+
373
+ /**
374
+ * O módulo já validado, com a porta construída e CONFERIDA.
375
+ *
376
+ * A conferência da porta (`checkTrackerPort`/`checkScmPort`) roda uma vez por
377
+ * módulo, não por chamada: o que pode estar defasado é o MÓDULO, e a forma da
378
+ * porta não depende do token.
379
+ *
380
+ * ⚠️ Este é o caminho por onde essas funções vão passar a rodar em PRODUÇÃO — e
381
+ * AINDA NÃO rodam: `getTracker`/`getScm` não têm chamador fora dos testes, e é o
382
+ * bloco E que afunila os ~35 call sites para cá. Até lá, quem constrói porta em
383
+ * produção é o próprio comando, sem passar por validação nenhuma. Escrever isto
384
+ * no presente seria o defeito do PR #146 de novo: prosa afirmando uma garantia
385
+ * que nada cumpre.
386
+ *
387
+ * `params` é repassado à fábrica como UM objeto, e cada plugin lê as chaves que
388
+ * conhece — é para isso que a aridade está presa em 1. O embutido lê `project`;
389
+ * um plugin de Jira leria `config`/`fieldMap` e ignoraria o resto.
390
+ *
391
+ * @param {object} args
392
+ * @param {'tracker'|'scm'} args.port
393
+ * @param {string} args.kind
394
+ * @param {string} [args.pkg]
395
+ * @param {string} [args.root]
396
+ * @param {object} args.params argumento-objeto da fábrica
397
+ * @returns {Promise<{porta: object|null, origem: string|null, error: string|null}>}
398
+ */
399
+ export async function buildPort({ port, kind, pkg, root, params }) {
400
+ const { mod, origem, error } = await loadPluginModule({ port, kind, pkg, root });
401
+ if (error) return { porta: null, origem, error };
402
+
403
+ const forma = FORMA[port];
404
+ let porta;
405
+ try {
406
+ porta = mod[forma.fabrica](params);
407
+ } catch (err) {
408
+ // A fábrica é código de TERCEIRO a partir daqui. Um throw viraria stack
409
+ // trace no terminal de quem só instalou um plugin quebrado.
410
+ return { porta: null, origem, error: `${origem}: a fábrica lançou: ${err.message.split('\n')[0]}` };
411
+ }
412
+
413
+ const chaveVerificada = `verificada|${port}|${origem}`;
414
+ if (!memo.has(chaveVerificada)) {
415
+ const problemas = forma.conferir(porta);
416
+ memo.set(chaveVerificada, problemas);
417
+ }
418
+ const problemas = memo.get(chaveVerificada);
419
+ if (problemas.length) {
420
+ return {
421
+ porta: null,
422
+ origem,
423
+ error: `${origem} não cumpre o contrato de ${port}:\n ${problemas.join('\n ')}`,
424
+ };
425
+ }
426
+ return { porta, origem, error: null };
427
+ }
@@ -32,6 +32,11 @@ import {
32
32
  getRepoNodeId,
33
33
  getRepoVariable,
34
34
  deleteRepoVariable,
35
+ // Diagnóstico do `verify({deep})` — bloco G leva 2.
36
+ getRepoInfo,
37
+ getRequiredStatusChecks,
38
+ listActionsSecretNames,
39
+ getActionsCanCreatePullRequests,
35
40
  isRepoInitialized,
36
41
  listPullRequestCommitMessages,
37
42
  listPullRequestReviews,
@@ -57,7 +62,7 @@ import { refKey, refNumber } from '../../lib/work-item-ref.mjs';
57
62
  export const SCM_KIND = 'github';
58
63
 
59
64
  /**
60
- * O que o GitHub sabe fazer, na forma do `rfc/protocol/scm.v1.json`.
65
+ * O que o GitHub sabe fazer, na forma do `protocol/scm.v1.json`.
61
66
  *
62
67
  * Congelado: o core LÊ isto para degradar, e uma capability que pudesse ser
63
68
  * mutada em runtime seria um plugin ganhando poder depois da carga.
@@ -226,6 +231,8 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
226
231
  listPullRequestReviews, mergePR, findOpenPR, setRepoVariable, updatePRBase, upsertFile,
227
232
  getPRClosingIssues, getRateLimit, listIssuePullRequests, listOpenPullRequests,
228
233
  markPullRequestReadyForReview,
234
+ getRepoInfo, getRequiredStatusChecks, listActionsSecretNames,
235
+ getActionsCanCreatePullRequests,
229
236
  ...api,
230
237
  };
231
238
 
@@ -240,16 +247,69 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
240
247
  return { warnings: [] };
241
248
  },
242
249
 
243
- async verify() {
250
+ async verify({ deep = false } = {}) {
244
251
  const problems = [];
245
252
  const facts = {};
246
253
  // Sonda de alcance: é o que `commands/repo.mjs` já faz hoje, chamando
247
254
  // getRepoNodeId e descartando o retorno. O que importa é o 404/403.
248
255
  try {
249
256
  facts.repoNodeId = await a.getRepoNodeId(token, owner, repo);
257
+ facts.repoReachable = true;
250
258
  } catch (err) {
259
+ facts.repoNodeId = null;
260
+ // TRÊS estados, não dois. `false` é "esta credencial não enxerga este
261
+ // repositório" — resposta definitiva, e a causa típica do erro silencioso
262
+ // na criação de issue. `null` é "não consegui verificar agora" (rede,
263
+ // 500, cota). Fundi-los faria o doctor acusar VERMELHO num repositório
264
+ // correto sempre que a API estivesse fora do ar.
265
+ facts.repoReachable = err.status === 404 ? false : null;
251
266
  problems.push(`repositório ${link.label} inacessível: ${err.message}`);
252
267
  }
268
+
269
+ // ── Fatos de AUTOMAÇÃO, só sob `deep` ─────────────────────────────────
270
+ //
271
+ // Três chamadas a mais, e nenhum outro chamador de `verify()` as imprime:
272
+ // o `init` e o `repo` usam esta operação como sonda de alcance. Cobrá-las
273
+ // de todo mundo seria pagar diagnóstico que ninguém lê.
274
+ //
275
+ // O plugin COLETA e não julga: quem decide se dá para publicar documento
276
+ // por PR é `inspectPrPublishing`, no core. E `null` aqui significa
277
+ // "consultei e NÃO pude ver" — as três consultas falham por permissão
278
+ // insuficiente com frequência, e tratar isso como "está desligado" viraria
279
+ // vermelho em repositório correto.
280
+ if (deep) {
281
+ try {
282
+ const info = await a.getRepoInfo(token, owner, repo);
283
+ facts.repoFullName = info.fullName;
284
+ facts.repoPrivate = info.isPrivate;
285
+ facts.defaultBranch = info.defaultBranch;
286
+ try {
287
+ facts.protectedChecks = await a.getRequiredStatusChecks(
288
+ token, owner, repo, info.defaultBranch);
289
+ } catch {
290
+ facts.protectedChecks = null;
291
+ }
292
+ } catch {
293
+ facts.repoFullName = null;
294
+ facts.repoPrivate = null;
295
+ facts.defaultBranch = null;
296
+ // Sem saber a branch default não há proteção a consultar — e isso é
297
+ // "não consegui", não "não há".
298
+ facts.protectedChecks = null;
299
+ }
300
+ try {
301
+ facts.automationSecretNames = await a.listActionsSecretNames(token, owner, repo);
302
+ } catch {
303
+ facts.automationSecretNames = null; // sem permissão: não afirmar ausência
304
+ }
305
+ try {
306
+ facts.automationCanOpenPullRequest =
307
+ await a.getActionsCanCreatePullRequests(token, owner, repo);
308
+ } catch {
309
+ facts.automationCanOpenPullRequest = null; // exige administration:read
310
+ }
311
+ }
312
+
253
313
  const quota = (await a.getRateLimit(token)) || {};
254
314
  return {
255
315
  ok: problems.length === 0,
@@ -437,3 +497,12 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
437
497
 
438
498
  /** Reexportado para quem precisa converter chave → número na fronteira. */
439
499
  export { refNumber };
500
+
501
+ // ── O que o LOADER lê (RFC-006 §9.2, Fase 2 bloco A) ────────────────────────
502
+ // Mesma razão do plugin de tracker: o embutido percorre o caminho do loader, e
503
+ // declarar aqui é o que faz a validação conferir o módulo REAL em vez de um
504
+ // objeto-módulo sintético montado pelo próprio loader.
505
+ export const specWaveScmApi = 1;
506
+ export const scmKind = SCM_KIND;
507
+ export const capabilities = GITHUB_SCM_CAPABILITIES;
508
+ export const createScm = createGithubScm;
@@ -21,7 +21,6 @@
21
21
  // `addProjectItem` uma vez. Sem memo, o par chamaria duas — em dez call sites.
22
22
  // O memo por instância REPÕE a contagem de hoje; ele não a reduz abaixo dela.
23
23
 
24
- import { Octokit } from '@octokit/rest';
25
24
 
26
25
  import {
27
26
  addBlockedBy,
@@ -35,6 +34,9 @@ import {
35
34
  getIssue,
36
35
  getMilestone,
37
36
  getOwnerType,
37
+ listIssuesByLabel,
38
+ // Diagnóstico do `verify({deep})` — bloco G leva 2.
39
+ getOrgMembershipState,
38
40
  listBlockedBy,
39
41
  listIssueComments,
40
42
  listIssuesByMilestone,
@@ -184,7 +186,7 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
184
186
  addProjectItem, addSubIssue, createProject, createSingleSelectField, createTextField,
185
187
  getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getRateLimit,
186
188
  linkProjectToRepo, listProjectItems, listSubIssues, setItemSingleSelect, setItemText,
187
- resolveField,
189
+ resolveField, getOrgMembershipState, listIssuesByLabel,
188
190
  ...api,
189
191
  };
190
192
 
@@ -298,7 +300,7 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
298
300
  return { config, warnings: [] };
299
301
  },
300
302
 
301
- async verify() {
303
+ async verify({ deep = false } = {}) {
302
304
  const problems = [];
303
305
  const facts = {};
304
306
  try {
@@ -309,20 +311,38 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
309
311
  problems.push(`o owner "${owner}" é uma conta pessoal; Projects v2 do spec-wave exige organização`);
310
312
  }
311
313
  } catch (err) {
314
+ // `null`, e não a ausência da chave: a diferença entre "este tracker não
315
+ // tem noção de owner" e "tem, e eu não consegui ler" é o que manda o
316
+ // usuário ao lugar certo (ver VerifyResult).
317
+ facts.ownerType = null;
312
318
  problems.push(err.message);
313
319
  }
314
320
  if (project?.id) {
315
321
  try {
316
322
  const snap = await a.getProjectSnapshot(ptk, project.id);
323
+ facts.boardFound = !!snap;
317
324
  if (!snap) problems.push('Project não encontrado com a credencial atual');
318
325
  else {
319
- facts.projectTitle = snap.title;
320
- facts.projectNumber = String(snap.number);
326
+ facts.boardTitle = snap.title;
327
+ facts.boardKey = String(snap.number);
328
+ // Nome → id das etapas REAIS. O `doctor` compara com o config por
329
+ // NOME (coluna renomeada/apagada) e por ID (config defasado, que faz
330
+ // toda escrita de Etapa falhar em silêncio) — duas leituras do mesmo
331
+ // fato, e nenhuma delas é julgamento do plugin.
332
+ facts.stageOptions = snap.fields?.[ETAPA_FIELD.name]?.options ?? null;
321
333
  }
322
334
  } catch (err) {
335
+ facts.boardFound = null;
323
336
  problems.push(err.message);
324
337
  }
325
338
  }
339
+ if (deep) {
340
+ // O usuário do token é membro ativo da organização dona do board? É o
341
+ // que separa "a conta ativa do `gh` não é o owner, e isso é normal numa
342
+ // org" de "esta credencial não pertence a esta organização". `null` =
343
+ // não dá para saber (conta pessoal, ou sem permissão de consultar).
344
+ facts.ownerMembership = await a.getOrgMembershipState(token, owner);
345
+ }
326
346
  const quota = (await a.getRateLimit(ptk)) || {};
327
347
  return {
328
348
  ok: problems.length === 0,
@@ -383,14 +403,16 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
383
403
  return { fields: snap?.fields || {} };
384
404
  },
385
405
 
406
+ // Passa pelo `a`, e isso não é estilo: um `new Octokit` INLINE não tem
407
+ // costura, então o duplo do teste não o intercepta e a chamada vai à rede de
408
+ // verdade no meio da suíte. Era inofensivo enquanto ninguém chamava (o
409
+ // cabeçalho deste arquivo dizia isso); o `doctor` passou a chamar na leva 2
410
+ // do bloco G, e foi o bloqueio de rede do teste de fumaça que acusou.
386
411
  async listWorkItemsByTag({ tag, state = 'open' } = {}) {
387
- const octokit = new Octokit({ auth: token });
388
- const issues = await octokit.paginate('GET /repos/{owner}/{repo}/issues', {
389
- owner, repo, labels: tag, state, per_page: 100,
390
- });
412
+ const issues = await a.listIssuesByLabel(token, owner, repo, { labels: tag, state });
391
413
  // A REST devolve Pull Request junto — eles são issues para a API, e não
392
414
  // para o fluxo.
393
- return issues.filter(i => !i.pull_request).map(toWorkItem);
415
+ return (issues || []).filter(i => !i.pull_request).map(toWorkItem);
394
416
  },
395
417
 
396
418
  async addComment({ ref, body } = {}) {
@@ -679,3 +701,23 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
679
701
  }
680
702
 
681
703
  export { FIELD_LABEL };
704
+
705
+ // ── O que o LOADER lê (RFC-006 §9.2, Fase 2 bloco A) ────────────────────────
706
+ //
707
+ // O plugin embutido declara exatamente o que um plugin de terceiro declara, e
708
+ // `src/plugins/load.mjs` o carrega pelo MESMO caminho — inclusive passando por
709
+ // `checkPluginModule` e `checkTrackerPort`.
710
+ //
711
+ // Os nomes são canônicos e não os locais (`TRACKER_KIND`, `createGithubTracker`)
712
+ // porque é o loader que os lê, e ele não pode saber o nome interno de cada
713
+ // fornecedor. Os locais ficam: 37 arquivos e a suíte os usam, e renomeá-los é o
714
+ // bloco E.
715
+ //
716
+ // Isto não é enfeite. A alternativa era o loader montar um objeto-módulo
717
+ // sintético para o embutido — um falso que passa por construção, que é o mesmo
718
+ // defeito da porta falsa escrita à mão: valida o que quem o escreveu imaginou.
719
+ // Declarando aqui, quem reprova é o módulo REAL.
720
+ export const specWaveTrackerApi = 1;
721
+ export const trackerKind = TRACKER_KIND;
722
+ export const capabilities = GITHUB_TRACKER_CAPABILITIES;
723
+ export const createTracker = createGithubTracker;