@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
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,15 +36,59 @@
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
47
- * `null` em 404 — é RESULTADO esperado (o documento pode não existir), não erro.
66
+ * **TEXTO, decodificado como UTF-8.** `null` em 404 — é RESULTADO esperado (o
67
+ * documento pode não existir), não erro.
68
+ *
69
+ * ⚠️ Ler um BINÁRIO por aqui não dá erro: dá mojibake. A decodificação é
70
+ * lossy e irreversível, e a saída do caso quebrado é indistinguível da do caso
71
+ * feliz — exatamente a degradação que o resto deste contrato persegue. Quem
72
+ * precisa dos bytes usa `readFileBytes`, e o plugin declara
73
+ * `fileReads.bytes: true` para oferecê-la.
74
+ *
75
+ * Onde `fileReads.bytes` é `true`, `readFile` **é** `readFileBytes`
76
+ * decodificado — não uma segunda rota. Isso é requisito e não coincidência:
77
+ * duas rotas independentes para o mesmo arquivo divergem no dia em que uma
78
+ * ganhar cache, retry ou tratamento de `ref` que a outra não tem.
79
+ * @property {(o: {path: string, ref?: string}) => Promise<Uint8Array|null>} [readFileBytes]
80
+ * Os BYTES, sem decodificação. `null` em 404, como `readFile`.
81
+ * *(fileReads.bytes)*
82
+ *
83
+ * Condicional, e não obrigatória, porque um SCM que só sirva documento de
84
+ * texto não deve precisar implementá-la. Mas **não é particularidade de
85
+ * fornecedor** — GitLab, Azure Repos e Bitbucket servem bytes igual —, e é por
86
+ * isso que ela é operação de contrato em vez de escape hatch do plugin.
87
+ *
88
+ * Quem a pediu foi a evidência visual de QA (vídeo e imagem), que a
89
+ * `spec-wave-ui` precisa ler. Nenhum comando da CLI lê binário hoje; o risco
90
+ * que ela fecha é o do PRÓXIMO plugin copiar a coerção do nosso `readFile` sem
91
+ * saber que ela existe, e embarcar arquivo corrompido sem sinal nenhum.
48
92
  * @property {(o: {branch: string, base: string, files: FileWrite[], message: string}) => Promise<CommitResult>} writeFiles
49
93
  * Atômico: N arquivos, um commit, ou nada. `fileWrites.mode`
50
94
  * (`tree-commit-ref` × `push`) é detalhe INTERNO do plugin.
@@ -94,6 +138,10 @@
94
138
  * @property {(o: {action: string, key: string}) => Promise<void>} [dispatch] remoteDispatch.mechanism !== 'none'
95
139
  */
96
140
 
141
+ // Mesma dependência de runtime do contrato de tracker, pelo mesmo motivo: a
142
+ // regra de vocabulário de capabilities é uma só (ver `./capabilities.mjs`).
143
+ import { checkCapabilityKeys } from './capabilities.mjs';
144
+
97
145
  /** Operações que todo SCM implementa. Ver a nota em `tracker.mjs`. */
