@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
@@ -17,8 +17,7 @@
17
17
  // implementação, que a essa altura já está commitada.
18
18
 
19
19
  import * as p from '@clack/prompts';
20
- import { createGithubScm } from '../plugins/scm-github/index.mjs';
21
- import { resolveScmLink } from '../ports/index.mjs';
20
+ import { requireScm, resolveScmLink } from '../ports/index.mjs';
22
21
  import { extractIssueRefs, hubIssueNumbers } from './pr-link.mjs';
23
22
 
24
23
  /**
@@ -84,13 +83,19 @@ export async function collectFeaturePullRequests({
84
83
  const hub = { owner, repo };
85
84
  // Uma porta POR REPOSITÓRIO — é o que o contrato manda, e é a razão de
86
85
  // `PullRequestRef` carregar o `link`: o número do PR colide entre repos.
87
- const portaDe = scmDe ?? (r => createGithubScm({
88
- link: resolveScmLink({ owner: r.owner, repo: r.repo, role: sameRepoQue(r, hub) ? 'hub' : 'code' }),
89
- token,
90
- }));
86
+ // A fábrica virou ASSÍNCRONA porque `requireScm` é — daí o `await` duplo nos
87
+ // call sites. Uma porta POR REPOSITÓRIO segue sendo o que o contrato manda, e é
88
+ // a razão de `PullRequestRef` carregar o `link`: o número do PR colide entre
89
+ // repos.
90
+ const portaDe = scmDe
91
+ ? (async r => scmDe(r))
92
+ : (r => requireScm({
93
+ link: resolveScmLink({ owner: r.owner, repo: r.repo, role: sameRepoQue(r, hub) ? 'hub' : 'code' }),
94
+ token,
95
+ }));
91
96
 
92
97
  for (const r of [hub, ...codeRepos]) {
93
- const abertos = await portaDe(r).listOpenPullRequests().catch(() => []);
98
+ const abertos = await (await portaDe(r)).listOpenPullRequests().catch(() => []);
94
99
  for (const bruto of abertos) {
95
100
  const pr = { ...bruto, repo: { owner: r.owner, repo: r.repo } };
96
101
  const fecha = hubIssueNumbers(extractIssueRefs(pr.body || '', { prRepo: pr.repo, linkMode }), hub);
@@ -99,7 +104,14 @@ export async function collectFeaturePullRequests({
99
104
  }
100
105
 
101
106
  // Vínculo NATIVO: só existe no hub (o GitHub não fecha issue entre repos).
102
- const hubScm = portaDe(hub);
107
+ //
108
+ // `await`: a fábrica virou assíncrona na leva 3 do bloco E. Sem ele `hubScm` é
109
+ // uma Promise, `.findPullRequestsReferencing` é `undefined`, o `TypeError`
110
+ // sincrônico NÃO é pego pelo `.catch(() => [])` logo abaixo — que só existe
111
+ // depois de haver promessa — e a busca por vínculo nativo devolvia vazio. Foi
112
+ // assim que o `markFeaturePrsReady` parou de achar PR em rascunho, e o teste de
113
+ // fumaça pegou: ele afirma que o PR FOI marcado, não só que nada vazou.
114
+ const hubScm = await portaDe(hub);
103
115
  for (const node of issueNodes) {
104
116
  if (!node?.nodeId) continue;
105
117
  const achados = await hubScm
@@ -170,12 +182,12 @@ export async function markFeaturePrsReady({
170
182
  // O PR pode estar em qualquer repo da Feature: a porta é a DELE, não a do
171
183
  // hub. Marcar um PR de repo de código com a porta do hub é 404 — ou pior,
172
184
  // o PR de mesmo número no hub.
173
- const portaDoPr = (pr) => {
185
+ const portaDoPr = async (pr) => {
174
186
  const r = { owner: pr.repo?.owner ?? owner, repo: pr.repo?.repo ?? repo };
175
187
  if (scmDe) return scmDe(r);
176
188
  // `role` sai de `pr.repo`, não de `r`: o par já traz fallback no hub, e
177
189
  // computar dali faria um `pr.repo` ausente virar 'hub' onde era 'code'.
178
- return createGithubScm({
190
+ return requireScm({
179
191
  link: resolveScmLink({ ...r, role: sameRepoQue(pr.repo, hub) ? 'hub' : 'code' }),
180
192
  token,
181
193
  });
@@ -184,7 +196,7 @@ export async function markFeaturePrsReady({
184
196
  const falhas = [];
185
197
  for (const pr of alvos) {
186
198
  try {
187
- await portaDoPr(pr).markReadyForReview({ id: pr.id });
199
+ await (await portaDoPr(pr)).markReadyForReview({ id: pr.id });
188
200
  marcados.push(prLabel(pr, hub));
189
201
  } catch (err) {
190
202
  falhas.push(`${prLabel(pr, hub)} (${err.message})`);
@@ -21,7 +21,6 @@
21
21
  import { existsSync, readFileSync } from 'node:fs';
22
22
  import path from 'node:path';
23
23
 
24
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
25
24
 
26
25
  // ── Tradução WorkItem → a forma que este módulo SEMPRE devolveu ─────────────
27
26
  //
@@ -75,6 +74,7 @@ import { featureDocPaths } from './doc-paths.mjs';
75
74
  import { parseDecompositionDoc } from './decomposition-doc.mjs';
76
75
  import { parseDependencies } from './dependencies.mjs';
77
76
  import { indexBoardItems } from './board.mjs';
77
+ import { getTracker, requireTracker } from '../ports/index.mjs';
78
78
  import {
79
79
  parseDependencyMap, storiesFromAppliedDoc, mergeDependencyEdges, isFresh,
80
80
  DEPENDENCY_MAP_FILE,
@@ -117,7 +117,7 @@ export async function loadFeatureStories({
117
117
 
118
118
  // ── sub-issues (com body!) — cache subissues-<n> ───────────────────────────
119
119
  const subsKey = `subissues-${feature.number}`;
120
- const tracker = trackerInjetado || createGithubTracker({ token, owner, repo });
120
+ const tracker = await requireTracker({ cwd: root, token, owner, repo, deps: { tracker: trackerInjetado } });
121
121
  const cached = refresh ? null : readCacheEntry(root, subsKey, { owner, repo });
122
122
  let allSubs;
123
123
  let subsFrom;
@@ -226,7 +226,8 @@ export async function cachedSubIssues({
226
226
  const hit = readCacheEntry(root, key, { owner, repo });
227
227
  if (hit && isFresh(hit, ttlSec)) return { subs: hit.data, fromCache: true, fetchedAt: hit.fetchedAt };
228
228
  }
229
- const subs = (await (tracker ?? createGithubTracker({ token, owner, repo })).listChildren({
229
+ const porta = await requireTracker({ cwd: root, token, owner, repo, deps: { tracker } });
230
+ const subs = (await porta.listChildren({
230
231
  ref: { key: String(parent.number), id: parent.nodeId || parent.node_id },
231
232
  })).map(comoSubIssue);
232
233
  writeCacheEntry(root, key, 'sub-issues', subs, { owner, repo });
@@ -277,7 +278,13 @@ export async function loadBoardSnapshot({
277
278
  };
278
279
  }
279
280
  }
280
- const items = (await (trackerInjetado || createGithubTracker({ token, owner, repo, project })).boardSnapshot())
281
+ // `board: true`: esta função TIRA UM RETRATO do board, então sem o bloco
282
+ // `project` não há o que endereçar — e a mensagem que diz para rodar o `init`
283
+ // é melhor que um `boardSnapshot` vazio passando por "nenhum item".
284
+ const portaBoard = await requireTracker({
285
+ cwd: root, token, owner, repo, board: true, deps: { tracker: trackerInjetado },
286
+ });
287
+ const items = (await portaBoard.boardSnapshot())
281
288
  .map(comoItemDoBoard);
282
289
  writeCacheEntry(root, key, 'board-items', items, { projectId: project.id });
283
290
  return {
@@ -304,8 +311,14 @@ export async function externalIssueInfo({
304
311
  const hit = readCacheEntry(root, key, { owner, repo });
305
312
  if (hit && isFresh(hit, ttlSec)) return { ...hit.data, fromCache: true };
306
313
  }
307
- const issue = await createGithubTracker({ token, owner, repo })
308
- .getWorkItem({ ref: { key: String(number) } }).catch(() => null);
314
+ // `getTracker` e não `requireTracker`: esta função é best-effort por contrato
315
+ // — ela devolve "(não foi possível ler)" em vez de lançar, e o chamador conta
316
+ // com isso para montar o mapa de dependências mesmo com uma issue externa
317
+ // ilegível. Um plugin quebrado é mais um motivo de ilegibilidade, não um motivo
318
+ // para derrubar o comando.
319
+ const { tracker: portaExterna } = await getTracker({ cwd: root, token, owner, repo });
320
+ const issue = await portaExterna
321
+ ?.getWorkItem({ ref: { key: String(number) } }).catch(() => null) ?? null;
309
322
  if (!issue) {
310
323
  // Falha não entra no cache: "não foi possível ler" com cara de fresco por
311
324
  // 10 minutos esconderia uma issue que voltou a ser legível.
@@ -0,0 +1,58 @@
1
+ // O tracker tem REGISTRO de tags? — função PURA. RFC-006 Fase 2, bloco C.
2
+ //
3
+ // `deleteTag` e `countOpenWithTag` são as duas únicas operações do contrato
4
+ // marcadas OPCIONAIS que nenhuma capability liga — o bloco C achou isso cruzando
5
+ // a prosa do manifesto com as tabelas de condicionais. A prosa as justifica com
6
+ // "usados por uninstall e update", que não é uma capability, então
7
+ // `trackerRequiredOperations` NUNCA pode exigi-las: um plugin conforme pode
8
+ // omiti-las, e `uninstall`/`update` as chamavam sem guarda.
9
+ //
10
+ // ── Por que não são obrigatórias ─────────────────────────────────────────────
11
+ //
12
+ // A ausência é legítima, e é o que impede a saída fácil de promovê-las a
13
+ // obrigatórias. No GitHub uma label é uma ENTIDADE do repositório: tem cor,
14
+ // descrição, e existe mesmo sem estar em item nenhum — então apagar e contar
15
+ // fazem sentido. No Jira uma label é uma STRING livre no campo `labels` do
16
+ // issue: não há registro para apagar, e "quantos itens abertos têm esta label" é
17
+ // uma busca, não uma propriedade da label. Exigir as duas obrigaria todo plugin
18
+ // a fingir um registro que o site dele não tem.
19
+ //
20
+ // ── Por que função pura, e não capability ────────────────────────────────────
21
+ //
22
+ // A resposta certa a longo prazo é uma capability (`tagRegistry: 'native' | 'none'`),
23
+ // e ela deve entrar no dia em que existir um segundo tracker — hoje inventá-la
24
+ // seria congelar a forma contra o único fornecedor que há, o mesmo argumento pelo
25
+ // qual a §3.2 do plano recusou espelhar `capabilities` no config.
26
+ //
27
+ // O que esta função faz é exatamente o que essa capability produziria: uma
28
+ // decisão, num lugar, com a razão escrita. Quando a capability existir, o corpo
29
+ // aqui passa a lê-la e os dois chamadores não mudam.
30
+ //
31
+ // ── E por que o guard não é zelo ─────────────────────────────────────────────
32
+ //
33
+ // Chamar `undefined` lança de forma **SINCRÔNICA**, antes de existir promessa a
34
+ // que anexar um `.catch`. Então nem o `.catch(() => null)` que já estava na linha
35
+ // do `countOpenWithTag` nem o `try` em volta salvam: o `TypeError` seria
36
+ // reportado como "Falha ao remover label", mandando o usuário procurar um
37
+ // problema de permissão num tracker que está certo.
38
+
39
+ /**
40
+ * O que dá para fazer com o registro de tags deste tracker (função PURA).
41
+ *
42
+ * @param {object|null} tracker a porta
43
+ * @returns {{canDelete: boolean, canCount: boolean, warning: string|null}}
44
+ * `warning` é a frase para o usuário quando apagar não é possível — `null`
45
+ * quando é, para o chamador não precisar decidir se avisa.
46
+ */
47
+ export function tagRegistryPlan(tracker) {
48
+ const canDelete = typeof tracker?.deleteTag === 'function';
49
+ const canCount = typeof tracker?.countOpenWithTag === 'function';
50
+ return {
51
+ canDelete,
52
+ canCount,
53
+ warning: canDelete
54
+ ? null
55
+ : 'Este tracker não tem registro de labels para apagar — as labels do spec-wave '
56
+ + 'continuam nos itens onde já estão. Remova-as na interface, se quiser.',
57
+ };
58
+ }
@@ -9,7 +9,7 @@
9
9
  // Contrato: registrar uso NUNCA derruba o fluxo principal — recordUsage é
