@spec-wave/cli 1.4.0 → 1.6.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 (57) hide show
  1. package/package.json +1 -1
  2. package/protocol/scm.v1.json +165 -0
  3. package/protocol/tracker.v1.json +175 -0
  4. package/src/api/github-rest.mjs +124 -2
  5. package/src/commands/audit.mjs +3 -5
  6. package/src/commands/code-review.mjs +10 -6
  7. package/src/commands/decompose.mjs +7 -6
  8. package/src/commands/doctor.mjs +389 -220
  9. package/src/commands/generate-bug.mjs +2 -2
  10. package/src/commands/generate-plan.mjs +5 -7
  11. package/src/commands/generate-qa-plan.mjs +3 -5
  12. package/src/commands/generate-spec.mjs +2 -2
  13. package/src/commands/implement.mjs +33 -21
  14. package/src/commands/init.mjs +36 -7
  15. package/src/commands/issue.mjs +6 -2
  16. package/src/commands/merge.mjs +20 -15
  17. package/src/commands/mode.mjs +18 -11
  18. package/src/commands/move.mjs +3 -3
  19. package/src/commands/order.mjs +3 -3
  20. package/src/commands/preflight.mjs +10 -6
  21. package/src/commands/qa-lead.mjs +6 -8
  22. package/src/commands/qa-run.mjs +39 -27
  23. package/src/commands/qa.mjs +10 -7
  24. package/src/commands/refresh.mjs +6 -3
  25. package/src/commands/repair-stage.mjs +1 -1
  26. package/src/commands/repo.mjs +6 -7
  27. package/src/commands/run.mjs +7 -5
  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 -6
  32. package/src/commands/update.mjs +47 -20
  33. package/src/commands/validate.mjs +3 -5
  34. package/src/commands/workspace.mjs +2 -2
  35. package/src/lib/artifact-publish.mjs +3 -3
  36. package/src/lib/board.mjs +22 -24
  37. package/src/lib/config-ports.mjs +114 -0
  38. package/src/lib/doc-source.mjs +16 -3
  39. package/src/lib/doctor-capabilities.mjs +168 -0
  40. package/src/lib/implement-board.mjs +1 -1
  41. package/src/lib/pr-ready.mjs +23 -11
  42. package/src/lib/story-graph.mjs +19 -6
  43. package/src/lib/tag-registry.mjs +58 -0
  44. package/src/lib/usage-report.mjs +15 -2
  45. package/src/plugin/.claude-plugin/plugin.json +1 -1
  46. package/src/plugins/load.mjs +427 -0
  47. package/src/plugins/scm-github/index.mjs +92 -6
  48. package/src/plugins/tracker-github-projects/index.mjs +52 -10
  49. package/src/ports/capabilities.mjs +47 -0
  50. package/src/ports/index.mjs +201 -46
  51. package/src/ports/scm.mjs +71 -3
  52. package/src/ports/tracker.mjs +43 -2
  53. package/src/ports/types.mjs +30 -6
  54. package/src/setup/files.mjs +2 -3
  55. package/src/setup/labels.mjs +2 -2
  56. package/src/setup/project.mjs +2 -2
  57. package/src/ui/wizard.mjs +76 -1
