@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
@@ -23,13 +23,11 @@ import { setTimeout as sleep } from 'node:timers/promises';
23
23
  import chalk from 'chalk';
24
24
 
25
25
  import { resolveToken } from '../api/auth.mjs';
26
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
26
+ import { requireTracker } from '../ports/index.mjs';
27
27
  import { detectIssueType } from '../lib/issue-type.mjs';
28
28
  import { loadConfig, findConfigPath } from '../lib/project-root.mjs';
29
29
  import { loadProjectConfig } from '../lib/board.mjs';
30
30
 
31
- /** Porta de tracker do hub — este comando trabalha por TRILHA, sempre no hub. */
32
- const trackerDe = (token, owner, repo) => createGithubTracker({ token, owner, repo });
33
31
  import { featureDocPaths } from '../lib/doc-paths.mjs';
34
32
  import { orderStories } from '../lib/dependencies.mjs';
35
33
  import { loadFeatureStories, loadBoardSnapshot } from '../lib/story-graph.mjs';
@@ -61,6 +59,16 @@ class QaLeadRefusal extends Error {
61
59
  }
62
60
  }
63
61
 
62
+ /**
63
+ * @param {object} params
64
+ * @param {object} [params.deps] seam de teste — `tracker`, `exec` (no lugar de
65
+ * `execSync`) e `push` (no lugar de `pushWithRebase`).
66
+ *
67
+ * O `bootstrap` é o ponto único onde token/owner/repo são resolvidos, e é ele
68
+ * que devolve a PORTA — os dez call sites são leitura de variável. Foi essa
69
+ * forma que tornou a leva 4 do bloco E uma troca de UMA linha aqui: a fábrica
70
+ * de topo de módulo já não era consultada em dez lugares.
71
+ */
64
72
  export async function qaLead({ action, milestone: milestoneArg, ...options }) {
65
73
  const acoes = { plan: qaLeadPlan, run: qaLeadRun, report: qaLeadReport };
66
74
  const fn = acoes[action];
@@ -75,7 +83,7 @@ export async function qaLead({ action, milestone: milestoneArg, ...options }) {
75
83
 
76
84
  // ── bootstrap compartilhado ──────────────────────────────────────────────────
77
85
 
78
- async function bootstrap(milestoneArg) {
86
+ async function bootstrap(milestoneArg, deps = {}) {
79
87
  const configPath = findConfigPath();
80
88
  if (!configPath) {
81
89
  throw new QaLeadRefusal(
@@ -90,12 +98,13 @@ async function bootstrap(milestoneArg) {
90
98
  }
91
99
  const token = await resolveToken();
92
100
 
93
- const milestones = await trackerDe(token, owner, repo).listMilestones();
101
+ const tracker = await requireTracker({ token, owner, repo, deps });
102
+ const milestones = await tracker.listMilestones();
94
103
  const resolved = resolveMilestoneRef(milestones, milestoneArg);
95
104
  if (resolved.error) throw new QaLeadRefusal(resolved.error);
96
105
 
97
106
  const lead = resolveLeadConfig(config?.qa?.lead);
98
- return { token, owner, repo, root, config, lead, milestone: resolved.milestone };
107
+ return { token, owner, repo, root, config, lead, milestone: resolved.milestone, tracker, deps };
99
108
  }
100
109
 
101
110
  // Tradução no ponto de leitura: o resto deste arquivo lê a forma antiga
@@ -113,8 +122,8 @@ const comoItem = w => w && ({
113
122
  // Itens do milestone separados por tipo — SEMPRE por Work Item Type (§4.1):
114
123
  // Stories e Bugs herdam o milestone do pai (D5), então filtrar por milestone
115
124
  // puro mandaria o Lead abrir container para Task.
116
- async function milestoneItems({ token, owner, repo, milestone }) {
117
- const issues = await trackerDe(token, owner, repo).listWorkItemsByMilestone({ milestone });
125
+ async function milestoneItems({ token, owner, repo, milestone, tracker }) {
126
+ const issues = await tracker.listWorkItemsByMilestone({ milestone });
118
127
  const byType = { Feature: [], Story: [], Bug: [] };
119
128
  for (const issue of issues) {
120
129
  const type = detectIssueType(issue);
@@ -127,12 +136,13 @@ async function milestoneItems({ token, owner, repo, milestone }) {
127
136
  // topológica das Stories, projetada nas Features donas. Arestas das fontes
128
137
  // LOCAIS (dependency-map/doc/body — lib/story-graph): sequenciar a trilha não
129
138
  // exige o blocked_by remoto, e era este laço que pagava F+S chamadas por fase.
130
- async function orderFeatures({ token, owner, repo, root, features, ttlSec }) {
139
+ async function orderFeatures({ token, owner, repo, root, features, ttlSec, tracker }) {
131
140
  const stories = [];
132
141
  const featureOfStory = new Map();
133
142
  const storiesOfFeature = new Map();
134
143
  for (const feature of features) {
135
144
  const carga = await loadFeatureStories({
145
+ tracker,
136
146
  token, owner, repo, root,
137
147
  feature: { number: feature.number, nodeId: feature.node_id, title: feature.title },
138
148
  ttlSec,
@@ -177,9 +187,9 @@ const PLAN_STATE_LABEL = {
177
187
  gerar: '🏷️ gatilho aplicado agora',
178
188
  };
179
189
 
180
- async function qaLeadPlan(milestoneArg, { watch = false, dryRun = false } = {}) {
181
- const ctx = await bootstrap(milestoneArg);
182
- const { token, owner, repo, root, lead, milestone } = ctx;
190
+ async function qaLeadPlan(milestoneArg, { watch = false, dryRun = false, deps = {} } = {}) {
191
+ const ctx = await bootstrap(milestoneArg, deps);
192
+ const { token, owner, repo, root, lead, milestone, tracker } = ctx;
183
193
 
184
194
  const { Feature: features } = await milestoneItems(ctx);
185
195
  if (features.length === 0) {
@@ -187,7 +197,7 @@ async function qaLeadPlan(milestoneArg, { watch = false, dryRun = false } = {})
187
197
  return;
188
198
  }
189
199
 
190
- const { ordered } = await orderFeatures({ token, owner, repo, root, features, ttlSec: resolveCacheTtl(ctx.config) });
200
+ const { ordered } = await orderFeatures({ token, owner, repo, root, features, tracker, ttlSec: resolveCacheTtl(ctx.config) });
191
201
 
192
202
  const classified = [];
193
203
  for (const feature of ordered) {
@@ -207,7 +217,7 @@ async function qaLeadPlan(milestoneArg, { watch = false, dryRun = false } = {})
207
217
  continue;
208
218
  }
209
219
  if (applied > 0) await sleep(TRIGGER_INTERVAL_MS);
210
- await trackerDe(token, owner, repo).addTag({ ref: { key: String(item.feature.number) }, tag: LABEL_QA });
220
+ await tracker.addTag({ ref: { key: String(item.feature.number) }, tag: LABEL_QA });
211
221
  applied += 1;
212
222
  item.state = 'em-voo';
213
223
  console.log(`Feature #${item.feature.number}: \`${LABEL_QA}\` aplicada — plano em geração.`);
@@ -221,7 +231,7 @@ async function qaLeadPlan(milestoneArg, { watch = false, dryRun = false } = {})
221
231
  await sleep(lead.pollIntervalSec * 1000);
222
232
  for (const item of classified) {
223
233
  if (item.state !== 'em-voo') continue;
224
- const issue = await trackerDe(token, owner, repo).getWorkItem({ ref: { key: String(item.feature.number) } }).catch(() => null);
234
+ const issue = await tracker.getWorkItem({ ref: { key: String(item.feature.number) } }).catch(() => null);
225
235
  if (!issue) continue;
226
236
  const { state } = classifyForPlan({ labels: labelNames(issue), hasSpecPlan: true });
227
237
  if (state !== 'em-voo') {
@@ -268,10 +278,10 @@ async function qaLeadPlan(milestoneArg, { watch = false, dryRun = false } = {})
268
278
  // ── fase B — qa-lead run ─────────────────────────────────────────────────────
269
279
 
270
280
  async function qaLeadRun(milestoneArg, {
271
- only: onlyArg, maxCycles: maxCyclesArg, dryRun = false,
281
+ only: onlyArg, maxCycles: maxCyclesArg, dryRun = false, deps = {},
272
282
  } = {}) {
273
- const ctx = await bootstrap(milestoneArg);
274
- const { token, owner, repo, root, config, lead, milestone } = ctx;
283
+ const ctx = await bootstrap(milestoneArg, deps);
284
+ const { token, owner, repo, root, config, lead, milestone, tracker } = ctx;
275
285
  const maxCycles = maxCyclesArg ? parseInt(maxCyclesArg, 10) : lead.maxCycles;
276
286
  if (!Number.isInteger(maxCycles) || maxCycles <= 0) {
277
287
  throw new QaLeadRefusal(`--max-cycles inválido: "${maxCyclesArg}".`);
@@ -290,7 +300,7 @@ async function qaLeadRun(milestoneArg, {
290
300
  console.log(`Milestone "${milestone.title}" não tem nenhuma Feature — nada a executar.`);
291
301
  return;
292
302
  }
293
- const { ordered, featureOfStory } = await orderFeatures({ token, owner, repo, root, features, ttlSec: resolveCacheTtl(config) });
303
+ const { ordered, featureOfStory } = await orderFeatures({ token, owner, repo, root, features, tracker, ttlSec: resolveCacheTtl(config) });
294
304
 
295
305
  // Etapa via snapshot do board (leitura pura — nada de addProjectItem aqui:
296
306
  // o dry-run promete zero escrita, e o run não precisa mutar para ler).
@@ -347,7 +357,7 @@ async function qaLeadRun(milestoneArg, {
347
357
  : [];
348
358
  const previousBugs = [];
349
359
  for (const n of previousBugNumbers) {
350
- const issue = await trackerDe(token, owner, repo).getWorkItem({ ref: { key: String(n) } }).catch(() => null);
360
+ const issue = await tracker.getWorkItem({ ref: { key: String(n) } }).catch(() => null);
351
361
  if (issue) previousBugs.push(issue);
352
362
  }
353
363
  const closedBugs = previousBugs.filter(b => b.state === 'closed');
@@ -368,7 +378,7 @@ async function qaLeadRun(milestoneArg, {
368
378
  } else {
369
379
  const lastResults = new Map();
370
380
  for (const t of inCycle) {
371
- const comments = await trackerDe(token, owner, repo).listComments({ ref: { key: String(t.feature.number) } }).catch(() => []);
381
+ const comments = await tracker.listComments({ ref: { key: String(t.feature.number) } }).catch(() => []);
372
382
  const parsed = parseLastQaReport(comments);
373
383
  lastResults.set(t.feature.number, [...parsed.results.entries()]
374
384
  .map(([numero, r]) => ({ numero, verdict: r.verdict })));
@@ -457,7 +467,7 @@ async function qaLeadRun(milestoneArg, {
457
467
  while (queue.length > 0) {
458
468
  const target = queue.shift();
459
469
  const before = parseLastQaReport(
460
- await trackerDe(token, owner, repo).listComments({ ref: { key: String(target.issue) } }).catch(() => [])).run;
470
+ await tracker.listComments({ ref: { key: String(target.issue) } }).catch(() => [])).run;
461
471
  console.log(`▶ despachando container: qa ${target.issue}${target.only ? ` --only ${target.only.join(',')}` : ''}`);
462
472
  const result = await backend.run({
463
473
  name: `qa-${target.issue}`,
@@ -477,7 +487,7 @@ async function qaLeadRun(milestoneArg, {
477
487
  // container — quem morreu depois de comentar não perde resultado; quem
478
488
  // morreu antes vira execucao-abortada (§3.3).
479
489
  const parsed = parseLastQaReport(
480
- await trackerDe(token, owner, repo).listComments({ ref: { key: String(target.issue) } }).catch(() => []));
490
+ await tracker.listComments({ ref: { key: String(target.issue) } }).catch(() => []));
481
491
  const fresh = parsed.run > before ? parsed : null;
482
492
  outcomes.set(target.issue, {
483
493
  target,
@@ -679,7 +689,7 @@ async function runPreflight({ backend, lead, root }) {
679
689
 
680
690
  // ── publicação do ciclo (as escritas 2 e 3 do §2.1) ──────────────────────────
681
691
 
682
- async function publishCycle({ token, owner, repo, root, milestone, report }) {
692
+ async function publishCycle({ token, owner, repo, root, milestone, report, tracker, deps = {} }) {
683
693
  const dirRel = qaTrailDir(milestone.title, report.cycle);
684
694
  const dirAbs = path.join(root, dirRel);
685
695
  mkdirSync(dirAbs, { recursive: true });
@@ -692,11 +702,11 @@ async function publishCycle({ token, owner, repo, root, milestone, report }) {
692
702
  // Commit escopado ao diretório do ciclo + push best-effort: o relatório é do
693
703
  // repositório (D-QAL4), mas uma falha de push não pode engolir o veredito.
694
704
  try {
695
- execSync(`git add -- ${JSON.stringify(dirRel)}`, { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
696
- execSync(
705
+ (deps.exec ?? execSync)(`git add -- ${JSON.stringify(dirRel)}`, { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
706
+ (deps.exec ?? execSync)(
697
707
  `git commit -m ${JSON.stringify(`docs: relatório de QA da trilha "${milestone.title}" ciclo ${report.cycle} [spec-wave]`)} -- ${JSON.stringify(dirRel)}`,
698
708
  { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
699
- const push = await pushWithRebase({ cwd: root });
709
+ const push = await (deps.push ?? pushWithRebase)({ cwd: root });
700
710
  if (!push.ok) {
701
711
  console.warn(chalk.yellow(`⚠️ Relatório commitado, mas o push falhou: ${String(push.error).split('\n')[0]} — pushe manualmente.`));
702
712
  }
@@ -707,9 +717,9 @@ async function publishCycle({ token, owner, repo, root, milestone, report }) {
707
717
  // Bloco delimitado na descrição do milestone — SUBSTITUI o bloco, nunca a
708
718
  // descrição (as Release Notes moram no mesmo campo — §4.4).
709
719
  try {
710
- const atual = await trackerDe(token, owner, repo).getMilestone({ key: milestone.key });
720
+ const atual = await tracker.getMilestone({ key: milestone.key });
711
721
  const description = upsertMilestoneBlock(atual.description, milestoneBlock(report, mdRel));
712
- await trackerDe(token, owner, repo).setMilestoneDescription({ key: milestone.key, description });
722
+ await tracker.setMilestoneDescription({ key: milestone.key, description });
713
723
  console.log('Bloco de trilha atualizado na descrição do milestone.');
714
724
  } catch (err) {
715
725
  console.warn(chalk.yellow(`⚠️ Não consegui atualizar a descrição do milestone: ${err.message}`));
@@ -741,8 +751,8 @@ function lastCycleReport(root, milestoneTitle, cycle = null) {
741
751
  }
742
752
  }
743
753
 
744
- async function qaLeadReport(milestoneArg, { cycle: cycleArg } = {}) {
745
- const ctx = await bootstrap(milestoneArg);
754
+ async function qaLeadReport(milestoneArg, { cycle: cycleArg, deps = {} } = {}) {
755
+ const ctx = await bootstrap(milestoneArg, deps);
746
756
  const { root, milestone } = ctx;
747
757
  const cycle = cycleArg ? parseInt(cycleArg, 10) : null;
748
758
  if (cycleArg && (!Number.isInteger(cycle) || cycle <= 0)) {