@spec-wave/cli 1.4.0 → 1.6.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/protocol/scm.v1.json +165 -0
  3. package/protocol/tracker.v1.json +175 -0
  4. package/src/api/github-rest.mjs +124 -2
  5. package/src/commands/audit.mjs +3 -5
  6. package/src/commands/code-review.mjs +10 -6
  7. package/src/commands/decompose.mjs +7 -6
  8. package/src/commands/doctor.mjs +389 -220
  9. package/src/commands/generate-bug.mjs +2 -2
  10. package/src/commands/generate-plan.mjs +5 -7
  11. package/src/commands/generate-qa-plan.mjs +3 -5
  12. package/src/commands/generate-spec.mjs +2 -2
  13. package/src/commands/implement.mjs +33 -21
  14. package/src/commands/init.mjs +36 -7
  15. package/src/commands/issue.mjs +6 -2
  16. package/src/commands/merge.mjs +20 -15
  17. package/src/commands/mode.mjs +18 -11
  18. package/src/commands/move.mjs +3 -3
  19. package/src/commands/order.mjs +3 -3
  20. package/src/commands/preflight.mjs +10 -6
  21. package/src/commands/qa-lead.mjs +6 -8
  22. package/src/commands/qa-run.mjs +39 -27
  23. package/src/commands/qa.mjs +10 -7
  24. package/src/commands/refresh.mjs +6 -3
  25. package/src/commands/repair-stage.mjs +1 -1
  26. package/src/commands/repo.mjs +6 -7
  27. package/src/commands/run.mjs +7 -5
  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 -6
  32. package/src/commands/update.mjs +47 -20
  33. package/src/commands/validate.mjs +3 -5
  34. package/src/commands/workspace.mjs +2 -2
  35. package/src/lib/artifact-publish.mjs +3 -3
  36. package/src/lib/board.mjs +22 -24
  37. package/src/lib/config-ports.mjs +114 -0
  38. package/src/lib/doc-source.mjs +16 -3
  39. package/src/lib/doctor-capabilities.mjs +168 -0
  40. package/src/lib/implement-board.mjs +1 -1
  41. package/src/lib/pr-ready.mjs +23 -11
  42. package/src/lib/story-graph.mjs +19 -6
  43. package/src/lib/tag-registry.mjs +58 -0
  44. package/src/lib/usage-report.mjs +15 -2
  45. package/src/plugin/.claude-plugin/plugin.json +1 -1
  46. package/src/plugins/load.mjs +427 -0
  47. package/src/plugins/scm-github/index.mjs +92 -6
  48. package/src/plugins/tracker-github-projects/index.mjs +52 -10
  49. package/src/ports/capabilities.mjs +47 -0
  50. package/src/ports/index.mjs +201 -46
  51. package/src/ports/scm.mjs +71 -3
  52. package/src/ports/tracker.mjs +43 -2
  53. package/src/ports/types.mjs +30 -6
  54. package/src/setup/files.mjs +2 -3
  55. package/src/setup/labels.mjs +2 -2
  56. package/src/setup/project.mjs +2 -2
  57. package/src/ui/wizard.mjs +76 -1
@@ -5,9 +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 } from '../plugins/scm-github/index.mjs';
10
- import { resolveScmLink } from '../ports/index.mjs';
8
+ import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
11
9
  import {
12
10
  resolveBranchName, composePrTitle, composePrBody, buildCommitMessage,
13
11
  decideConfigInPr, decideSkillInPr, composeConfigCleanupHint, explainGitWriteError,
@@ -25,6 +23,7 @@ import { findConfigPath } from '../lib/project-root.mjs';
25
23
  import { configuredRole } from '../lib/repo-role.mjs';
26
24
  import { currentGitBranch } from '../lib/repo-links.mjs';
27
25
  import { cliRef } from '../lib/cli-ref.mjs';
26
+ import { tagRegistryPlan } from '../lib/tag-registry.mjs';
28
27
 
29
28
  // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
30
29
  const REPO_FILES = [
@@ -201,9 +200,10 @@ async function buildConfigContent(token, config) {
201
200
  }
202
201
  // `provision: false` é leitura do schema vivo — a mesma operação que o
203
202
  // `refresh --config` usa para regravar os ids do board.
204
- const { config: vivo } = await createGithubTracker({
205
- token, owner: config.owner, repo: config.repo, project: config.project,
206
- }).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 });
207
207
  if (!vivo) return { content: null, error: 'Project não encontrado' };
