@spec-wave/cli 1.0.8 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/package.json +1 -1
  2. package/src/commands/audit.mjs +24 -18
  3. package/src/commands/code-review.mjs +89 -58
  4. package/src/commands/decompose.mjs +254 -218
  5. package/src/commands/generate-bug.mjs +51 -44
  6. package/src/commands/generate-plan.mjs +83 -63
  7. package/src/commands/generate-qa-plan.mjs +144 -117
  8. package/src/commands/generate-spec.mjs +33 -28
  9. package/src/commands/implement.mjs +154 -79
  10. package/src/commands/init.mjs +8 -3
  11. package/src/commands/issue.mjs +26 -39
  12. package/src/commands/merge.mjs +71 -20
  13. package/src/commands/mode.mjs +8 -4
  14. package/src/commands/move.mjs +16 -20
  15. package/src/commands/order.mjs +33 -22
  16. package/src/commands/preflight.mjs +24 -13
  17. package/src/commands/qa-lead.mjs +28 -16
  18. package/src/commands/qa-run.mjs +122 -101
  19. package/src/commands/qa.mjs +55 -44
  20. package/src/commands/refresh.mjs +24 -16
  21. package/src/commands/repair-stage.mjs +29 -16
  22. package/src/commands/repo.mjs +10 -3
  23. package/src/commands/run.mjs +23 -11
  24. package/src/commands/story.mjs +20 -25
  25. package/src/commands/task.mjs +21 -27
  26. package/src/commands/triage.mjs +33 -31
  27. package/src/commands/uninstall.mjs +7 -3
  28. package/src/commands/update.mjs +29 -21
  29. package/src/commands/validate.mjs +60 -52
  30. package/src/commands/workspace.mjs +7 -5
  31. package/src/config.mjs +7 -1
  32. package/src/lib/artifact-publish.mjs +20 -18
  33. package/src/lib/board-policy.mjs +144 -0
  34. package/src/lib/board.mjs +134 -233
  35. package/src/lib/doc-availability.mjs +10 -3
  36. package/src/lib/doc-source.mjs +9 -9
  37. package/src/lib/implement-board.mjs +23 -26
  38. package/src/lib/issue-type.mjs +5 -1
  39. package/src/lib/pr-ready.mjs +48 -10
  40. package/src/lib/pr-step.mjs +3 -1
  41. package/src/lib/qa-exec.mjs +3 -1
  42. package/src/lib/qa-lead.mjs +11 -3
  43. package/src/lib/qa-plan-doc.mjs +10 -4
  44. package/src/lib/spec-audit.mjs +1 -1
  45. package/src/lib/story-graph.mjs +62 -8
  46. package/src/lib/usage-report.mjs +8 -5
  47. package/src/lib/work-item-ref.mjs +176 -0
  48. package/src/plugin/.claude-plugin/plugin.json +1 -1
  49. package/src/plugins/scm-github/index.mjs +439 -0
  50. package/src/plugins/tracker-github-projects/fields.mjs +73 -0
  51. package/src/plugins/tracker-github-projects/index.mjs +625 -0
  52. package/src/ports/scm.mjs +197 -0
  53. package/src/ports/tracker.mjs +239 -0
  54. package/src/ports/types.mjs +254 -0
  55. package/src/setup/files.mjs +14 -12
  56. package/src/setup/labels.mjs +17 -12
  57. package/src/setup/project.mjs +40 -59
@@ -20,9 +20,8 @@ import * as p from '@clack/prompts';
20
20
  import chalk from 'chalk';
21
21
 
22
22
  import { resolveToken } from '../api/auth.mjs';
23
- import {
24
- getRepoDefaultBranch, getRepoVariable, listMilestones, listIssuesByMilestone,
25
- } from '../api/github-rest.mjs';
23
+ import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
24
+ import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
26
25
  import { CONFIG_FILE } from '../config.mjs';
27
26
  import { inspectPrPublishing, readPrPublishingContext } from './doctor.mjs';
28
27
  import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
