@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
@@ -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
+ }
@@ -96,6 +96,10 @@ export function planBoardMoves(phase, {
96
96
  */
97
97
  export async function applyBoardMoves({
98
98
  token, moves, cwd = process.cwd(), log = p.log, dryRun = false,
99
+ // Passthrough de porta, como `loadBoardSnapshot` e `cachedSubIssues`. Sem
100
+ // ele o `implement` não tem teste de caminho fora do dry-run: cada movimento
101
+ // construía a porta real, e a falha era engolida pelo `try` abaixo.
102
+ tracker: trackerInjetado = null,
99
103
  }) {
100
104
  if (!moves || moves.length === 0) return;
101
105
  if (dryRun) {
@@ -107,8 +111,9 @@ export async function applyBoardMoves({
107
111
  try {
108
112
  // PROJECT_TOKEN é a credencial do board — ver a tabela em
109
113
  // src/plugins/tracker-github-projects/index.mjs.
110
- const { tracker, error } = openTracker({
114
+ const { tracker, error } = await openTracker({
111
115
  token, projectToken: process.env.PROJECT_TOKEN || token, cwd,
116
+ tracker: trackerInjetado,
112
117
  });
113
118
  if (error) {
114
119
  log.warn(`board: ${error} — Etapas não atualizadas.`);
@@ -0,0 +1,87 @@
1
+ // Stream do agente interno do `implement`, por story (RFC-008 fase 3, P24).
2
+ //
3
+ // Sob o spec-wave-agent, cada story roda um agente interno (o comando do
4
+ // specKit) dentro de uma chamada Bash do orquestrador — e a saída dele só
5
+ // aparecia no fim, quando o Bash devolvia. Para a tela Development do
6
+ // spec-wave mostrar cada story AO VIVO, o agente define SPEC_WAVE_STREAM_DIR:
7
+ // o `implement` passa a gravar a saída do agente interno, linha a linha, em
8
+ // `<dir>/story-<n>.jsonl`, e o agente acompanha o arquivo e retransmite.
9
+ //
10
+ // Duas decisões:
11
+ // - Para o stdout (que vira o resultado do Bash do orquestrador) vai só o
12
+ // RESUMO — o texto final do agente interno —, não o stream-json inteiro:
13
+ // milhares de linhas de JSON encheriam o contexto do orquestrador à toa.
14
+ // - Se o comando é o Claude Code e não pede formato de saída, o `implement`
15
+ // acrescenta `--output-format stream-json --verbose` (o texto puro do
16
+ // `claude -p` só sai no fim). Outros agentes (opencode, codex…) rodam como
17
+ // estão: o que não for JSON vai para o arquivo e é ecoado igual a antes.
18
+ //
19
+ // Sem SPEC_WAVE_STREAM_DIR, nada muda: o comando roda com stdio herdado.
20
+
21
+ import { spawn } from 'node:child_process';
22
+ import { appendFileSync, mkdirSync } from 'node:fs';
23
+ import path from 'node:path';
24
+ import { createInterface } from 'node:readline';
25
+
26
+ export const STREAM_DIR_ENV = 'SPEC_WAVE_STREAM_DIR';
27
+
28
+ // Acrescenta o formato stream-json ao Claude Code quando o comando não escolhe
29
+ // formato. Só para `claude`: as flags não existem nos outros agentes.
30
+ // Comando composto (pipe, `;`, `&&`, redirecionamento) fica como está: as
31
+ // flags iriam para o fim da linha — o último comando da cadeia, não o claude.
32
+ export function withStreamJson(command) {
33
+ if (!/^\s*claude(\s|$)/.test(command)) return command;
34
+ if (/--output-format\b/.test(command)) return command;
35
+ const unquoted = command.replace(/"(?:\\.|[^"\\])*"|'[^']*'/g, '');
36
+ if (/[|;&<>\n`]|\$\(/.test(unquoted)) return command;
37
+ return `${command} --output-format stream-json --verbose`;
38
+ }
39
+
40
+ // O que ecoar no stdout para uma linha de saída do agente interno. null =
41
+ // nada (evento de stream que só interessa à tela ao vivo).
42
+ export function summaryOfLine(line) {
43
+ let event;
44
+ try {
45
+ event = JSON.parse(line);
46
+ } catch {
47
+ return line; // não é JSON: agente que não fala stream-json — ecoa igual
48
+ }
49
+ if (!event || typeof event !== 'object' || typeof event.type !== 'string') return line;
50
+ if (event.type !== 'result') return null;
51
+ if (event.is_error) {
52
+ return `✖ agente interno terminou com erro${event.subtype ? ` (${event.subtype})` : ''}` +
53
+ (typeof event.result === 'string' && event.result ? `: ${event.result}` : '');
54
+ }
55
+ return typeof event.result === 'string' && event.result ? event.result : '✔ agente interno concluído';
56
+ }
57
+
58
+ export function streamFileFor(dir, issueNumber) {
59
+ return path.join(dir, `story-${issueNumber}.jsonl`);
60
+ }
61
+
62
+ // Roda o comando (via shell, como o execSync de sempre) gravando cada linha do
63
+ // stdout em `streamFile` e ecoando o resumo. stdin e stderr continuam herdados.
64
+ // Resolve com o exit code (1 quando morto por sinal).
65
+ export function runStreamed(command, { streamFile, cwd, write = (s) => process.stdout.write(s) }) {
66
+ mkdirSync(path.dirname(streamFile), { recursive: true });
67
+ return new Promise((resolve, reject) => {
68
+ const child = spawn(command, { shell: true, cwd, stdio: ['inherit', 'pipe', 'inherit'] });
69
+ const lines = createInterface({ input: child.stdout });
70
+ lines.on('line', (line) => {
71
+ // Arquivo primeiro: é a fonte da tela ao vivo. Falha de disco não pode
72
+ // derrubar a implementação — só deixa a tela sem essa linha.
73
+ try {
74
+ appendFileSync(streamFile, `${line}\n`);
75
+ } catch {
76
+ /* melhor esforço */
77
+ }
78
+ const summary = summaryOfLine(line);
79
+ if (summary !== null) write(`${summary}\n`);
80
+ });
81
+ child.on('error', reject);
82
+ child.on('close', (code, signal) => {
83
+ lines.close();
84
+ resolve(code ?? (signal ? 1 : 0));
85
+ });
86
+ });
87
+ }
@@ -17,7 +17,7 @@
17
17
  // implementação, que a essa altura já está commitada.
18
18
 
19
19
  import * as p from '@clack/prompts';
20
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
20
+ import { requireScm, resolveScmLink } from '../ports/index.mjs';
21
21
  import { extractIssueRefs, hubIssueNumbers } from './pr-link.mjs';
22
22
 
23
23
  /**
@@ -83,13 +83,19 @@ export async function collectFeaturePullRequests({
83
83
  const hub = { owner, repo };
84
84
  // Uma porta POR REPOSITÓRIO — é o que o contrato manda, e é a razão de
85
85
  // `PullRequestRef` carregar o `link`: o número do PR colide entre repos.
86
- const portaDe = scmDe ?? (r => createGithubScm({
87
- link: githubLink({ owner: r.owner, repo: r.repo, role: sameRepoQue(r, hub) ? 'hub' : 'code' }),
88
- token,
89
- }));
86
+ // A fábrica virou ASSÍNCRONA porque `requireScm` é — daí o `await` duplo nos
87
+ // call sites. Uma porta POR REPOSITÓRIO segue sendo o que o contrato manda, e é
88
+ // a razão de `PullRequestRef` carregar o `link`: o número do PR colide entre
89
+ // repos.
90
+ const portaDe = scmDe
91
+ ? (async r => scmDe(r))
92
+ : (r => requireScm({
93
+ link: resolveScmLink({ owner: r.owner, repo: r.repo, role: sameRepoQue(r, hub) ? 'hub' : 'code' }),
94
+ token,
95
+ }));
90
96
 
91
97
  for (const r of [hub, ...codeRepos]) {
92
- const abertos = await portaDe(r).listOpenPullRequests().catch(() => []);
98
+ const abertos = await (await portaDe(r)).listOpenPullRequests().catch(() => []);
93
99
  for (const bruto of abertos) {
94
100
  const pr = { ...bruto, repo: { owner: r.owner, repo: r.repo } };
95
101
  const fecha = hubIssueNumbers(extractIssueRefs(pr.body || '', { prRepo: pr.repo, linkMode }), hub);
@@ -98,7 +104,14 @@ export async function collectFeaturePullRequests({
98
104
  }
99
105
 
100
106
  // Vínculo NATIVO: só existe no hub (o GitHub não fecha issue entre repos).
101
- const hubScm = portaDe(hub);
107
+ //
108
+ // `await`: a fábrica virou assíncrona na leva 3 do bloco E. Sem ele `hubScm` é
109
+ // uma Promise, `.findPullRequestsReferencing` é `undefined`, o `TypeError`
110
+ // sincrônico NÃO é pego pelo `.catch(() => [])` logo abaixo — que só existe
111
+ // depois de haver promessa — e a busca por vínculo nativo devolvia vazio. Foi
112
+ // assim que o `markFeaturePrsReady` parou de achar PR em rascunho, e o teste de
113
+ // fumaça pegou: ele afirma que o PR FOI marcado, não só que nada vazou.
114
+ const hubScm = await portaDe(hub);
102
115
  for (const node of issueNodes) {
103
116
  if (!node?.nodeId) continue;
104
117
  const achados = await hubScm
@@ -169,13 +182,13 @@ export async function markFeaturePrsReady({
169
182
  // O PR pode estar em qualquer repo da Feature: a porta é a DELE, não a do
170
183
  // hub. Marcar um PR de repo de código com a porta do hub é 404 — ou pior,
171
184
  // o PR de mesmo número no hub.
172
- const portaDoPr = (pr) => {
185
+ const portaDoPr = async (pr) => {
173
186
  const r = { owner: pr.repo?.owner ?? owner, repo: pr.repo?.repo ?? repo };
174
187
  if (scmDe) return scmDe(r);
175
188
  // `role` sai de `pr.repo`, não de `r`: o par já traz fallback no hub, e
176
189
  // computar dali faria um `pr.repo` ausente virar 'hub' onde era 'code'.
177
- return createGithubScm({
178
- link: githubLink({ ...r, role: sameRepoQue(pr.repo, hub) ? 'hub' : 'code' }),
190
+ return requireScm({
191
+ link: resolveScmLink({ ...r, role: sameRepoQue(pr.repo, hub) ? 'hub' : 'code' }),
179
192
  token,
180
193
  });
181
194
  };
@@ -183,7 +196,7 @@ export async function markFeaturePrsReady({
183
196
  const falhas = [];
184
197
  for (const pr of alvos) {
185
198
  try {
186
- await portaDoPr(pr).markReadyForReview({ id: pr.id });
199
+ await (await portaDoPr(pr)).markReadyForReview({ id: pr.id });
187
200
  marcados.push(prLabel(pr, hub));
188
201
  } catch (err) {
189
202
  falhas.push(`${prLabel(pr, hub)} (${err.message})`);
@@ -21,7 +21,6 @@
21
21
  import { existsSync, readFileSync } from 'node:fs';
22
22
  import path from 'node:path';
23
23
 
24
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
25
24
 
26
25
  // ── Tradução WorkItem → a forma que este módulo SEMPRE devolveu ─────────────
27
26
  //
@@ -75,6 +74,7 @@ import { featureDocPaths } from './doc-paths.mjs';
75
74
  import { parseDecompositionDoc } from './decomposition-doc.mjs';
76
75
  import { parseDependencies } from './dependencies.mjs';
77
76
  import { indexBoardItems } from './board.mjs';
77
+ import { getTracker, requireTracker } from '../ports/index.mjs';
78
78
  import {
79
79
  parseDependencyMap, storiesFromAppliedDoc, mergeDependencyEdges, isFresh,
80
80
  DEPENDENCY_MAP_FILE,
@@ -107,13 +107,17 @@ import {
107
107
  export async function loadFeatureStories({
108
108
  token, owner, repo, root, feature, remote = false, refresh = false,
109
109
  ttlSec = DEFAULT_CACHE_TTL_SEC,
110
+ // Passthrough de porta, como `cachedSubIssues` e `loadBoardSnapshot` já têm.
111
+ // Sem ele o `merge` não tem teste de caminho: a primeira coisa que ele faz é
112
+ // listar as sub-issues, e a lista vem daqui.
113
+ tracker: trackerInjetado = null,
110
114
  } = {}) {
111
115
  const warnings = [];
112
116
  const nodeId = feature.nodeId || feature.node_id;
113
117
 
114
118
  // ── sub-issues (com body!) — cache subissues-<n> ───────────────────────────
115
119
  const subsKey = `subissues-${feature.number}`;
116
- const tracker = createGithubTracker({ token, owner, repo });
120
+ const tracker = await requireTracker({ cwd: root, token, owner, repo, deps: { tracker: trackerInjetado } });
117
121
  const cached = refresh ? null : readCacheEntry(root, subsKey, { owner, repo });
118
122
  let allSubs;
119
123
  let subsFrom;
@@ -222,7 +226,8 @@ export async function cachedSubIssues({
222
226
  const hit = readCacheEntry(root, key, { owner, repo });
223
227
  if (hit && isFresh(hit, ttlSec)) return { subs: hit.data, fromCache: true, fetchedAt: hit.fetchedAt };
224
228
  }
225
- const subs = (await (tracker ?? createGithubTracker({ token, owner, repo })).listChildren({
229
+ const porta = await requireTracker({ cwd: root, token, owner, repo, deps: { tracker } });
230
+ const subs = (await porta.listChildren({
226
231
  ref: { key: String(parent.number), id: parent.nodeId || parent.node_id },
227
232
  })).map(comoSubIssue);
228
233
  writeCacheEntry(root, key, 'sub-issues', subs, { owner, repo });
@@ -257,6 +262,9 @@ function safeDocPaths(root, title) {
257
262
  */
258
263
  export async function loadBoardSnapshot({
259
264
  token, owner, repo, project, root, refresh = false, fresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
265
+ // Passthrough de porta, como `cachedSubIssues` e `loadFeatureStories`. Sem
266
+ // ele o `order` não tem teste de caminho: o board é a entrada dele.
267
+ tracker: trackerInjetado = null,
260
268
  } = {}) {
261
269
  const key = 'board-items';
262
270
  if (!refresh && !fresh) {
@@ -270,7 +278,13 @@ export async function loadBoardSnapshot({
270
278
  };
271
279
  }
272
280
  }
273
- const items = (await createGithubTracker({ token, owner, repo, project }).boardSnapshot())
281
+ // `board: true`: esta função TIRA UM RETRATO do board, então sem o bloco
282
+ // `project` não há o que endereçar — e a mensagem que diz para rodar o `init`
283
+ // é melhor que um `boardSnapshot` vazio passando por "nenhum item".
284
+ const portaBoard = await requireTracker({
285
+ cwd: root, token, owner, repo, board: true, deps: { tracker: trackerInjetado },
286
+ });
287
+ const items = (await portaBoard.boardSnapshot())
274
288
  .map(comoItemDoBoard);
275
289
  writeCacheEntry(root, key, 'board-items', items, { projectId: project.id });
276
290
  return {
@@ -297,8 +311,14 @@ export async function externalIssueInfo({
297
311
  const hit = readCacheEntry(root, key, { owner, repo });
298
312
  if (hit && isFresh(hit, ttlSec)) return { ...hit.data, fromCache: true };
299
313
  }
300
- const issue = await createGithubTracker({ token, owner, repo })
301
- .getWorkItem({ ref: { key: String(number) } }).catch(() => null);
314
+ // `getTracker` e não `requireTracker`: esta função é best-effort por contrato
315
+ // — ela devolve "(não foi possível ler)" em vez de lançar, e o chamador conta
316
+ // com isso para montar o mapa de dependências mesmo com uma issue externa
317
+ // ilegível. Um plugin quebrado é mais um motivo de ilegibilidade, não um motivo
318
+ // para derrubar o comando.
319
+ const { tracker: portaExterna } = await getTracker({ cwd: root, token, owner, repo });
320
+ const issue = await portaExterna
321
+ ?.getWorkItem({ ref: { key: String(number) } }).catch(() => null) ?? null;
302
322
  if (!issue) {
303
323
  // Falha não entra no cache: "não foi possível ler" com cara de fresco por
304
324
  // 10 minutos esconderia uma issue que voltou a ser legível.
@@ -0,0 +1,58 @@
1
+ // O tracker tem REGISTRO de tags? — função PURA. RFC-006 Fase 2, bloco C.
2
+ //
3
+ // `deleteTag` e `countOpenWithTag` são as duas únicas operações do contrato
4
+ // marcadas OPCIONAIS que nenhuma capability liga — o bloco C achou isso cruzando
5
+ // a prosa do manifesto com as tabelas de condicionais. A prosa as justifica com
6
+ // "usados por uninstall e update", que não é uma capability, então
7
+ // `trackerRequiredOperations` NUNCA pode exigi-las: um plugin conforme pode
8
+ // omiti-las, e `uninstall`/`update` as chamavam sem guarda.
9
+ //
10
+ // ── Por que não são obrigatórias ─────────────────────────────────────────────
11
+ //
12
+ // A ausência é legítima, e é o que impede a saída fácil de promovê-las a
13
+ // obrigatórias. No GitHub uma label é uma ENTIDADE do repositório: tem cor,
14
+ // descrição, e existe mesmo sem estar em item nenhum — então apagar e contar
15
+ // fazem sentido. No Jira uma label é uma STRING livre no campo `labels` do
16
+ // issue: não há registro para apagar, e "quantos itens abertos têm esta label" é
17
+ // uma busca, não uma propriedade da label. Exigir as duas obrigaria todo plugin
18
+ // a fingir um registro que o site dele não tem.
19
+ //
20
+ // ── Por que função pura, e não capability ────────────────────────────────────
21
+ //
22
+ // A resposta certa a longo prazo é uma capability (`tagRegistry: 'native' | 'none'`),
23
+ // e ela deve entrar no dia em que existir um segundo tracker — hoje inventá-la
24
+ // seria congelar a forma contra o único fornecedor que há, o mesmo argumento pelo
25
+ // qual a §3.2 do plano recusou espelhar `capabilities` no config.
26
+ //
27
+ // O que esta função faz é exatamente o que essa capability produziria: uma
28
+ // decisão, num lugar, com a razão escrita. Quando a capability existir, o corpo
29
+ // aqui passa a lê-la e os dois chamadores não mudam.
30
+ //
31
+ // ── E por que o guard não é zelo ─────────────────────────────────────────────
32
+ //
33
+ // Chamar `undefined` lança de forma **SINCRÔNICA**, antes de existir promessa a
34
+ // que anexar um `.catch`. Então nem o `.catch(() => null)` que já estava na linha
35
+ // do `countOpenWithTag` nem o `try` em volta salvam: o `TypeError` seria
36
+ // reportado como "Falha ao remover label", mandando o usuário procurar um
37
+ // problema de permissão num tracker que está certo.
38
+
39
+ /**
40
+ * O que dá para fazer com o registro de tags deste tracker (função PURA).
41
+ *
42
+ * @param {object|null} tracker a porta
43
+ * @returns {{canDelete: boolean, canCount: boolean, warning: string|null}}
44
+ * `warning` é a frase para o usuário quando apagar não é possível — `null`
45
+ * quando é, para o chamador não precisar decidir se avisa.
46
+ */
47
+ export function tagRegistryPlan(tracker) {
48
+ const canDelete = typeof tracker?.deleteTag === 'function';
49
+ const canCount = typeof tracker?.countOpenWithTag === 'function';
50
+ return {
51
+ canDelete,
52
+ canCount,
53
+ warning: canDelete
54
+ ? null
55
+ : 'Este tracker não tem registro de labels para apagar — as labels do spec-wave '
56
+ + 'continuam nos itens onde já estão. Remova-as na interface, se quiser.',
57
+ };
58
+ }
@@ -9,7 +9,7 @@
9
9
  // Contrato: registrar uso NUNCA derruba o fluxo principal — recordUsage é
10
10
  // best-effort e engole qualquer erro com um console.warn.
11
11
 
12
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
12
+ import { getTracker } from '../ports/index.mjs';
13
13
 
14
14
  // Marcador HTML invisível que identifica o comentário de uso na issue.
15
15
  export const USAGE_MARKER = '<!-- spec-wave:usage -->';
@@ -149,7 +149,20 @@ export function renderUsageComment(entries) {
149
149
  */
150
150
  export async function recordUsage({ token, owner, repo, issueNumber, entries, tracker = null } = {}) {
151
151
  if (!Array.isArray(entries) || entries.length === 0) return;
152
- const porta = tracker || createGithubTracker({ token, owner, repo });
152
+ // `getTracker` e não `requireTracker`: o contrato no topo deste arquivo é
153
+ // "registrar uso NUNCA derruba o fluxo principal", e a construção da porta está
154
+ // FORA do `try` abaixo. Derrubar um `generate-*` por causa do comentário de
155
+ // custo jogaria fora uma geração de IA já paga.
156
+ //
157
+ // ⚠️ Diferente do `doc-source`, este ramo É alcançável: `getTracker` recusa
158
+ // quando o `kind` do config não tem plugin, e este arquivo não crava fornecedor
159
+ // nenhum. Daí o `console.warn` em vez de silêncio — telemetria que não sai
160
+ // precisa dizer que não saiu, senão a conta de uso mente por omissão.
161
+ const { tracker: porta, error: erroPorta } = await getTracker({ token, owner, repo, deps: { tracker } });
162
+ if (erroPorta) {
163
+ console.warn(`⚠️ Uso não registrado: ${erroPorta}`);
164
+ return;
165
+ }
153
166
  const ref = { key: String(issueNumber) };
154
167
  try {
155
168
  const comments = await porta.listComments({ ref });
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.3.0",
4
+ "version": "1.5.0",
5
5
  "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
6
6
  "author": {
7
7
  "name": "Astratech",