@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
@@ -9,13 +9,11 @@ import {
9
9
  PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE, labelNames,
10
10
  TRAILER_STORY, TRAILER_TASKS, TRAILER_AGENT,
11
11
  } from '../config.mjs';
12
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
13
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
12
+ import { getScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
14
13
 
15
14
  // Fábrica local: este arquivo é longo e os helpers recebem (token, owner, repo)
16
15
  // separadamente. As operações abaixo são todas de LEITURA e não usam o memo do
17
16
  // board, então construir por chamada não muda contagem nenhuma.
18
- const trackerDe = (token, owner, repo) => createGithubTracker({ token, owner, repo });
19
17
 
20
18
  /** WorkItem → a forma que este arquivo consome em dezenas de pontos. */
21
19
  const comoSubIssue = w => ({
@@ -37,6 +35,7 @@ import { loadArtifact } from '../lib/doc-source.mjs';
37
35
  import { buildBugContext } from '../lib/bug-context.mjs';
38
36
  import { slugify } from '../lib/slugify.mjs';
39
37
  import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
38
+ import { STREAM_DIR_ENV, runStreamed, streamFileFor, withStreamJson } from '../lib/implement-stream.mjs';
40
39
  import { loadProjectConfig } from '../lib/board.mjs';
41
40
  import { planBoardMoves, applyBoardMoves } from '../lib/implement-board.mjs';
42
41
  import { markFeaturePrsReady } from '../lib/pr-ready.mjs';
@@ -66,8 +65,10 @@ const MAX_COMMENT_CHARS = 2000;
66
65
  // "Feature" e devolve { number, title } — usado para resolver docs/features/<slug>
67
66
  // e para as instruções de fim de Story (mover a Feature para Code Review). Limita
68
67
  // a profundidade para evitar loops em dados inconsistentes.
69
- async function resolveFeature(token, owner, repo, startRef) {
70
- const tracker = trackerDe(token, owner, repo);
68
+ async function resolveFeature(token, owner, repo, startRef, trackerInjetado) {
69
+ // A porta chega SEMPRE: quem chama passa `deps.tracker`, já resolvido no
70
+ // bootstrap. O parâmetro fica por ser a assinatura que o teste usa.
71
+ const tracker = trackerInjetado;
71
72
  let current = startRef;
72
73
  for (let depth = 0; depth < 5 && current; depth++) {
73
74
  const parent = await tracker.getParent({ ref: current });
@@ -90,9 +91,9 @@ async function resolveFeature(token, owner, repo, startRef) {
90
91
  *
91
92
  * Best-effort como a sonda que substitui: nunca lança, nunca bloqueia.
92
93
  */
93
- async function probeMissingDoc({ token, owner, repo, root, pathRel, doc, issueNumber, fallback }) {
94
+ async function probeMissingDoc({ token, owner, repo, root, pathRel, doc, issueNumber, fallback, deps = {} }) {
94
95
  if (issueNumber) {
95
- const achado = await loadArtifact({ token, owner, repo, root, pathRel, doc, issueNumber })
96
+ const achado = await loadArtifact({ token, owner, repo, root, pathRel, doc, issueNumber, scm: deps.scm ?? null })
96
97
  .catch(() => null);
97
98
  if (achado?.state === 'pending-pr' || achado?.state === 'branch-only') {
98
99
  return missingDocMessage({
@@ -102,9 +103,13 @@ async function probeMissingDoc({ token, owner, repo, root, pathRel, doc, issueNu
102
103
  if (achado?.state === 'remote') return missingDocMessage({ pathRel, onRemote: true, fallback });
103
104
  if (achado?.state === 'missing') return missingDocMessage({ pathRel, onRemote: false, fallback });
104
105
  }
105
- const scm = token && owner && repo
106
- ? createGithubScm({ link: githubLink({ owner, repo }), token })
107
- : null;
106
+ // `getScm` e não `requireScm`: esta sonda é best-effort — `existsOnRemote`
107
+ // recebe `null` e devolve "não sei", e a mensagem de documento ausente sai do
108
+ // mesmo jeito. Derrubar o `implement` porque a SONDA não pôde ser construída
109
+ // seria trocar um aviso por uma falha.
110
+ const { scm } = token && owner && repo
111
+ ? await getScm({ link: resolveScmLink({ owner, repo }), token, deps })
112
+ : { scm: deps.scm ?? null };
108
113
  const onRemote = await existsOnRemote({ scm, pathRel });
109
114
  return missingDocMessage({ pathRel, onRemote, fallback });
110
115
  }
@@ -377,7 +382,7 @@ export function buildContext({
377
382
  * @param {{warnOnSkip?:boolean}} [opts]
378
383
  * @returns {Promise<Map<number, string|null>>}
379
384
  */
380
- async function fetchStagesOf(token, owner, repo, items, { warnOnSkip = false } = {}) {
385
+ async function fetchStagesOf(token, owner, repo, items, { warnOnSkip = false, deps = {} } = {}) {
381
386
  const stageOf = new Map();
382
387
  if (items.length === 0) return stageOf;
383
388
  const { project, error: projectError } = loadProjectConfig();
@@ -389,7 +394,9 @@ async function fetchStagesOf(token, owner, repo, items, { warnOnSkip = false } =
389
394
  }
390
395
  try {
391
396
  const { root } = loadConfig();
392
- const snapshot = await loadBoardSnapshot({ token, owner, repo, project, root, fresh: true });
397
+ const snapshot = await loadBoardSnapshot({
398
+ token, owner, repo, project, root, fresh: true, tracker: deps.tracker,
399
+ });
393
400
  for (const s of items) {
394
401
  stageOf.set(s.number, snapshot.index.get(s.number)?.fields?.Etapa ?? null);
395
402
  }
@@ -639,7 +646,7 @@ function renderCommand(template, vars) {
639
646
  * existe (o caso do P0, que dispensa o documento), o contexto assume a
640
647
  * investigação inteira.
641
648
  */
642
- async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot }) {
649
+ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot, deps = {} }) {
643
650
  const issueNumber = bug.number;
644
651
  const severity = (labelNames(bug).find(n => /^P[0-3]$/.test(n))) || null;
645
652
 
@@ -647,7 +654,7 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
647
654
  // de um Bug pode ser Feature OU Story — o tipo vem do prefixo do título.
648
655
  let parent = null;
649
656
  try {
650
- const p0 = await trackerDe(token, owner, repo)
657
+ const p0 = await deps.tracker
651
658
  .getParent({ ref: { key: String(bug.number), id: bug.node_id } });
652
659
  if (p0?.ref?.key) {
653
660
  parent = {
@@ -668,6 +675,7 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
668
675
  p.log.info(`bug.md encontrado em ${chalk.cyan(fileRel)}.`);
669
676
  } else {
670
677
  p.log.warn(await probeMissingDoc({
678
+ deps,
671
679
  token, owner, repo, root: repoRoot,
672
680
  pathRel: fileRel, doc: 'bug', issueNumber: bug.number,
673
681
  fallback: 'o contexto assume a investigação inteira.',
@@ -676,14 +684,14 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
676
684
 
677
685
  // Board: Bug → Desenvolvimento (In Progress). Não move a Feature-pai.
678
686
  await applyBoardMoves({
679
- token,
687
+ token, tracker: deps.tracker,
680
688
  moves: planBoardMoves('start', { bug: { nodeId: bug.node_id, number: issueNumber } }),
681
689
  cwd: repoRoot || process.cwd(),
682
690
  dryRun,
683
691
  });
684
692
 
685
693
  const comments = [];
686
- const all = await trackerDe(token, owner, repo).listComments({ ref: { key: String(issueNumber) } }).catch(() => []);
694
+ const all = await deps.tracker.listComments({ ref: { key: String(issueNumber) } }).catch(() => []);
687
695
  if (all.length > 0) {
688
696
  const items = all.slice(-MAX_COMMENTS_PER_ISSUE).map(c => ({
689
697
  ...c,
@@ -703,7 +711,7 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
703
711
 
704
712
  const blockedByWarnings = [];
705
713
  try {
706
- const blocked = await trackerDe(token, owner, repo).listBlockedBy({ ref: { key: String(issueNumber) } }).catch(() => []);
714
+ const blocked = await deps.tracker.listBlockedBy({ ref: { key: String(issueNumber) } }).catch(() => []);
707
715
  for (const b of blocked) {
708
716
  // `listBlockedBy` devolve `{ ref, title, state }` — nunca `number`. Lido
709
717
  // cru, o aviso que vai para o contexto do executor saía "#undefined".
@@ -724,6 +732,7 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
724
732
  });
725
733
 
726
734
  await writeContextAndRunSpecKit({
735
+ deps,
727
736
  config,
728
737
  issueNumber,
729
738
  type: 'Bug',
@@ -739,7 +748,7 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
739
748
  : `Bug #${issueNumber} corrigido — abra o PR com \`Fixes #${issueNumber}\`.`,
740
749
  onSuccess: async () => {
741
750
  await applyBoardMoves({
742
- token,
751
+ token, tracker: deps.tracker,
743
752
  moves: planBoardMoves('success', { bug: { nodeId: bug.node_id, number: issueNumber } }),
744
753
  cwd: repoRoot || process.cwd(),
745
754
  dryRun,
@@ -748,7 +757,7 @@ async function implementBug({ token, owner, repo, config, bug, dryRun, repoRoot
748
757
  });
749
758
  }
750
759
 
751
- async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun, repoRoot, refresh = false }) {
760
+ async function implementFeature({ token, owner, repo, config, feature, featureDirOpt, dryRun, repoRoot, refresh = false, deps = {} }) {
752
761
  const ttlSec = resolveCacheTtl(config);
753
762
  const currentBranch = currentGitBranch(repoRoot);
754
763
  const mode = deliveryMode({ branch: currentBranch });
@@ -762,6 +771,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
762
771
  let carga;
763
772
  try {
764
773
  carga = await loadFeatureStories({
774
+ tracker: deps.tracker,
765
775
  token, owner, repo, root: repoRoot,
766
776
  feature: { number: itemNumber(feature), nodeId: feature.node_id, title: feature.title },
767
777
  refresh, ttlSec,
@@ -784,7 +794,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
784
794
  for (const w of carga.warnings) p.log.warn(w);
785
795
 
786
796
  // F1-board. Feature → Desenvolvimento (In Progress) já no início.
787
- await applyBoardMoves({ token, dryRun, moves: planBoardMoves('start', {
797
+ await applyBoardMoves({ token, dryRun, tracker: deps.tracker, moves: planBoardMoves('start', {
788
798
  feature: { nodeId: feature.node_id, number: itemNumber(feature) },
789
799
  }) });
790
800
 
@@ -797,7 +807,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
797
807
  const codeRepos = codeReposForItems(config, { labels: feature.labels || [], children: enriched }).repos;
798
808
 
799
809
  // F3. Etapa de cada Story no board (best-effort — sem board, nada é pulado).
800
- const stageOf = await fetchStagesOf(token, owner, repo, enriched, { warnOnSkip: true });
810
+ const stageOf = await fetchStagesOf(token, owner, repo, enriched, { warnOnSkip: true, deps });
801
811
 
802
812
  // F4. Planejamento: pendentes em ordem topológica, puladas, ciclos.
803
813
  const { pending, skipped, cycle } = planFeatureImplementation(
@@ -824,7 +834,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
824
834
  // Feature. Sem isso, uma Feature que ficou para trás (executor que concluiu
825
835
  // sem mover o card, run interrompido) não tinha como ser destravada —
826
836
  // reexecutar o implement caía aqui e retornava.
827
- await applyBoardMoves({ token, dryRun, moves: planBoardMoves('success', {
837
+ await applyBoardMoves({ token, dryRun, tracker: deps.tracker, moves: planBoardMoves('success', {
828
838
  feature: { nodeId: feature.node_id, number: itemNumber(feature) },
829
839
  }) });
830
840
  // Mesmo destravamento do lado dos PRs: a Feature está pronta para review,
@@ -834,6 +844,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
834
844
  feature: { nodeId: feature.node_id, number: itemNumber(feature) },
835
845
  stories: enriched,
836
846
  linkMode: resolveLinkMode(config),
847
+ scmDe: deps.scmDe,
837
848
  });
838
849
  p.outro(`Todas as ${stories.length} story(ies) da Feature #${itemNumber(feature)} já estão implementadas — nada a fazer.`);
839
850
  return;
@@ -845,6 +856,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
845
856
  const noTasks = [];
846
857
  for (const s of pending) {
847
858
  const { subs: storySubs } = await cachedSubIssues({
859
+ tracker: deps.tracker,
848
860
  token, owner, repo, root: repoRoot, parent: { number: s.number, nodeId: s.nodeId }, refresh, ttlSec,
849
861
  }).catch(() => ({ subs: [] }));
850
862
  s.tasks = storySubs
@@ -870,6 +882,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
870
882
  } else {
871
883
  const specRel = `docs/features/${slugify(feature.title)}/spec.md`;
872
884
  p.log.warn(await probeMissingDoc({
885
+ deps,
873
886
  token, owner, repo, root: repoRoot,
874
887
  pathRel: specRel, doc: 'spec', issueNumber: itemNumber(feature),
875
888
  fallback: 'seguindo só com as Stories.',
@@ -882,7 +895,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
882
895
  try {
883
896
  const internal = new Set(stories.map(s => s.number));
884
897
  const featureDeps = new Set(parseDependencies(feature.body));
885
- const featureBlocked = await trackerDe(token, owner, repo).listBlockedBy({ ref: { key: String(itemNumber(feature)) } }).catch(() => []);
898
+ const featureBlocked = await deps.tracker.listBlockedBy({ ref: { key: String(itemNumber(feature)) } }).catch(() => []);
886
899
  for (const n of itemNumbers(featureBlocked)) featureDeps.add(n);
887
900
  const check = [
888
901
  { kind: 'Feature', number: itemNumber(feature), deps: featureDeps },
@@ -891,7 +904,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
891
904
  for (const c of check) {
892
905
  for (const depNumber of [...c.deps].sort((a, b) => a - b)) {
893
906
  if (internal.has(depNumber)) continue;
894
- const dep = await trackerDe(token, owner, repo)
907
+ const dep = await deps.tracker
895
908
  .getWorkItem({ ref: { key: String(depNumber) } })
896
909
  .then(w => w && comoSubIssue(w))
897
910
  .catch(() => null);
@@ -912,7 +925,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
912
925
  ...pending.map(s => ({ number: s.number, kind: 'Story' })),
913
926
  ];
914
927
  for (const src of commentSources) {
915
- const all = await trackerDe(token, owner, repo).listComments({ ref: { key: String(src.number) } }).catch(() => []);
928
+ const all = await deps.tracker.listComments({ ref: { key: String(src.number) } }).catch(() => []);
916
929
  if (all.length === 0) continue;
917
930
  const items = all.slice(-MAX_COMMENTS_PER_ISSUE).map(c => ({
918
931
  ...c,
@@ -945,6 +958,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
945
958
  hub: { owner, repo },
946
959
  });
947
960
  await writeContextAndRunSpecKit({
961
+ deps,
948
962
  config,
949
963
  repoSlugs: slugsForItem({ labels: feature.labels || [], children: pending }),
950
964
  issueNumber: itemNumber(feature),
@@ -967,7 +981,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
967
981
  // Execução única para todas as pendentes: no sucesso, Tasks → Done e
968
982
  // Stories → Code Review.
969
983
  for (const s of pending) {
970
- await applyBoardMoves({ token, moves: planBoardMoves('success', {
984
+ await applyBoardMoves({ token, tracker: deps.tracker, moves: planBoardMoves('success', {
971
985
  story: { nodeId: s.nodeId, number: s.number },
972
986
  tasks: s.tasks || [],
973
987
  }) });
@@ -982,7 +996,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
982
996
  // do PR como plano B. Sob o dev-agent, que trabalha num branch único e
983
997
  // não abre PR, nenhum dos dois acontecia: as 6 Stories da feature #18
984
998
  // foram para Code Review e a Feature ficou em Desenvolvimento.
985
- await applyBoardMoves({ token, moves: planBoardMoves('success', {
999
+ await applyBoardMoves({ token, tracker: deps.tracker, moves: planBoardMoves('success', {
986
1000
  feature: { nodeId: feature.node_id, number: itemNumber(feature) },
987
1001
  }) });
988
1002
  // A Feature avançou de Etapa; os PRs precisam contar a mesma história.
@@ -999,8 +1013,18 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
999
1013
  });
1000
1014
  }
1001
1015
 
1016
+ /**
1017
+ * @param {object} [params]
1018
+ * @param {object} [params.deps] seam de teste — `tracker`, `scm` e `exec`.
1019
+ *
1020
+ * `trackerDe` é const de TOPO DE MÓDULO, chamada de cinco funções. Em vez de
1021
+ * levar `deps` às cinco, a PORTA viaja nos mesmos objetos que já carregam
1022
+ * token/owner/repo — mesma técnica do `qa-lead`, onde o `bootstrap` passou a
1023
+ * devolvê-la.
1024
+ */
1002
1025
  export async function implement({
1003
1026
  issue: issueArg, featureDir: featureDirOpt, dryRun, refresh = false, verifyCommits = false,
1027
+ deps = {},
1004
1028
  }) {
1005
1029
  const issueNumber = parseInt(String(issueArg).replace('#', ''), 10);
1006
1030
  if (!Number.isInteger(issueNumber)) {
@@ -1043,12 +1067,21 @@ export async function implement({
1043
1067
  return;
1044
1068
  }
1045
1069
 
1070
+ // Bloco E, leva 4: a porta do hub é resolvida UMA vez, aqui, e viaja no
1071
+ // `deps` — que é por onde ela já chegava nas 13 chamadas espalhadas por cinco
1072
+ // funções. Resolver em cada site custaria 13 leituras de config (`loadConfig`
1073
+ // não cacheia) e manteria 13 construções duplicadas de uma porta única.
1074
+ //
1075
+ // Reatribuir o parâmetro é legal e é o menor diff possível: o objeto novo
1076
+ // alcança tudo que recebe `deps` daqui para baixo.
1077
+ deps = { ...deps, tracker: await requireTracker({ token, owner, repo, deps }) };
1078
+
1046
1079
  p.intro(chalk.bold(`spec-wave implement #${issueNumber}`));
1047
1080
 
1048
1081
  // 2. Lê a issue alvo.
1049
1082
  let issue;
1050
1083
  try {
1051
- issue = await trackerDe(token, owner, repo)
1084
+ issue = await deps.tracker
1052
1085
  .getWorkItem({ ref: { key: String(issueNumber) } })
1053
1086
  .then(w => w && comoSubIssue(w));
1054
1087
  } catch (err) {
@@ -1061,7 +1094,7 @@ export async function implement({
1061
1094
  const type = detectIssueType(issue);
1062
1095
  let tasks;
1063
1096
  if (type === 'Story') {
1064
- const subs = (await trackerDe(token, owner, repo).listChildren({ ref: issue.ref })).map(comoSubIssue);
1097
+ const subs = (await deps.tracker.listChildren({ ref: issue.ref })).map(comoSubIssue);
1065
1098
  tasks = subs.filter(s => detectIssueType({ title: s.title, labels: s.labels }) === 'Task');
1066
1099
  if (tasks.length === 0) {
1067
1100
  p.log.error(`Story #${issueNumber} não tem Tasks (sub-issues) para implementar.`);
@@ -1074,12 +1107,12 @@ export async function implement({
1074
1107
  p.log.info(`Task única #${issueNumber}.`);
1075
1108
  } else if (type === 'Feature') {
1076
1109
  // Modo Feature: Stories pendentes em ordem de dependência, contexto único.
1077
- await implementFeature({ token, owner, repo, config, feature: issue, featureDirOpt, dryRun, repoRoot, refresh });
1110
+ await implementFeature({ token, owner, repo, config, feature: issue, featureDirOpt, dryRun, repoRoot, refresh, deps });
1078
1111
  return;
1079
1112
  } else if (type === 'Bug') {
1080
1113
  // Modo Bug: sem tasks e sem spec/plan — o trabalho é investigar antes de
1081
1114
  // corrigir, e o contexto impõe essa ordem.
1082
- await implementBug({ token, owner, repo, config, bug: issue, dryRun, repoRoot });
1115
+ await implementBug({ token, owner, repo, config, bug: issue, dryRun, repoRoot, deps });
1083
1116
  return;
1084
1117
  } else {
1085
1118
  p.log.error(
@@ -1091,7 +1124,7 @@ export async function implement({
1091
1124
 
1092
1125
  // 4. Resolve a Feature (pai na cadeia) — para spec.md/plan.md e para as
1093
1126
  // instruções de fim de Story (avançar a Etapa para Code Review).
1094
- const feature = await resolveFeature(token, owner, repo, issue.ref);
1127
+ const feature = await resolveFeature(token, owner, repo, issue.ref, deps.tracker);
1095
1128
  let featureDir = featureDirOpt;
1096
1129
  if (!featureDir && feature?.title) {
1097
1130
  // Ancorado na RAIZ do repo: o config é encontrado subindo na árvore, e os
@@ -1107,6 +1140,7 @@ export async function implement({
1107
1140
  : featureDir;
1108
1141
  p.log.warn(feature?.title
1109
1142
  ? await probeMissingDoc({
1143
+ deps,
1110
1144
  token, owner, repo, root: repoRoot,
1111
1145
  pathRel: specRel, doc: 'spec', issueNumber: feature?.number,
1112
1146
  fallback: 'seguindo só com as tasks.',
@@ -1119,7 +1153,7 @@ export async function implement({
1119
1153
  // 4a-board. Board determinístico: Feature/Story → Desenvolvimento (In
1120
1154
  // Progress) já no início — a UI mostra o desenvolvimento em andamento sem
1121
1155
  // depender de o LLM mover cards. Best-effort: falha vira warn.
1122
- await applyBoardMoves({ token, dryRun, moves: planBoardMoves('start', {
1156
+ await applyBoardMoves({ token, dryRun, tracker: deps.tracker, moves: planBoardMoves('start', {
1123
1157
  feature: feature ? { nodeId: feature.nodeId, number: itemNumber(feature) } : null,
1124
1158
  story: type === 'Story' ? { nodeId: issue.node_id, number: itemNumber(issue) } : null,
1125
1159
  tasks: tasks.map(t => ({ nodeId: t.nodeId, number: t.number })),
@@ -1131,7 +1165,7 @@ export async function implement({
1131
1165
  // verificar antes de mover a Feature.
1132
1166
  let siblingStories = [];
1133
1167
  if (type === 'Story' && feature?.nodeId) {
1134
- const featureSubs = (await trackerDe(token, owner, repo)
1168
+ const featureSubs = (await deps.tracker
1135
1169
  .listChildren({ ref: { key: String(itemNumber(feature)), id: feature.nodeId } })
1136
1170
  .catch(() => [])).map(comoSubIssue);
1137
1171
  siblingStories = featureSubs
@@ -1150,7 +1184,7 @@ export async function implement({
1150
1184
  }
1151
1185
  commentSources.push({ number: itemNumber(issue), kind: type });
1152
1186
  for (const src of commentSources) {
1153
- const all = await trackerDe(token, owner, repo).listComments({ ref: { key: String(src.number) } }).catch(() => []);
1187
+ const all = await deps.tracker.listComments({ ref: { key: String(src.number) } }).catch(() => []);
1154
1188
  if (all.length === 0) continue;
1155
1189
  const items = all.slice(-MAX_COMMENTS_PER_ISSUE).map(c => ({
1156
1190
  ...c,
@@ -1168,7 +1202,7 @@ export async function implement({
1168
1202
  try {
1169
1203
  let sinceIso = issue.createdAt || null;
1170
1204
  if (feature?.number) {
1171
- const featureIssue = await trackerDe(token, owner, repo)
1205
+ const featureIssue = await deps.tracker
1172
1206
  .getWorkItem({ ref: { key: String(itemNumber(feature)) } })
1173
1207
  .then(w => w && comoSubIssue(w))
1174
1208
  .catch(() => null);
@@ -1186,10 +1220,10 @@ export async function implement({
1186
1220
  const blockedByWarnings = [];
1187
1221
  try {
1188
1222
  const depNumbers = new Set(parseDependencies(issue.body));
1189
- const blocked = await trackerDe(token, owner, repo).listBlockedBy({ ref: { key: String(itemNumber(issue)) } }).catch(() => []);
1223
+ const blocked = await deps.tracker.listBlockedBy({ ref: { key: String(itemNumber(issue)) } }).catch(() => []);
1190
1224
  for (const n of itemNumbers(blocked)) depNumbers.add(n);
1191
1225
  for (const depNumber of [...depNumbers].sort((a, b) => a - b)) {
1192
- const dep = await trackerDe(token, owner, repo)
1226
+ const dep = await deps.tracker
1193
1227
  .getWorkItem({ ref: { key: String(depNumber) } })
1194
1228
  .then(w => w && comoSubIssue(w))
1195
1229
  .catch(() => null);
@@ -1214,6 +1248,7 @@ export async function implement({
1214
1248
  hub: { owner, repo },
1215
1249
  });
1216
1250
  await writeContextAndRunSpecKit({
1251
+ deps,
1217
1252
  config, issueNumber, type, title: issue.title, specPlan, context, dryRun,
1218
1253
  mode, repoRoot, expectedBranch: currentBranch,
1219
1254
  verifyCommits,
@@ -1228,7 +1263,7 @@ export async function implement({
1228
1263
  : `${chalk.green('✓')} Implementação acionada para ${type} #${issueNumber}.\n` +
1229
1264
  ' Próximo: revise as mudanças e abra o PR — o board já foi atualizado.',
1230
1265
  onSuccess: async () => {
1231
- await applyBoardMoves({ token, moves: planBoardMoves('success', {
1266
+ await applyBoardMoves({ token, tracker: deps.tracker, moves: planBoardMoves('success', {
1232
1267
  story: type === 'Story' ? { nodeId: issue.node_id, number: itemNumber(issue) } : null,
1233
1268
  tasks: tasks.map(t => ({ nodeId: t.nodeId, number: t.number })),
1234
1269
  }) });
@@ -1247,10 +1282,10 @@ export async function implement({
1247
1282
  // Sem irmãs, esta era a única Story: a Feature avança direto (nada a
1248
1283
  // consultar). Com irmãs, todas precisam já estar em Code Review+.
1249
1284
  if (siblingStories.length > 0) {
1250
- const stageOf = await fetchStagesOf(token, owner, repo, siblingStories, {});
1285
+ const stageOf = await fetchStagesOf(token, owner, repo, siblingStories, { deps });
1251
1286
  if (!featureCanAdvance(siblingStories, stageOf)) return;
1252
1287
  }
1253
- await applyBoardMoves({ token, dryRun, moves: planBoardMoves('success', {
1288
+ await applyBoardMoves({ token, dryRun, tracker: deps.tracker, moves: planBoardMoves('success', {
1254
1289
  feature: { nodeId: feature.nodeId, number: itemNumber(feature) },
1255
1290
  }) });
1256
1291
  // Chegou aqui = era a última Story pendente. É ESTE o momento que o
@@ -1275,7 +1310,7 @@ export async function implement({
1275
1310
  async function writeContextAndRunSpecKit({
1276
1311
  config, issueNumber, type, title, specPlan, context, dryRun, outroSuccess, onSuccess,
1277
1312
  mode = 'pr-stack', repoRoot = null, expectedBranch = null,
1278
- verifyCommits = false, expectedTrailers = null, repoSlugs = [],
1313
+ verifyCommits = false, expectedTrailers = null, repoSlugs = [], deps = {},
1279
1314
  }) {
1280
1315
  mkdirSync(WORK_DIR, { recursive: true });
1281
1316
  const tasksFile = path.join(WORK_DIR, `implement-${issueNumber}.md`);
@@ -1339,15 +1374,36 @@ async function writeContextAndRunSpecKit({
1339
1374
  return;
1340
1375
  }
1341
1376
 
1342
- const command = renderCommand(template, vars);
1377
+ // Sob o spec-wave-agent com a tela ao vivo (SPEC_WAVE_STREAM_DIR), a saída
1378
+ // do agente interno vai para um arquivo por story e o stdout recebe só o
1379
+ // resumo (lib/implement-stream.mjs). Sem a env, stdio herdado como sempre.
1380
+ const streamDir = process.env[STREAM_DIR_ENV];
1381
+ const command = streamDir
1382
+ ? withStreamJson(renderCommand(template, vars))
1383
+ : renderCommand(template, vars);
1343
1384
 
1344
1385
  p.log.step(`Executando: ${chalk.dim(command)}`);
1345
- try {
1346
- execSync(command, { stdio: 'inherit' });
1347
- } catch (err) {
1348
- p.log.error(`spec-kit implement falhou: ${err.message}`);
1349
- process.exitCode = 1;
1350
- return;
1386
+ if (streamDir) {
1387
+ let code;
1388
+ try {
1389
+ code = await runStreamed(command, { streamFile: streamFileFor(streamDir, issueNumber) });
1390
+ } catch (err) {
1391
+ code = 1;
1392
+ p.log.error(`spec-kit implement falhou ao iniciar: ${err.message}`);
1393
+ }
1394
+ if (code !== 0) {
1395
+ p.log.error(`spec-kit implement falhou (exit ${code}).`);
1396
+ process.exitCode = 1;
1397
+ return;
1398
+ }
1399
+ } else {
1400
+ try {
1401
+ (deps.exec ?? execSync)(command, { stdio: 'inherit' });
1402
+ } catch (err) {
1403
+ p.log.error(`spec-kit implement falhou: ${err.message}`);
1404
+ process.exitCode = 1;
1405
+ return;
1406
+ }
1351
1407
  }
1352
1408
 
1353
1409
  // Guarda barata contra o sintoma do item 1 do rfc/plano-hardening-agentes-
@@ -7,8 +7,9 @@ import { runWizard } from '../ui/wizard.mjs';
7
7
  import { setupProject } from '../setup/project.mjs';
8
8
  import { setupLabels } from '../setup/labels.mjs';
9
9
  import { setupFiles } from '../setup/files.mjs';
10
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
11
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
10
+ import {
11
+ DEFAULT_SCM_KIND, DEFAULT_TRACKER_KIND, requireScm, requireTracker, resolveScmLink,
12
+ } from '../ports/index.mjs';
12
13
  import {
13
14
  CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL, WORKFLOW_FILES, CODE_WORKFLOW_FILES,
14
15
  ISSUE_TEMPLATE_FILES, STATUS_OPTIONS, ALL_LABELS, HUB_DISPATCH_SECRET,
@@ -92,6 +93,7 @@ export async function init(options) {
92
93
 
93
94
  // --- Wizard ou flags ---
94
95
  let owner, repo, projectTitle, provider, model;
96
+ let trackerKind, scmKind;
95
97
  if (role === 'code') {
96
98
  const self = parseRepoRef(options.repo);
97
99
  if (!self) {
@@ -122,8 +124,15 @@ export async function init(options) {
122
124
  p.log.info(`Projeto: ${projectTitle}`);
123
125
  p.log.info(`IA: ${getProvider(provider).label} · modelo ${model}`);
124
126
  } else {
125
- ({ owner, repo, projectTitle, provider, model } = await runWizard());
127
+ ({
128
+ owner, repo, projectTitle, provider, model, trackerKind, scmKind,
129
+ } = await runWizard());
126
130
  }
131
+ // Modo não-interativo (`--repo`): sem wizard não há pergunta, e o fornecedor é o
132
+ // embutido. Uma flag para escolhê-lo entra quando houver um segundo — hoje ela
133
+ // só daria ao usuário uma forma de errar.
134
+ trackerKind ??= DEFAULT_TRACKER_KIND;
135
+ scmKind ??= DEFAULT_SCM_KIND;
127
136
 
128
137
  const providerMeta = getProvider(provider);
129
138
 
@@ -139,7 +148,13 @@ export async function init(options) {
139
148
  try {
140
149
  // `verify()` é a sonda org-vs-user: o GitHub App só alcança Projects v2 de
141
150
  // ORGANIZAÇÃO, e é aqui que o init recusa antes de criar qualquer coisa.
142
- const diag = await createGithubTracker({ token, owner, repo }).verify();
151
+ // `kind` EXPLÍCITO: o `init` roda antes de existir `.spec-wave.json`, então
152
+ // não há bloco `tracker` a normalizar. É esta a API que o bloco F vai usar
153
+ // para carregar o fornecedor que o usuário escolher nas duas perguntas.
154
+ const trackerSonda = await requireTracker({
155
+ token, owner, repo, kind: trackerKind,
156
+ });
157
+ const diag = await trackerSonda.verify();
143
158
  ownerType = diag.facts.ownerType;
144
159
  } catch (err) {
145
160
  ownerSpinner.stop('');
@@ -188,8 +203,9 @@ export async function init(options) {
188
203
  const localConfigPath = path.join(process.cwd(), CONFIG_FILE);
189
204
  const raw = existsSync(localConfigPath)
190
205
  ? readFileSync(localConfigPath, 'utf-8')
191
- : await createGithubScm({ link: githubLink({ owner, repo }), token })
192
- .readFile({ path: CONFIG_FILE });
206
+ : await (await requireScm({
207
+ link: resolveScmLink({ owner, repo }), token,
208
+ })).readFile({ path: CONFIG_FILE });
193
209
  if (raw) {
194
210
  const existing = JSON.parse(raw);
195
211
  if (existing.project) {
@@ -293,6 +309,20 @@ export async function init(options) {
293
309
  role,
294
310
  owner,
295
311
  repo,
312
+ // Bloco F: o fornecedor fica EXPLÍCITO num repo novo. Sem `config` nem
313
+ // `capabilities` ao lado, de propósito:
314
+ //
315
+ // • `tracker.config` seria uma cópia do bloco `project` logo abaixo — o
316
+ // bloco D já o deriva na leitura, e duas fontes com o mesmo conteúdo
317
+ // divergem no dia em que uma das duas for editada. Um plugin que
318
+ // precise de configuração PRÓPRIA (o `site`/`projectKey` de um Jira) a
319
+ // recebe do `setup()` dele, não daqui;
320
+ // • `capabilities` espelhadas é o desvio declarado da §9.1 (§3.2 do
321
+ // plano): com um plugin que sobe junto com a CLI, a cópia nunca
322
+ // divergiria do runtime — envelheceria sem informar nada, e uma cópia
323
+ // que ninguém pode contradizer é a pior espécie.
324
+ tracker: { kind: trackerKind },
325
+ scm: { kind: scmKind },
296
326
  project: {
297
327
  title: projectTitle,
298
328
  url: projectUrl ?? null,
@@ -4,7 +4,7 @@ import { readFileSync } from 'node:fs';
4
4
  import { resolveToken } from '../api/auth.mjs';
5
5
  import { CONFIG_FILE, PRIORITY_LABELS, WORK_ITEM_TYPES, initialStageForType } from '../config.mjs';
6
6
  import { findConfigPath } from '../lib/project-root.mjs';
7
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
7
+ import { requireTracker } from '../ports/index.mjs';
8
8
 
9
9
  const VALID_PRIORITIES = PRIORITY_LABELS.map(l => l.name);
10
10
 
@@ -77,7 +77,11 @@ export async function issue(options) {
77
77
  return;
78
78
  }
79
79
 
80
- const tracker = options.deps?.tracker ?? createGithubTracker({ token, owner, repo, project });
80
+ // `project` vem do CHAMADOR e não do config: o `issue` o recebe já resolvido
81
+ // por quem o invocou. `getTracker` o normaliza a partir do bloco `tracker`, então
82
+ // passar `board: true` aqui exigiria um bloco que este caminho não usa — o que
83
+ // o `issue` faz com a porta é criar e etiquetar, não mexer no board.
84
+ const tracker = await requireTracker({ token, owner, repo, deps: options.deps || {} });
81
85
 
82
86
  p.intro(chalk.bold(`spec-wave issue (${type})`));
83
87