@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
@@ -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
  import { detectIssueType } from '../lib/issue-type.mjs';
16
15
  import { openTracker, advanceToStage } from '../lib/board.mjs';
17
16
  import { resolveHubContext } from '../lib/project-root.mjs';
18
17
  import { resolveTriageAction, canAcceptBug } from '../lib/bug-triage.mjs';
18
+ import { requireTracker } from '../ports/index.mjs';
19
19
  import {
20
20
  CONFIG_FILE, STAGE_READY, PROGRESS_TODO, PRIORITY_LABELS,
21
21
  LABEL_TRIAGED, LABEL_DUPLICATE, LABEL_WONT_FIX, labelNames,
@@ -64,7 +64,7 @@ export async function triage({ action: actionArg, issue: issueArg, reason, of, s
64
64
 
65
65
  p.intro(chalk.bold(`spec-wave triage ${action} #${issueNumber}`));
66
66
 
67
- const tracker = deps.tracker ?? createGithubTracker({ token, owner, repo });
67
+ const tracker = await requireTracker({ token, owner, repo, deps });
68
68
  const ref = { key: String(issueNumber) };
69
69
 
70
70
  let issue;
@@ -153,7 +153,7 @@ export async function triage({ action: actionArg, issue: issueArg, reason, of, s
153
153
  }
154
154
 
155
155
  async function moveToReady({ token, issueNumber, issue, root, deps = {} }) {
156
- const { tracker, error } = openTracker({ token, cwd: root || process.cwd(), tracker: deps.tracker });
156
+ const { tracker, error } = await openTracker({ token, cwd: root || process.cwd(), tracker: deps.tracker });
157
157
  if (error) {
158
158
  p.log.warn(`${error} — board não atualizado.`);
159
159
  return;
@@ -4,8 +4,8 @@ import { readFileSync, existsSync, unlinkSync } from 'node:fs';
4
4
  import path from 'node:path';
5
5
  import { resolveToken } from '../api/auth.mjs';
6
6
  import { CONFIG_FILE, ALL_LABELS, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES } from '../config.mjs';
7
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
8
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
7
+ import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
8
+ import { tagRegistryPlan } from '../lib/tag-registry.mjs';
9
9
 
10
10
  const REPO_FILES = [
11
11
  ...WORKFLOW_FILES.map(f => `.github/workflows/${f}`),
@@ -45,7 +45,9 @@ export async function uninstall(options = {}) {
45
45
  return;
46
46
  }
47
47
 
48
- const doLabels = !options.skipLabels;
48
+ // `let` porque o guard de `deleteTag` pode desligá-lo depois de a porta existir
49
+ // (um tracker sem registro de labels — ver o bloco de labels abaixo).
50
+ let doLabels = !options.skipLabels;
49
51
  const doFiles = !options.skipFiles;
50
52
  const doConfig = hasConfig && !options.keepConfig;
51
53
 
@@ -81,10 +83,17 @@ export async function uninstall(options = {}) {
81
83
  return;
82
84
  }
83
85
 
84
- const tracker = createGithubTracker({ token, owner, repo });
85
- const scm = createGithubScm({ link: githubLink({ owner, repo }), token });
86
+ const tracker = await requireTracker({ token, owner, repo });
87
+ const scm = await requireScm({ link: resolveScmLink({ owner, repo }), token });
86
88
 
87
89
  // --- Labels ---
90
+ // `deleteTag` é OPCIONAL no contrato e nenhuma capability a liga — ver
91
+ // `lib/tag-registry.mjs`, que tem a razão inteira.
92
+ const registro = tagRegistryPlan(tracker);
93
+ if (doLabels && !registro.canDelete) {
94
+ p.log.warn(registro.warning);
95
+ doLabels = false;
96
+ }
88
97
  if (doLabels) {
89
98
  const spinner = p.spinner();
90
99
  spinner.start('Removendo labels...');
@@ -5,8 +5,7 @@ import { homedir } from 'node:os';
5
5
  import path from 'node:path';
6
6
  import { resolveToken } from '../api/auth.mjs';
7
7
  import { CONFIG_FILE, WORKFLOW_FILES, CODE_WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS, allLabelsFor } from '../config.mjs';
8
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
9
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
8
+ import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
10
9
  import {
11
10
  resolveBranchName, composePrTitle, composePrBody, buildCommitMessage,
12
11
  decideConfigInPr, decideSkillInPr, composeConfigCleanupHint, explainGitWriteError,
@@ -24,6 +23,7 @@ import { findConfigPath } from '../lib/project-root.mjs';
24
23
  import { configuredRole } from '../lib/repo-role.mjs';
25
24
  import { currentGitBranch } from '../lib/repo-links.mjs';
26
25
  import { cliRef } from '../lib/cli-ref.mjs';
26
+ import { tagRegistryPlan } from '../lib/tag-registry.mjs';
27
27
 
28
28
  // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
29
29
  const REPO_FILES = [
@@ -200,9 +200,10 @@ async function buildConfigContent(token, config) {
200
200
  }
201
201
  // `provision: false` é leitura do schema vivo — a mesma operação que o
202
202
  // `refresh --config` usa para regravar os ids do board.
203
- const { config: vivo } = await createGithubTracker({
204
- token, owner: config.owner, repo: config.repo, project: config.project,
205
- }).setup({ provision: false });
203
+ const trackerVivo = await requireTracker({
204
+ token, owner: config.owner, repo: config.repo, board: true,
205
+ });
206
+ const { config: vivo } = await trackerVivo.setup({ provision: false });
206
207
  if (!vivo) return { content: null, error: 'Project não encontrado' };
207
208
  const snapshot = {
208
209
  id: vivo.projectId, number: vivo.projectNumber,
@@ -247,11 +248,22 @@ async function buildConfigContent(token, config) {
247
248
  * só o que REALMENTE passou — é o que o corpo do PR vai afirmar a quem
248
249
  * revisa, e ele não pode prometer o que falhou.
249
250
  */
250
- /** Porta de SCM do repositório-alvo. Memoizada por token: `tk` é lazy. */
251
- const scmDe = (tk, owner, repo) => createGithubScm({ link: githubLink({ owner, repo }), token: tk });
251
+ /**
252
+ * Porta de SCM do repositório-alvo — ASSÍNCRONA desde a leva 4 do bloco E.
253
+ *
254
+ * `tk` é lazy, e é por isso que ela fica mecânica (`await` duplo nos 8 call
255
+ * sites) em vez de resolver a porta uma vez: o token só existe depois de uma
256
+ * cadeia de decisões, e antecipá-la para resolver a porta mudaria a ordem em que
257
+ * o `update` pede credencial. O custo são 8 leituras de arquivo num comando que
258
+ * faz dezenas de chamadas de rede.
259
+ *
260
+ * (O comentário anterior dizia "memoizada" e ela nunca foi — construía uma porta
261
+ * por chamada. Corrigido de passagem.)
262
+ */
263
+ const scmDe = (tk, owner, repo) => requireScm({ link: resolveScmLink({ owner, repo }), token: tk });
252
264
 
253
265
  async function applyLabels(token, owner, repo, labelDiff, forceLabels = false) {
254
- const tracker = createGithubTracker({ token, owner, repo });
266
+ const tracker = await requireTracker({ token, owner, repo });
255
267
  const done = { created: [], updated: [], removed: [] };
256
268
  for (const label of labelDiff.missing) {
257
269
  try {
@@ -271,11 +283,22 @@ async function applyLabels(token, owner, repo, labelDiff, forceLabels = false) {
271
283
  p.log.error(`Falha ao atualizar label ${label.name}: ${err.message}`);
272
284
  }
273
285
  }
274
- for (const label of labelDiff.orphan) {
286
+ // `countOpenWithTag` e `deleteTag` são OPCIONAIS no contrato e nenhuma
287
+ // capability as liga — ver `lib/tag-registry.mjs`, que tem a razão inteira.
288
+ const registro = tagRegistryPlan(tracker);
289
+ if (labelDiff.orphan.length > 0 && !registro.canDelete) {
290
+ p.log.warn(`${labelDiff.orphan.length} label(s) descontinuada(s) a remover: ${registro.warning}`);
291
+ }
292
+ for (const label of registro.canDelete ? labelDiff.orphan : []) {
275
293
  try {
294
+ // Sem contagem, o portão de segurança (não remover label em uso) não pode
295
+ // ser avaliado — e `null` é exatamente o que `shouldDeleteOrphanLabel` já
296
+ // trata como "não sei", que recusa sem `--force-labels`. Degradar para o
297
+ // valor mais conservador é o certo: o risco de apagar label em uso é maior
298
+ // que o incômodo de pedir a flag.
276
299
  const inUse = forceLabels
277
300
  ? 0
278
- : await tracker.countOpenWithTag({ tag: label.name }).catch(() => null);
301
+ : (registro.canCount ? await tracker.countOpenWithTag({ tag: label.name }).catch(() => null) : null);
279
302
  const decision = shouldDeleteOrphanLabel({ inUse, forceLabels });
280
303
  if (!decision.ok) {
281
304
  p.log.warn(`Label ${label.name}: ${decision.motivo}. Use --force-labels para remover mesmo assim.`);
@@ -382,12 +405,13 @@ export async function update(options = {}) {
382
405
  } else {
383
406
  try {
384
407
  for (const f of repoFilesFor(role)) {
385
- const remote = await scmDe(tk, owner, repo).readFile({ path: f.repoPath });
408
+ const remote = await (await scmDe(tk, owner, repo)).readFile({ path: f.repoPath });
386
409
  const local = readTemplate(...f.template);
387
410
  if (remote === null) repoFiles.push({ ...f, reason: 'ausente', local });
388
411
  else if (remote !== local) repoFiles.push({ ...f, reason: 'desatualizado', local });
389
412
  }
390
- labelDiff = diffLabels(await createGithubTracker({ token: tk, owner, repo }).listTags(), config?.ai, config?.devAgent);
413
+ const trackerLabels = await requireTracker({ token: tk, owner, repo });
414
+ labelDiff = diffLabels(await trackerLabels.listTags(), config?.ai, config?.devAgent);
391
415
  repoChecked = true;
392
416
  s.stop('Repositório comparado.');
393
417
  } catch (err) {
@@ -407,7 +431,7 @@ export async function update(options = {}) {
407
431
  if (prMode) {
408
432
  const tk = await getToken();
409
433
  try {
410
- base = await scmDe(tk, owner, repo).defaultBranch();
434
+ base = await (await scmDe(tk, owner, repo)).defaultBranch();
411
435
  if (branch === base) {
412
436
  p.log.error(
413
437
  `--branch "${branch}" é a própria branch default do repositório; ` +
@@ -416,8 +440,8 @@ export async function update(options = {}) {
416
440
  p.cancel('Update cancelado.');
417
441
  return;
418
442
  }
419
- remoteConfigRaw = await scmDe(tk, owner, repo).readFile({ path: CONFIG_FILE, ref: base });
420
- const status = await scmDe(tk, owner, repo).compare({ base: base, head: branch });
443
+ remoteConfigRaw = await (await scmDe(tk, owner, repo)).readFile({ path: CONFIG_FILE, ref: base });
444
+ const status = await (await scmDe(tk, owner, repo)).compare({ base: base, head: branch });
421
445
  branchExists = status !== null;
422
446
  if (status === 'behind' || status === 'identical') {
423
447
  // Não fazemos force-push: só avisamos. Empilhar um commit numa branch já
@@ -467,8 +491,12 @@ export async function update(options = {}) {
467
491
  for (const { job, targets } of skillCandidates) {
468
492
  // Em paralelo: o destino do Codex são 20+ arquivos, e um GET por vez
469
493
  // transformaria a checagem na parte mais lenta do comando.
494
+ // A porta é resolvida UMA vez, fora do `map`: dentro dele cada `await`
495
+ // seria uma leitura de config por arquivo — 20+ no destino do Codex —, e
496
+ // o arrow teria de virar assíncrono só para isso.
497
+ const scmAlvo = await scmDe(tk, owner, repo);
470
498
  const remotes = await Promise.all(
471
- targets.map(t => scmDe(tk, owner, repo).readFile({ path: t.relPath, ref: base }))
499
+ targets.map(t => scmAlvo.readFile({ path: t.relPath, ref: base }))
472
500
  );
473
501
  targets.forEach((t, i) => {
474
502
  const remote = remotes[i];
@@ -732,7 +760,7 @@ export async function update(options = {}) {
732
760
  s.start(`Enviando ${treeFiles.length} arquivo(s) em um único commit para "${branch}"...`);
733
761
  let commitOk = false;
734
762
  try {
735
- const res = await scmDe(tk, owner, repo).writeFiles({
763
+ const res = await (await scmDe(tk, owner, repo)).writeFiles({
736
764
  branch,
737
765
  base,
738
766
  files: treeFiles.map(f => ({ path: f.path, content: f.content })),
@@ -752,7 +780,7 @@ export async function update(options = {}) {
752
780
  // write" pode não ter "Pull requests: write" — permissão NOVA neste modo.
753
781
  if (commitOk) {
754
782
  try {
755
- const { pr } = await scmDe(tk, owner, repo).ensurePullRequest({
783
+ const { pr } = await (await scmDe(tk, owner, repo)).ensurePullRequest({
756
784
  branch,
757
785
  base,
758
786
  title: composePrTitle({ version: CLI_VERSION }),
@@ -791,7 +819,7 @@ export async function update(options = {}) {
791
819
  const tk = await getToken();
792
820
  for (const f of repoFiles) {
793
821
  try {
794
- await scmDe(tk, owner, repo).installAutomation({ files: [{ path: f.repoPath, content: f.local, message: `chore: update ${path.basename(f.repoPath)} [spec-wave]` }] });
822
+ await (await scmDe(tk, owner, repo)).installAutomation({ files: [{ path: f.repoPath, content: f.local, message: `chore: update ${path.basename(f.repoPath)} [spec-wave]` }] });
795
823
  p.log.success(`Arquivo atualizado no repo: ${f.repoPath}`);
796
824
  } catch (err) {
797
825
  p.log.error(`Falha ao atualizar ${f.repoPath}: ${err.message}`);
@@ -1,5 +1,4 @@
1
1
  import { resolveToken } from '../api/auth.mjs';
2
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
3
2
  import { slugify } from '../lib/slugify.mjs';
4
3
  import {
5
4
  CONFIG_FILE, LABEL_CRITIQUE_FAILED, LABEL_NEEDS_HUMAN, LABEL_BUG, LABEL_BUG_APPROVED,
@@ -15,7 +14,7 @@ import { docBlobUrl } from '../lib/repo-links.mjs';
15
14
  import { loadArtifact } from '../lib/doc-source.mjs';
16
15
  import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
17
16
  import { isAwaitingMerge } from '../lib/doc-source.mjs';
18
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
17
+ import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
19
18
  import { dependencySection } from '../lib/spec-audit.mjs';
20
19
 
21
20
  /**
@@ -175,8 +174,8 @@ export async function validate({ issueNumber, deps = {} }) {
175
174
  }
176
175
 
177
176
  const n = parseInt(issueNumber, 10);
178
- const tracker = deps.tracker ?? createGithubTracker({ token, owner, repo });
179
- const scm = deps.scm ?? createGithubScm({ link: githubLink({ owner, repo }), token });
177
+ const tracker = await requireTracker({ token, owner, repo, deps });
178
+ const scm = await requireScm({ link: resolveScmLink({ owner, repo }), token, deps });
180
179
  const issue = await tracker.getWorkItem({ ref: { key: String(n) } });
181
180
 
182
181
  // Branch base para a leitura em camadas. Best-effort: sem ela o resolvedor cai
@@ -6,7 +6,6 @@
6
6
  import * as p from '@clack/prompts';
7
7
  import chalk from 'chalk';
8
8
  import { resolveToken } from '../api/auth.mjs';
9
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
10
9
  import { detectIssueType } from '../lib/issue-type.mjs';
11
10
  import { resolveHubContext } from '../lib/project-root.mjs';
12
11
  import { cachedSubIssues } from '../lib/story-graph.mjs';
@@ -17,6 +16,7 @@ import {
17
16
  writeWorkspaceManifest, WORKSPACE_OVERRIDE_FILE,
18
17
  } from '../lib/workspace.mjs';
19
18
  import { CONFIG_FILE } from '../config.mjs';
19
+ import { requireTracker } from '../ports/index.mjs';
20
20
 
21
21
  export async function workspace({ action, issue: issueArg, json = false, dryRun = false, refresh = false, deps = {} } = {}) {
22
22
  if (action !== 'prepare') {
@@ -40,7 +40,7 @@ export async function workspace({ action, issue: issueArg, json = false, dryRun
40
40
 
41
41
  const log = json ? { info() {}, warn: (m) => console.error(m) } : { info: p.log.info, warn: p.log.warn };
42
42
  const token = await resolveToken();
43
- const issue = await (deps.tracker ?? createGithubTracker({ token, owner, repo }))
43
+ const issue = await (await requireTracker({ token, owner, repo, deps }))
44
44
  .getWorkItem({ ref: { key: String(issueNumber) } });
45
45
  const type = detectIssueType(issue);
46
46
 
@@ -22,7 +22,7 @@
22
22
  // deixaria no clone um arquivo que o usuário não pediu e que colide no `git pull`
23
23
  // depois do merge — justamente porque o merge pode trazer as edições do revisor.
24
24
 
25
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
25
+ import { requireScm, resolveScmLink } from '../ports/index.mjs';
26
26
  import { resolveBranchName, explainGitWriteError } from './pr-branch.mjs';
27
27
  import {
28
28
  artifactBranch, composeArtifactPrTitle, composeArtifactPrBody, artifactCommitMessage,
@@ -87,8 +87,9 @@ export async function publishArtifact({
87
87
  // `resolvePrToken` entra na CONSTRUÇÃO da porta, não numa chamada: a porta
88
88
  // já sabe que só `ensurePullRequest` usa essa credencial. A política de qual
89
89
  // token abre PR continua visível aqui, que é onde ela sempre esteve.
90
- const porta = scm || createGithubScm({
91
- link: githubLink({ owner, repo }), token, prToken: resolvePrToken(token),
90
+ const porta = await requireScm({
91
+ link: resolveScmLink({ owner, repo }), token, prToken: resolvePrToken(token),
92
+ deps: { scm },
92
93
  });
93
94
 
94
95
  const branch = artifactBranch({ issueNumber, doc });
package/src/lib/board.mjs CHANGED
@@ -15,7 +15,9 @@
15
15
  // é o Todo/In Progress/Done DENTRO dela, e os dois são dimensões separadas.
16
16
 
17
17
  import { CONFIG_FILE, WORK_ITEM_TYPES } from '../config.mjs';
18
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
18
+ // Bloco E, leva 1: `openTracker` delega ao loader, então este arquivo saiu da
19
+ // lista de pendentes da barreira — não constrói mais porta nenhuma.
20
+ import { getTracker } from '../ports/index.mjs';
19
21
  import { loadConfig } from './project-root.mjs';
20
22
  import { invalidateCache } from './net-cache.mjs';
21
23
  import { planStageMove } from './board-policy.mjs';
@@ -93,29 +95,25 @@ export function trackerAvailable({ cwd = process.cwd() } = {}) {
93
95
  * saindo do config, porque os chamadores o usam para achar os documentos.
94
96
  * @returns {{ tracker: object|null, root: string|null, error: string|null }}
95
97
  */
96
- export function openTracker({ token, projectToken, owner, repo, cwd = process.cwd(), tracker: injetado = null } = {}) {
97
- const { config, root, error: configError } = loadConfig(cwd);
98
- if (injetado) return { tracker: injetado, root, error: null };
99
- if (configError) return { tracker: null, root, error: configError };
100
- const project = config.project || {};
101
- if (!project.id) {
102
- return { tracker: null, root, error: `Project não configurado em ${CONFIG_FILE}` };
103
- }
104
- // owner/repo caem no config quando o chamador não os tem: `loadProjectConfig`
105
- // nunca precisou deles (o board é endereçado por `project.id`), mas a porta
106
- // também faz REST de issue, que é endereçada por repositório. Quem TEM o par
107
- // resolvido — os comandos, via resolveHubContext — passa o dele e vence.
108
- return {
109
- tracker: createGithubTracker({
110
- token,
111
- projectToken,
112
- owner: owner || config.owner,
113
- repo: repo || config.repo,
114
- project,
115
- }),
116
- root,
117
- error: null,
118
- };
98
+ export async function openTracker({
99
+ token, projectToken, owner, repo, cwd = process.cwd(), tracker: injetado = null,
100
+ } = {}) {
101
+ // ── Bloco E, leva 1: isto DELEGA ao loader e não constrói mais nada ────────
102
+ //
103
+ // Era o único ponto do core que construía tracker a partir do config, e é por
104
+ // isso que foi o primeiro a migrar: dez call sites passam por aqui, e o custo
105
+ // para eles é um `await` — todos já estavam em função assíncrona (medido).
106
+ //
107
+ // **`board: true` é daqui.** `getTracker` não exige o bloco `project`, porque
108
+ // os comandos constroem DUAS portas: uma para trabalho de issue, que num repo
109
+ // de papel `code` funciona sem bloco `project` nenhum, e esta, do BOARD, que
110
+ // sem o bloco não tem o que endereçar. Quem precisa do board é quem pede.
111
+ //
112
+ // owner/repo caem no config quando o chamador não os tem: o board é endereçado
113
+ // por `project.id`, mas a porta também faz REST de issue, que é endereçada por
114
+ // repositório. Quem TEM o par resolvido — os comandos, via `resolveHubContext`
115
+ // — passa o dele e vence. Esse fallback agora vive no `getTracker`.
116
+ return getTracker({ cwd, token, projectToken, owner, repo, board: true, deps: { tracker: injetado } });
119
117
  }
120
118
 
121
119
  /**
@@ -0,0 +1,114 @@
1
+ // Os blocos `tracker`/`scm` do `.spec-wave.json`, normalizados na LEITURA —
2
+ // RFC-006 §3.4, Fase 2 bloco D. Função PURA, zero imports.
3
+ //
4
+ // ── A regra, e o que ela proíbe exatamente ───────────────────────────────────
5
+ //
6
+ // §3.4: "normalizar na leitura, nunca regravar". A leitura que o plano fixou
7
+ // (§3.1) é que a regra proíbe **exigir** a regravação, não regravar: `refresh` e
8
+ // `update` seguem dropando legado, porque quem os roda já pediu para o config ser
9
+ // reescrito. O que a regra impede é o fluxo normal obrigar o usuário a migrar
10
+ // formato para continuar funcionando.
11
+ //
12
+ // Daí este arquivo: um `.spec-wave.json` da era 0.16.4 — sem bloco `tracker`, sem
13
+ // bloco `scm` — é LIDO como se os tivesse. Nada é gravado.
14
+ //
15
+ // ── Por que o `kind` entra por parâmetro ─────────────────────────────────────
16
+ //
17
+ // Seria mais curto escrever `kind: 'github-projects'` aqui. Mas isto é core, e o
18
+ // core não nomeia fornecedor — é o acoplamento que o bloco E0 passou 21 arquivos
19
+ // removendo, e `test/ports-boundary.test.mjs` o vigia. Os defaults vêm de
20
+ // `src/plugins/load.mjs` (`DEFAULT_TRACKER_KIND`/`DEFAULT_SCM_KIND`), que é o
21
+ // único lugar autorizado a saber qual é o fornecedor embutido.
22
+ //
23
+ // O que fica aqui é conhecimento sobre o FORMATO HISTÓRICO do nosso próprio
24
+ // arquivo — que o bloco `project` era a configuração de board e que `owner`/`repo`
25
+ // endereçavam o repositório. Isso é memória da spec-wave, não API de fornecedor.
26
+ //
27
+ // ── Nunca MUTA, e isso é o risco central ────────────────────────────────────
28
+ //
29
+ // Se um bloco derivado vazasse para uma gravação, TODO repositório passaria a
30
+ // acusar divergência no `update`, que faz diff byte a byte contra a cópia remota
31
+ // (`serializeConfig` é byte-exato por esse motivo — RFC §3.4). `updateConfig`
32
+ // relê o arquivo do disco, então o vazamento não pode vir por ali; o que pode
33
+ // vazar é uma mutação no objeto que o chamador ainda tem na mão. Por isso tudo
34
+ // aqui devolve objeto NOVO, e há teste ponta a ponta afirmando que o disco não
35
+ // muda.
36
+
37
+ /**
38
+ * O bloco `tracker`, com o que falta derivado do formato legado (função PURA).
39
+ *
40
+ * **Só preenche o que está AUSENTE.** Um `tracker.kind: "jira"` escrito à mão não
41
+ * ganha `config` derivada do bloco `project`: quem declarou Jira não quer a
42
+ * configuração do board do GitHub por baixo. Derivar sobre o que já está escrito
43
+ * é o oposto de normalizar.
44
+ *
45
+ * @param {object} config o `.spec-wave.json` lido
46
+ * @param {object} [opts]
47
+ * @param {string} [opts.defaultKind] o fornecedor embutido, vindo do loader
48
+ * @returns {{kind: string|null, package: string|undefined, config: object|null,
49
+ * stageMap: object|undefined, fieldMap: object|undefined,
50
+ * typeMap: object|undefined, derived: boolean}}
51
+ */
52
+ export function deriveTrackerBlock(config, { defaultKind = null } = {}) {
53
+ const escrito = config?.tracker || null;
54
+ return {
55
+ kind: escrito?.kind || defaultKind,
56
+ package: escrito?.package,
57
+ // O bloco `project` É a configuração de tracker de um repo da era 0.x: id do
58
+ // Project, número, mapa de campos, e o par legado `etapaFieldId`/`stageOptions`
59
+ // que `plugins/tracker-github-projects/fields.mjs` ainda lê. Passar o bloco
60
+ // INTEIRO é o que mantém o caminho legado vivo sem este arquivo conhecê-lo.
61
+ config: escrito?.config ?? config?.project ?? null,
62
+ // Sem equivalente legado: os mapas nasceram com a Fase 2. Ausentes ficam
63
+ // ausentes — um `{}` diria "mapeado para nada", que não é a mesma coisa.
64
+ stageMap: escrito?.stageMap,
65
+ fieldMap: escrito?.fieldMap,
66
+ typeMap: escrito?.typeMap,
67
+ derived: !escrito?.kind,
68
+ };
69
+ }
70
+
71
+ /**
72
+ * O bloco `scm`, com o que falta derivado de `owner`/`repo` (função PURA).
73
+ *
74
+ * Num repo de papel `code` (RFC-005) não há bloco `project`, mas há `owner`/`repo`
75
+ * — então ele TEM um SCM próprio e nenhum tracker próprio. É por isso que as duas
76
+ * derivações são independentes em vez de uma só: elas não têm a mesma condição de
77
+ * existência, e juntá-las faria um repo de código parecer sem SCM.
78
+ *
79
+ * @param {object} config
80
+ * @param {object} [opts]
81
+ * @param {string} [opts.defaultKind]
82
+ * @returns {{kind: string|null, package: string|undefined,
83
+ * config: object|null, derived: boolean}}
84
+ */
85
+ export function deriveScmBlock(config, { defaultKind = null } = {}) {
86
+ const escrito = config?.scm || null;
87
+ const owner = config?.owner;
88
+ const repo = config?.repo;
89
+ return {
90
+ kind: escrito?.kind || defaultKind,
91
+ package: escrito?.package,
92
+ // `{owner, repo}` é o endereço de repositório da era 0.x. Um par incompleto
93
+ // vira `null` em vez de `{owner: undefined, repo: 'x'}`: meio endereço é
94
+ // pior que nenhum, porque atravessa uma checagem de presença e falha depois.
95
+ config: escrito?.config ?? (owner && repo ? { owner, repo } : null),
96
+ derived: !escrito?.kind,
97
+ };
98
+ }
99
+
100
+ /**
101
+ * Os dois blocos de uma vez (função PURA).
102
+ *
103
+ * @param {object} config
104
+ * @param {object} [opts]
105
+ * @param {string} [opts.trackerKind]
106
+ * @param {string} [opts.scmKind]
107
+ * @returns {{tracker: object, scm: object}}
108
+ */
109
+ export function derivePortBlocks(config, { trackerKind = null, scmKind = null } = {}) {
110
+ return {
111
+ tracker: deriveTrackerBlock(config, { defaultKind: trackerKind }),
112
+ scm: deriveScmBlock(config, { defaultKind: scmKind }),
113
+ };
114
+ }
@@ -922,6 +922,16 @@ export async function runCritique({
922
922
  kind, spec, specs, plan, techContextYaml, decomposition, qaPlan, bugDoc, bugReport,
923
923
  attempt = 1, maxAttempts = DEFAULT_MAX_CRITIQUE_ATTEMPTS,
924
924
  model, labels = [], usage, cwd, decisions = null, standalone = false,
925
+ // Seam de teste, no PONTO DO MODELO e não na função inteira: assim o que roda
926
+ // nos testes é a crítica REAL — construção do prompt, `downgradeUnsupportedFindings`
927
+ // e `renderCritiqueMarkdown` — sobre um modelo falso. Trocar a `runCritique`
928
+ // toda deixaria justamente essa lógica sem exercício, e ela é a que produz o
929
+ // TEXTO que vai para a issue.
930
+ //
931
+ // A crítica é a SEGUNDA chamada de modelo do fluxo, e é fácil esquecer dela:
932
+ // costurar só o `generateDocument` deixava `generate-bug` levando 25 s de rede
933
+ // dentro da suíte, pagando um modelo de verdade.
934
+ gerarEstruturado = generateStructured,
925
935
  } = {}) {
926
936
  const sections = [];
927
937
  if (spec) sections.push(`## spec.md\n\n${spec}`);
@@ -961,7 +971,7 @@ export async function runCritique({
961
971
  if (decisoesBloco) sections.push(decisoesBloco);
962
972
  const userContent = sections.join('\n\n') || '(nenhum documento fornecido)';
963
973
 
964
- const report = await generateStructured(buildSystemPrompt(kind, cwd), userContent, {
974
+ const report = await gerarEstruturado(buildSystemPrompt(kind, cwd), userContent, {
965
975
  action: 'critique',
966
976
  temperature: 0,
967
977
  schema: {
@@ -20,7 +20,7 @@
20
20
  import { existsSync, readFileSync } from 'node:fs';
21
21
  import path from 'node:path';
22
22
 
23
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
23
+ import { getScm, resolveScmLink } from '../ports/index.mjs';
24
24
  import { artifactBranch } from './artifact-pr.mjs';
25
25
 
26
26
  /**
@@ -93,7 +93,21 @@ export async function loadArtifact({
93
93
  if (!token || !owner || !repo) {
94
94
  return { content: null, state: 'unknown', ref: null, pr: null };
95
95
  }
96
- const porta = scm || createGithubScm({ link: githubLink({ owner, repo }), token });
96
+ // `getScm` e não `requireScm`: esta função diz "I/O — NUNCA lança", e a
97
+ // construção da porta está FORA do `try` abaixo. Um plugin que não carrega tem
98
+ // de virar `state: 'unknown'` — "não consegui olhar" não é "não existe", e
99
+ // devolver `missing` faria o chamador REGERAR por cima de um documento que
100
+ // existe, pagando uma geração de IA para sobrescrever trabalho. É a mesma razão
101
+ // do caso sem token, três linhas acima.
102
+ //
103
+ // ⚠️ O ramo `erroPorta` é INALCANÇÁVEL HOJE, e está aqui de propósito:
104
+ // `resolveScmLink` ainda crava o fornecedor embutido (ver a nota nela), então o
105
+ // loader não tem como recusar. Ele passa a ser alcançável quando ela deixar de
106
+ // cravar — bloco F mais os call sites de E. Não é prosa prometendo garantia:
107
+ // é a guarda que impede a migração de quebrar um contrato ESCRITO no dia em que
108
+ // a porta puder falhar. Usar `requireScm` aqui seria plantar a violação.
109
+ const { scm: porta, error: erroPorta } = await getScm({ link: resolveScmLink({ owner, repo }), token, deps: { scm } });
110
+ if (erroPorta) return { content: null, state: 'unknown', ref: null, pr: null };
97
111
 
98
112
  let naBase;
99
113
  try {