98
146
  export const SCM_REQUIRED_OPERATIONS = Object.freeze([
99
147
  'setup', 'verify',
@@ -108,6 +156,7 @@ export const SCM_REQUIRED_OPERATIONS = Object.freeze([
108
156
 
109
157
  /** @type {Readonly<Record<string, Readonly<string[]>>>} */
110
158
  export const SCM_CONDITIONAL_OPERATIONS = Object.freeze({
159
+ 'fileReads.bytes=true': Object.freeze(['readFileBytes']),
111
160
  'pullRequests.draft=true': Object.freeze(['markReadyForReview']),
112
161
  'pullRequests.retarget=true': Object.freeze(['setPullRequestBase']),
113
162
  'pullRequests.referenceSearch=true': Object.freeze(['findPullRequestsReferencing']),
@@ -116,6 +165,20 @@ export const SCM_CONDITIONAL_OPERATIONS = Object.freeze({
116
165
  'remoteDispatch!=none': Object.freeze(['dispatch']),
117
166
  });
118
167
 
168
+ /**
169
+ * O vocabulário de `capabilities` desta versão do contrato de SCM.
170
+ *
171
+ * Mesma razão do tracker (ver `TRACKER_CAPABILITY_KEYS`): chave desconhecida é
172
+ * ignorada em silêncio e a operação que ela deveria exigir deixa de ser cobrada.
173
+ * Aqui a superfície é ainda mais afiada — `pullRequests.draft` controla
174
+ * `markReadyForReview`, e um plugin que escrevesse `pullRequest` (singular)
175
+ * carregaria conforme e não saberia tirar PR de rascunho.
176
+ */
177
+ export const SCM_CAPABILITY_KEYS = Object.freeze([
178
+ 'automation', 'fileReads', 'fileWrites', 'identity', 'pullRequests', 'remoteDispatch',
179
+ 'variables',
180
+ ]);
181
+
119
182
  /**
120
183
  * As operações exigidas de um SCM com estas capabilities (função PURA).
121
184
  *
@@ -126,6 +189,10 @@ export function scmRequiredOperations(capabilities = {}) {
126
189
  const exigidas = new Set(SCM_REQUIRED_OPERATIONS);
127
190
  const pr = capabilities.pullRequests || {};
128
191
  const ligada = {
192
+ // Ausente vale `false`, como toda capability: um plugin que não declara
193
+ // `fileReads.bytes` não ganha a operação por omissão, e o core tem de
194
+ // perguntar antes de oferecer.
195
+ 'fileReads.bytes=true': capabilities.fileReads?.bytes === true,
129
196
  'pullRequests.draft=true': pr.draft === true,
130
197
  'pullRequests.retarget=true': pr.retarget === true,
131
198
  'pullRequests.referenceSearch=true': pr.referenceSearch === true,
@@ -151,6 +218,7 @@ export function checkScmPort(port) {
151
218
  if (!port || typeof port !== 'object') return ['porta de SCM ausente'];
152
219
  if (!port.kind) problemas.push('porta de SCM sem `kind`');
153
220
  if (!port.link?.id) problemas.push(`porta de SCM ${port.kind} sem \`link.id\``);
221
+ problemas.push(...checkCapabilityKeys(port.capabilities, SCM_CAPABILITY_KEYS));
154
222
  for (const op of scmRequiredOperations(port.capabilities || {})) {
155
223
  if (typeof port[op] !== 'function') {
156
224
  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
@@ -334,6 +361,19 @@ export function checkKeyPattern(pattern) {
334
361
  return [];
335
362
  }
336
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
+
337
377
  /**
338
378
  * Confere um plugin de tracker contra as capabilities que ele declara.
339
379
  *
@@ -352,6 +392,7 @@ export function checkTrackerPort(port) {
352
392
  // ainda não existem, e um plugin de terceiro com `keyPattern` permissivo
353
393
  // precisa reprovar na CARGA, onde nenhum teste nosso o alcança.
354
394
  problemas.push(...checkKeyPattern(port.capabilities?.identity?.keyPattern));
395
+ problemas.push(...checkCapabilityKeys(port.capabilities, TRACKER_CAPABILITY_KEYS));
355
396
  for (const op of trackerRequiredOperations(port.capabilities || {})) {
356
397
  if (typeof port[op] !== 'function') {
357
398
  problemas.push(`operação "${op}" exigida pelas capabilities e ausente na porta ${port.kind}`);
@@ -8,8 +8,10 @@
8
8
  // duas) e são o que a spec-wave-ui precisa ler para implementar as portas dela
9
9
  // contra O MESMO contrato — não contra um parecido (RFC-007 §3.1).
10
10
  //
11
- // Na Fase 2 estes tipos viram `protocol/{tracker,scm}.v1.json` publicados no
12
- // pacote. Enquanto a RFC é Proposta, o normativo é `rfc/protocol/*.v1.json`.
11
+ // O normativo é `protocol/{tracker,scm}.v1.json`, DENTRO deste pacote e
12
+ // publicado no npm desde a RFC-006 ser aprovada (Fase 2, bloco H). O que isso
13
+ // muda na prática: mexer no contrato passou a ser bump de
14
+ // `specWaveTrackerApi`/`specWaveScmApi`, não edição de rascunho.
13
15
 
14
16
  /**
15
17
  * Identidade de um work item (RFC-006 §4).
@@ -310,14 +312,36 @@
310
312
  * Resultado de `verify()` — diagnóstico SEM efeito, nas duas portas.
311
313
  *
312
314
  * `facts` é o saco de "User vs Organization", título do project, contagem de
313
- * campos: o que o `doctor` imprime e o core não interpreta. Sacola aberta de
314
- * propósito — cada fornecedor tem fatos próprios, e forçá-los num schema
315
- * fechado seria inventar campo que só um deles preenche.
315
+ * campos. Sacola aberta de propósito — cada fornecedor tem fatos próprios, e
316
+ * forçá-los num schema fechado seria inventar campo que só um deles preenche.
317
+ *
318
+ * ── Três regras, e a do meio é a que custa caro esquecer ──────────────────
319
+ *
320
+ * 1. **O valor não é só string.** O `doctor` precisa de listas (contextos de
321
+ * status check obrigatório, nomes de secret) e de booleanos, e serializá-los
322
+ * para caber num `Record<string,string>` é perder a forma na ida e adivinhá-la
323
+ * na volta.
324
+ *
325
+ * 2. **Ausente ≠ `null`.** Chave AUSENTE é "este fornecedor não tem essa noção";
326
+ * `null` é "tem, e eu NÃO CONSEGUI consultar". As duas mandam o usuário a
327
+ * lugares diferentes — a primeira é informação, a segunda é permissão
328
+ * faltando —, e um plugin que devolva `null` para as duas apaga a distinção
329
+ * que o bloco G inteiro existe para preservar.
330
+ *
331
+ * 3. **O plugin COLETA, o core JULGA.** Nada em `facts` é veredito: o que decide
332
+ * se um repositório pode publicar documento por PR é `inspectPrPublishing`,
333
+ * no core, sobre estes fatos. Mover o julgamento para o plugin devolveria
334
+ * política ao fornecedor — a mesma fronteira que a Fase 1 defendeu para o
335
+ * avanço de Etapa.
336
+ *
337
+ * Os fatos que o `doctor` sabe ler estão documentados em cada porta
338
+ * (`tracker.mjs`/`scm.mjs`, na entrada `verify`). São todos OPCIONAIS: fato que
339
+ * não vem vira "não verificável", jamais falha.
316
340
  *
317
341
  * @typedef {object} VerifyResult
318
342
  * @property {boolean} ok
319
343
  * @property {{remaining: number|null, limit: number|null, resetAt: string|null}} quota
320
- * @property {Record<string, string>} facts
344
+ * @property {Record<string, unknown>} facts
321
345
  * @property {string[]} problems
322
346
  */
323
347
 
@@ -1,6 +1,5 @@
1
1
  import { WORKFLOW_FILES, CODE_WORKFLOW_FILES } from '../config.mjs';
2
- import { createGithubScm } from '../plugins/scm-github/index.mjs';
3
- import { resolveScmLink } from '../ports/index.mjs';
2
+ import { requireScm, resolveScmLink } from '../ports/index.mjs';
4
3
  // readTemplate resolve {{CLI_VERSION}} — é o que fixa a versão da CLI nos
5
4
  // workflows gravados no repo-alvo (ver src/lib/templates.mjs).
6
5
  import { readTemplate } from '../lib/templates.mjs';
@@ -46,7 +45,7 @@ export async function setupFiles(token, owner, repo, spinner, { role = 'hub', po
46
45
  // `repoFilesFor` continua no CORE: QUAL papel recebe QUAIS arquivos é regra
47
46
  // de fluxo (RFC-005 §7.5). O que saiu para o plugin foi a gravação — e o
48
47
  // conteúdo dos templates, que é formato de motor de automação, não de fluxo.
49
- const scm = port || createGithubScm({ link: resolveScmLink({ owner, repo, role }), token });
48
+ const scm = await requireScm({ link: resolveScmLink({ owner, repo, role }), token, deps: { scm: port } });
50
49
 
51
50
  spinner.message('Verificando repositório...');
52
51
  const initialized = await scm.isInitialized();
@@ -1,5 +1,5 @@
1
1
  import { allLabelsFor } from '../config.mjs';
2
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
2
+ import { requireTracker } from '../ports/index.mjs';
3
3
 
4
4
  /**
5
5
  * Pausa entre criações de label.
@@ -17,7 +17,7 @@ const DELAY_MS = 120;
17
17
  // vazios (o config ainda nem foi gravado) e o conjunto é só o do fluxo; quem
18
18
  // cria as de modelo/fila depois é o `update`, que já lê o config do repo.
19
19
  export async function setupLabels(token, owner, repo, spinner, fileAi, devAgent, { port } = {}) {
20
- const tracker = port || createGithubTracker({ token, owner, repo });
20
+ const tracker = await requireTracker({ token, owner, repo, deps: { tracker: port } });
21
21
  const labels = allLabelsFor(fileAi, devAgent);
22
22
  await tracker.ensureTags({
23
23
  tags: labels,
@@ -13,7 +13,7 @@
13
13
  // a chama com um spinner do Clack, e trocar o formato do progresso do `init`
14
14
  // seria mudança de comportamento numa fase que promete não ter nenhuma.
15
15
 
16
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
16
+ import { requireTracker } from '../ports/index.mjs';
17
17
 
18
18
  /**
19
19
  * Cria o GitHub Project e os campos do RFC-001.
@@ -27,7 +27,7 @@ import { createGithubTracker } from '../plugins/tracker-github-projects/index.mj
27
27
  * @returns {Promise<{projectId, projectNumber, projectUrl, fields, linkWarning?}>}
28
28
  */
29
29
  export async function setupProject(token, owner, repo, projectTitle, spinner, { port } = {}) {
30
- const tracker = port || createGithubTracker({ token, owner, repo });
30
+ const tracker = await requireTracker({ token, owner, repo, deps: { tracker: port } });
31
31
  const { config, warnings } = await tracker.setup({
32
32
  provision: true,
33
33
  title: projectTitle,
package/src/ui/wizard.mjs CHANGED
@@ -4,10 +4,75 @@ import {
4
4
  AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES,
5
5
  STATUS_OPTIONS, CUSTOM_FIELDS, ALL_LABELS,
6
6
  } from '../config.mjs';
7
+ // Bloco F (RFC-006 §9.3): as duas perguntas de fornecedor. `listPluginKinds` é o
8
+ // que permite NÃO perguntar quando não há escolha — ver `escolhaDeFornecedor`.
9
+ //
10
+ // Vem de `ports/index.mjs` e não de `src/plugins/load.mjs`: o wizard é CORE, e o
11
+ // portão da barreira pegou o import direto na primeira tentativa. Descobrir de onde
12
+ // vem um plugin é da entrada das portas.
13
+ import { listPluginKinds } from '../ports/index.mjs';
7
14
 
8
- export async function runWizard() {
15
+ /**
16
+ * A pergunta de fornecedor de uma porta — ou a ausência dela (função quase pura:
17
+ * só varre diretório, via `listPluginKinds`).
18
+ *
19
+ * **Com um fornecedor só, não pergunta.** A §9.3 pede duas perguntas no `init`, e
20
+ * elas só fazem sentido com mais de uma resposta: um `select` de uma opção é ruído,
21
+ * e pior — sugere que os outros existem e que a escolha tem consequência. Foi a
22
+ * mesma razão que fez a §3.2 recusar espelhar `capabilities` antes de haver
23
+ * divergência possível.
24
+ *
25
+ * Devolve `{ kind, pergunta }`: `pergunta` é `null` quando não há o que escolher, e
26
+ * aí `kind` já é a resposta.
27
+ *
28
+ * @param {object} params
29
+ * @param {'tracker'|'scm'} params.port
30
+ * @param {string} params.rotulo como a pergunta se refere à porta
31
+ * @param {string} [params.root]
32
+ * @returns {{kind: string|null, pergunta: Function|null, disponiveis: object[]}}
33
+ */
34
+ /**
35
+ * O `hint` de uma opção de fornecedor (função PURA).
36
+ *
37
+ * A ORIGEM entra no texto porque ela muda o que acontece DEPOIS: um plugin da fenda
38
+ * local não é versionado, e um repositório inicializado com ele para de funcionar na
39
+ * máquina de outra pessoa. Sem o aviso a escolha parece equivalente às outras, e o
40
+ * custo aparece longe de quem escolheu.
41
+ *
42
+ * Extraída para ser testável: o `p.select` que a consome precisa de TTY, então uma
43
+ * asserção sobre o texto só é possível aqui.
44
+ *
45
+ * @param {{origem: string, spec: string|null}} d
46
+ * @returns {string}
47
+ */
48
+ export function hintDoFornecedor(d) {
49
+ if (d.origem === 'embutido') return 'embutido na CLI';
50
+ if (d.origem === 'local') return `${d.spec} — NÃO versionado; só funciona nesta máquina`;
51
+ return d.spec;
52
+ }
53
+
54
+ export function escolhaDeFornecedor({ port, rotulo, root }) {
55
+ const disponiveis = listPluginKinds({ port, root });
56
+ if (disponiveis.length <= 1) {
57
+ return { kind: disponiveis[0]?.kind ?? null, pergunta: null, disponiveis };
58
+ }
59
+ return {
60
+ kind: null,
61
+ disponiveis,
62
+ pergunta: () => p.select({
63
+ message: `Qual ${rotulo} este repositório usa?`,
64
+ options: disponiveis.map(d => ({ value: d.kind, label: d.kind, hint: hintDoFornecedor(d) })),
65
+ initialValue: disponiveis[0].kind,
66
+ }),
67
+ };
68
+ }
69
+
70
+ export async function runWizard({ root } = {}) {
9
71
  p.intro('spec-wave — configuração do fluxo spec-driven');
10
72
 
73
+ const tracker = escolhaDeFornecedor({ port: 'tracker', rotulo: 'tracker (board e work items)', root });
74
+ const scm = escolhaDeFornecedor({ port: 'scm', rotulo: 'SCM (código e Pull Requests)', root });
75
+
11
76
  const answers = await p.group(
12
77
  {
13
78
  repo: () =>
@@ -27,6 +92,11 @@ export async function runWizard() {
27
92
  placeholder: 'Meu Projeto — Spec Wave',
28
93
  }),
29
94
 
95
+ // Só entram quando há o que escolher. `p.group` chama o que estiver aqui,
96
+ // então a ausência da chave É a ausência da pergunta.
97
+ ...(tracker.pergunta ? { trackerKind: tracker.pergunta } : {}),
98
+ ...(scm.pergunta ? { scmKind: scm.pergunta } : {}),
99
+
30
100
  provider: () =>
31
101
  p.select({
32
102
  message: 'Qual provider de IA os workflows devem usar?',
@@ -96,6 +166,11 @@ export async function runWizard() {
96
166
  projectTitle: answers.projectTitle,
97
167
  provider: answers.provider,
98
168
  model: answers.model.trim(),
169
+ // A resposta, ou o único fornecedor que havia. O `init` grava os dois no
170
+ // `.spec-wave.json` — é o que faz um repo NOVO ser explícito, enquanto os
171
+ // antigos seguem valendo por derivação (bloco D).
172
+ trackerKind: answers.trackerKind ?? tracker.kind,
173
+ scmKind: answers.scmKind ?? scm.kind,
99
174
  };
100
175
  }
101
176