@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
@@ -2,20 +2,43 @@
2
2
  // do gh, .spec-wave.json, acesso ao repo, configuração de IA e workflows.
3
3
  // Best-effort: NUNCA lança — falha de rede/API vira "!" (não verificável);
4
4
  // só problemas confirmados viram "✗". Sai com exit 1 se houver algum "✗".
5
+ //
6
+ // ── Bloco G leva 2: este arquivo deixou de saber o que é GitHub ─────────────
7
+ //
8
+ // Ele era a última ilha de Octokit CRU do core — 14 chamadas em rotas que
9
+ // nenhuma porta tinha — e a única entrada que sobrava na allowlist de
10
+ // `test/ports-boundary.test.mjs` depois do bloco E.
11
+ //
12
+ // As 14 foram por DOIS caminhos, e a divisão é a própria fronteira do RFC-006:
13
+ //
14
+ // • as que tinham operação no contrato viraram chamada de porta —
15
+ // `listTags`, `listWorkItemsByTag`, `boardSnapshot`, `getWorkItem`,
16
+ // `getVariable`. Custo de contrato: zero;
17
+ // • as que não tinham — secrets do Actions, permissão de workflow, proteção de
18
+ // branch, tipo do owner, snapshot do board — viraram FATOS do `verify()`,
19
+ // que já era a operação de diagnóstico das duas portas. Criar
20
+ // `listActionsSecrets()` no contrato é o risco §6.1 do plano: 14 operações
21
+ // GitHub-only que Jira e Azure jamais satisfariam.
22
+ //
23
+ // **O plugin coleta, o doctor julga.** `inspectPrPublishing`,
24
+ // `inspectBoardHygiene`, `inspectStageIds` e as outras funções puras deste
25
+ // arquivo continuam sendo quem decide — mover o veredito para o plugin
26
+ // devolveria política ao fornecedor, que é a fronteira que a Fase 1 defendeu
27
+ // para o avanço de Etapa.
28
+ //
29
+ // O que um fornecedor sem essas noções vê: o gating da leva 1 (`requires`) pula
30
+ // o check com `○` e o motivo, e fato ausente vira "não verificável" — nunca "✗".
5
31
  import { execSync } from 'node:child_process';
6
32
  import { existsSync, readFileSync, readdirSync } from 'node:fs';
7
33
  import path from 'node:path';
8
34
  import { fileURLToPath } from 'node:url';
9
35
  import * as p from '@clack/prompts';
10
36
  import chalk from 'chalk';
11
- import { Octokit } from '@octokit/rest';
12
37
  import yaml from 'js-yaml';
13
38
  import {
14
39
  resolveToken, verifyTokenScopes, describeTokenSource, activeGhAccount,
15
40
  tokenMismatchWarning, parseActiveAccount,
16
41
  } from '../api/auth.mjs';
17
- import { getProjectSnapshot, listProjectItems, getRateLimit } from '../api/github-graphql.mjs';
18
- import { getRepoVariable, getOwnerType } from '../api/github-rest.mjs';
19
42
  import { configuredRole } from '../lib/repo-role.mjs';