@@ -174,7 +173,7 @@ export function inspectPreflight({
174
173
 
175
174
  const MARCA = { local: '✓ no disco', remote: '✓ na base', 'pending-pr': '⏳ em PR aberto', 'branch-only': '⚠ em branch sem PR', missing: '· gerar', unknown: '? indeterminado' };
176
175
 
177
- export async function preflight({ milestone: milestoneArg, json = false } = {}) {
176
+ export async function preflight({ milestone: milestoneArg, json = false, deps = {} } = {}) {
178
177
  const saida = { milestone: null, modo: null, publicacao: null, inventario: null, veredito: null };
179
178
  const falhar = (msg) => {
180
179
  if (json) console.log(JSON.stringify({ ...saida, erro: msg }, null, 2));
@@ -199,12 +198,15 @@ export async function preflight({ milestone: milestoneArg, json = false } = {})
199
198
  return falhar(`Sem token utilizável para ${owner}/${repo}: ${err.message}`);
200
199
  }
201
200
 
201
+ const tracker = deps.tracker ?? createGithubTracker({ token, owner, repo });
202
+ const scm = deps.scm ?? createGithubScm({ link: githubLink({ owner, repo }), token });
203
+
202
204
  const s = json ? null : p.spinner();
203
205
  s?.start('Consultando o repositório...');
204
206
 
205
207
  let base;
206
208
  try {
207
- base = await getRepoDefaultBranch(token, owner, repo);
209
+ base = await scm.defaultBranch();
208
210
  } catch (err) {
209
211
  s?.stop('');
210
212
  return falhar(`Não foi possível ler o repositório ${owner}/${repo}: ${err.message}`);
@@ -213,7 +215,7 @@ export async function preflight({ milestone: milestoneArg, json = false } = {})
213
215
  // --- Modo de execução: config × variável (o mesmo par que o doctor confere).
214
216
  let variable;
215
217
  try {
216
- variable = await getRepoVariable(token, owner, repo, EXECUTION_VARIABLE);
218
+ variable = await scm.getVariable({ name: EXECUTION_VARIABLE });
217
219
  } catch {
218
220
  variable = undefined; // exige admin — "não deu para ler" não é "ausente"
219
221
  }
@@ -231,7 +233,7 @@ export async function preflight({ milestone: milestoneArg, json = false } = {})
231
233
  // --- Inventário da milestone.
232
234
  let milestones;
233
235
  try {
234
- milestones = await listMilestones(token, owner, repo);
236
+ milestones = await tracker.listMilestones();
235
237
  } catch (err) {
236
238
  s?.stop('');
237
239
  return falhar(`Não foi possível listar as milestones: ${err.message}`);
@@ -244,7 +246,7 @@ export async function preflight({ milestone: milestoneArg, json = false } = {})
244
246
 
245
247
  let issues;
246
248
  try {
247
- issues = await listIssuesByMilestone(token, owner, repo, milestone.number);
249
+ issues = await tracker.listWorkItemsByMilestone({ milestone });
248
250
  } catch (err) {
249
251
  s?.stop('');
250
252
  return falhar(`Não foi possível listar as issues da milestone "${milestone.title}": ${err.message}`);
@@ -253,24 +255,33 @@ export async function preflight({ milestone: milestoneArg, json = false } = {})
253
255
  // O estado do spec.md de cada Feature, nas quatro camadas. Uma issue por vez:
254
256
  // são até 3 requisições cada, e disparar tudo de uma vez numa milestone de 20
255
257
  // Features é o caminho mais curto para o rate limit secundário.
258
+ // `inspectMilestone` é PURA e testada contra a forma da issue crua. Em vez de
259
+ // mudá-la (e o teste junto), a normalização acontece aqui, num lugar só.
260
+ const comoIssue = w => ({
261
+ number: Number(w.ref.key),
262
+ title: w.title,
263
+ state: w.state,
264
+ labels: w.tags,
265
+ });
266
+
256
267
  const featureIssues = issues.filter(i => detectIssueType(i) === 'Feature');
257
268
  const specStates = {};
258
269
  for (const issue of featureIssues) {
259
270
  const docs = featureDocPaths(root, issue, 'Feature');
260
271
  const estados = await artifactStates({
261
- token, owner, repo, root, base,
262
- issueNumber: issue.number,
272
+ token, owner, repo, root, base, scm,
273
+ issueNumber: issue.ref.key,
263
274
  docs: [{ doc: 'spec', pathRel: docs.spec.rel }],
264
275
  });
265
- specStates[issue.number] = estados.spec;
276
+ specStates[issue.ref.key] = estados.spec;
266
277
  }
267
278
 
268
- const inventario = inspectMilestone({ issues, specStates });
279
+ const inventario = inspectMilestone({ issues: issues.map(comoIssue), specStates });
269
280
  const veredito = inspectPreflight({ tokenOk: true, modo, publicacao, inventario });
270
281
  s?.stop(`Milestone "${milestone.title}": ${inventario.features.length} Feature(s).`);
271
282
 
272
283
  Object.assign(saida, {
273
- milestone: { title: milestone.title, number: milestone.number, base },
284
+ milestone: { title: milestone.title, number: Number(milestone.key), base },
274
285
  modo: { configured: configuredMode(config), variable: variable ?? null, status: modo.status, summary: modo.summary },
275
286
  publicacao: { status: publicacao.status, notes: publicacao.notes },
276
287
  inventario,
@@ -23,13 +23,13 @@ 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 {
27
- addLabel, getIssue, listMilestones, listIssuesByMilestone,
28
- getMilestone, updateMilestoneDescription, listIssueComments,
29
- } from '../api/github-rest.mjs';
26
+ import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
30
27
  import { detectIssueType } from '../lib/issue-type.mjs';
31
28
  import { loadConfig, findConfigPath } from '../lib/project-root.mjs';
32
29
  import { loadProjectConfig } from '../lib/board.mjs';
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
33
  import { featureDocPaths } from '../lib/doc-paths.mjs';
34
34
  import { orderStories } from '../lib/dependencies.mjs';
35
35
  import { loadFeatureStories, loadBoardSnapshot } from '../lib/story-graph.mjs';
@@ -90,7 +90,7 @@ async function bootstrap(milestoneArg) {
90
90
  }
91
91
  const token = await resolveToken();
92
92
 
93
- const milestones = await listMilestones(token, owner, repo);
93
+ const milestones = await trackerDe(token, owner, repo).listMilestones();
94
94
  const resolved = resolveMilestoneRef(milestones, milestoneArg);
95
95
  if (resolved.error) throw new QaLeadRefusal(resolved.error);
96
96
 
@@ -98,15 +98,27 @@ async function bootstrap(milestoneArg) {
98
98
  return { token, owner, repo, root, config, lead, milestone: resolved.milestone };
99
99
  }
100
100
 
101
+ // Tradução no ponto de leitura: o resto deste arquivo lê a forma antiga
102
+ // (`number`, `node_id`, `labels`) em dezenas de pontos — `byNumber`, o
103
+ // `featureOfStory` e o `addTag({ ref })` entre eles. Converter aqui é o que
104
+ // mantém o `WorkItem` da porta contido na fronteira.
105
+ const comoItem = w => w && ({
106
+ ...w,
107
+ number: Number(w.ref.key),
108
+ nodeId: w.ref.id,
109
+ node_id: w.ref.id,
110
+ labels: w.tags || [],
111
+ });
112
+
101
113
  // Itens do milestone separados por tipo — SEMPRE por Work Item Type (§4.1):
102
114
  // Stories e Bugs herdam o milestone do pai (D5), então filtrar por milestone
103
115
  // puro mandaria o Lead abrir container para Task.
104
116
  async function milestoneItems({ token, owner, repo, milestone }) {
105
- const issues = await listIssuesByMilestone(token, owner, repo, milestone.number);
117
+ const issues = await trackerDe(token, owner, repo).listWorkItemsByMilestone({ milestone });
106
118
  const byType = { Feature: [], Story: [], Bug: [] };
107
119
  for (const issue of issues) {
108
120
  const type = detectIssueType(issue);
109
- if (byType[type]) byType[type].push(issue);
121
+ if (byType[type]) byType[type].push(comoItem(issue));
110
122
  }
111
123
  return byType;
112
124
  }
@@ -195,7 +207,7 @@ async function qaLeadPlan(milestoneArg, { watch = false, dryRun = false } = {})
195
207
  continue;
196
208
  }
197
209
  if (applied > 0) await sleep(TRIGGER_INTERVAL_MS);
198
- await addLabel(token, owner, repo, item.feature.number, LABEL_QA);
210
+ await trackerDe(token, owner, repo).addTag({ ref: { key: String(item.feature.number) }, tag: LABEL_QA });
199
211
  applied += 1;
200
212
  item.state = 'em-voo';
201
213
  console.log(`Feature #${item.feature.number}: \`${LABEL_QA}\` aplicada — plano em geração.`);
@@ -209,7 +221,7 @@ async function qaLeadPlan(milestoneArg, { watch = false, dryRun = false } = {})
209
221
  await sleep(lead.pollIntervalSec * 1000);
210
222
  for (const item of classified) {
211
223
  if (item.state !== 'em-voo') continue;
212
- const issue = await getIssue(token, owner, repo, item.feature.number).catch(() => null);
224
+ const issue = await trackerDe(token, owner, repo).getWorkItem({ ref: { key: String(item.feature.number) } }).catch(() => null);
213
225
  if (!issue) continue;
214
226
  const { state } = classifyForPlan({ labels: labelNames(issue), hasSpecPlan: true });
215
227
  if (state !== 'em-voo') {
@@ -288,7 +300,7 @@ async function qaLeadRun(milestoneArg, {
288
300
  // `fresh: true`: o escopo decide O QUE EXECUTA em container — gate de
289
301
  // execução não decide com cache. O snapshot fresco fica gravado para os
290
302
  // comandos seguintes da sessão.
291
- boardIndex = (await loadBoardSnapshot({ token, project, root, fresh: true })
303
+ boardIndex = (await loadBoardSnapshot({ token, owner, repo, project, root, fresh: true })
292
304
  .catch(() => ({ index: new Map() }))).index;
293
305
  } else {
294
306
  console.warn(chalk.yellow(`⚠️ ${projectError || 'Project não configurado'} — Etapas não legíveis; Features contarão como fora-do-ciclo.`));
@@ -335,7 +347,7 @@ async function qaLeadRun(milestoneArg, {
335
347
  : [];
336
348
  const previousBugs = [];
337
349
  for (const n of previousBugNumbers) {
338
- const issue = await getIssue(token, owner, repo, n).catch(() => null);
350
+ const issue = await trackerDe(token, owner, repo).getWorkItem({ ref: { key: String(n) } }).catch(() => null);
339
351
  if (issue) previousBugs.push(issue);
340
352
  }
341
353
  const closedBugs = previousBugs.filter(b => b.state === 'closed');
@@ -356,7 +368,7 @@ async function qaLeadRun(milestoneArg, {
356
368
  } else {
357
369
  const lastResults = new Map();
358
370
  for (const t of inCycle) {
359
- const comments = await listIssueComments(token, owner, repo, t.feature.number).catch(() => []);
371
+ const comments = await trackerDe(token, owner, repo).listComments({ ref: { key: String(t.feature.number) } }).catch(() => []);
360
372
  const parsed = parseLastQaReport(comments);
361
373
  lastResults.set(t.feature.number, [...parsed.results.entries()]
362
374
  .map(([numero, r]) => ({ numero, verdict: r.verdict })));
@@ -445,7 +457,7 @@ async function qaLeadRun(milestoneArg, {
445
457
  while (queue.length > 0) {
446
458
  const target = queue.shift();
447
459
  const before = parseLastQaReport(
448
- await listIssueComments(token, owner, repo, target.issue).catch(() => [])).run;
460
+ await trackerDe(token, owner, repo).listComments({ ref: { key: String(target.issue) } }).catch(() => [])).run;
449
461
  console.log(`▶ despachando container: qa ${target.issue}${target.only ? ` --only ${target.only.join(',')}` : ''}`);
450
462
  const result = await backend.run({
451
463
  name: `qa-${target.issue}`,
@@ -465,7 +477,7 @@ async function qaLeadRun(milestoneArg, {
465
477
  // container — quem morreu depois de comentar não perde resultado; quem
466
478
  // morreu antes vira execucao-abortada (§3.3).
467
479
  const parsed = parseLastQaReport(
468
- await listIssueComments(token, owner, repo, target.issue).catch(() => []));
480
+ await trackerDe(token, owner, repo).listComments({ ref: { key: String(target.issue) } }).catch(() => []));
469
481
  const fresh = parsed.run > before ? parsed : null;
470
482
  outcomes.set(target.issue, {
471
483
  target,
@@ -695,9 +707,9 @@ async function publishCycle({ token, owner, repo, root, milestone, report }) {
695
707
  // Bloco delimitado na descrição do milestone — SUBSTITUI o bloco, nunca a
696
708
  // descrição (as Release Notes moram no mesmo campo — §4.4).
697
709
  try {
698
- const atual = await getMilestone(token, owner, repo, milestone.number);
710
+ const atual = await trackerDe(token, owner, repo).getMilestone({ key: milestone.key });
699
711
  const description = upsertMilestoneBlock(atual.description, milestoneBlock(report, mdRel));
700
- await updateMilestoneDescription(token, owner, repo, milestone.number, description);
712
+ await trackerDe(token, owner, repo).setMilestoneDescription({ key: milestone.key, description });
701
713
  console.log('Bloco de trilha atualizado na descrição do milestone.');
702
714
  } catch (err) {
703
715
  console.warn(chalk.yellow(`⚠️ Não consegui atualizar a descrição do milestone: ${err.message}`));