@@ -26,12 +26,18 @@ import {
26
26
  deleteFile,
27
27
  ensurePullRequest,
28
28
  getBranchHead,
29
- getFileContent,
29
+
30
30
  getPR,
31
31
  getRepoDefaultBranch,
32
32
  getRepoNodeId,
33
+ getFileBytes,
33
34
  getRepoVariable,
34
35
  deleteRepoVariable,
36
+ // Diagnóstico do `verify({deep})` — bloco G leva 2.
37
+ getRepoInfo,
38
+ getRequiredStatusChecks,
39
+ listActionsSecretNames,
40
+ getActionsCanCreatePullRequests,
35
41
  isRepoInitialized,
36
42
  listPullRequestCommitMessages,
37
43
  listPullRequestReviews,
@@ -57,12 +63,16 @@ import { refKey, refNumber } from '../../lib/work-item-ref.mjs';
57
63
  export const SCM_KIND = 'github';
58
64
 
59
65
  /**
60
- * O que o GitHub sabe fazer, na forma do `rfc/protocol/scm.v1.json`.
66
+ * O que o GitHub sabe fazer, na forma do `protocol/scm.v1.json`.
61
67
  *
62
68
  * Congelado: o core LÊ isto para degradar, e uma capability que pudesse ser
63
69
  * mutada em runtime seria um plugin ganhando poder depois da carga.
64
70
  */
65
71
  export const GITHUB_SCM_CAPABILITIES = Object.freeze({
72
+ // A Contents API devolve base64: os bytes estão lá, e decodificar é decisão de
73
+ // quem chama. Era exatamente o contrário — a coerção para UTF-8 morava dentro
74
+ // da camada HTTP, escondida de quem lia o contrato (issue #140).
75
+ fileReads: Object.freeze({ bytes: true }),
66
76
  fileWrites: Object.freeze({
67
77
  mode: 'tree-commit-ref',
68
78
  atomicMultiFile: true,
@@ -221,14 +231,19 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
221
231
 
222
232
  const a = {
223
233
  commitFilesToBranch, compareBranches, deleteBranch, deleteFile, ensurePullRequest,
224
- getBranchHead, getFileContent, getPR, getRepoDefaultBranch, getRepoNodeId,
234
+ getBranchHead, getPR, getRepoDefaultBranch, getRepoNodeId,
225
235
  getRepoVariable, deleteRepoVariable, isRepoInitialized, listPullRequestCommitMessages,
226
236
  listPullRequestReviews, mergePR, findOpenPR, setRepoVariable, updatePRBase, upsertFile,
227
237
  getPRClosingIssues, getRateLimit, listIssuePullRequests, listOpenPullRequests,
228
238
  markPullRequestReadyForReview,
239
+ getRepoInfo, getRequiredStatusChecks, listActionsSecretNames,
240
+ getActionsCanCreatePullRequests, getFileBytes,
229
241
  ...api,
230
242
  };
231
243
 
244
+ /** A única rota de leitura de arquivo — ver `readFile`/`readFileBytes`. */
245
+ const lerBytes = (p, ref) => a.getFileBytes(token, owner, repo, p, ref);
246
+
232
247
  return {
233
248
  kind: SCM_KIND,
234
249
  link,
@@ -240,16 +255,69 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
240
255
  return { warnings: [] };
241
256
  },
242
257
 
243
- async verify() {
258
+ async verify({ deep = false } = {}) {
244
259
  const problems = [];
245
260
  const facts = {};
246
261
  // Sonda de alcance: é o que `commands/repo.mjs` já faz hoje, chamando
247
262
  // getRepoNodeId e descartando o retorno. O que importa é o 404/403.
248
263
  try {
249
264
  facts.repoNodeId = await a.getRepoNodeId(token, owner, repo);
265
+ facts.repoReachable = true;
250
266
  } catch (err) {
267
+ facts.repoNodeId = null;
268
+ // TRÊS estados, não dois. `false` é "esta credencial não enxerga este
269
+ // repositório" — resposta definitiva, e a causa típica do erro silencioso
270
+ // na criação de issue. `null` é "não consegui verificar agora" (rede,
271
+ // 500, cota). Fundi-los faria o doctor acusar VERMELHO num repositório
272
+ // correto sempre que a API estivesse fora do ar.
273
+ facts.repoReachable = err.status === 404 ? false : null;
251
274
  problems.push(`repositório ${link.label} inacessível: ${err.message}`);
252
275
  }
276
+
277
+ // ── Fatos de AUTOMAÇÃO, só sob `deep` ─────────────────────────────────
278
+ //
279
+ // Três chamadas a mais, e nenhum outro chamador de `verify()` as imprime:
280
+ // o `init` e o `repo` usam esta operação como sonda de alcance. Cobrá-las
281
+ // de todo mundo seria pagar diagnóstico que ninguém lê.
282
+ //
283
+ // O plugin COLETA e não julga: quem decide se dá para publicar documento
284
+ // por PR é `inspectPrPublishing`, no core. E `null` aqui significa
285
+ // "consultei e NÃO pude ver" — as três consultas falham por permissão
286
+ // insuficiente com frequência, e tratar isso como "está desligado" viraria
287
+ // vermelho em repositório correto.
288
+ if (deep) {
289
+ try {
290
+ const info = await a.getRepoInfo(token, owner, repo);
291
+ facts.repoFullName = info.fullName;
292
+ facts.repoPrivate = info.isPrivate;
293
+ facts.defaultBranch = info.defaultBranch;
294
+ try {
295
+ facts.protectedChecks = await a.getRequiredStatusChecks(
296
+ token, owner, repo, info.defaultBranch);
297
+ } catch {
298
+ facts.protectedChecks = null;
299
+ }
300
+ } catch {
301
+ facts.repoFullName = null;
302
+ facts.repoPrivate = null;
303
+ facts.defaultBranch = null;
304
+ // Sem saber a branch default não há proteção a consultar — e isso é
305
+ // "não consegui", não "não há".
306
+ facts.protectedChecks = null;
307
+ }
308
+ try {
309
+ facts.automationSecretNames = await a.listActionsSecretNames(token, owner, repo);
310
+ } catch {
311
+ facts.automationSecretNames = null; // sem permissão: não afirmar ausência
312
+ }
313
+ try {
314
+ facts.automationCanOpenPullRequest =
315
+ await a.getActionsCanCreatePullRequests(token, owner, repo);
316
+ } catch {
317
+ facts.automationCanOpenPullRequest = null; // exige administration:read
318
+ }
319
+ }
320
+
253
321
  const quota = (await a.getRateLimit(token)) || {};
254
322
  return {
255
323
  ok: problems.length === 0,
@@ -271,8 +339,17 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
271
339
  return a.isRepoInitialized(token, owner, repo);
272
340
  },
273
341
 
274
- readFile({ path: p, ref } = {}) {
275
- return a.getFileContent(token, owner, repo, p, ref);
342
+ // TEXTO: é `readFileBytes` decodificado, e o contrato exige que seja isso e
343
+ // não uma segunda rota (issue #140). As duas saem da MESMA função local —
344
+ // com duas rotas independentes, a que ganhasse cache ou retry deixaria a
345
+ // outra para trás em silêncio.
346
+ async readFile({ path: p, ref } = {}) {
347
+ const bytes = await lerBytes(p, ref);
348
+ return bytes === null ? null : Buffer.from(bytes).toString('utf-8');
349
+ },
350
+
351
+ async readFileBytes({ path: p, ref } = {}) {
352
+ return lerBytes(p, ref);
276
353
  },
277
354
 
278
355
  writeFiles({ branch, base, files, message } = {}) {
@@ -437,3 +514,12 @@ export function createGithubScm({ link, token, prToken, trackerKind = 'github-pr
437
514
 
438
515
  /** Reexportado para quem precisa converter chave → número na fronteira. */
439
516
  export { refNumber };
517
+
518
+ // ── O que o LOADER lê (RFC-006 §9.2, Fase 2 bloco A) ────────────────────────
519
+ // Mesma razão do plugin de tracker: o embutido percorre o caminho do loader, e
520
+ // declarar aqui é o que faz a validação conferir o módulo REAL em vez de um
521
+ // objeto-módulo sintético montado pelo próprio loader.
522
+ export const specWaveScmApi = 1;
523
+ export const scmKind = SCM_KIND;
524
+ export const capabilities = GITHUB_SCM_CAPABILITIES;
525
+ 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;
@@ -0,0 +1,47 @@
1
+ // A regra de vocabulário das `capabilities`, compartilhada pelas duas portas.
2
+ //
3
+ // Mora em módulo próprio e não em `types.mjs` porque aquele é declaradamente sem
4
+ // runtime, e não em `tracker.mjs` porque `scm.mjs` também a usa — uma porta
5
+ // importando a outra seria acoplamento sem razão.
6
+ //
7
+ // ── Por que a regra existe ───────────────────────────────────────────────────
8
+ //
9
+ // Uma chave de capability DESCONHECIDA é silenciosa e cara. `trackerRequiredOperations`
10
+ // lê `capabilities.commentMarkers`; quem escrever `markers` cai no ramo default
11
+ // sem nenhum sinal, e a validação da carga passa a cobrar o conjunto ERRADO de
12
+ // operações — o plugin carrega "conforme" e falta uma operação que ninguém
13
+ // pediu. No SCM é mais afiado ainda: `pullRequests.draft` é o que exige
14
+ // `markReadyForReview`, e um `pullRequest` no singular carregaria conforme e não
15
+ // saberia tirar PR de rascunho.
16
+ //
17
+ // Aconteceu comigo escrevendo o teste do loader: quatro chaves inventadas
18
+ // (`markers`, `board`, `comments`, `tags`) mudaram a lista de operações exigidas
19
+ // de 35 para 37, e o que me avisou foi a lista de operações faltando — não a
20
+ // causa. Isto é o que transforma o sintoma em causa.
21
+ //
22
+ // `protocol/{tracker,scm}.v1.json` têm `additionalProperties: true`, que é o
23
+ // que deixa o erro passar do lado do manifesto. Aqui a lista é fechada, e
24
+ // `test/protocol-schemas.test.mjs` afirma que ela não divergiu do schema: uma
25
+ // fonte em runtime, com guarda contra deriva.
26
+
27
+ /**
28
+ * Chave de capability fora do vocabulário (função PURA).
29
+ *
30
+ * Exportada, e não embutida em `checkTrackerPort`, pela mesma razão de
31
+ * `checkKeyPattern`: o kit de conformidade da §9.4 tem de cobrar a MESMA regra,
32
+ * e duas cópias divergem.
33
+ *
34
+ * @param {object} capabilities
35
+ * @param {readonly string[]} conhecidas
36
+ * @returns {string[]} problemas; vazio = vocabulário limpo
37
+ */
38
+ export function checkCapabilityKeys(capabilities, conhecidas) {
39
+ if (!capabilities || typeof capabilities !== 'object') return ['`capabilities` ausente'];
40
+ const desconhecidas = Object.keys(capabilities).filter(k => !conhecidas.includes(k));
41
+ if (desconhecidas.length === 0) return [];
42
+ return [
43
+ `capability desconhecida: ${desconhecidas.map(k => `\`${k}\``).join(', ')}. `
44
+ + 'Uma chave que o contrato não lê é IGNORADA em silêncio, e a operação que ela '
45
+ + `deveria exigir deixa de ser cobrada. O vocabulário é: ${conhecidas.join(', ')}`,
46
+ ];
47
+ }
@@ -31,13 +31,16 @@
31
31
  // qualquer resolução. Sem isso, cada comando migrado precisaria de um seam
32
32
  // próprio de novo.
33
33
  //
34
- // ── O que este arquivo AINDA não faz ────────────────────────────────────────
34
+ // ── A resolução mora no loader (bloco A) ────────────────────────────────────
35
35
  //
36
- // A resolução é estática: devolve o plugin do GitHub, sempre. O bloco A põe
37
- // aqui a ordem de resolução da §9.2 (`package` explícito → `@spec-wave/
38
- // tracker-<kind>` → `spec-wave-<kind>-plugin` → caminho local), o `import()`
39
- // dinâmico, a validação de `specWaveTrackerApi === 1` e a chamada de
40
- // `checkTrackerPort` na carga. Os pontos estão marcados com `bloco A`.
36
+ // Até o bloco 0 este arquivo importava as duas fábricas do GitHub direto. Agora
37
+ // ele não conhece fornecedor nenhum: `src/plugins/load.mjs` faz a resolução da
38
+ // §9.2, valida `specWaveTrackerApi === 1` e as `capabilities` × `operations` na
39
+ // CARGA, e devolve a porta já conferida por `checkTrackerPort`/`checkScmPort`.
40
+ //
41
+ // ⚠️ E isso só vale para quem passar por AQUI. Hoje ninguém passa: estas duas
42
+ // funções não têm chamador em produção, e é o bloco E que traz os ~35 call sites.
43
+ // A validação existe e está testada; ela ainda não protege um comando real.
41
44
  //
42
45
  // `getScm` toma um `ScmLink` já pronto de propósito: `ScmLink` é tipo do
43
46
  // CONTRATO e qualquer plugin sabe produzir um, então a assinatura sobrevive ao
@@ -45,10 +48,35 @@
45
48
  // core importavam `githubLink` do plugin —, e o bloco E0 o fechou com
46
49
  // `resolveScmLink` (no fim deste arquivo) mais a extensão da barreira.
47
50
 
48
- import { createGithubTracker, TRACKER_KIND } from '../plugins/tracker-github-projects/index.mjs';
49
- import { createGithubScm, githubLink, SCM_KIND } from '../plugins/scm-github/index.mjs';
51
+ import {
52
+ buildPort, listPluginKinds, DEFAULT_TRACKER_KIND, DEFAULT_SCM_KIND,
53
+ } from '../plugins/load.mjs';
54
+
55
+ // Reexportados: o core precisa nomear o fornecedor embutido em DOIS lugares — o
56
+ // `init`, que pergunta antes de haver config, e o default de leitura do bloco D —
57
+ // e a barreira só autoriza este arquivo a falar com `src/plugins/`. Sem isto, um
58
+ // comando importaria o loader direto para pegar a constante.
59
+ export { DEFAULT_TRACKER_KIND, DEFAULT_SCM_KIND };
60
+
61
+ /**
62
+ * Os fornecedores DISPONÍVEIS para uma porta — RFC-006 §9.3, bloco F.
63
+ *
64
+ * Reexportada por aqui e não importada do loader, e o portão da barreira pegou
65
+ * isso na hora: o wizard é CORE, e descobrir de onde vem um plugin é do
66
+ * `ports/index.mjs`. Deixar o wizard importar `src/plugins/load.mjs` teria
67
+ * reaberto a porta que o bloco E acabou de fechar — por uma constante.
68
+ */
69
+ export { listPluginKinds };
70
+ import { githubLink, SCM_KIND } from '../plugins/scm-github/index.mjs';
50
71
  import { CONFIG_FILE } from '../config.mjs';
51
72
  import { loadConfig } from '../lib/project-root.mjs';
73
+ // Bloco D: normalização do bloco `tracker` na LEITURA (§3.4). O default de
74
+ // `kind` vem do loader, não daqui — o core não nomeia fornecedor.
75
+ //
76
+ // `deriveScmBlock` existe no mesmo módulo e NÃO é importada aqui: `getScm` toma
77
+ // um `link` e não sabe de qual repositório é o `cwd` (ver a nota dentro dela). O
78
+ // consumidor dela é o bloco F (`init` gravando o bloco) e os call sites de E.
79
+ import { deriveTrackerBlock } from '../lib/config-ports.mjs';
52
80
 
53
81
  /** @typedef {import('./tracker.mjs').TrackerPort} TrackerPort */
54
82
  /** @typedef {import('./scm.mjs').ScmPort} ScmPort */
@@ -69,11 +97,19 @@ import { loadConfig } from '../lib/project-root.mjs';
69
97
  * @param {string} [params.projectToken] credencial de board; ausente = `token`
70
98
  * @param {string} [params.owner] vence o que estiver no config
71
99
  * @param {string} [params.repo] idem
100
+ * @param {boolean} [params.board=false] exigir o bloco `project`? Só quem vai
101
+ * MEXER no board passa `true` — ver a nota no corpo. Um repo de papel `code`
102
+ * não tem o bloco e ainda assim usa a porta para issue.
103
+ * @param {string} [params.kind] fornecedor EXPLÍCITO, dispensando o config. Só o
104
+ * `init` usa hoje, porque é o único comando que roda antes de o
105
+ * `.spec-wave.json` existir — ver a nota no corpo.
106
+ * @param {string} [params.pkg] pacote explícito, junto com `kind`
72
107
  * @param {object} [params.deps] `deps.tracker` injeta uma porta já construída
73
108
  * @returns {Promise<{tracker: TrackerPort|null, root: string|null, error: string|null}>}
74
109
  */
75
110
  export async function getTracker({
76
- cwd = process.cwd(), token, projectToken, owner, repo, deps = {},
111
+ cwd = process.cwd(), token, projectToken, owner, repo, board = false,
112
+ kind: kindExplicito, pkg: pkgExplicito, deps = {},
77
113
  } = {}) {
78
114
  const { config, root, error: configError } = loadConfig(cwd);
79
115
 
@@ -82,10 +118,57 @@ export async function getTracker({
82
118
  // chamadores o usam para achar os documentos.
83
119
  if (deps.tracker) return { tracker: deps.tracker, root, error: null };
84
120
 
121
+ // ── `kind` EXPLÍCITO dispensa o config, e o `init` é por que isso existe ────
122
+ //
123
+ // `init` roda ANTES de haver `.spec-wave.json` — ele o grava no fim. Exigir o
124
+ // config ali tornaria o único comando que ainda constrói porta à mão o único que
125
+ // não pode deixar de construir. A leva 5 do bloco E descobriu isso ao tentar
126
+ // migrá-lo: o plano falava de "colisão com o bloco F no mesmo arquivo", e o
127
+ // motivo real é mais afiado — não há config a ler.
128
+ //
129
+ // É também a API de que o bloco F precisa: as duas perguntas do `init`
130
+ // (§9.3) escolhem o fornecedor ANTES de gravar qualquer coisa, e é este
131
+ // parâmetro que carrega a escolha até o loader.
132
+ if (kindExplicito) {
133
+ const { porta, error } = await buildPort({
134
+ port: 'tracker',
135
+ kind: kindExplicito,
136
+ pkg: pkgExplicito,
137
+ root: root || cwd,
138
+ params: { token, projectToken, owner, repo },
139
+ });
140
+ return { tracker: porta, root, error };
141
+ }
142
+
85
143
  if (configError) return { tracker: null, root, error: configError };
86
144
 
87
- const project = config.project || {};
88
- if (!project.id) {
145
+ // Bloco D: o bloco `tracker` é NORMALIZADO na leitura, ANTES de qualquer
146
+ // guarda. Um config da era 0.16.4 não o tem, e é lido como se tivesse — `kind`
147
+ // do fornecedor embutido, `config` vinda do bloco `project`. Nada é gravado
148
+ // (§3.4).
149
+ //
150
+ // A normalização vem antes do guard de propósito: guardar contra
151
+ // `config.project` e entregar `bloco.config` à fábrica seria meia-migração — um
152
+ // `tracker.config` escrito à mão, com o id lá dentro, seria recusado por falta
153
+ // de um bloco `project` que ele veio justamente substituir.
154
+ const bloco = deriveTrackerBlock(config, { defaultKind: DEFAULT_TRACKER_KIND });
155
+
156
+ // ── `board` é OPT-IN, e o bloco E é que mostrou por quê ────────────────────
157
+ //
158
+ // O bloco 0 congelou esta função exigindo `project.id` sempre. Errado, e o
159
+ // sintoma só apareceu ao migrar os call sites: os comandos constroem DUAS
160
+ // portas de tracker — uma para trabalho de ISSUE (`createGithubTracker({token,
161
+ // owner, repo})`, sem `project`, porque o plugin resolve o board de forma
162
+ // preguiçosa) e uma para o BOARD (via `openTracker`, que exige o bloco).
163
+ //
164
+ // Exigir `project.id` na porta de issue quebraria todo repositório de papel
165
+ // `code` (RFC-005): ele não tem bloco `project` — o board é do hub — e ainda
166
+ // assim comenta, etiqueta e lê issue do hub. `preflight`, `workspace`,
167
+ // `code-review` e `qa` rodam lá.
168
+ //
169
+ // Quem exige o board é quem precisa dele, e diz isso: `board: true`. É o que
170
+ // `openTracker` passa.
171
+ if (board && !bloco.config?.id) {
89
172
  return { tracker: null, root, error: `Project não configurado em ${CONFIG_FILE}` };
90
173
  }
91
174
 
@@ -99,25 +182,32 @@ export async function getTracker({
99
182
  };
100
183
  }
101
184
 
102
- // bloco A: aqui entra a resolução da §9.2, a partir de `config.tracker.kind`
103
- // (que o bloco D passa a derivar do bloco `project` quando ausente).
185
+ // O argumento-objeto vai inteiro para a fábrica, e cada plugin lê as chaves
186
+ // que conhece: o embutido lê `project`; um plugin de Jira leria `config`,
187
+ // `fieldMap` e `stageMap`. É para isso que a aridade está presa em 1.
104
188
  //
105
- // O try/catch não é zelo: a fábrica de um plugin é código de TERCEIRO, e a
106
- // partir do bloco A pode lançar por qualquer motivo. Um throw aqui viraria
107
- // stack trace no terminal de quem só instalou um plugin quebrado, em vez de
108
- // uma linha dizendo qual plugin e por quê.
109
- try {
110
- const tracker = createGithubTracker({
189
+ // `project` sai de `bloco.config` e NÃO de `config.project`: depois da
190
+ // normalização existe uma fonte só, e um `tracker.config` escrito à mão vence
191
+ // o bloco legado em vez de conviver com ele. Duas fontes com o mesmo conteúdo
192
+ // divergem no dia em que uma das duas é editada.
193
+ const { porta, error } = await buildPort({
194
+ port: 'tracker',
195
+ kind: bloco.kind,
196
+ pkg: bloco.package,
197
+ root: root || cwd,
198
+ params: {
111
199
  token,
112
200
  projectToken,
113
201
  owner: donoResolvido,
114
202
  repo: repoResolvido,
115
- project,
116
- });
117
- return { tracker, root, error: null };
118
- } catch (err) {
119
- return { tracker: null, root, error: `tracker "${TRACKER_KIND}" não pôde ser construído: ${err.message}` };
120
- }
203
+ project: bloco.config,
204
+ config: bloco.config,
205
+ stageMap: bloco.stageMap,
206
+ fieldMap: bloco.fieldMap,
207
+ typeMap: bloco.typeMap,
208
+ },
209
+ });
210
+ return { tracker: porta, root, error };
121
211
  }
122
212
 
123
213
  /**
@@ -142,28 +232,81 @@ export async function getTracker({
142
232
  * @param {object} [params.deps] `deps.scm` injeta uma porta já construída
143
233
  * @returns {Promise<{scm: ScmPort|null, error: string|null}>}
144
234
  */
145
- export async function getScm({ link, token, prToken, trackerKind, deps = {} } = {}) {
235
+ export async function getScm({
236
+ link, token, prToken, trackerKind, cwd = process.cwd(), pkg, deps = {},
237
+ } = {}) {
146
238
  if (deps.scm) return { scm: deps.scm, error: null };
147
239
  if (!link?.kind) return { scm: null, error: 'getScm: `link` sem `kind`' };
148
240
 
149
- // bloco A: resolução por `link.kind`. Até lá, só existe um fornecedor — e
150
- // recusar explicitamente o que não é ele vale mais que cair num default
151
- // silencioso, que é como um plugin errado entregaria a porta errada.
152
- if (link.kind !== SCM_KIND) {
153
- return { scm: null, error: `getScm: nenhum plugin de SCM para "${link.kind}"` };
154
- }
241
+ // ⚠️ `getScm` NÃO lê o config, e isso é decisão do bloco D e não omissão.
242
+ //
243
+ // Eu tinha escrito a leitura aqui — `scm.package` e `trackerKind` saindo do
244
+ // `.spec-wave.json` quando o chamador não os passa — e ela estava errada por
245
+ // dois motivos que só apareceram ao conferir o teste:
246
+ //
247
+ // 1. **`cwd` é ambíguo em multi-repo.** Uma instância de SCM é UM repositório,
248
+ // e `merge`/`code-review`/`qa` constroem portas para o hub E para repos de
249
+ // código com o mesmo `cwd` — o do hub. Ler `scm.package` dali e aplicá-lo
250
+ // ao repo de código é supor que há um plugin só para todos, o que a
251
+ // RFC-005 §12 vai reexpressar como LISTA. Adivinhar agora congela a forma
252
+ // errada;
253
+ // 2. **o teste passou lendo o config deste repositório.** `getScm({link})` sem
254
+ // `cwd` cai em `process.cwd()`, e a suíte roda na raiz, que tem
255
+ // `.spec-wave.json`. Verde por dependência escondida em estado real.
256
+ //
257
+ // `pkg` e `trackerKind` continuam vindo do CHAMADOR. Quem tem o config na mão é
258
+ // o comando, e é ele que sabe qual repositório está endereçando.
259
+ const { porta, error } = await buildPort({
260
+ port: 'scm',
261
+ kind: link.kind,
262
+ pkg,
263
+ root: cwd,
264
+ params: { link, token, prToken, trackerKind: trackerKind || DEFAULT_TRACKER_KIND },
265
+ });
266
+ return { scm: porta, error };
267
+ }
155
268
 
156
- // Mesmo motivo do try/catch do tracker: `createGithubScm` já lança quando o
157
- // `link` não traz `config.owner`/`config.repo`, e a partir do bloco A quem
158
- // lança é código de terceiro.
159
- try {
160
- return {
161
- scm: createGithubScm({ link, token, prToken, trackerKind: trackerKind || TRACKER_KIND }),
162
- error: null,
163
- };
164
- } catch (err) {
165
- return { scm: null, error: `scm "${link.kind}" não pôde ser construído: ${err.message}` };
166
- }
269
+ /**
270
+ * A porta de tracker, ou LANÇA — Fase 2 bloco E, leva 2.
271
+ *
272
+ * Os ~27 call sites do padrão A (`deps.tracker ?? create…`) não tinham caminho de
273
+ * erro, porque construir a porta era montar um objeto local e não podia falhar.
274
+ * Com o loader, pode: plugin ausente, quebrado, ou de versão de contrato errada.
275
+ *
276
+ * **Lançar é o tratamento uniforme, e é uniforme por uma razão, não por
277
+ * conveniência:** nesses sites o erro só pode vir do LOADER. O `deps` faz
278
+ * curto-circuito antes de qualquer leitura, `board` é false (então nada exige o
279
+ * bloco `project`) e `owner`/`repo` chegam do chamador, que já validou estar num
280
+ * repositório. Sobra "o plugin não carregou" — que não é condição de fluxo, é a
281
+ * CLI inutilizável, e a resposta certa é a mesma em todos.
282
+ *
283
+ * E lançar chega bem ao usuário: `src/cli.mjs` envolve cada comando em
284
+ * `.catch(err => { console.error(err.message); process.exit(1); })`, então sai a
285
+ * mensagem do loader — que nomeia o plugin e lista o que foi tentado — sem stack
286
+ * trace. Dar a cada site um `if (error)` próprio seria 27 decisões para uma
287
+ * falha só, e é assim que uma delas sai errada.
288
+ *
289
+ * @param {object} params o mesmo de `getTracker`
290
+ * @returns {Promise<object>} a porta
291
+ * @throws {Error} com a mensagem do loader
292
+ */
293
+ export async function requireTracker(params = {}) {
294
+ const { tracker, error } = await getTracker(params);
295
+ if (error) throw new Error(error);
296
+ return tracker;
297
+ }
298
+
299
+ /**
300
+ * A porta de SCM, ou LANÇA. Mesma razão de `requireTracker`.
301
+ *
302
+ * @param {object} params o mesmo de `getScm`
303
+ * @returns {Promise<object>} a porta
304
+ * @throws {Error}
305
+ */
306
+ export async function requireScm(params = {}) {
307
+ const { scm, error } = await getScm(params);
308
+ if (error) throw new Error(error);
309
+ return scm;
167
310
  }
168
311
 
169
312
  /**
@@ -175,9 +318,21 @@ export async function getScm({ link, token, prToken, trackerKind, deps = {} } =
175
318
  * e este entrava por outra porta. O bloco E0 migrou os 21 para cá e estendeu a
176
319
  * barreira, que hoje tem um guard só para `githubLink` no core.
177
320
  *
178
- * Aqui é um forward, e é de propósito: o valor está em existir UM ponto para o
179
- * bloco A trocar por "pergunte ao plugin resolvido", em vez de 21. Enquanto o
180
- * `kind` não vier do config (bloco D), o default é o único fornecedor que há.
321
+ * **Continua SÍNCRONA e com import estático do embutido, e o bloco A não mudou
322
+ * isso.** Duas razões, e a segunda é a que decide:
323
+ *
324
+ * 1. os 21 call sites que o E0 migrou são síncronos. Torná-la assíncrona os
325
+ * tocaria uma segunda vez, que é exatamente o que o bloco 0 existe para
326
+ * evitar — e sem ganho nenhum hoje;
327
+ * 2. a assinatura **já é** específica de fornecedor: ela toma `owner`/`repo`,
328
+ * que é o endereço de um repositório do GitHub. Um Azure DevOps precisa de
329
+ * `org/project/repo`. Rotear isto pelo loader não a generalizaria — só
330
+ * esconderia a especificidade atrás de um `await`. Generalizar é trabalho
331
+ * próprio: quem chama precisa deixar de saber o FORMATO do endereço, e isso
332
+ * é o bloco F (`init` grava o `config` do SCM) mais os call sites de E.
333
+ *
334
+ * O `throw` para `kind` desconhecido fica: é a única coisa aqui que diz a
335
+ * verdade sobre o alcance da função.
181
336
  *
182
337
  * @param {object} params
183
338
  * @param {string} params.owner