208
208
  const snapshot = {
209
209
  id: vivo.projectId, number: vivo.projectNumber,
@@ -248,11 +248,22 @@ async function buildConfigContent(token, config) {
248
248
  * só o que REALMENTE passou — é o que o corpo do PR vai afirmar a quem
249
249
  * revisa, e ele não pode prometer o que falhou.
250
250
  */
251
- /** Porta de SCM do repositório-alvo. Memoizada por token: `tk` é lazy. */
252
- const scmDe = (tk, owner, repo) => createGithubScm({ link: resolveScmLink({ 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 });
253
264
 
254
265
  async function applyLabels(token, owner, repo, labelDiff, forceLabels = false) {
255
- const tracker = createGithubTracker({ token, owner, repo });
266
+ const tracker = await requireTracker({ token, owner, repo });
256
267
  const done = { created: [], updated: [], removed: [] };
257
268
  for (const label of labelDiff.missing) {
258
269
  try {
@@ -272,11 +283,22 @@ async function applyLabels(token, owner, repo, labelDiff, forceLabels = false) {
272
283
  p.log.error(`Falha ao atualizar label ${label.name}: ${err.message}`);
273
284
  }
274
285
  }
275
- 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 : []) {
276
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.
277
299
  const inUse = forceLabels
278
300
  ? 0
279
- : await tracker.countOpenWithTag({ tag: label.name }).catch(() => null);
301
+ : (registro.canCount ? await tracker.countOpenWithTag({ tag: label.name }).catch(() => null) : null);
280
302
  const decision = shouldDeleteOrphanLabel({ inUse, forceLabels });
281
303
  if (!decision.ok) {
282
304
  p.log.warn(`Label ${label.name}: ${decision.motivo}. Use --force-labels para remover mesmo assim.`);
@@ -383,12 +405,13 @@ export async function update(options = {}) {
383
405
  } else {
384
406
  try {
385
407
  for (const f of repoFilesFor(role)) {
386
- const remote = await scmDe(tk, owner, repo).readFile({ path: f.repoPath });
408
+ const remote = await (await scmDe(tk, owner, repo)).readFile({ path: f.repoPath });
387
409
  const local = readTemplate(...f.template);
388
410
  if (remote === null) repoFiles.push({ ...f, reason: 'ausente', local });
389
411
  else if (remote !== local) repoFiles.push({ ...f, reason: 'desatualizado', local });
390
412
  }
391
- 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);
392
415
  repoChecked = true;
393
416
  s.stop('Repositório comparado.');
394
417
  } catch (err) {
@@ -408,7 +431,7 @@ export async function update(options = {}) {
408
431
  if (prMode) {
409
432
  const tk = await getToken();
410
433
  try {
411
- base = await scmDe(tk, owner, repo).defaultBranch();
434
+ base = await (await scmDe(tk, owner, repo)).defaultBranch();
412
435
  if (branch === base) {
413
436
  p.log.error(
414
437
  `--branch "${branch}" é a própria branch default do repositório; ` +
@@ -417,8 +440,8 @@ export async function update(options = {}) {
417
440
  p.cancel('Update cancelado.');
418
441
  return;
419
442
  }
420
- remoteConfigRaw = await scmDe(tk, owner, repo).readFile({ path: CONFIG_FILE, ref: base });
421
- 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 });
422
445
  branchExists = status !== null;
423
446
  if (status === 'behind' || status === 'identical') {
424
447
  // Não fazemos force-push: só avisamos. Empilhar um commit numa branch já
@@ -468,8 +491,12 @@ export async function update(options = {}) {
468
491
  for (const { job, targets } of skillCandidates) {
469
492
  // Em paralelo: o destino do Codex são 20+ arquivos, e um GET por vez
470
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);
471
498
  const remotes = await Promise.all(
472
- targets.map(t => scmDe(tk, owner, repo).readFile({ path: t.relPath, ref: base }))
499
+ targets.map(t => scmAlvo.readFile({ path: t.relPath, ref: base }))
473
500
  );
474
501
  targets.forEach((t, i) => {
475
502
  const remote = remotes[i];
@@ -733,7 +760,7 @@ export async function update(options = {}) {
733
760
  s.start(`Enviando ${treeFiles.length} arquivo(s) em um único commit para "${branch}"...`);
734
761
  let commitOk = false;
735
762
  try {
736
- const res = await scmDe(tk, owner, repo).writeFiles({
763
+ const res = await (await scmDe(tk, owner, repo)).writeFiles({
737
764
  branch,
738
765
  base,
739
766
  files: treeFiles.map(f => ({ path: f.path, content: f.content })),
@@ -753,7 +780,7 @@ export async function update(options = {}) {
753
780
  // write" pode não ter "Pull requests: write" — permissão NOVA neste modo.
754
781
  if (commitOk) {
755
782
  try {
756
- const { pr } = await scmDe(tk, owner, repo).ensurePullRequest({
783
+ const { pr } = await (await scmDe(tk, owner, repo)).ensurePullRequest({
757
784
  branch,
758
785
  base,
759
786
  title: composePrTitle({ version: CLI_VERSION }),
@@ -792,7 +819,7 @@ export async function update(options = {}) {
792
819
  const tk = await getToken();
793
820
  for (const f of repoFiles) {
794
821
  try {
795
- 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]` }] });
796
823
  p.log.success(`Arquivo atualizado no repo: ${f.repoPath}`);
797
824
  } catch (err) {
798
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,8 +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 } from '../plugins/scm-github/index.mjs';
19
- import { resolveScmLink } from '../ports/index.mjs';
17
+ import { requireScm, requireTracker, resolveScmLink } from '../ports/index.mjs';
20
18
  import { dependencySection } from '../lib/spec-audit.mjs';
21
19
 
22
20
  /**
@@ -176,8 +174,8 @@ export async function validate({ issueNumber, deps = {} }) {
176
174
  }
177
175
 
178
176
  const n = parseInt(issueNumber, 10);
179
- const tracker = deps.tracker ?? createGithubTracker({ token, owner, repo });
180
- const scm = deps.scm ?? createGithubScm({ link: resolveScmLink({ owner, repo }), token });
177
+ const tracker = await requireTracker({ token, owner, repo, deps });
178
+ const scm = await requireScm({ link: resolveScmLink({ owner, repo }), token, deps });
181
179
  const issue = await tracker.getWorkItem({ ref: { key: String(n) } });
182
180
 
183
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,8 +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 } from '../plugins/scm-github/index.mjs';
26
- import { resolveScmLink } from '../ports/index.mjs';
25
+ import { requireScm, resolveScmLink } from '../ports/index.mjs';
27
26
  import { resolveBranchName, explainGitWriteError } from './pr-branch.mjs';
28
27
  import {
29
28
  artifactBranch, composeArtifactPrTitle, composeArtifactPrBody, artifactCommitMessage,
@@ -88,8 +87,9 @@ export async function publishArtifact({
88
87
  // `resolvePrToken` entra na CONSTRUÇÃO da porta, não numa chamada: a porta
89
88
  // já sabe que só `ensurePullRequest` usa essa credencial. A política de qual
90
89
  // token abre PR continua visível aqui, que é onde ela sempre esteve.
91
- const porta = scm || createGithubScm({
90
+ const porta = await requireScm({
92
91
  link: resolveScmLink({ owner, repo }), token, prToken: resolvePrToken(token),
92
+ deps: { scm },
93
93
  });
94
94
 
95
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
+ }
@@ -20,8 +20,7 @@
20
20
  import { existsSync, readFileSync } from 'node:fs';
21
21
  import path from 'node:path';
22
22
 
23
- import { createGithubScm } from '../plugins/scm-github/index.mjs';
24
- import { resolveScmLink } from '../ports/index.mjs';
23
+ import { getScm, resolveScmLink } from '../ports/index.mjs';
25
24
  import { artifactBranch } from './artifact-pr.mjs';
26
25
 
27
26
  /**
@@ -94,7 +93,21 @@ export async function loadArtifact({
94
93
  if (!token || !owner || !repo) {
95
94
  return { content: null, state: 'unknown', ref: null, pr: null };
96
95
  }
97
- const porta = scm || createGithubScm({ link: resolveScmLink({ 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 };
98
111
 
99
112
  let naBase;
100
113
  try {
@@ -0,0 +1,168 @@
1
+ // Quais checks do `doctor` fazem sentido para ESTE fornecedor — RFC-006 §7.4/§7.5,
2
+ // Fase 2 bloco G. Função PURA, zero imports.
3
+ //
4
+ // ── O problema que isto resolve ──────────────────────────────────────────────
5
+ //
6
+ // O `doctor` tem 15 checks, e vários diagnosticam coisas que só existem no GitHub:
7
+ // variável de repositório, permissão de workflow, proteção de branch, Projects v2
8
+ // de organização. Num tracker que não tem essas coisas — e a Fase 2 existe para que
9
+ // haja um — esses checks não podem sair como FALHA: o fornecedor está correto, é o
10
+ // diagnóstico que não se aplica.
11
+ //
12
+ // Mas também não podem sair como OK. "Está tudo bem" e "não olhei" com a mesma cara
13
+ // é a degradação que esta base persegue há sete blocos, e num comando de diagnóstico
14
+ // é pior: o `doctor` existe para o usuário confiar no que ele diz. Daí o status
15
+ // `skip`, com símbolo próprio e o MOTIVO no detalhe.
16
+ //
17
+ // ── Por que capability, e não `kind` ────────────────────────────────────────
18
+ //
19
+ // `if (kind === 'github')` no meio de um check recria por dentro o acoplamento que
20
+ // a Fase 1 desmontou — e `test/ports-boundary.test.mjs` reprova o padrão. O que
21
+ // decide é a capability declarada: `variables === 'repo'`, `automation !== 'none'`,
22
+ // `boardProvisioning === 'create'`. Um fornecedor novo não precisa ser conhecido
23
+ // aqui; precisa declarar o que faz.
24
+ //
25
+ // ── O que este arquivo NÃO resolve ──────────────────────────────────────────
26
+ //
27
+ // `doctor.mjs` segue com 14 chamadas de Octokit CRU (secrets do Actions, membership
28
+ // de org, permissões de workflow, proteção de branch) e por isso continua na
29
+ // allowlist da barreira. O gating impede que elas sejam apresentadas como falha de
30
+ // um fornecedor que não as tem; ele NÃO as remove. O lugar delas é o `verify()` de
31
+ // cada plugin, que já está no contrato — e é isso que tira a entrada da allowlist.
32
+ // Fica para a leva 2 do bloco G, porque mover diagnóstico de 1728 linhas é trabalho
33
+ // próprio, e o risco §6.1 do plano é justamente apressar isso e acabar
34
+ // acrescentando 14 operações GitHub-only ao contrato.
35
+
36
+ /**
37
+ * Requisito de capability de um check, na forma `<porta>.<caminho><op><valor>`.
38
+ *
39
+ * Escrito como STRING e não como função para que a tabela seja legível de uma vez:
40
+ * o que interessa a quem lê o `doctor` é quais checks dependem de quê, e uma tabela
41
+ * de closures esconde isso.
42
+ *
43
+ * @typedef {string} Requisito
44
+ */
45
+
46
+ /** Operadores aceitos, do mais específico para o menos. */
47
+ const OPERADORES = [
48
+ ['!==', (a, b) => a !== b],
49
+ ['===', (a, b) => a === b],
50
+ ];
51
+
52
+ /**
53
+ * Lê um caminho pontilhado (`pullRequests.draft`) num objeto (função PURA).
54
+ */
55
+ function valorEm(obj, caminho) {
56
+ return caminho.split('.').reduce((atual, chave) => (atual == null ? undefined : atual[chave]), obj);
57
+ }
58
+
59
+ /**
60
+ * O requisito está satisfeito? (função PURA)
61
+ *
62
+ * @param {Requisito} requisito ex.: `scm.variables === 'repo'`
63
+ * @param {{tracker?: object, scm?: object}} capabilities as declaradas por porta
64
+ * @returns {{ok: boolean, motivo: string|null}} `motivo` preenchido quando NÃO ok
65
+ */
66
+ export function avaliarRequisito(requisito, capabilities = {}) {
67
+ const texto = String(requisito).trim();
68
+ const op = OPERADORES.find(([sinal]) => texto.includes(sinal));
69
+ if (!op) return { ok: false, motivo: `requisito sem operador reconhecido: "${texto}"` };
70
+
71
+ const [sinal, compara] = op;
72
+ const [esquerda, direita] = texto.split(sinal).map(x => x.trim());
73
+ const [porta, ...resto] = esquerda.split('.');
74
+ const caminho = resto.join('.');
75
+ if (!porta || !caminho) {
76
+ return { ok: false, motivo: `requisito sem porta e caminho: "${texto}"` };
77
+ }
78
+
79
+ const declaradas = capabilities[porta];
80
+ // Porta ausente é diferente de capability ausente: significa que nem deu para
81
+ // construir a porta (plugin faltando, config incompleta). O check é pulado, e o
82
+ // motivo diz QUAL das duas coisas aconteceu — senão o usuário procura no lugar
83
+ // errado.
84
+ if (!declaradas) {
85
+ return { ok: false, motivo: `a porta de ${porta} não pôde ser consultada` };
86
+ }
87
+
88
+ const esperado = direita.replace(/^['"]|['"]$/g, '');
89
+ const atual = valorEm(declaradas, caminho);
90
+ // `true`/`false` chegam como palavra na string do requisito.
91
+ const alvo = esperado === 'true' ? true : esperado === 'false' ? false : esperado;
92
+ if (compara(atual, alvo)) return { ok: true, motivo: null };
93
+
94
+ return {
95
+ ok: false,
96
+ motivo: `este fornecedor declara \`${caminho}\` = ${JSON.stringify(atual)}, `
97
+ + `e o check vale para ${sinal === '===' ? '' : 'qualquer valor exceto '}${JSON.stringify(alvo)}`,
98
+ };
99
+ }
100
+
101
+ /**
102
+ * O check deve rodar? (função PURA)
103
+ *
104
+ * Um check SEM `requires` roda sempre — é o caso da maioria, que diagnostica coisa
105
+ * local (arquivos, config, IA) e não depende de fornecedor.
106
+ *
107
+ * Com vários requisitos, TODOS têm de valer: um check que precisa de variável de
108
+ * repositório E de automação não diz nada útil com metade.
109
+ *
110
+ * @param {{name?: string, requires?: Requisito[]}} check
111
+ * @param {{tracker?: object, scm?: object}} capabilities
112
+ * @returns {{roda: boolean, motivo: string|null}}
113
+ */
114
+ export function decidirCheck(check, capabilities = {}) {
115
+ const requisitos = check?.requires;
116
+ if (!Array.isArray(requisitos) || requisitos.length === 0) {
117
+ return { roda: true, motivo: null };
118
+ }
119
+ for (const requisito of requisitos) {
120
+ const { ok, motivo } = avaliarRequisito(requisito, capabilities);
121
+ if (!ok) return { roda: false, motivo };
122
+ }
123
+ return { roda: true, motivo: null };
124
+ }
125
+
126
+ /**
127
+ * Roda a lista de checks respeitando o `requires` de cada um.
128
+ *
129
+ * Extraída de `doctor()` porque lá ela é INTESTÁVEL: o comando tem 1728 linhas, 15
130
+ * checks e rede em quase todos. A mutação do bloco G mostrou o custo disso — tirar o
131
+ * motivo do check pulado, e mesmo IGNORAR o gating por inteiro, sobrevivia à suíte.
132
+ *
133
+ * Nunca lança: cada check é best-effort, e um que estoure vira "não verificável".
134
+ * Derrubar o `doctor` por causa de um check é o contrário do que ele existe para
135
+ * fazer — diagnosticar ambiente quebrado.
136
+ *
137
+ * @param {Array<Function & {requires?: string[]}>} checks
138
+ * @param {object} ctx contexto compartilhado dos checks
139
+ * @param {{tracker?: object, scm?: object}} capabilities
140
+ * @returns {Promise<Array<{name: string, status: string, detail?: string}>>}
141
+ */
142
+ export async function rodarChecks(checks, ctx, capabilities = {}) {
143
+ const resultados = [];
144
+ for (const check of checks || []) {
145
+ const nome = String(check?.name || 'check').replace(/^check/, '');
146
+ const { roda, motivo } = decidirCheck(check, capabilities);
147
+ if (!roda) {
148
+ // O MOTIVO vai no detalhe, e é ele que separa "este fornecedor não faz isso"
149
+ // de "não consegui olhar". Sem ele, `○` é um símbolo sem informação.
150
+ resultados.push({
151
+ name: nome,
152
+ status: 'skip',
153
+ detail: `Não se aplica a este fornecedor: ${motivo}`,
154
+ });
155
+ continue;
156
+ }
157
+ try {
158
+ resultados.push(await check(ctx));
159
+ } catch (err) {
160
+ resultados.push({
161
+ name: nome,
162
+ status: 'warn',
163
+ detail: `Check falhou inesperadamente: ${err.message}`,
164
+ });
165
+ }
166
+ }
167
+ return resultados;
168
+ }
@@ -111,7 +111,7 @@ export async function applyBoardMoves({
111
111
  try {
112
112
  // PROJECT_TOKEN é a credencial do board — ver a tabela em
113
113
  // src/plugins/tracker-github-projects/index.mjs.
114
- const { tracker, error } = openTracker({
114
+ const { tracker, error } = await openTracker({
115
115
  token, projectToken: process.env.PROJECT_TOKEN || token, cwd,
116
116
  tracker: trackerInjetado,
117
117
  });