10
10
  // best-effort e engole qualquer erro com um console.warn.
11
11
 
12
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
12
+ import { getTracker } from '../ports/index.mjs';
13
13
 
14
14
  // Marcador HTML invisível que identifica o comentário de uso na issue.
15
15
  export const USAGE_MARKER = '<!-- spec-wave:usage -->';
@@ -149,7 +149,20 @@ export function renderUsageComment(entries) {
149
149
  */
150
150
  export async function recordUsage({ token, owner, repo, issueNumber, entries, tracker = null } = {}) {
151
151
  if (!Array.isArray(entries) || entries.length === 0) return;
152
- const porta = tracker || createGithubTracker({ token, owner, repo });
152
+ // `getTracker` e não `requireTracker`: o contrato no topo deste arquivo é
153
+ // "registrar uso NUNCA derruba o fluxo principal", e a construção da porta está
154
+ // FORA do `try` abaixo. Derrubar um `generate-*` por causa do comentário de
155
+ // custo jogaria fora uma geração de IA já paga.
156
+ //
157
+ // ⚠️ Diferente do `doc-source`, este ramo É alcançável: `getTracker` recusa
158
+ // quando o `kind` do config não tem plugin, e este arquivo não crava fornecedor
159
+ // nenhum. Daí o `console.warn` em vez de silêncio — telemetria que não sai
160
+ // precisa dizer que não saiu, senão a conta de uso mente por omissão.
161
+ const { tracker: porta, error: erroPorta } = await getTracker({ token, owner, repo, deps: { tracker } });
162
+ if (erroPorta) {
163
+ console.warn(`⚠️ Uso não registrado: ${erroPorta}`);
164
+ return;
165
+ }
153
166
  const ref = { key: String(issueNumber) };
154
167
  try {
155
168
  const comments = await porta.listComments({ ref });
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.4.0",
4
+ "version": "1.6.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",
@@ -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
+ }