@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,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
+ }
@@ -0,0 +1,347 @@
1
+ // A entrada única para obter uma porta — RFC-006 Fase 2, bloco 0.
2
+ //
3
+ // Hoje o core constrói `createGithubTracker`/`createGithubScm` direto em ~35
4
+ // arquivos, em quatro padrões de injetabilidade diferentes. O objetivo da Fase
5
+ // 2 é que TODOS passem por aqui, e que este arquivo seja o único que sabe de
6
+ // onde um plugin vem.
7
+ //
8
+ // ── Por que existe antes de ter chamador ────────────────────────────────────
9
+ //
10
+ // Este arquivo é o bloco 0 do plano (`rfc/plano-fase2-portas.md`): a assinatura
11
+ // congelada, sem consumidor nenhum. É o que torna o resto paralelizável, e é a
12
+ // mesma disciplina que salvou a Fase 1 — o shim 9a→9d evitou que a mudança de
13
+ // assinatura do board fanasse por 11 arquivos num commit só. Assinatura primeiro,
14
+ // migração depois, em levas.
15
+ //
16
+ // ── Três decisões de forma, e as razões ─────────────────────────────────────
17
+ //
18
+ // **ASSÍNCRONAS**, mesmo devolvendo hoje um plugin embutido por import estático.
19
+ // O bloco A troca a resolução por `import()` dinâmico (§9.2), que é assíncrono
20
+ // por natureza. Nascer síncrono e virar assíncrono depois obrigaria a mexer em
21
+ // todos os ~35 call sites uma SEGUNDA vez — exatamente o que o bloco 0 existe
22
+ // para evitar.
23
+ //
24
+ // **Devolvem `{ porta, error }`, nunca lançam.** É a convenção da casa para
25
+ // falha de configuração: `loadConfig`, `openTracker` e `loadProjectConfig` já
26
+ // fazem assim, e os chamadores imprimem a string e saem com código. Um throw
27
+ // aqui viraria stack trace no terminal de quem só esqueceu de rodar o `init`.
28
+ //
29
+ // **`deps` continua sendo o seam de teste**, com a mesma forma de
30
+ // `lib/artifact-publish.mjs` e dos testes de fumaça: porta já construída vence
31
+ // qualquer resolução. Sem isso, cada comando migrado precisaria de um seam
32
+ // próprio de novo.
33
+ //
34
+ // ── A resolução mora no loader (bloco A) ────────────────────────────────────
35
+ //
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.
44
+ //
45
+ // `getScm` toma um `ScmLink` já pronto de propósito: `ScmLink` é tipo do
46
+ // CONTRATO e qualquer plugin sabe produzir um, então a assinatura sobrevive ao
47
+ // bloco A. Quem o CONSTRÓI era o buraco que o plano não previa — 21 arquivos do
48
+ // core importavam `githubLink` do plugin —, e o bloco E0 o fechou com
49
+ // `resolveScmLink` (no fim deste arquivo) mais a extensão da barreira.
50
+
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';
71
+ import { CONFIG_FILE } from '../config.mjs';
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';
80
+
81
+ /** @typedef {import('./tracker.mjs').TrackerPort} TrackerPort */
82
+ /** @typedef {import('./scm.mjs').ScmPort} ScmPort */
83
+ /** @typedef {import('./types.mjs').ScmLink} ScmLink */
84
+
85
+ /**
86
+ * A porta de tracker deste workspace.
87
+ *
88
+ * `projectToken` é separado porque quatro comandos e uma lib usam
89
+ * `PROJECT_TOKEN || token` SÓ para o board, com o token simples fazendo as
90
+ * issues no mesmo comando. Uma porta presa a uma credencial promoveria
91
+ * `PROJECT_TOKEN` às chamadas de issue — 403 num PAT com escopo `project` e sem
92
+ * `repo`, que nenhum teste desta suíte enxerga.
93
+ *
94
+ * @param {object} [params]
95
+ * @param {string} [params.cwd=process.cwd()] onde começar a busca do config
96
+ * @param {string} [params.token] credencial padrão (REST de issue)
97
+ * @param {string} [params.projectToken] credencial de board; ausente = `token`
98
+ * @param {string} [params.owner] vence o que estiver no config
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`
107
+ * @param {object} [params.deps] `deps.tracker` injeta uma porta já construída
108
+ * @returns {Promise<{tracker: TrackerPort|null, root: string|null, error: string|null}>}
109
+ */
110
+ export async function getTracker({
111
+ cwd = process.cwd(), token, projectToken, owner, repo, board = false,
112
+ kind: kindExplicito, pkg: pkgExplicito, deps = {},
113
+ } = {}) {
114
+ const { config, root, error: configError } = loadConfig(cwd);
115
+
116
+ // Porta injetada vence tudo, e nem o bloco `project` é exigido: quem injeta
117
+ // já decidiu de onde ela vem. `root` continua saindo do config porque os
118
+ // chamadores o usam para achar os documentos.
119
+ if (deps.tracker) return { tracker: deps.tracker, root, error: null };
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
+
143
+ if (configError) return { tracker: null, root, error: configError };
144
+
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) {
172
+ return { tracker: null, root, error: `Project não configurado em ${CONFIG_FILE}` };
173
+ }
174
+
175
+ const donoResolvido = owner || config.owner;
176
+ const repoResolvido = repo || config.repo;
177
+ if (!donoResolvido || !repoResolvido) {
178
+ return {
179
+ tracker: null,
180
+ root,
181
+ error: `owner/repo ausentes no chamador e em ${CONFIG_FILE}`,
182
+ };
183
+ }
184
+
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.
188
+ //
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: {
199
+ token,
200
+ projectToken,
201
+ owner: donoResolvido,
202
+ repo: repoResolvido,
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 };
211
+ }
212
+
213
+ /**
214
+ * A porta de SCM de UM repositório.
215
+ *
216
+ * Toma um `ScmLink` e não um par `owner`/`repo` porque uma instância de SCM **é
217
+ * um repositório**, e porque o par não cabe no Azure DevOps (`org/project/repo`).
218
+ * Em arquivo que fala com dois repositórios, o identificador nunca é `scm`
219
+ * pelado — `hubScm`, `prScm`, `scmFor(link)`: uma variável errada abre PR no hub
220
+ * em vez do repo de código, e nenhum teste pega.
221
+ *
222
+ * `prToken` existe porque `lib/artifact-publish.mjs` usa
223
+ * `SPEC_WAVE_PR_TOKEN || GH_PR_TOKEN || token` SÓ para abrir PR, e a promoção
224
+ * dessa credencial ao resto das chamadas é invisível para a suíte.
225
+ *
226
+ * @param {object} params
227
+ * @param {ScmLink} params.link
228
+ * @param {string} [params.token]
229
+ * @param {string} [params.prToken] credencial de PR; ausente = `token`
230
+ * @param {string} [params.trackerKind] com qual tracker este SCM foi pareado —
231
+ * §8.1: nenhum plugin de SCM descobre isso sozinho, o core injeta
232
+ * @param {object} [params.deps] `deps.scm` injeta uma porta já construída
233
+ * @returns {Promise<{scm: ScmPort|null, error: string|null}>}
234
+ */
235
+ export async function getScm({
236
+ link, token, prToken, trackerKind, cwd = process.cwd(), pkg, deps = {},
237
+ } = {}) {
238
+ if (deps.scm) return { scm: deps.scm, error: null };
239
+ if (!link?.kind) return { scm: null, error: 'getScm: `link` sem `kind`' };
240
+
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
+ }
268
+
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;
310
+ }
311
+
312
+ /**
313
+ * Um `ScmLink` a partir do endereço de um repositório.
314
+ *
315
+ * Existia porque 21 arquivos do core importavam `githubLink` DO PLUGIN — o core
316
+ * nomeando um fornecedor, que é o acoplamento que as portas existem para
317
+ * remover. A barreira não enxergava: ela varria imports de `src/api/github-*`,
318
+ * e este entrava por outra porta. O bloco E0 migrou os 21 para cá e estendeu a
319
+ * barreira, que hoje tem um guard só para `githubLink` no core.
320
+ *
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.
336
+ *
337
+ * @param {object} params
338
+ * @param {string} params.owner
339
+ * @param {string} params.repo
340
+ * @param {'hub'|'code'} [params.role]
341
+ * @param {string} [params.kind]
342
+ * @returns {ScmLink}
343
+ */
344
+ export function resolveScmLink({ owner, repo, role = 'hub', kind = SCM_KIND }) {
345
+ if (kind !== SCM_KIND) throw new Error(`resolveScmLink: nenhum plugin de SCM para "${kind}"`);
346
+ return githubLink({ owner, repo, role });
347
+ }
package/src/ports/scm.mjs CHANGED
@@ -11,7 +11,7 @@
11
11
  // pelado é proibido em arquivo que lida com mais de um: uma variável errada
