@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
@@ -19,12 +19,9 @@ import path from 'node:path';
19
19
  import chalk from 'chalk';
20
20
 
21
21
  import { resolveToken } from '../api/auth.mjs';
22
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
23
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
22
+ import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
24
23
 
25
24
  /** Portas do hub — o QA roda sempre contra o repositório das issues. */
26
- const trackerDe = (token, owner, repo) => createGithubTracker({ token, owner, repo });
27
- const scmDe = (token, owner, repo) => createGithubScm({ link: githubLink({ owner, repo }), token });
28
25
 
29
26
  /** WorkItem → a forma `{number, nodeId, title, labels}` que este arquivo usa. */
30
27
  const comoItem = w => w && ({
@@ -75,8 +72,8 @@ class QaRefusal extends Error {
75
72
  }
76
73
  }
77
74
 
78
- async function resolveParentFeature(token, owner, repo, startRef) {
79
- const tracker = trackerDe(token, owner, repo);
75
+ async function resolveParentFeature(token, owner, repo, startRef, deps = {}) {
76
+ const tracker = deps.tracker ?? deps.tracker;
80
77
  let current = startRef;
81
78
  for (let depth = 0; depth < 5 && current; depth++) {
82
79
  const parent = await tracker.getParent({ ref: current });
@@ -91,9 +88,9 @@ async function resolveParentFeature(token, owner, repo, startRef) {
91
88
 
92
89
  // Campos do board, resolvidos uma vez. Best-effort: sem board, os movimentos
93
90
  // viram avisos (o veredito e o relatório não dependem dele).
94
- async function resolveBoard(root, projectToken, token, owner, repo) {
95
- const { tracker, error } = openTracker({
96
- token, projectToken, owner, repo, cwd: root || process.cwd(),
91
+ async function resolveBoard(root, projectToken, token, owner, repo, deps = {}) {
92
+ const { tracker, error } = await openTracker({
93
+ token, projectToken, owner, repo, cwd: root || process.cwd(), tracker: deps.tracker,
97
94
  });
98
95
  return { tracker, error: error || null };
99
96
  }
@@ -105,9 +102,9 @@ async function readStage(board, number, nodeId) {
105
102
  .catch(() => null);
106
103
  }
107
104
 
108
- function headShaOf(root) {
105
+ function headShaOf(root, exec = execSync) {
109
106
  try {
110
- return execSync('git rev-parse --short HEAD', {
107
+ return exec('git rev-parse --short HEAD', {
111
108
  cwd: root || process.cwd(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
112
109
  }).trim() || null;
113
110
  } catch {
@@ -123,19 +120,19 @@ function headShaOf(root) {
123
120
  //
124
121
  // Devolve o SHA curto do commit (ou do HEAD, quando não havia nada a commitar
125
122
  // — conteúdo idêntico é no-op, não falha), ou null quando o commit falhou.
126
- function commitLocalPath(root, rel, message) {
123
+ function commitLocalPath(root, rel, message, exec = execSync) {
127
124
  const cwd = root || process.cwd();
128
125
  try {
129
- execSync(`git add -A -- ${JSON.stringify(rel)}`, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
130
- const staged = execSync(`git diff --cached --name-only -- ${JSON.stringify(rel)}`, {
126
+ exec(`git add -A -- ${JSON.stringify(rel)}`, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
127
+ const staged = exec(`git diff --cached --name-only -- ${JSON.stringify(rel)}`, {
131
128
  cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'],
132
129
  }).trim();
133
130
  if (staged) {
134
- execSync(`git commit -m ${JSON.stringify(message)} -- ${JSON.stringify(rel)}`, {
131
+ exec(`git commit -m ${JSON.stringify(message)} -- ${JSON.stringify(rel)}`, {
135
132
  cwd, stdio: ['ignore', 'pipe', 'pipe'],
136
133
  });
137
134
  }
138
- return headShaOf(root) || 'HEAD';
135
+ return headShaOf(root, exec) || 'HEAD';
139
136
  } catch (err) {
140
137
  console.warn(chalk.yellow(
141
138
  `⚠️ ${rel} escrito, mas o commit local falhou (${String(err.message).split('\n')[0]}) — ` +
@@ -166,7 +163,7 @@ function commitLocalPath(root, rel, message) {
166
163
  // Exportada para o teste de integração em repositório temporário; `push` é
167
164
  // injetável pelo mesmo motivo (o teste não tem remoto).
168
165
  export async function publishEvidence({
169
- root, results, stagingAbs, targetRel, targetAbs, push = pushWithRebase,
166
+ root, results, stagingAbs, targetRel, targetAbs, push = pushWithRebase, exec = execSync,
170
167
  }) {
171
168
  const cwd = root || process.cwd();
172
169
  let copied = 0;
@@ -203,7 +200,7 @@ export async function publishEvidence({
203
200
  if (copied === 0 && removed === 0) return null;
204
201
 
205
202
  const sha = commitLocalPath(root, targetRel,
206
- `docs: evidência visual do QA em ${targetRel} (${copied} arquivo(s)) [spec-wave]`);
203
+ `docs: evidência visual do QA em ${targetRel} (${copied} arquivo(s)) [spec-wave]`, exec);
207
204
  if (!sha) return null;
208
205
  if (copied > 0) console.log(`Evidência visual publicada em ${chalk.cyan(targetRel)}/ (${copied} arquivo(s), commit ${sha}).`);
209
206
  const pushed = await push({ cwd });
@@ -213,7 +210,7 @@ export async function publishEvidence({
213
210
  `${String(pushed.error).split('\n')[0]} — os links do relatório só vão resolver depois do seu push.`
214
211
  ));
215
212
  }
216
- return headShaOf(root) || sha;
213
+ return headShaOf(root, exec) || sha;
217
214
  }
218
215
 
219
216
  function parseOnly(only) {
@@ -225,8 +222,8 @@ function parseOnly(only) {
225
222
  return [...new Set(nums)];
226
223
  }
227
224
 
228
- async function trimmedComments(token, owner, repo, issueNumber, kind) {
229
- const all = await trackerDe(token, owner, repo).listComments({ ref: { key: String(issueNumber) } }).catch(() => []);
225
+ async function trimmedComments(token, owner, repo, issueNumber, kind, deps = {}) {
226
+ const all = await deps.tracker.listComments({ ref: { key: String(issueNumber) } }).catch(() => []);
230
227
  if (all.length === 0) return { all, groups: [] };
231
228
  const items = all.slice(-MAX_COMMENTS).map(c => ({
232
229
  // Formas do contrato (`author`, `createdAt`) primeiro, REST crua depois.
@@ -240,7 +237,18 @@ async function trimmedComments(token, owner, repo, issueNumber, kind) {
240
237
  return { all, groups: [{ issueNumber, kind, total: all.length, items }] };
241
238
  }
242
239
 
243
- export async function qaRun({ issue: issueArg, only: onlyArg, severity: severityArg, dryRun = false }) {
240
+ /**
241
+ * @param {object} [params]
242
+ * @param {object} [params.deps] seam de teste — `tracker`, `scm`, `exec`, `push`.
243
+ *
244
+ * `trackerDe` é const de TOPO DE MÓDULO, chamada de 20 lugares. A porta viaja
245
+ * no `outcome`, que já é espalhado nas três funções de escrita — um ponto de
246
+ * costura em vez de sete. `deps.exec` é o que impede o teste de RODAR o
247
+ * comando de QA configurado.
248
+ */
249
+ export async function qaRun({
250
+ issue: issueArg, only: onlyArg, severity: severityArg, dryRun = false, deps = {},
251
+ }) {
244
252
  const number = parseInt(String(issueArg).replace('#', ''), 10);
245
253
  if (!Number.isInteger(number) || number <= 0) {
246
254
  throw new QaRefusal(`Issue inválida: "${issueArg}". Use o número da issue, ex.: 12 ou #12.`);
@@ -269,7 +277,17 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
269
277
  const token = await resolveToken();
270
278
  const projectToken = process.env.PROJECT_TOKEN || token;
271
279
 
272
- const issue = comoItem(await trackerDe(token, owner, repo).getWorkItem({ ref: { key: String(number) } }));
280
+ // Bloco E, leva 4: a porta do hub é resolvida UMA vez e viaja no `deps`, que já
281
+ // era o caminho dela para as 21 chamadas espalhadas por sete funções — o
282
+ // `outcome` a espalha nas três de escrita. Resolver por site custaria 21
283
+ // leituras de config (`loadConfig` não cacheia) para uma porta que é única.
284
+ //
285
+ // `projectToken` NÃO entra aqui: esta é a porta de ISSUE. A do board sai do
286
+ // `openTracker`, que é quem leva a credencial de Projects v2 — promovê-la aqui
287
+ // daria 403 num PAT com escopo `project` e sem `repo`, que nenhum teste vê.
288
+ deps = { ...deps, tracker: await requireTracker({ token, owner, repo, deps }) };
289
+
290
+ const issue = comoItem(await deps.tracker.getWorkItem({ ref: { key: String(number) } }));
273
291
  const type = detectIssueType(issue);
274
292
 
275
293
  // ── Feature dona do plano (Feature/Story) ──────────────────────────────────
@@ -280,14 +298,14 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
280
298
  labels: labelNames(issue), milestone: issue.milestone || null,
281
299
  };
282
300
  } else if (type === 'Story') {
283
- const parent = await resolveParentFeature(token, owner, repo, issue.ref).catch(() => null);
301
+ const parent = await resolveParentFeature(token, owner, repo, issue.ref, deps).catch(() => null);
284
302
  if (!parent) {
285
303
  throw new QaRefusal(
286
304
  `A Story #${number} não tem Feature-pai — o plano de QA é por Feature (D-QA1), ` +
287
305
  'e sem ela não há plano a executar. Vincule a Story como sub-issue de uma Feature.'
288
306
  );
289
307
  }
290
- const parentIssue = comoItem(await trackerDe(token, owner, repo).getWorkItem({ ref: parent.ref }));
308
+ const parentIssue = comoItem(await deps.tracker.getWorkItem({ ref: parent.ref }));
291
309
  feature = {
292
310
  number: parent.number, title: parentIssue.title, nodeId: parentIssue.node_id,
293
311
  labels: labelNames(parentIssue), milestone: parentIssue.milestone || null,
@@ -298,7 +316,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
298
316
  // item ao Project, que é mutação, e o dry-run promete ZERO escrita. ─────────
299
317
  const board = dryRun
300
318
  ? { tracker: null, error: 'dry-run' }
301
- : await resolveBoard(root, projectToken, token, owner, repo);
319
+ : await resolveBoard(root, projectToken, token, owner, repo, deps);
302
320
  let stage = null;
303
321
  if (!dryRun) {
304
322
  if (board.error) console.warn(chalk.yellow(`⚠️ ${board.error} — Etapa não verificada e board não será atualizado.`));
@@ -336,6 +354,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
336
354
  if (!existsSync(fileAbs)) {
337
355
  const achado = await loadArtifact({
338
356
  token, owner, repo, root, pathRel: fileRel, doc: 'bug', issueNumber: number,
357
+ scm: deps.scm ?? null,
339
358
  }).catch(() => null);
340
359
  if (achado && isAwaitingMerge(achado.state)) {
341
360
  const b = awaitingMergeBlock({ pathRel: fileRel, state: achado.state, pr: achado.pr, branch: achado.ref });
@@ -375,6 +394,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
375
394
  evidenceTarget = paths.qaEvidenceDir;
376
395
  const plano = await loadArtifact({
377
396
  token, owner, repo, root, pathRel: qaPlanRel, doc: 'qa-plan', issueNumber: feature.number,
397
+ scm: deps.scm ?? null,
378
398
  }).catch(() => null);
379
399
  if (!plano || plano.content == null || plano.state === 'unknown') {
380
400
  // `qa-ready` está na Feature (o portão passou), então o plano EXISTE em
@@ -414,7 +434,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
414
434
  // Stories já aprovadas saem do alvo no modo Feature.
415
435
  let subStories = [];
416
436
  try {
417
- subStories = (await trackerDe(token, owner, repo).listChildren({ ref: feature.ref ?? { key: String(feature.number), id: feature.nodeId } })).map(comoItem)
437
+ subStories = (await deps.tracker.listChildren({ ref: feature.ref ?? { key: String(feature.number), id: feature.nodeId } })).map(comoItem)
418
438
  .filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
419
439
  } catch (err) {
420
440
  console.warn(chalk.yellow(`⚠️ Não foi possível listar as Stories da Feature: ${err.message}.`));
@@ -458,11 +478,17 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
458
478
 
459
479
  // ── Estado anterior (relatórios) e contexto ────────────────────────────────
460
480
  const { all: allComments, groups: commentGroups } =
461
- await trimmedComments(token, owner, repo, number, type);
481
+ await trimmedComments(token, owner, repo, number, type, deps);
462
482
  const previous = parseLastQaReport(allComments);
463
483
  const run = previous.run + 1;
464
484
 
465
- const pullRequests = await scmDe(token, owner, repo)
485
+ // A porta em UMA linha e a chamada em outra, de propósito. `await requireScm(…)
486
+ // .findPullRequestsReferencing(…)` chamaria o método na PROMESSA — `undefined`,
487
+ // `TypeError` sincrônico, e o `.catch(() => [])` abaixo não o pega, porque só
488
+ // existe depois de haver promessa. O sintoma foi a lista de PRs vazia, e o que
489
+ // o denunciou foi o teste que afirma que o EXECUTOR foi invocado.
490
+ const scmHub = await requireScm({ link: resolveScmLink({ owner, repo }), token, deps });
491
+ const pullRequests = await scmHub
466
492
  .findPullRequestsReferencing({ ref: issue.ref ?? { key: String(issue.number), id: issue.node_id } })
467
493
  .catch(() => []);
468
494
 
@@ -533,7 +559,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
533
559
  console.log(`\nExecutando: ${chalk.dim(command)}\n`);
534
560
  let executorFailed = null;
535
561
  try {
536
- execSync(command, {
562
+ (deps.exec ?? execSync)(command, {
537
563
  stdio: 'inherit',
538
564
  cwd: root || process.cwd(),
539
565
  // §3.1 da spec-qa-lead: a env do PROCESSO vence a `qa.env`, chave a chave
@@ -590,7 +616,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
590
616
 
591
617
  // headSha = o commit TESTADO (vai no marcador do relatório). O commit da
592
618
  // evidência vem depois e só serve os links.
593
- const headSha = headShaOf(root);
619
+ const headSha = headShaOf(root, deps.exec);
594
620
 
595
621
  // ── Evidência visual → repositório (antes do veredito, nunca o altera) ─────
596
622
  let evidenceBase = null;
@@ -598,6 +624,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
598
624
  const evidenceSha = evidenceTarget
599
625
  ? await publishEvidence({
600
626
  root, results, stagingAbs: evidenceAbs, targetRel: evidenceTarget.rel, targetAbs: evidenceTarget.abs,
627
+ push: deps.push, exec: deps.exec,
601
628
  })
602
629
  : null;
603
630
  if (evidenceSha) evidenceBase = { owner, repo, sha: evidenceSha };
@@ -621,7 +648,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
621
648
 
622
649
  const outcome = {
623
650
  token, projectToken, owner, repo, root, config, board, issue, number, type, feature,
624
- featureStories, evidenceBase,
651
+ featureStories, evidenceBase, deps,
625
652
  };
626
653
 
627
654
  let bugs = [];
@@ -707,7 +734,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
707
734
 
708
735
  async function postReport({
709
736
  token, owner, repo, number, type, run, verdict, planSha, headSha, evidenceBase,
710
- combined, pendingNumbers, bugs, trailer,
737
+ combined, pendingNumbers, bugs, trailer, deps = {},
711
738
  }) {
712
739
  // Cenário herdado (`--only`) traz links de uma corrida anterior, servidos
713
740
  // pelo commit daquela corrida — sem a base desta, cai na branch default.
@@ -722,7 +749,7 @@ async function postReport({
722
749
  pendingNumbers,
723
750
  trailer,
724
751
  });
725
- await trackerDe(token, owner, repo).addComment({ ref: { key: String(number) }, body: markdown })
752
+ await deps.tracker.addComment({ ref: { key: String(number) }, body: markdown })
726
753
  .catch(err => console.warn(chalk.yellow(`⚠️ Falha ao comentar o relatório: ${err.message}`)));
727
754
  }
728
755
 
@@ -747,7 +774,7 @@ async function stayInQa({ board, issue }) {
747
774
  // estado que a spec proíbe.
748
775
  async function openBugsForFailures({
749
776
  token, projectToken, owner, repo, root, board,
750
- failed, byNumero, severity, headSha, qaPlanRel, feature, evidenceBase,
777
+ failed, byNumero, severity, headSha, qaPlanRel, feature, evidenceBase, deps = {},
751
778
  }) {
752
779
  const bugs = [];
753
780
  const pushFailures = [];
@@ -758,7 +785,7 @@ async function openBugsForFailures({
758
785
 
759
786
  let story = null;
760
787
  try {
761
- story = comoItem(await trackerDe(token, owner, repo).getWorkItem({ ref: { key: String(storyNumber) } }));
788
+ story = comoItem(await deps.tracker.getWorkItem({ ref: { key: String(storyNumber) } }));
762
789
  } catch (err) {
763
790
  console.warn(chalk.yellow(`⚠️ Não consegui ler a Story #${storyNumber} (${err.message}) — Bug do cenário ${r.numero} NÃO criado.`));
764
791
  pushFailures.push({ numero: r.numero, error: `Story #${storyNumber} ilegível: ${err.message}` });
@@ -767,7 +794,7 @@ async function openBugsForFailures({
767
794
 
768
795
  // Idempotência: Bug filho ABERTO com o mesmo marcador de origem → comenta
769
796
  // nele em vez de duplicar.
770
- const children = (await trackerDe(token, owner, repo).listChildren({ ref: story.ref ?? { key: String(story.number), id: story.node_id } }).catch(() => [])).map(comoItem);
797
+ const children = (await deps.tracker.listChildren({ ref: story.ref ?? { key: String(story.number), id: story.node_id } }).catch(() => [])).map(comoItem);
771
798
  const existing = children.find(c =>
772
799
  detectIssueType({ title: c.title, labels: c.labels }) === 'Bug' &&
773
800
  c.state !== 'closed' &&
@@ -777,7 +804,7 @@ async function openBugsForFailures({
777
804
  const midia = (r.evidenceFiles || []).length > 0 && evidenceBase
778
805
  ? `\n\n**Evidência visual:** ${r.evidenceFiles.map(f => `[${f.split('/').pop()}](${evidenceMediaUrl(evidenceBase.owner, evidenceBase.repo, evidenceBase.sha, f)})`).join(' · ')}`
779
806
  : '';
780
- await trackerDe(token, owner, repo).addComment({
807
+ await deps.tracker.addComment({
781
808
  ref: { key: String(existing.number) },
782
809
  body:
783
810
  `🧪 **O cenário ${scenario.numero} da Story #${storyNumber} reprovou de novo** ` +
@@ -823,12 +850,13 @@ async function openBugsForFailures({
823
850
  continue;
824
851
  }
825
852
  const committed = commitLocalPath(root, fileRel,
826
- `docs: gera ${fileRel} (reprovação de QA, cenário ${scenario.numero} da Story #${storyNumber}) [spec-wave]`);
853
+ `docs: gera ${fileRel} (reprovação de QA, cenário ${scenario.numero} da Story #${storyNumber}) [spec-wave]`,
854
+ deps.exec);
827
855
  if (!committed) {
828
856
  pushFailures.push({ numero: r.numero, error: `commit do ${fileRel} falhou` });
829
857
  continue;
830
858
  }
831
- const push = await pushWithRebase({ cwd: root || process.cwd() });
859
+ const push = await (deps.push ?? pushWithRebase)({ cwd: root || process.cwd() });
832
860
  if (!push.ok) {
833
861
  console.warn(chalk.yellow(
834
862
  `⚠️ Push do ${fileRel} rejeitado após ${push.attempts} tentativa(s): ` +
@@ -841,7 +869,7 @@ async function openBugsForFailures({
841
869
  let created;
842
870
  try {
843
871
  created = comoItem({
844
- ref: await trackerDe(token, owner, repo).createWorkItem({
872
+ ref: await deps.tracker.createWorkItem({
845
873
  title, body: bodyLines.join('\n'), type: 'Bug', tags: labels,
846
874
  milestone: milestone ? { key: String(milestone) } : null,
847
875
  }),
@@ -854,7 +882,7 @@ async function openBugsForFailures({
854
882
  }
855
883
  console.log(`Bug #${created.number} criado para o cenário ${scenario.numero} (filho da Story #${storyNumber}).`);
856
884
 
857
- await trackerDe(token, owner, repo).addChild({ parent: story.ref ?? { key: String(story.number), id: story.node_id }, child: created.ref })
885
+ await deps.tracker.addChild({ parent: story.ref ?? { key: String(story.number), id: story.node_id }, child: created.ref })
858
886
  .catch(err => console.warn(chalk.yellow(`⚠️ Bug #${created.number} criado, mas não vinculado à Story: ${err.message}`)));
859
887
 
860
888
  // Board: 🧪 QA achou → o Bug nasce em ✅ Ready (triagem já feita pela reprova).
@@ -877,9 +905,9 @@ async function openBugsForFailures({
877
905
 
878
906
  // `bug-approved` direto: reprodução, esperado/obtido e regressão são a
879
907
  // execução observada — regerar por IA só introduziria alucinação.
880
- await trackerDe(token, owner, repo).addTag({ ref: { key: String(created.number) }, tag: LABEL_BUG_APPROVED }).catch(() => {});
908
+ await deps.tracker.addTag({ ref: { key: String(created.number) }, tag: LABEL_BUG_APPROVED }).catch(() => {});
881
909
 
882
- await trackerDe(token, owner, repo).addComment({
910
+ await deps.tracker.addComment({
883
911
  ref: { key: String(created.number) },
884
912
  body:
885
913
  `🧪 **Bug aberto pela reprovação de QA** — ${scenario.anchor} da Story #${storyNumber}.\n\n` +
@@ -898,7 +926,7 @@ async function openBugsForFailures({
898
926
  // quando todas as Stories liberarem. Guarda dura: Bug filho aberto segura tudo.
899
927
  async function applyGreen({
900
928
  token, projectToken, owner, repo, board, issue, number, type, feature, combined, byNumero,
901
- featureStories = [],
929
+ featureStories = [], deps = {},
902
930
  }) {
903
931
  const move = async (ref, targetStage, itemType) => {
904
932
  if (!board.tracker) return false;
@@ -908,7 +936,7 @@ async function applyGreen({
908
936
  };
909
937
 
910
938
  if (type === 'Bug') {
911
- await trackerDe(token, owner, repo).addTag({ ref: { key: String(number) }, tag: LABEL_QA_APPROVED }).catch(() => {});
939
+ await deps.tracker.addTag({ ref: { key: String(number) }, tag: LABEL_QA_APPROVED }).catch(() => {});
912
940
  const target = greenTargetStage('Bug');
913
941
  try {
914
942
  await move(issue.ref, target, 'Bug');
@@ -920,7 +948,7 @@ async function applyGreen({
920
948
  }
921
949
 
922
950
  if (type === 'Story') {
923
- const children = ((await trackerDe(token, owner, repo).listChildren({ ref: issue.ref }).catch(() => [])).map(comoItem))
951
+ const children = ((await deps.tracker.listChildren({ ref: issue.ref }).catch(() => [])).map(comoItem))
924
952
  .map(c => ({ ...c, type: detectIssueType({ title: c.title, labels: c.labels }) }));
925
953
  const guard = storyCanAdvance({ children });
926
954
  if (!guard.ok) {
@@ -933,7 +961,7 @@ async function applyGreen({
933
961
  'e rode o `qa` de novo.',
934
962
  };
935
963
  }
936
- await trackerDe(token, owner, repo).addTag({ ref: { key: String(number) }, tag: LABEL_QA_APPROVED }).catch(() => {});
964
+ await deps.tracker.addTag({ ref: { key: String(number) }, tag: LABEL_QA_APPROVED }).catch(() => {});
937
965
  try {
938
966
  await move(issue.ref, STAGE_UAT, 'Story');
939
967
  console.log(`Story #${number} → "${STAGE_UAT}" / Status "${PROGRESS_TODO}".`);
@@ -945,7 +973,7 @@ async function applyGreen({
945
973
  let featureAdvanced = false;
946
974
  if (feature?.nodeId) {
947
975
  featureAdvanced = await maybeAdvanceFeature({
948
- token, projectToken, owner, repo, board, feature, justApproved: number, move,
976
+ token, projectToken, owner, repo, board, feature, justApproved: number, move, deps,
949
977
  });
950
978
  }
951
979
  return {
@@ -965,14 +993,14 @@ async function applyGreen({
965
993
  const daStory = combined.filter(r => byNumero.get(r.numero)?.story === story.number);
966
994
  if (daStory.length === 0) continue;
967
995
  if (!daStory.every(r => r.verdict === 'pass')) continue;
968
- const children = ((await trackerDe(token, owner, repo).listChildren({ ref: story.ref ?? { key: String(story.number), id: story.nodeId } }).catch(() => [])).map(comoItem))
996
+ const children = ((await deps.tracker.listChildren({ ref: story.ref ?? { key: String(story.number), id: story.nodeId } }).catch(() => [])).map(comoItem))
969
997
  .map(c => ({ ...c, type: detectIssueType({ title: c.title, labels: c.labels }) }));
970
998
  const guard = storyCanAdvance({ children });
971
999
  if (!guard.ok) {
972
1000
  console.log(chalk.yellow(`Story #${story.number} verde, mas com Bug aberto (${guard.openBugs.map(n => `#${n}`).join(', ')}) — não avança.`));
973
1001
  continue;
974
1002
  }
975
- await trackerDe(token, owner, repo).addTag({ ref: { key: String(story.number) }, tag: LABEL_QA_APPROVED }).catch(() => {});
1003
+ await deps.tracker.addTag({ ref: { key: String(story.number) }, tag: LABEL_QA_APPROVED }).catch(() => {});
976
1004
  try {
977
1005
  await move(story.ref ?? { key: String(story.number), id: story.nodeId }, STAGE_UAT, 'Story');
978
1006
  console.log(`Story #${story.number} → "${STAGE_UAT}".`);
@@ -984,7 +1012,7 @@ async function applyGreen({
984
1012
 
985
1013
  const featureAdvanced = await maybeAdvanceFeature({
986
1014
  token, projectToken, owner, repo, board, feature,
987
- justApproved: approvedNow, move,
1015
+ justApproved: approvedNow, move, deps,
988
1016
  });
989
1017
  return {
990
1018
  trailer:
@@ -998,11 +1026,11 @@ async function applyGreen({
998
1026
 
999
1027
  // A Feature avança quando TODAS as Stories têm qa-approved ou já estão em
1000
1028
  // Homologação+ — mesma regra do Code Review (spec §6.3).
1001
- async function maybeAdvanceFeature({ token, projectToken, owner, repo, board, feature, justApproved, move }) {
1029
+ async function maybeAdvanceFeature({ token, projectToken, owner, repo, board, feature, justApproved, move, deps = {} }) {
1002
1030
  const aprovadas = new Set(Array.isArray(justApproved) ? justApproved : [justApproved]);
1003
1031
  let stories = [];
1004
1032
  try {
1005
- stories = ((await trackerDe(token, owner, repo).listChildren({ ref: feature.ref ?? { key: String(feature.number), id: feature.nodeId } })).map(comoItem))
1033
+ stories = ((await deps.tracker.listChildren({ ref: feature.ref ?? { key: String(feature.number), id: feature.nodeId } })).map(comoItem))
1006
1034
  .filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Story');
1007
1035
  } catch {
1008
1036
  return false; // sem a lista, na dúvida a Feature não avança
@@ -1023,7 +1051,7 @@ async function maybeAdvanceFeature({ token, projectToken, owner, repo, board, fe
1023
1051
  }
1024
1052
  return false;
1025
1053
  }
1026
- await trackerDe(token, owner, repo).addTag({ ref: { key: String(feature.number) }, tag: LABEL_QA_APPROVED }).catch(() => {});
1054
+ await deps.tracker.addTag({ ref: { key: String(feature.number) }, tag: LABEL_QA_APPROVED }).catch(() => {});
1027
1055
  try {
1028
1056
  await move(feature.ref ?? { key: String(feature.number), id: feature.nodeId }, STAGE_UAT, 'Feature');
1029
1057
  console.log(`Feature #${feature.number} → "${STAGE_UAT}".`);
@@ -1,6 +1,5 @@
1
1
  import { resolveToken } from '../api/auth.mjs';
2
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
3
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
2
+ import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
4
3
  import { detectIssueType } from '../lib/issue-type.mjs';
5
4
  import { openTracker, advanceToStage } from '../lib/board.mjs';
6
5
  import { resolveHubContext, resolvePrRepo } from '../lib/project-root.mjs';
@@ -53,8 +52,8 @@ export async function qa({ prNumber, prRepo: prRepoOpt, deps = {} }) {
53
52
 
54
53
  // A porta do PR é a do repositório DELE (RFC-005): `--pr-repo` pode apontar
55
54
  // para um repo de código, e o número de PR colide entre repositórios.
56
- const prScm = deps.scm ?? createGithubScm({
57
- link: githubLink({ owner: prRepo.owner, repo: prRepo.repo, role: 'code' }), token,
55
+ const prScm = await requireScm({
56
+ link: resolveScmLink({ owner: prRepo.owner, repo: prRepo.repo, role: 'code' }), token, deps,
58
57
  });
59
58
  const pr = await prScm.getPullRequest({ number: String(prNum) });
60
59
  // Mesmo parser e mesma régua do code-review: o vínculo que levou a Story a
@@ -73,7 +72,7 @@ export async function qa({ prNumber, prRepo: prRepoOpt, deps = {} }) {
73
72
  }
74
73
 
75
74
  // PROJECT_TOKEN é a credencial do board; `token` segue fazendo as issues.
76
- const { tracker, error: projectError } = openTracker({ token, projectToken, owner, repo, tracker: deps.tracker });
75
+ const { tracker, error: projectError } = await openTracker({ token, projectToken, owner, repo, tracker: deps.tracker });
77
76
  if (projectError) {
78
77
  console.warn(`${projectError} — board não atualizado.`);
79
78
  return;
@@ -133,7 +132,12 @@ export async function qa({ prNumber, prRepo: prRepoOpt, deps = {} }) {
133
132
  if (updated.length > 0) {
134
133
  // O comentário vai no PR, no repositório do PR — por isso um tracker
135
134
  // próprio dali, e não o do hub.
136
- await (deps.prTracker ?? createGithubTracker({ token, owner: prRepo.owner, repo: prRepo.repo }))
135
+ // `deps.prTracker` e NÃO `deps.tracker`: o PR #77 do repo de código não é a
136
+ // issue #77 do hub. A porta do PR entra pelo seam próprio mesmo passando pelo
137
+ // loader — sem fallback, que é o que o `.catch` do call site esconderia.
138
+ await (await requireTracker({
139
+ token, owner: prRepo.owner, repo: prRepo.repo, deps: { tracker: deps.prTracker },
140
+ }))
137
141
  .addComment({
138
142
  ref: { key: String(prNum) },
139
143
  body:
@@ -4,9 +4,9 @@ import { readFileSync, writeFileSync } from 'node:fs';
4
4
  import { resolveToken } from '../api/auth.mjs';
5
5
  import { CONFIG_FILE, STATUS_OPTIONS } from '../config.mjs';
6
6
  import { findConfigPath } from '../lib/project-root.mjs';
7
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
8
7
  // Trata o escape de empacotamento (SPEC_WAVE_CLI_VERSION) — ver lib/templates.mjs.
9
8
  import { CLI_VERSION } from '../lib/templates.mjs';
9
+ import { requireTracker } from '../ports/index.mjs';
10
10
 
11
11
  /**
12
12
  * Plano de sincronização das opções do campo "Etapa" (função PURA).
@@ -204,8 +204,11 @@ export async function refresh(options = {}) {
204
204
 
205
205
  p.intro(chalk.bold(`spec-wave refresh${options.stages ? ' --stages' : ' --config'}`));
206
206
 
207
- const tracker = createGithubTracker({
208
- token, owner: config.owner, repo: config.repo, project: config.project,
207
+ // `board: true`: o `refresh` LÊ o schema do board para regravar os ids. Sem o
208
+ // bloco `project` não há o que ler, e a mensagem que manda rodar o `init` é
209
+ // melhor que um `setup({provision:false})` devolvendo vazio.
210
+ const tracker = await requireTracker({
211
+ token, owner: config.owner, repo: config.repo, board: true,
209
212
  });
210
213
  const leSchema = async () => {
211
214
  // `provision: false` é leitura: devolve o bloco de config que descreve o
@@ -152,7 +152,7 @@ export async function repairStage(issuesArg, stageArg, options = {}) {
152
152
  `spec-wave repair-stage ${numbers.map(n => `#${n}`).join(', ')} → ${stage}${options.dryRun ? ' (dry-run)' : ''}`
153
153
  ));
154
154
 
155
- const { tracker, error: projectError } = openTracker({ token, owner, repo, cwd: root || process.cwd(), tracker: options.deps?.tracker });
155
+ const { tracker, error: projectError } = await openTracker({ token, owner, repo, cwd: root || process.cwd(), tracker: options.deps?.tracker });
156
156
  if (projectError) {
157
157
  p.log.error(`${projectError} — nada a reparar. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);
158
158
  process.exitCode = 1;
@@ -7,8 +7,7 @@
7
7
  import * as p from '@clack/prompts';
8
8
  import chalk from 'chalk';
9
9
  import { resolveToken } from '../api/auth.mjs';
10
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
11
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
10
+ import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
12
11
  import { resolveHubContext } from '../lib/project-root.mjs';
13
12
  import { updateConfig } from '../lib/config-file.mjs';
14
13
  import {
@@ -76,9 +75,10 @@ export async function repoCommand({ action, slug, repo: repoArg, dryRun = false,
76
75
  try {
77
76
  // Sonda de ALCANCE, não leitura: o que importa é se o token enxerga o
78
77
  // repositório-alvo antes de o hub passar a apontar para ele.
79
- const alvo = await createGithubScm({
80
- link: githubLink({ owner: target.owner, repo: target.repo, role: 'code' }), token,
81
- }).verify();
78
+ const alvoScm = await requireScm({
79
+ link: resolveScmLink({ owner: target.owner, repo: target.repo, role: 'code' }), token,
80
+ });
81
+ const alvo = await alvoScm.verify();
82
82
  if (!alvo.ok) throw new Error(alvo.problems.join('; '));
83
83
  } catch (err) {
84
84
  throw new Error(`Não consegui ler ${target.owner}/${target.repo}: ${err.status === 404 ? 'não existe ou o token não o enxerga' : err.message}.`);
@@ -94,8 +94,8 @@ export async function repoCommand({ action, slug, repo: repoArg, dryRun = false,
94
94
 
95
95
  const spec = repoLabelSpec(slug);
96
96
  try {
97
- await createGithubTracker({ token, owner: ctx.owner, repo: ctx.repo })
98
- .ensureTags({ tags: [spec] });
97
+ const trackerHub = await requireTracker({ token, owner: ctx.owner, repo: ctx.repo });
98
+ await trackerHub.ensureTags({ tags: [spec] });
99
99
  p.log.success(`Label ${spec.name} garantida em ${ctx.owner}/${ctx.repo}.`);
100
100
  } catch (err) {
101
101
  p.log.warn(`Não consegui criar a label ${spec.name}: ${err.message} — o decompose --apply tenta de novo.`);
@@ -20,8 +20,7 @@ import path from 'node:path';
20
20
  import chalk from 'chalk';
21
21
 
22
22
  import { resolveToken } from '../api/auth.mjs';
23
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
24
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
23
+ import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
25
24
  import { trackerAvailable } from '../lib/board.mjs';
26
25
  import { loadArtifact } from '../lib/doc-source.mjs';
27
26
  import { featureDocPaths, bugDocPaths } from '../lib/doc-paths.mjs';
@@ -341,7 +340,7 @@ async function runForPr({ prNumber, dryRun, yes, only, json }) {
341
340
  const token = await resolveToken();
342
341
  const n = parseInt(prNumber, 10);
343
342
 
344
- const scm = createGithubScm({ link: githubLink({ owner, repo }), token });
343
+ const scm = await requireScm({ link: resolveScmLink({ owner, repo }), token });
345
344
  const pr = await scm.getPullRequest({ number: String(n) });
346
345
  const reviews = await scm.listPullRequestReviews({ number: String(n) });
347
346
  const verdict = reviewVerdict(reviews);
@@ -446,8 +445,12 @@ export async function run(issueArg, options = {}) {
446
445
  const passos = [];
447
446
  let ultimoTipo = null;
448
447
 
448
+ // A porta sai do laço: ela era reconstruída a cada volta, e agora cada
449
+ // construção custaria uma leitura de config também. O laço roda até `teto`.
450
+ const trackerRun = await requireTracker({ token, owner, repo });
451
+
449
452
  for (let i = 0; i < teto; i++) {
450
- const issue = await createGithubTracker({ token, owner, repo })
453
+ const issue = await trackerRun
451
454
  .getWorkItem({ ref: { key: String(parseInt(issueNumber, 10)) } });
452
455
  const type = detectIssueType(issue);
453
456
  const { docs, docPaths } = localDocStates(issue, type, root);
@@ -8,11 +8,11 @@
8
8
  import * as p from '@clack/prompts';
9
9
  import chalk from 'chalk';
10
10
  import { resolveToken } from '../api/auth.mjs';
11
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
12
11
  import { detectIssueType } from '../lib/issue-type.mjs';
13
12
  import { openTracker, advanceToStage } from '../lib/board.mjs';
14
13
  import { resolveHubContext } from '../lib/project-root.mjs';
15
14
  import { CONFIG_FILE, STAGE_CODE_REVIEW, PROGRESS_TODO } from '../config.mjs';
15
+ import { requireTracker } from '../ports/index.mjs';
16
16
 
17
17
  export async function story({ action, issue: issueArg, deps = {} }) {
18
18
  if (action !== 'review') {
@@ -55,7 +55,7 @@ export async function story({ action, issue: issueArg, deps = {} }) {
55
55
  // 1. Lê a issue e valida o tipo.
56
56
  let issue;
57
57
  try {
58
- issue = await (deps.tracker ?? createGithubTracker({ token, owner, repo }))
58
+ issue = await (await requireTracker({ token, owner, repo, deps }))
59
59
  .getWorkItem({ ref: { key: String(issueNumber) } });
60
60
  } catch (err) {
61
61
  p.log.error(`Não foi possível ler a issue #${issueNumber}: ${err.message}`);
@@ -73,7 +73,7 @@ export async function story({ action, issue: issueArg, deps = {} }) {
73
73
  }
74
74
 
75
75
  // 2. Tracker do .spec-wave.json — sem ele não há board para atualizar.
76
- const { tracker, error: projectError } = openTracker({ token, owner, repo, tracker: deps.tracker });
76
+ const { tracker, error: projectError } = await openTracker({ token, owner, repo, tracker: deps.tracker });
77
77
  if (projectError) {
78
78
  p.log.error(`${projectError} — board não atualizado. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);
79
79
  process.exitCode = 1;
@@ -11,11 +11,11 @@
11
11
  import * as p from '@clack/prompts';
12
12
  import chalk from 'chalk';
13
13
  import { resolveToken } from '../api/auth.mjs';
14
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
15
14
 
16
15
  import { detectIssueType } from '../lib/issue-type.mjs';
17
16
  import { openTracker, advanceToStage, setProgress } from '../lib/board.mjs';
18
17
  import { resolveHubContext } from '../lib/project-root.mjs';
18
+ import { requireTracker } from '../ports/index.mjs';
19
19
  import {
20
20
  CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_DONE,
21
21
  PROGRESS_IN_PROGRESS, PROGRESS_DONE,
@@ -77,7 +77,7 @@ export async function task({ action, issue: issueArg, deps = {} }) {
77
77
  // 1. Lê a issue e valida o tipo.
78
78
  let issue;
79
79
  try {
80
- issue = await (deps.tracker ?? createGithubTracker({ token, owner, repo }))
80
+ issue = await (await requireTracker({ token, owner, repo, deps }))
81
81
  .getWorkItem({ ref: { key: String(issueNumber) } });
82
82
  } catch (err) {
83
83
  p.log.error(`Não foi possível ler a issue #${issueNumber}: ${err.message}`);
@@ -95,7 +95,7 @@ export async function task({ action, issue: issueArg, deps = {} }) {
95
95
  }
96
96
 
97
97
  // 2. Tracker do .spec-wave.json — sem ele não há board para atualizar.
98
- const { tracker, error: projectError } = openTracker({ token, owner, repo, tracker: deps.tracker });
98
+ const { tracker, error: projectError } = await openTracker({ token, owner, repo, tracker: deps.tracker });
99
99
  if (projectError) {
100
100
  p.log.error(`${projectError} — board não atualizado. Rode \`spec-wave init\` (ou \`spec-wave refresh --config\`).`);
101
101
  process.exitCode = 1;