20
43
  import {
21
44
  CONFIG_FILE, WORKFLOW_FILES, CODE_WORKFLOW_FILES, ARTIFACT_WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER,
@@ -32,6 +55,9 @@ import { resolveCacheTtl } from '../lib/net-cache.mjs';
32
55
  import { QA_PLAN_FILE } from '../lib/qa-plan-doc.mjs';
33
56
  import { resolveQaEvidenceConfig } from '../lib/qa-exec.mjs';
34
57
  import { findConfigPath } from '../lib/project-root.mjs';
58
+ // Bloco G: o doctor passa a PERGUNTAR o que o fornecedor faz, em vez de supor.
59
+ import { getScm, getTracker, resolveScmLink } from '../ports/index.mjs';
60
+ import { rodarChecks } from '../lib/doctor-capabilities.mjs';
35
61
  import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
36
62
  import { unguardedWorkflows } from './mode.mjs';
37
63
  import {
@@ -41,25 +67,51 @@ import { CLI_VERSION } from '../lib/templates.mjs';
41
67
  import { parseDecompositionDoc, DECOMPOSITION_FILE } from '../lib/decomposition-doc.mjs';
42
68
  import { cliRef } from '../lib/cli-ref.mjs';
43
69
 
44
- // Mesmo padrão de instanciação de github-rest.mjs, mas com o logger mudo:
45
- // aqui 404/403 são resultados esperados dos checks, não erros a logar.
46
- const silentLog = { debug() {}, info() {}, warn() {}, error() {} };
47
- function makeOctokit(token) {
48
- return new Octokit({ auth: token, log: silentLog });
70
+ /**
71
+ * O fato que a porta reportou, com as três respostas SEPARADAS (função PURA).
72
+ *
73
+ * `verify()` devolve uma sacola aberta, e ler dela com `?.` colapsa em silêncio
74
+ * os três casos que o doctor precisa distinguir:
75
+ *
76
+ * • a porta nem pôde ser construída ou verificada → `estado: 'sem-porta'`
77
+ * • o fornecedor não tem essa noção (chave AUSENTE) → `estado: 'ausente'`
78
+ * • tem, e a consulta falhou (valor `null`) → `estado: 'ilegivel'`
79
+ *
80
+ * Os três viram "não verificável" na tela, mas com motivos diferentes — e é o
81
+ * motivo que decide se o usuário procura permissão, plugin ou nada.
82
+ *
83
+ * @param {object|null} verificacao retorno de `verify()`, ou null
84
+ * @param {string} chave nome do fato
85
+ * @returns {{estado: 'ok'|'ausente'|'ilegivel'|'sem-porta', valor: unknown}}
86
+ */
87
+ export function fatoDaPorta(verificacao, chave) {
88
+ if (!verificacao?.facts) return { estado: 'sem-porta', valor: null };
89
+ if (!(chave in verificacao.facts)) return { estado: 'ausente', valor: null };
90
+ const valor = verificacao.facts[chave];
91
+ if (valor === null || valor === undefined) return { estado: 'ilegivel', valor: null };
92
+ return { estado: 'ok', valor };
49
93
  }
50
94
 
51
95
  /**
52
96
  * Formata o relatório do doctor (função PURA — testável sem rede).
53
97
  *
54
- * @param {Array<{name: string, status: 'ok'|'fail'|'warn', detail?: string}>} results
55
- * @returns {string} relatório com ✓ (ok, verde), ✗ (problema, vermelho) e
56
- * ! (não verificável, amarelo); detail é indentado sob o nome.
98
+ * @param {Array<{name: string, status: 'ok'|'fail'|'warn'|'skip', detail?: string}>} results
99
+ * @returns {string} relatório com ✓ (ok, verde), ✗ (problema, vermelho),
100
+ * ! (não verificável, amarelo) e ○ (pulado por capability, cinza);
101
+ * detail é indentado sob o nome.
102
+ *
103
+ * `skip` tem SÍMBOLO PRÓPRIO, e isso é o ponto do bloco G: um check que não
104
+ * rodou porque o fornecedor não tem a capability correspondente não pode sair
105
+ * igual a um que passou. "Está tudo bem" e "não olhei" com a mesma cara é a
106
+ * degradação silenciosa que esta base persegue — e num diagnóstico ela é pior,
107
+ * porque o comando existe justamente para o usuário confiar no que ele diz.
57
108
  */
58
109
  export function renderDoctorReport(results) {
59
110
  const SYMBOLS = {
60
111
  ok: chalk.green('✓'),
61
112
  fail: chalk.red('✗'),
62
113
  warn: chalk.yellow('!'),
114
+ skip: chalk.dim('○'),
63
115
  };
64
116
  const lines = [];
65
117
  for (const r of results || []) {
@@ -89,7 +141,12 @@ async function checkToken(ctx) {
89
141
  // Divergência entre a conta ativa do gh e a origem do token: o sintoma é um
90
142
  // GraphQL dizendo "Could not resolve to a Repository" enquanto o REST
91
143
  // funciona — 403 mascarado de 404.
92
- ctx.activeGhAccount = activeGhAccount();
144
+ // `activeGhAccount()` shella `gh auth status`, que fala com a rede e custa
145
+ // ~1,2 s. Mesma costura de `checkGhAccount`, e o caminho de PRODUÇÃO fica
146
+ // byte-idêntico: sem `deps`, é a função real que roda.
147
+ ctx.activeGhAccount = ctx.deps?.ghAuthStatus
148
+ ? parseActiveAccount(ctx.deps.ghAuthStatus())
149
+ : activeGhAccount();
93
150
  const mismatch = tokenMismatchWarning();
94
151
  if (mismatch) {
95
152
  return { name, status: 'warn', detail: `Token resolvido via ${source}.\n${mismatch}` };
@@ -115,40 +172,28 @@ async function checkRateLimit(ctx) {
115
172
  if (!ctx.token) {
116
173
  return { name, status: 'warn', detail: 'Sem token — cota não verificável.' };
117
174
  }
118
- ctx.rateLimit = await getRateLimit(ctx.token);
175
+ // `quota` é campo do `VerifyResult` das DUAS portas — cota é conceito de
176
+ // fornecedor, mas todo fornecedor tem um, então ela não é fato solto: é parte
177
+ // do contrato de diagnóstico. Sem capability que a descreva, este check
178
+ // continua sem `requires` e degrada.
179
+ const q = ctx.trackerVerify?.quota;
180
+ ctx.rateLimit = q && q.remaining != null ? q : null;
119
181
  if (!ctx.rateLimit) {
120
182
  return { name, status: 'warn', detail: 'Não foi possível consultar a cota agora.' };
121
183
  }
122
184
  const { remaining, limit, resetAt } = ctx.rateLimit;
123
- const reset = new Date(resetAt).toLocaleTimeString('pt-BR');
185
+ // Sem `resetAt` a hora fica de fora. `new Date(null)` é a época e imprimiria
186
+ // uma hora PLAUSÍVEL e errada — o pior modo de faltar um dado.
187
+ const reset = resetAt ? ` (reset ${new Date(resetAt).toLocaleTimeString('pt-BR')})` : '';
124
188
  const status = remaining < 500 ? 'warn' : 'ok';
125
189
  return {
126
190
  name,
127
191
  status,
128
- detail: `${remaining}/${limit} pontos restantes (reset ${reset}).` +
192
+ detail: `${remaining}/${limit} pontos restantes${reset}.` +
129
193
  (status === 'warn' ? ' Cota baixa — checks caros do doctor podem ser pulados; veja as notas deles.' : ''),
130
194
  };
131
195
  }
132
196
 
133
- /**
134
- * Nomes dos secrets do Actions visíveis ao repo: os do repositório e os da
135
- * organização compartilhados com ele (é onde a GitHub App da org costuma
136
- * viver). Só NOMES — a API nunca expõe valores. Lança se nem os do repo forem
137
- * legíveis; os de org são best-effort (a listagem exige permissão a mais).
138
- */
139
- async function listActionsSecretNames(token, owner, repo) {
140
- const octokit = makeOctokit(token);
141
- const res = await octokit.request('GET /repos/{owner}/{repo}/actions/secrets', { owner, repo });
142
- const names = (res.data.secrets || []).map((s) => s.name);
143
- try {
144
- const org = await octokit.request('GET /repos/{owner}/{repo}/actions/organization-secrets', { owner, repo });
145
- for (const s of org.data.secrets || []) if (!names.includes(s.name)) names.push(s.name);
146
- } catch {
147
- // repo de usuário ou sem permissão para ver os da org — fica só com os do repo
148
- }
149
- return names;
150
- }
151
-
152
197
  async function checkScopes(ctx) {
153
198
  const name = 'Escopos do token';
154
199
  if (!ctx.token) {
@@ -156,7 +201,11 @@ async function checkScopes(ctx) {
156
201
  }
157
202
  let info;
158
203
  try {
159
- info = await verifyTokenScopes(ctx.token);
204
+ // A ÚNICA chamada de rede que o doctor ainda faz fora das portas, e ela é a
205
+ // dívida declarada de `api/auth.mjs` — a última entrada da allowlist da
206
+ // barreira. Costurada por `deps` como as portas: sem isso o teste de fumaça
207
+ // paga o retry do octokit contra o `fetch` bloqueado, 2,3 s por caso.
208
+ info = await (ctx.deps?.verifyTokenScopes || verifyTokenScopes)(ctx.token);
160
209
  } catch (err) {
161
210
  return { name, status: 'warn', detail: `Não foi possível consultar a API (GET /user): ${err.message}` };
162
211
  }
@@ -182,29 +231,17 @@ async function checkScopes(ctx) {
182
231
  }
183
232
 
184
233
  // Header vazio/ausente: fine-grained PAT ou GITHUB_TOKEN de Actions — os
185
- // escopos não são legíveis. Degrada para checks funcionais (repo + project).
234
+ // escopos não são legíveis. Degrada para checks funcionais (repo + board), e
235
+ // os dois saem do `verify()` que já rodou: é a MESMA sonda, sem pagá-la duas
236
+ // vezes.
186
237
  const { cfg } = ctx;
187
238
  const functional = [];
188
- if (cfg?.owner && cfg?.repo) {
189
- try {
190
- await makeOctokit(ctx.token).rest.repos.get({ owner: cfg.owner, repo: cfg.repo });
191
- ctx.repoAccess = 'ok';
192
- functional.push(`repo ${cfg.owner}/${cfg.repo}`);
193
- } catch (err) {
194
- ctx.repoAccess = err.status === 404 ? '404' : 'error';
195
- }
196
- }
197
- if (cfg?.project?.id) {
198
- try {
199
- const snapshot = await getProjectSnapshot(ctx.token, cfg.project.id);
200
- if (snapshot) {
201
- ctx.projectSnapshot = snapshot;
202
- functional.push(`project "${snapshot.title}"`);
203
- }
204
- } catch {
205
- // acesso ao project não confirmado — segue sem ele
206
- }
239
+ const alcance = fatoDaPorta(ctx.scmVerify, 'repoReachable');
240
+ if (cfg?.owner && cfg?.repo && alcance.estado === 'ok' && alcance.valor === true) {
241
+ functional.push(`repo ${cfg.owner}/${cfg.repo}`);
207
242
  }
243
+ const board = fatoDaPorta(ctx.trackerVerify, 'boardTitle');
244
+ if (board.estado === 'ok') functional.push(`board "${board.valor}"`);
208
245
  // Token de instalação de GitHub App (`ghs_`) cai aqui também: as permissões
209
246
  // são da App, não escopos — o que dá para afirmar é o acesso funcional.
210
247
  const tipo = info.kind === 'app' ? 'token de instalação de GitHub App' : 'fine-grained PAT?';
@@ -228,7 +265,12 @@ async function checkGhAccount(ctx) {
228
265
  const name = 'Conta ativa do gh';
229
266
  let out;
230
267
  try {
231
- out = execSync('gh auth status', { stdio: ['pipe', 'pipe', 'pipe'] }).toString();
268
+ // Costurado pelo mesmo motivo de `verifyTokenScopes`: `gh auth status` fala
269
+ // com a rede e custava 2,3 s por caso de teste. É a razão de `noRepo` já
270
+ // forçar `CI=1` para o `resolveToken`.
271
+ out = ctx.deps?.ghAuthStatus
272
+ ? ctx.deps.ghAuthStatus()
273
+ : execSync('gh auth status', { stdio: ['pipe', 'pipe', 'pipe'] }).toString();
232
274
  } catch {
233
275
  return { name, status: 'warn', detail: 'gh não instalado ou não logado — verificação de conta pulada.' };
234
276
  }
@@ -250,20 +292,15 @@ async function checkGhAccount(ctx) {
250
292
  return { name, status: 'ok', detail: `Conta ativa: ${active} — coincide com o owner ${owner}.` };
251
293
  }
252
294
  // Conta ativa ≠ owner (caso real: moacsjr ativo com repo da org de moacir-k9).
253
- // Se o owner for uma org, tenta confirmar membership com o token resolvido.
254
- if (ctx.token) {
255
- try {
256
- const res = await makeOctokit(ctx.token).request('GET /user/memberships/orgs/{org}', { org: owner });
257
- if (res.data?.state === 'active') {
258
- return {
259
- name,
260
- status: 'ok',
261
- detail: `Conta ativa ${active} ≠ owner ${owner}, mas o usuário do token é membro ativo da org ${owner}.`,
262
- };
263
- }
264
- } catch {
265
- // owner não é org, ou membership não consultável — cai no warn abaixo
266
- }
295
+ // O vínculo do usuário da credencial com o dono do board é fato do tracker —
296
+ // era `GET /user/memberships/orgs/{org}` com octokit cru aqui.
297
+ const vinculo = fatoDaPorta(ctx.trackerVerify, 'ownerMembership');
298
+ if (vinculo.estado === 'ok' && vinculo.valor === 'active') {
299
+ return {
300
+ name,
301
+ status: 'ok',
302
+ detail: `Conta ativa ${active} ≠ owner ${owner}, mas o usuário do token é membro ativo da org ${owner}.`,
303
+ };
267
304
  }
268
305
  return {
269
306
  name,
@@ -281,11 +318,11 @@ async function checkOwnerType(ctx) {
281
318
  if (!ctx.token) {
282
319
  return { name, status: 'warn', detail: 'Sem token resolvido — verificação pulada.' };
283
320
  }
284
- try {
285
- const type = await getOwnerType(ctx.token, owner);
286
- if (type === 'Organization') {
287
- return { name, status: 'ok', detail: `${owner} é uma organização.` };
288
- }
321
+ const { estado, valor } = fatoDaPorta(ctx.trackerVerify, 'ownerType');
322
+ if (estado === 'ok' && valor === 'Organization') {
323
+ return { name, status: 'ok', detail: `${owner} é uma organização.` };
324
+ }
325
+ if (estado === 'ok') {
289
326
  return {
290
327
  name,
291
328
  status: 'fail',
@@ -294,9 +331,16 @@ async function checkOwnerType(ctx) {
294
331
  'O GitHub App do spec-wave só acessa Projects v2 de organizações — transfira o ' +
295
332
  `repositório e o Project para uma organização e rode \`init\` novamente apontando para ela.`,
296
333
  };
297
- } catch (err) {
298
- return { name, status: 'warn', detail: `Não foi possível verificar o tipo de conta de ${owner}: ${err.message}` };
299
334
  }
335
+ // Ausente é "este tracker não tem noção de owner" — e aí o check não fala do
336
+ // fornecedor, fala do vazio. Nunca vermelho.
337
+ return {
338
+ name,
339
+ status: 'warn',
340
+ detail: estado === 'ausente'
341
+ ? 'Este tracker não expõe o tipo da conta dona do board.'
342
+ : `Não foi possível verificar o tipo de conta de ${owner}.`,
343
+ };
300
344
  }
301
345
 
302
346
  async function checkConfig(ctx) {
@@ -332,31 +376,31 @@ async function checkConfig(ctx) {
332
376
  }
333
377
 
334
378
  // Com token e project.id, confere se as opções de Etapa do config ainda
335
- // existem no project real (alguém pode ter renomeado/apagado colunas).
379
+ // existem no board real (alguém pode ter renomeado/apagado colunas).
336
380
  if (ctx.token && cfg.project?.id) {
337
- try {
338
- const snapshot = ctx.projectSnapshot || await getProjectSnapshot(ctx.token, cfg.project.id);
339
- if (!snapshot) {
340
- return { name, status: 'warn', detail: notes.join('\n') + '\nProject do config não encontrado no GitHub (id inválido ou sem acesso).' };
341
- }
342
- ctx.projectSnapshot = snapshot;
343
- const realEtapa = snapshot.fields?.['Etapa']?.options || {};
344
- const diverged = Object.keys(fields['Etapa'].options || {}).filter((opt) => !(opt in realEtapa));
345
- if (diverged.length > 0) {
346
- return {
347
- name,
348
- status: 'warn',
349
- detail:
350
- notes.join('\n') +
351
- `\nOpções de Etapa do config ausentes no project real: ${diverged.join(', ')} — rode \`npx ${cliRef()} refresh\`.`,
352
- };
353
- }
354
- notes.push(`Project "${snapshot.title}" verificado — campos Etapa/Status em sincronia.`);
355
- } catch (err) {
356
- return { name, status: 'warn', detail: notes.join('\n') + `\nProject não verificável agora: ${err.message}` };
381
+ const achado = fatoDaPorta(ctx.trackerVerify, 'boardFound');
382
+ const opcoes = fatoDaPorta(ctx.trackerVerify, 'stageOptions');
383
+ if (achado.estado === 'ok' && achado.valor === false) {
384
+ return { name, status: 'warn', detail: notes.join('\n') + '\nBoard do config não encontrado no fornecedor (id inválido ou sem acesso).' };
357
385
  }
386
+ if (opcoes.estado !== 'ok') {
387
+ return { name, status: 'warn', detail: notes.join('\n') + '\nBoard não verificável agora (as etapas reais não puderam ser lidas).' };
388
+ }
389
+ const diverged = Object.keys(fields['Etapa'].options || {}).filter((opt) => !(opt in opcoes.valor));
390
+ if (diverged.length > 0) {
391
+ return {
392
+ name,
393
+ status: 'warn',
394
+ detail:
395
+ notes.join('\n') +
396
+ `\nOpções de Etapa do config ausentes no board real: ${diverged.join(', ')} — rode \`npx ${cliRef()} refresh\`.`,
397
+ };
398
+ }
399
+ const titulo = fatoDaPorta(ctx.trackerVerify, 'boardTitle');
400
+ notes.push(
401
+ `Board${titulo.estado === 'ok' ? ` "${titulo.valor}"` : ''} verificado — campos Etapa/Status em sincronia.`);
358
402
  } else {
359
- notes.push('Campos Etapa/Status presentes no config (project real não verificado — sem token ou sem project.id).');
403
+ notes.push('Campos Etapa/Status presentes no config (board real não verificado — sem token ou sem project.id).');
360
404
  }
361
405
  return { name, status: 'ok', detail: notes.join('\n') };
362
406
  }
@@ -519,33 +563,33 @@ async function checkBoardHygiene(ctx) {
519
563
  return { name, status: 'warn', detail: 'Sem project no config — verificação pulada.' };
520
564
  }
521
565
 
566
+ const opcoesReais = fatoDaPorta(ctx.trackerVerify, 'stageOptions');
522
567
  let boardStages = null;
523
- const snapshot = ctx.projectSnapshot;
524
- if (snapshot?.fields?.['Etapa']?.options) {
525
- boardStages = Object.keys(snapshot.fields['Etapa'].options);
568
+ if (opcoesReais.estado === 'ok') {
569
+ boardStages = Object.keys(opcoesReais.valor);
526
570
  } else if (cfg.project.fields?.['Etapa']?.options) {
527
- // Sem snapshot (sem token/rede), o config é a melhor aproximação — foi nele
528
- // que a coluna extra "📋 Backlog Técnico" ficou pendurada.
571
+ // Sem leitura do board (sem token/rede), o config é a melhor aproximação —
572
+ // foi nele que a coluna extra "📋 Backlog Técnico" ficou pendurada.
529
573
  boardStages = Object.keys(cfg.project.fields['Etapa'].options);
530
574
  }
531
575
 
576
+ // As duas leituras têm operação no CONTRATO — `listTags` e
577
+ // `listWorkItemsByTag` —, então aqui não sobra nada de fornecedor. Era
578
+ // `octokit.paginate` sobre `/labels` e `/issues`.
532
579
  let repoLabels = null;
533
580
  let openBugCount = 0;
534
- if (ctx.token && cfg.owner && cfg.repo) {
581
+ if (ctx.tracker) {
535
582
  try {
536
- const res = await makeOctokit(ctx.token)
537
- .paginate('GET /repos/{owner}/{repo}/labels', { owner: cfg.owner, repo: cfg.repo, per_page: 100 });
538
- repoLabels = res.map(l => l.name);
583
+ repoLabels = (await ctx.tracker.listTags()).map(l => l.name);
539
584
  } catch {
540
- // labels não verificáveis agora — segue só com o board
585
+ // tags não verificáveis agora — segue só com o board
541
586
  }
542
587
  try {
543
- const bugs = await makeOctokit(ctx.token).paginate('GET /repos/{owner}/{repo}/issues', {
544
- owner: cfg.owner, repo: cfg.repo, labels: '[BUG]', state: 'open', per_page: 100,
545
- });
546
- openBugCount = bugs.filter(i => !i.pull_request).length;
588
+ // Só work item: `listWorkItemsByTag` não devolve Pull Request, que é o que
589
+ // o filtro `!i.pull_request` da versão crua tirava à mão.
590
+ openBugCount = (await ctx.tracker.listWorkItemsByTag({ tag: '[BUG]', state: 'open' })).length;
547
591
  } catch {
548
- // sem acesso às issues — o check da trilha do Bug fica de fora
592
+ // sem acesso aos itens — o check da trilha do Bug fica de fora
549
593
  }
550
594
  }
551
595
 
@@ -591,7 +635,7 @@ async function checkBoardHygiene(ctx) {
591
635
  // compara nomes, e fatal para toda escrita de Etapa.
592
636
  const { staleIds, checked } = inspectStageIds({
593
637
  configOptions: cfg.project.fields?.['Etapa']?.options ?? null,
594
- boardOptions: snapshot?.fields?.['Etapa']?.options ?? null,
638
+ boardOptions: opcoesReais.estado === 'ok' ? opcoesReais.valor : null,
595
639
  });
596
640
  if (checked && staleIds.length > 0) {
597
641
  status = 'warn';
@@ -670,29 +714,35 @@ async function checkRepoAccess(ctx) {
670
714
  if (!cfg?.owner || !cfg?.repo) {
671
715
  return { name, status: 'warn', detail: `Sem owner/repo no ${CONFIG_FILE} — acesso não verificável.` };
672
716
  }
673
- // Reaproveita o resultado do check funcional de escopos, se já rodou.
674
- if (ctx.repoAccess === 'ok') {
675
- return { name, status: 'ok', detail: `Token enxerga ${cfg.owner}/${cfg.repo} (já confirmado no check de escopos).` };
676
- }
677
- try {
678
- const res = await makeOctokit(ctx.token).rest.repos.get({ owner: cfg.owner, repo: cfg.repo });
717
+ // A sonda é o `verify()` do SCM — a mesma que `commands/repo.mjs` usa. Era
718
+ // `octokit.rest.repos.get` aqui, e mantê-la significava o doctor pagando uma
719
+ // chamada que a porta já fez.
720
+ const alcance = fatoDaPorta(ctx.scmVerify, 'repoReachable');
721
+ if (alcance.estado === 'ok' && alcance.valor === true) {
722
+ const nome = fatoDaPorta(ctx.scmVerify, 'repoFullName');
723
+ const privado = fatoDaPorta(ctx.scmVerify, 'repoPrivate');
724
+ const visibilidade = privado.estado === 'ok' ? ` (${privado.valor ? 'privado' : 'público'})` : '';
679
725
  return {
680
726
  name,
681
727
  status: 'ok',
682
- detail: `Token enxerga ${res.data.full_name} (${res.data.private ? 'privado' : 'público'}).`,
728
+ detail: `Token enxerga ${nome.estado === 'ok' ? nome.valor : `${cfg.owner}/${cfg.repo}`}${visibilidade}.`,
729
+ };
730
+ }
731
+ // `false` é resposta DEFINITIVA ("esta credencial não enxerga este
732
+ // repositório"); `null`/`ilegivel` é "não consegui verificar agora". Só o
733
+ // primeiro é vermelho — vermelho por API fora do ar manda investigar
734
+ // permissão que está correta.
735
+ if (alcance.estado === 'ok' && alcance.valor === false) {
736
+ return {
737
+ name,
738
+ status: 'fail',
739
+ detail:
740
+ `Token não enxerga ${cfg.owner}/${cfg.repo} — causa típica do erro silencioso na criação de issues.\n` +
741
+ 'Verifique se o token tem acesso à org/repo (SSO autorizado, fine-grained com o repo selecionado).',
683
742
  };
684
- } catch (err) {
685
- if (err.status === 404 || ctx.repoAccess === '404') {
686
- return {
687
- name,
688
- status: 'fail',
689
- detail:
690
- `Token não enxerga ${cfg.owner}/${cfg.repo} (404) — causa típica do erro silencioso na criação de issues.\n` +
691
- 'Verifique se o token tem acesso à org/repo (SSO autorizado, fine-grained com o repo selecionado).',
692
- };
693
- }
694
- return { name, status: 'warn', detail: `Acesso não verificável agora: ${err.message}` };
695
743
  }
744
+ const motivo = (ctx.scmVerify?.problems || []).join('; ');
745
+ return { name, status: 'warn', detail: `Acesso não verificável agora${motivo ? `: ${motivo}` : '.'}` };
696
746
  }
697
747
 
698
748
  async function checkAi(ctx) {
@@ -997,8 +1047,8 @@ async function checkDecompositions(ctx) {
997
1047
  if (!doc.appliedAt) continue; // ainda é proposta, não registro
998
1048
  aplicados += 1;
999
1049
 
1000
- if (!ctx.token || !doc.issueNumber) {
1001
- notes.push(`${rel}: aplicado em ${doc.appliedAt} (issues não verificadas — sem token ou sem número no marcador).`);
1050
+ if (!ctx.token || !ctx.tracker || !doc.issueNumber) {
1051
+ notes.push(`${rel}: aplicado em ${doc.appliedAt} (issues não verificadas — sem token, sem tracker ou sem número no marcador).`);
1002
1052
  continue;
1003
1053
  }
1004
1054
 
@@ -1023,13 +1073,15 @@ async function checkDecompositions(ctx) {
1023
1073
  // cache.ttlSec) e, só com --deep, as de cada Story também.
1024
1074
  const atual = new Map();
1025
1075
  try {
1026
- const issue = await makeOctokit(ctx.token).rest.issues.get({
1027
- owner: ctx.cfg.owner, repo: ctx.cfg.repo, issue_number: doc.issueNumber,
1028
- });
1076
+ // O node id do pai sai do `ref` que a porta devolve — era um
1077
+ // `rest.issues.get` só para lê-lo. `cachedSubIssues` ainda o quer porque a
1078
+ // API de hierarquia do GitHub endereça por id opaco, não por número.
1079
+ const pai = await ctx.tracker.getWorkItem({ ref: doc.issueNumber });
1080
+ if (!pai) throw new Error(`item #${doc.issueNumber} não encontrado`);
1029
1081
  const ttlSec = resolveCacheTtl(ctx.cfg);
1030
1082
  const { subs } = await cachedSubIssues({
1031
1083
  token: ctx.token, owner: ctx.cfg.owner, repo: ctx.cfg.repo, root, ttlSec,
1032
- parent: { number: doc.issueNumber, nodeId: issue.data.node_id },
1084
+ parent: { number: doc.issueNumber, nodeId: pai.ref.id },
1033
1085
  });
1034
1086
  for (const s of subs) {
1035
1087
  atual.set(s.number, { title: s.title, state: s.state, stateReason: s.stateReason });
@@ -1120,21 +1172,47 @@ export function checkSpecKit(ctx) {
1120
1172
  * que o fluxo de QA existe para fechar. Só aviso: gerar o plano é um passo, não
1121
1173
  * um defeito de configuração.
1122
1174
  *
1175
+ * Lê as DUAS formas do item — a crua do GitHub (`number`, `fields['Work Item
1176
+ * Type']`, `fields.Etapa`, `state: 'CLOSED'`) e a CANÔNICA da porta (`ref.key`,
1177
+ * `fields.workItemType`, `stage`, `state: 'closed'`). É o remédio preferido do
1178
+ * padrão que gerou 29 defeitos na Fase 1: passar a forma nova para uma função
1179
+ * que espera a antiga não dá erro — dá `undefined` dentro do texto GERADO, com
1180
+ * a suíte verde, porque os testes montam o objeto à mão.
1181
+ *
1123
1182
  * @param {object} params
1124
- * @param {Array<{number, title, state, fields}>} [params.items] itens do board
1183
+ * @param {Array<object>} [params.items] itens do board, em qualquer das formas
1125
1184
  * @param {(rel: string) => boolean} params.exists sonda de existência no disco
1126
- * @returns {Array<{number: number, rel: string}>}
1185
+ * @returns {Array<{number: string|number, rel: string}>}
1127
1186
  */
1128
1187
  export function featuresInQaWithoutPlan({ items = [], exists = () => false } = {}) {
1129
1188
  return items
1130
- .filter(i => i?.number
1131
- && String(i.state || '').toUpperCase() !== 'CLOSED'
1132
- && (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
1133
- && i.fields?.Etapa === STAGE_QA)
1134
- .map(i => ({ number: i.number, rel: `docs/features/${slugify(i.title || '')}/${QA_PLAN_FILE}` }))
1189
+ .map(i => ({ item: i, chave: itemKey(i) }))
1190
+ .filter(({ item, chave }) => chave
1191
+ && String(item.state || '').toUpperCase() !== 'CLOSED'
1192
+ && (itemType(item) === 'Feature' || /^\s*\[FEATURE\]/i.test(item.title || ''))
1193
+ && itemStage(item) === STAGE_QA)
1194
+ .map(({ item, chave }) => ({
1195
+ number: chave,
1196
+ rel: `docs/features/${slugify(item.title || '')}/${QA_PLAN_FILE}`,
1197
+ }))
1135
1198
  .filter(f => !exists(f.rel));
1136
1199
  }
1137
1200
 
1201
+ /** A chave do item nas duas formas: `ref.key` (porta) ou `number` (crua). */
1202
+ function itemKey(item) {
1203
+ return item?.ref?.key ?? item?.number ?? null;
1204
+ }
1205
+
1206
+ /** O tipo nas duas formas: `fields.workItemType` (porta) ou o rótulo de exibição. */
1207
+ function itemType(item) {
1208
+ return item?.fields?.workItemType ?? item?.fields?.['Work Item Type'] ?? null;
1209
+ }
1210
+
1211
+ /** A etapa nas duas formas: `stage` (porta) ou `fields.Etapa` (crua). */
1212
+ function itemStage(item) {
1213
+ return item?.stage ?? item?.fields?.Etapa ?? null;
1214
+ }
1215
+
1138
1216
  /**
1139
1217
  * Checks do bloco `qa.lead` (função PURA — rfc/spec-qa-lead.md §6.6).
1140
1218
  *
@@ -1272,9 +1350,9 @@ async function checkQa(ctx) {
1272
1350
  if (evidenceCheck.warn) status = 'warn';
1273
1351
  notes.push(...evidenceCheck.notes);
1274
1352
 
1275
- if (ctx.token && ctx.cfg?.project?.id && ctx.root) {
1353
+ if (ctx.tracker && ctx.cfg?.project?.id && ctx.root) {
1276
1354
  try {
1277
- const items = await listProjectItems(ctx.token, ctx.cfg.project.id);
1355
+ const items = await ctx.tracker.boardSnapshot();
1278
1356
  const semPlano = featuresInQaWithoutPlan({
1279
1357
  items,
1280
1358
  exists: rel => existsSync(path.join(ctx.root, rel)),
@@ -1292,19 +1370,17 @@ async function checkQa(ctx) {
1292
1370
 
1293
1371
  // Trilha travada no portão da fase B (spec-qa-lead §6.6): Feature em
1294
1372
  // 🧪 QA sem `qa-ready` faz o `qa-lead run` do milestone dela recusar.
1295
- const emQa = items.filter(i => i?.number
1373
+ const emQa = items.filter(i => itemKey(i)
1296
1374
  && String(i.state || '').toUpperCase() !== 'CLOSED'
1297
- && (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
1298
- && i.fields?.Etapa === STAGE_QA);
1375
+ && (itemType(i) === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
1376
+ && itemStage(i) === STAGE_QA);
1299
1377
  const semReady = [];
1300
1378
  for (const item of emQa) {
1301
- const issue = await makeOctokit(ctx.token).rest.issues
1302
- .get({ owner: ctx.cfg.owner, repo: ctx.cfg.repo, issue_number: item.number })
1303
- .catch(() => null);
1304
- if (!issue) continue;
1305
- const labels = (issue.data.labels || []).map(l => (typeof l === 'string' ? l : l.name));
1306
- if (!labels.includes(LABEL_QA_READY)) {
1307
- semReady.push({ number: item.number, milestone: issue.data.milestone?.title || '(sem milestone)' });
1379
+ const chave = itemKey(item);
1380
+ const wi = await ctx.tracker.getWorkItem({ ref: chave }).catch(() => null);
1381
+ if (!wi) continue;
1382
+ if (!(wi.tags || []).includes(LABEL_QA_READY)) {
1383
+ semReady.push({ number: chave, milestone: wi.milestone?.title || '(sem milestone)' });
1308
1384
  }
1309
1385
  }
1310
1386
  if (semReady.length > 0) {
@@ -1357,9 +1433,11 @@ async function checkExecutionMode(ctx) {
1357
1433
  const configured = configuredMode(ctx.cfg);
1358
1434
 
1359
1435
  let variable; // undefined = não verificável
1360
- if (ctx.token && ctx.cfg?.owner && ctx.cfg?.repo) {
1436
+ if (ctx.scm) {
1361
1437
  try {
1362
- variable = await getRepoVariable(ctx.token, ctx.cfg.owner, ctx.cfg.repo, EXECUTION_VARIABLE);
1438
+ // `getVariable` é condicional a `variables: 'repo'`, que é justamente o
1439
+ // `requires` deste check — quando ele roda, a operação existe.
1440
+ variable = await ctx.scm.getVariable({ name: EXECUTION_VARIABLE });
1363
1441
  } catch (err) {
1364
1442
  variable = undefined;
1365
1443
  if (err.status !== 403 && err.status !== 404) {
@@ -1522,51 +1600,49 @@ export function readWorkflowPrPermissions(dir) {
1522
1600
  * que isso signifique "está errado", e duplicar esse tratamento em dois comandos
1523
1601
  * é como as duas respostas passam a divergir.
1524
1602
  *
1525
- * @param {{token?: string, owner?: string, repo?: string, root?: string}} params
1526
- * @returns {Promise<{canCreatePr: boolean|null, workflowPerms: object,
1527
- * requiredChecks: string[]|null, prTokenPresent: boolean|null}>}
1603
+ * Bloco G leva 2: os três fatos saem de `scm.verify({deep: true})`, que já era a
1604
+ * operação de diagnóstico da porta. O que ficou AQUI é a única parte que é
1605
+ * política do spec-wave e não do fornecedor: saber que `GH_PR_TOKEN`, ou o par
1606
+ * `SPEC_WAVE_APP_*`, é a credencial alternativa de abrir PR. Nomes de secret o
1607
+ * plugin lista; o que eles SIGNIFICAM é nosso.
1608
+ *
1609
+ * Recebe o `VerifyResult` PRONTO, e não a porta: quem chama já o tem (o doctor
1610
+ * verifica uma vez para sete checks) e uma segunda verificação aqui dobraria as
1611
+ * três consultas em silêncio. `null` — porta ausente, verify que falhou — devolve
1612
+ * os três fatos como `null`, que é "não consegui olhar", e é o que
1613
+ * `inspectPrPublishing` já trata sem afirmar nada.
1614
+ *
1615
+ * O único I/O que sobrou é a leitura dos YAML, que é local.
1616
+ *
1617
+ * @param {{verificacao?: object|null, root?: string}} params
1618
+ * @returns {{canCreatePr: boolean|null, workflowPerms: object,
1619
+ * requiredChecks: string[]|null, prTokenPresent: boolean|null}}
1528
1620
  */
1529
- export async function readPrPublishingContext({ token, owner, repo, root }) {
1621
+ export function readPrPublishingContext({ verificacao = null, root } = {}) {
1530
1622
  const workflowPerms = readWorkflowPrPermissions(path.join(root || process.cwd(), '.github', 'workflows'));
1531
1623
 
1532
- let canCreatePr = null;
1533
- let requiredChecks = null;
1534
- let prTokenPresent = null;
1535
- if (token && owner && repo) {
1536
- const octokit = makeOctokit(token);
1537
- try {
1538
- // A GitHub App da org também abre PR que dispara workflows — com ela
1539
- // presente, o GH_PR_TOKEN deixa de ser necessário.
1540
- const names = await listActionsSecretNames(token, owner, repo);
1541
- prTokenPresent = names.includes('GH_PR_TOKEN') ||
1542
- (names.includes('SPEC_WAVE_APP_PRIVATE_KEY') && names.includes('SPEC_WAVE_APP_ID'));
1543
- } catch {
1544
- prTokenPresent = null; // sem permissão de ler secrets — não afirmar ausência
1545
- }
1546
- try {
1547
- const res = await octokit.request('GET /repos/{owner}/{repo}/actions/permissions/workflow',
1548
- { owner, repo });
1549
- canCreatePr = res.data?.can_approve_pull_request_reviews ?? null;
1550
- } catch {
1551
- canCreatePr = null; // exige administration:read — ausência é comum, não é erro
1552
- }
1553
- try {
1554
- const info = await octokit.rest.repos.get({ owner, repo });
1555
- const branch = info.data.default_branch;
1556
- const prot = await octokit.rest.repos.getBranchProtection({ owner, repo, branch });
1557
- requiredChecks = prot.data?.required_status_checks?.contexts || [];
1558
- } catch {
1559
- requiredChecks = null; // sem proteção (404) ou sem permissão — nos dois casos, não afirmar
1560
- }
1561
- }
1562
- return { canCreatePr, workflowPerms, requiredChecks, prTokenPresent };
1624
+ const segredos = fatoDaPorta(verificacao, 'automationSecretNames');
1625
+ // A GitHub App da org também abre PR que dispara workflows — com ela presente,
1626
+ // o GH_PR_TOKEN deixa de ser necessário.
1627
+ const prTokenPresent = segredos.estado === 'ok'
1628
+ ? segredos.valor.includes('GH_PR_TOKEN') ||
1629
+ (segredos.valor.includes('SPEC_WAVE_APP_PRIVATE_KEY') && segredos.valor.includes('SPEC_WAVE_APP_ID'))
1630
+ : null;
1631
+
1632
+ const podeAbrir = fatoDaPorta(verificacao, 'automationCanOpenPullRequest');
1633
+ const checks = fatoDaPorta(verificacao, 'protectedChecks');
1634
+ return {
1635
+ canCreatePr: podeAbrir.estado === 'ok' ? podeAbrir.valor : null,
1636
+ workflowPerms,
1637
+ requiredChecks: checks.estado === 'ok' ? checks.valor : null,
1638
+ prTokenPresent,
1639
+ };
1563
1640
  }
1564
1641
 
1565
1642
  async function checkPrPublishing(ctx) {
1566
1643
  const name = 'Publicação por Pull Request';
1567
- const cfg = ctx.cfg || {};
1568
- const contexto = await readPrPublishingContext({
1569
- token: ctx.token, owner: cfg.owner, repo: cfg.repo, root: ctx.root || ctx.cwd,
1644
+ const contexto = readPrPublishingContext({
1645
+ verificacao: ctx.scmVerify, root: ctx.root || ctx.cwd,
1570
1646
  });
1571
1647
 
1572
1648
  if (Object.keys(contexto.workflowPerms).length === 0) {
@@ -1659,11 +1735,83 @@ async function checkWorkflows(ctx) {
1659
1735
 
1660
1736
  // ── Comando ─────────────────────────────────────────────────────────────────
1661
1737
 
1662
- export async function doctor(options = {}) {
1663
- p.intro(chalk.bold('spec-wave doctor'));
1738
+ /**
1739
+ * Abre as duas portas e as VERIFICA uma vez (best-effort — NUNCA lança).
1740
+ *
1741
+ * Escreve em `ctx`: `tracker`, `scm` (as portas), `trackerVerify`/`scmVerify`
1742
+ * (o `VerifyResult` de cada uma) e `capabilities` (o que a leva 1 usa para
1743
+ * gatear os checks).
1744
+ *
1745
+ * **Uma vez por comando, como toda porta desta base.** Sete checks consomem esses
1746
+ * resultados; resolvê-los por check seria uma leitura de config e uma construção
1747
+ * de porta por check, além de repetir as consultas de diagnóstico — que é
1748
+ * exatamente o que o doctor fazia com `getProjectSnapshot` em dois checks.
1749
+ *
1750
+ * Porta que não pôde ser construída vira `null`, e `decidirCheck` pula os checks
1751
+ * que dependiam dela DIZENDO qual porta faltou — não silenciosamente. Isso importa
1752
+ * porque as duas causas mandam o usuário a lugares diferentes: "o plugin não
1753
+ * carregou" é problema de instalação; "este fornecedor não tem variáveis de
1754
+ * repositório" é informação, não defeito.
1755
+ *
1756
+ * Usa `getTracker`/`getScm` (e não os `require*`): o doctor é o comando que
1757
+ * diagnostica ambiente quebrado, então ele é o último que pode lançar por causa de
1758
+ * um ambiente quebrado.
1759
+ *
1760
+ * @param {object} ctx
1761
+ * @param {{tracker?: object, scm?: object}} [deps] costura de teste
1762
+ */
1763
+ async function abrirPortas(ctx, deps = {}) {
1764
+ ctx.tracker = null;
1765
+ ctx.scm = null;
1766
+ ctx.trackerVerify = null;
1767
+ ctx.scmVerify = null;
1768
+ ctx.capabilities = { tracker: null, scm: null };
1769
+ if (!ctx.cfg?.owner || !ctx.cfg?.repo) return;
1770
+ let token = ctx.token;
1771
+ if (!token) {
1772
+ try {
1773
+ token = await resolveToken();
1774
+ } catch {
1775
+ return;
1776
+ }
1777
+ }
1778
+ const cwd = ctx.root || ctx.cwd;
1779
+ try {
1780
+ const { tracker } = await getTracker({
1781
+ cwd, token, owner: ctx.cfg.owner, repo: ctx.cfg.repo, deps,
1782
+ });
1783
+ ctx.tracker = tracker ?? null;
1784
+ ctx.capabilities.tracker = tracker?.capabilities ?? null;
1785
+ // `deep: true` nas DUAS portas porque é o doctor: ele é o consumidor que os
1786
+ // fatos caros existem para servir. `init` e `repo` chamam `verify()` como
1787
+ // sonda de alcance e não pagam por eles.
1788
+ if (tracker) ctx.trackerVerify = await tracker.verify({ deep: true }).catch(() => null);
1789
+ } catch { /* best-effort */ }
1790
+ try {
1791
+ const { scm } = await getScm({
1792
+ cwd, link: resolveScmLink({ owner: ctx.cfg.owner, repo: ctx.cfg.repo }), token, deps,
1793
+ });
1794
+ ctx.scm = scm ?? null;
1795
+ ctx.capabilities.scm = scm?.capabilities ?? null;
1796
+ if (scm) ctx.scmVerify = await scm.verify({ deep: true }).catch(() => null);
1797
+ } catch { /* best-effort */ }
1798
+ }
1664
1799
 
1665
- // Contexto compartilhado entre os checks (token, config, resultados parciais).
1666
- const ctx = { cwd: process.cwd(), deep: !!options.deep };
1800
+ /**
1801
+ * Roda o diagnóstico inteiro e devolve os resultados — SEM imprimir nem sair.
1802
+ *
1803
+ * Separada de `doctor()` pelo mesmo motivo que fez o laço de checks virar
1804
+ * `rodarChecks` na leva 1: o comando termina em `process.exit(1)` quando há
1805
+ * qualquer "✗", e um teste de caminho que morre com o processo não é teste. Com
1806
+ * a extração, a costura `deps` alcança as duas portas e o caminho inteiro do
1807
+ * doctor passa a ser exercitável sem rede — o que ele nunca foi.
1808
+ *
1809
+ * @param {{deep?: boolean}} [options]
1810
+ * @param {{tracker?: object, scm?: object}} [deps]
1811
+ * @returns {Promise<{ctx: object, results: Array<{name, status, detail?}>}>}
1812
+ */
1813
+ export async function doctorResults(options = {}, deps = {}) {
1814
+ const ctx = { cwd: process.cwd(), deep: !!options.deep, deps };
1667
1815
  // Procurado subindo na árvore: rodar o doctor de um subdiretório deve
1668
1816
  // diagnosticar o repositório, não reportar "não inicializado".
1669
1817
  ctx.configPath = findConfigPath(ctx.cwd);
@@ -1678,38 +1826,59 @@ export async function doctor(options = {}) {
1678
1826
  ctx.cfgError = err.message;
1679
1827
  }
1680
1828
 
1829
+ // ── Bloco G: cada check declara o que EXIGE do fornecedor ─────────────────
1830
+ //
1831
+ // `requires` é lido por `decidirCheck` (lib/doctor-capabilities.mjs) contra as
1832
+ // capabilities das portas. Check sem `requires` roda sempre — é a maioria, que
1833
+ // diagnostica coisa local (arquivos, config, IA).
1834
+ //
1835
+ // Os requisitos são CAPABILITY, nunca `kind`: `if (kind === 'github')` recria por
1836
+ // dentro o acoplamento que a Fase 1 desmontou, e a barreira reprova o padrão.
1681
1837
  const checks = [
1682
1838
  checkToken,
1839
+ // Cota de API é conceito de fornecedor, e não há capability que a descreva —
1840
+ // por isso este fica sem `requires` e segue best-effort. Ele é um dos que a
1841
+ // leva 2 move para o `verify()` do plugin, junto das 14 chamadas cruas.
1683
1842
  checkRateLimit,
1684
1843
  checkScopes,
1685
1844
  checkGhAccount,
1686
- checkOwnerType,
1845
+ // Projects v2 de ORGANIZAÇÃO: só faz sentido onde o board é provisionado por
1846
+ // nós. Num tracker `map-only` o board já existe e o dono dele não é da
1847
+ // nossa conta.
1848
+ Object.assign(checkOwnerType, { requires: ["tracker.boardProvisioning === 'create'"] }),
1687
1849
  checkConfig,
1688
1850
  checkRepoAccess,
1689
- checkBoardHygiene,
1851
+ // Higiene de board precisa de board.
1852
+ Object.assign(checkBoardHygiene, { requires: ["tracker.boardProvisioning === 'create'"] }),
1690
1853
  checkAi,
1691
1854
  checkDecompositions,
1692
1855
  checkSpecKit,
1693
1856
  checkQa,
1694
- checkWorkflows,
1695
- checkPrPublishing,
1696
- checkExecutionMode,
1857
+ // Workflows e publicação de PR dependem de automação no SCM.
1858
+ Object.assign(checkWorkflows, { requires: ["scm.automation !== 'none'"] }),
1859
+ Object.assign(checkPrPublishing, { requires: ["scm.pullRequests.draft === true"] }),
1860
+ // O interruptor de execução é uma VARIÁVEL de repositório.
1861
+ Object.assign(checkExecutionMode, { requires: ["scm.variables === 'repo'"] }),
1697
1862
  ];
1698
- const results = [];
1863
+
1864
+ // As duas portas, verificadas UMA vez para os sete checks que as consomem.
1865
+ // Best-effort como todo o resto do doctor: porta que não pôde ser construída
1866
+ // vira `null`, e `decidirCheck` pula os checks que dependiam dela DIZENDO
1867
+ // isso — não silenciosamente.
1868
+ await abrirPortas(ctx, deps);
1869
+
1870
+ // O laço vive em `lib/doctor-capabilities.mjs`: aqui ele era intestável (1728
1871
+ // linhas, rede em quase todo check), e a mutação mostrou o custo — ignorar o
1872
+ // gating por inteiro sobrevivia à suíte.
1873
+ return { ctx, results: await rodarChecks(checks, ctx, ctx.capabilities) };
1874
+ }
1875
+
1876
+ export async function doctor(options = {}, deps = {}) {
1877
+ p.intro(chalk.bold('spec-wave doctor'));
1878
+
1699
1879
  const spinner = p.spinner();
1700
1880
  spinner.start('Rodando checks de preflight...');
1701
- for (const check of checks) {
1702
- try {
1703
- results.push(await check(ctx));
1704
- } catch (err) {
1705
- // Best-effort: nenhum check derruba o doctor — vira "não verificável".
1706
- results.push({
1707
- name: check.name.replace(/^check/, ''),
1708
- status: 'warn',
1709
- detail: `Check falhou inesperadamente: ${err.message}`,
1710
- });
1711
- }
1712
- }
1881
+ const { results } = await doctorResults(options, deps);
1713
1882
  spinner.stop('Checks concluídos.');
1714
1883
 
1715
1884
  console.log('\n' + renderDoctorReport(results) + '\n');