12
12
  // abre PR no repositório errado e nenhum teste pega.
13
13
  //
14
- // @see rfc/protocol/scm.v1.json — o contrato normativo
14
+ // @see protocol/scm.v1.json — o contrato normativo, publicado no npm
15
15
  // @see src/ports/types.mjs — os tipos do domínio
16
16
 
17
17
  /**
@@ -36,11 +36,30 @@
36
36
  * ── SEMPRE ────────────────────────────────────────────────────────────────
37
37
  *
38
38
  * @property {(o?: {log?: Function}) => Promise<{warnings: string[]}>} setup
39
- * @property {() => Promise<VerifyResult>} verify
39
+ * @property {(o?: {deep?: boolean}) => Promise<VerifyResult>} verify
40
40
  * Absorve a sonda de alcance do repositório — hoje `getRepoNodeId` chamada
41
41
  * por `commands/repo.mjs` com o retorno descartado. `ok: false` é "não
42
42
  * alcanço este repositório com esta credencial".
43
43
  *
44
+ * Fato SEMPRE reportado, e com três estados: `repoReachable` — `true`
45
+ * alcançado, `false` "esta credencial NÃO enxerga este repositório" (resposta
46
+ * definitiva), `null` "não consegui verificar agora". Fundir os dois últimos
47
+ * faria um diagnóstico acusar repositório correto sempre que a API oscilasse.
48
+ *
49
+ * `deep` pede os fatos de AUTOMAÇÃO, que custam chamadas a mais e que só o
50
+ * `doctor` imprime. Todos OPCIONAIS, e nenhum é veredito (ver `VerifyResult`):
51
+ * • `repoFullName` / `repoPrivate` / `defaultBranch`;
52
+ * • `automationSecretNames` — nomes (nunca valores) dos segredos que a
53
+ * automação enxerga. É o core que sabe o que `GH_PR_TOKEN` significa: a
54
+ * convenção é do spec-wave, não do fornecedor;
55
+ * • `automationCanOpenPullRequest` — a automação pode abrir PR aqui.
56
+ * `null` = consultei e não pude ver (exige permissão de administração, e
57
+ * não tê-la é o caso comum), que NÃO é "não pode";
58
+ * • `protectedChecks` — contextos de status check obrigatórios na branch
59
+ * default. `[]` é "nenhum"; `null` é "não consegui ler a proteção". A
60
+ * diferença decide um FAIL: PR aberto pela automação não dispara workflow,
61
+ * então um check obrigatório trava TODO PR de documento, sem erro visível.
62
+ *
44
63
  * @property {() => Promise<string>} defaultBranch
45
64
  * @property {() => Promise<boolean>} isInitialized
46
65
  * @property {(o: {path: string, ref?: string}) => Promise<string|null>} readFile
@@ -94,6 +113,10 @@
94
113
  * @property {(o: {action: string, key: string}) => Promise<void>} [dispatch] remoteDispatch.mechanism !== 'none'
95
114
  */
96
115
 
116
+ // Mesma dependência de runtime do contrato de tracker, pelo mesmo motivo: a
117
+ // regra de vocabulário de capabilities é uma só (ver `./capabilities.mjs`).
118
+ import { checkCapabilityKeys } from './capabilities.mjs';
119
+
97
120
  /** Operações que todo SCM implementa. Ver a nota em `tracker.mjs`. */
98
121
  export const SCM_REQUIRED_OPERATIONS = Object.freeze([
99
122
  'setup', 'verify',
@@ -116,6 +139,19 @@ export const SCM_CONDITIONAL_OPERATIONS = Object.freeze({
116
139
  'remoteDispatch!=none': Object.freeze(['dispatch']),
117
140
  });
118
141
 
142
+ /**
143
+ * O vocabulário de `capabilities` desta versão do contrato de SCM.
144
+ *
145
+ * Mesma razão do tracker (ver `TRACKER_CAPABILITY_KEYS`): chave desconhecida é
146
+ * ignorada em silêncio e a operação que ela deveria exigir deixa de ser cobrada.
147
+ * Aqui a superfície é ainda mais afiada — `pullRequests.draft` controla
148
+ * `markReadyForReview`, e um plugin que escrevesse `pullRequest` (singular)
149
+ * carregaria conforme e não saberia tirar PR de rascunho.
150
+ */
151
+ export const SCM_CAPABILITY_KEYS = Object.freeze([
152
+ 'automation', 'fileWrites', 'identity', 'pullRequests', 'remoteDispatch', 'variables',
153
+ ]);
154
+
119
155
  /**
120
156
  * As operações exigidas de um SCM com estas capabilities (função PURA).
121
157
  *
@@ -151,6 +187,7 @@ export function checkScmPort(port) {
151
187
  if (!port || typeof port !== 'object') return ['porta de SCM ausente'];
152
188
  if (!port.kind) problemas.push('porta de SCM sem `kind`');
153
189
  if (!port.link?.id) problemas.push(`porta de SCM ${port.kind} sem \`link.id\``);
190
+ problemas.push(...checkCapabilityKeys(port.capabilities, SCM_CAPABILITY_KEYS));
154
191
  for (const op of scmRequiredOperations(port.capabilities || {})) {
155
192
  if (typeof port[op] !== 'function') {
156
193
  problemas.push(`operação "${op}" exigida pelas capabilities e ausente na porta ${port.kind}`);
@@ -31,7 +31,7 @@
31
31
  // assinatura das operações: é o que hoje faz `makeOctokit(token)` nascer por
32
32
  // chamada e não haver ponto único onde trocar o fornecedor.
33
33
  //
34
- // @see rfc/protocol/tracker.v1.json — o contrato normativo
34
+ // @see protocol/tracker.v1.json — o contrato normativo, publicado no npm
35
35
  // @see src/ports/types.mjs — os tipos do domínio
36
36
 
37
37
  /**
@@ -46,6 +46,11 @@
46
46
  * @typedef {import('./types.mjs').VerifyResult} VerifyResult
47
47
  */
48
48
 
49
+ // A única dependência de RUNTIME deste contrato, e ela é para as duas portas:
50
+ // `src/ports/capabilities.mjs`. Não mora em `types.mjs` porque aquele é
51
+ // declaradamente sem runtime, nem aqui porque `scm.mjs` também a usa.
52
+ import { checkCapabilityKeys } from './capabilities.mjs';
53
+
49
54
  /**
50
55
  * @typedef {object} TrackerPort
51
56
  * @property {string} kind `'github-projects'`, `'jira'`.
@@ -61,12 +66,26 @@
61
66
  * quem serializa é `lib/config-file.mjs`, byte-exato, porque o `update` faz
62
67
  * diff contra a cópia remota.
63
68
  *
64
- * @property {() => Promise<VerifyResult>} verify
69
+ * @property {(o?: {deep?: boolean}) => Promise<VerifyResult>} verify
65
70
  * Diagnóstico SEM efeito. Absorve `getRateLimit`, `getProjectSnapshot`,
66
71
  * `getSingleSelectField` e `getOwnerType` — esta última é a sonda org-vs-user
67
72
  * que bloqueia o `init`, porque o GitHub App só alcança Projects v2 de
68
73
  * organização. Num tracker sem noção de "owner" ela some de `facts`.
69
74
  *
75
+ * `deep` é para o `doctor`: pede os fatos que custam chamadas a mais. O `init`
76
+ * e o `repo` chamam sem ele e não pagam por diagnóstico que não vão imprimir.
77
+ *
78
+ * Fatos que o `doctor` sabe ler, todos OPCIONAIS (ver `VerifyResult`):
79
+ * • `ownerType` — `'Organization'` | `'User'`;
80
+ * • `boardTitle` / `boardKey` — como o board se identifica no fornecedor;
81
+ * • `boardFound` — o board do config existe com esta credencial;
82
+ * • `stageOptions` — `Record<nome, id>` das etapas REAIS. É o que separa
83
+ * "renomearam a coluna" de "o id no config envelheceu", e o segundo faz
84
+ * TODA escrita de Etapa falhar em silêncio;
85
+ * • `ownerMembership` (só com `deep`) — o vínculo do usuário da credencial
86
+ * com quem é dono do board. `'active'` é o caso bom; `null` é "não dá para
87
+ * saber", que NÃO é "não pertence".
88
+ *
70
89
  * @property {(o: {title: string, body: string, type: string, tags?: string[], milestone?: MilestoneRef|null, parent?: WorkItemRef|null}) => Promise<WorkItemRef>} createWorkItem
71
90
  * @property {(o: {ref: WorkItemRef|string|number}) => Promise<WorkItem|null>} getWorkItem
72
91
  * `ref` pode vir só com a chave — é o que o usuário digita. O plugin resolve
@@ -83,6 +102,14 @@
83
102
  * `color`/`description` são IGNORADOS quando `tagConstraints.colors` /
84
103
  * `.descriptions` é false. O core manda sempre; o plugin descarta. É mais
85
104
  * barato que o core aprender o que cada tracker guarda.
105
+ *
106
+ * ⚠️ `created` significa **"tentei criar"**, não "criei agora". O plugin do
107
+ * GitHub chama `createLabel` e engole o 422 de "já existe", porque a operação é
108
+ * idempotente POR EFEITO: chamar duas vezes deixa a tag existindo uma vez. A
109
+ * ambiguidade estava só na cabeça de quem leu o nome — o kit de conformidade
110
+ * (bloco B) reprovou o plugin embutido por eu ter afirmado, no kit, a leitura
111
+ * errada. Quem precisa saber se a tag NASCEU agora compara `listTags` antes e
112
+ * depois; o retorno serve para relatar o que foi tentado.
86
113
  * @property {() => Promise<Array<{name: string, color?: string, description?: string}>>} listTags
87
114
  *
88
115
  * @property {(o: {ref: WorkItemRef}) => Promise<string|null>} getStage
@@ -288,10 +315,69 @@ export function trackerRequiredOperations(capabilities = {}) {
288
315
  return [...exigidas];
289
316
  }
290
317
 
318
+ /**
319
+ * Chaves que um `keyPattern` NUNCA pode aceitar (função PURA).
320
+ *
321
+ * `#` é sigilo ou separador em três pontos do texto que o fluxo gera e
322
+ * reanalisa depois: `refKey()` descarta um `#` inicial porque ali ele é o
323
+ * prefixo da referência e não parte da chave; `Depende de: #4, #5` é escrito no
324
+ * corpo das Stories e lido de volta por `lib/dependencies.mjs`; e
325
+ * `owner/repo#n` sai no `closingKeyword` em multi-repo. Uma chave com `#`
326
+ * tornaria `#A#B` indistinguível de duas referências, e o estrago apareceria
327
+ * como dependência que some — não como erro.
328
+ *
329
+ * `1#2` está na lista para cobrar ÂNCORA: sem `^…$` um `[0-9]+` solto casa o
330
+ * "1" dentro de "1#2" e `test` devolve true, e aí a proibição passaria por
331
+ * acidente num pattern que na verdade aceita qualquer coisa em volta.
332
+ */
333
+ const CHAVES_PROIBIDAS = Object.freeze(['#', '1#2', '#42', 'PROJ-1#2', 'a#']);
334
+
335
+ /**
336
+ * O `identity.keyPattern` declarado é utilizável? (função PURA)
337
+ *
338
+ * Separada de `checkTrackerPort` para o kit de conformidade da Fase 2
339
+ * (`@spec-wave/plugin-conformance`) poder chamar a MESMA regra — o manifesto
340
+ * afirma que ele confere isto, e duas cópias da regra divergiriam. É por isso
341
+ * que ela é exportada apesar de ter um chamador só hoje.
342
+ *
343
+ * @param {string} [pattern]
344
+ * @returns {string[]} problemas; vazio = utilizável
345
+ */
346
+ export function checkKeyPattern(pattern) {
347
+ if (!pattern) return ['`identity.keyPattern` ausente'];
348
+ let re;
349
+ try {
350
+ re = new RegExp(pattern);
351
+ } catch {
352
+ return [`\`identity.keyPattern\` não é regex válida: ${pattern}`];
353
+ }
354
+ const aceitas = CHAVES_PROIBIDAS.filter(c => re.test(c));
355
+ if (aceitas.length) {
356
+ return [
357
+ `\`identity.keyPattern\` ${pattern} aceita ${aceitas.map(c => `"${c}"`).join(', ')}: ` +
358
+ 'a chave não pode conter `#`, que é o sigilo de referência em `#N`, `Depende de:` e `owner/repo#n`',
359
+ ];
360
+ }
361
+ return [];
362
+ }
363
+
364
+ /**
365
+ * O vocabulário de `capabilities` desta versão do contrato de tracker.
366
+ *
367
+ * A razão de a lista ser FECHADA está em `./capabilities.mjs`, junto da regra.
368
+ * Aqui basta: chave desconhecida é ignorada em silêncio, e a operação que ela
369
+ * deveria exigir deixa de ser cobrada.
370
+ */
371
+ export const TRACKER_CAPABILITY_KEYS = Object.freeze([
372
+ 'boardProvisioning', 'closeSemantics', 'commentFormat', 'commentMarkers',
373
+ 'dependencies', 'fields', 'hierarchy', 'identity', 'milestones', 'progress',
374
+ 'reopen', 'stages', 'tagConstraints', 'workItemTypes',
375
+ ]);
376
+
291
377
  /**
292
378
  * Confere um plugin de tracker contra as capabilities que ele declara.
293
379
  *
294
- * Roda na CARGA, não no meio de um comando: as duas checagens são baratas, e um
380
+ * Roda na CARGA, não no meio de um comando: as checagens são baratas, e um
295
381
  * plugin publicado independentemente VAI ficar para trás do core — descobrir
296
382
  * isso na primeira chamada de rede é o pior momento possível.
297
383
  *
@@ -302,6 +388,11 @@ export function checkTrackerPort(port) {
302
388
  const problemas = [];
303
389
  if (!port || typeof port !== 'object') return ['porta de tracker ausente'];
304
390
  if (!port.kind) problemas.push('porta de tracker sem `kind`');
391
+ // Aqui, e não só no teste da suíte: o invariante existe para os plugins que
392
+ // ainda não existem, e um plugin de terceiro com `keyPattern` permissivo
393
+ // precisa reprovar na CARGA, onde nenhum teste nosso o alcança.
394
+ problemas.push(...checkKeyPattern(port.capabilities?.identity?.keyPattern));
395
+ problemas.push(...checkCapabilityKeys(port.capabilities, TRACKER_CAPABILITY_KEYS));
305
396
  for (const op of trackerRequiredOperations(port.capabilities || {})) {
306
397
  if (typeof port[op] !== 'function') {
307
398
  problemas.push(`operação "${op}" exigida pelas capabilities e ausente na porta ${port.kind}`);