@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.
- package/package.json +1 -1
- package/protocol/scm.v1.json +154 -0
- package/protocol/tracker.v1.json +175 -0
- package/src/api/github-rest.mjs +109 -0
- package/src/commands/audit.mjs +3 -4
- package/src/commands/code-review.mjs +11 -6
- package/src/commands/decompose.mjs +29 -9
- package/src/commands/doctor.mjs +389 -220
- package/src/commands/generate-bug.mjs +17 -7
- package/src/commands/generate-plan.mjs +21 -13
- package/src/commands/generate-qa-plan.mjs +19 -11
- package/src/commands/generate-spec.mjs +19 -6
- package/src/commands/implement.mjs +105 -49
- package/src/commands/init.mjs +36 -6
- package/src/commands/issue.mjs +6 -2
- package/src/commands/merge.mjs +31 -18
- package/src/commands/mode.mjs +18 -10
- package/src/commands/move.mjs +3 -3
- package/src/commands/order.mjs +30 -20
- package/src/commands/preflight.mjs +10 -5
- package/src/commands/qa-lead.mjs +41 -31
- package/src/commands/qa-run.mjs +83 -55
- package/src/commands/qa.mjs +10 -6
- package/src/commands/refresh.mjs +6 -3
- package/src/commands/repair-stage.mjs +1 -1
- package/src/commands/repo.mjs +7 -7
- package/src/commands/run.mjs +7 -4
- package/src/commands/story.mjs +3 -3
- package/src/commands/task.mjs +3 -3
- package/src/commands/triage.mjs +3 -3
- package/src/commands/uninstall.mjs +14 -5
- package/src/commands/update.mjs +47 -19
- package/src/commands/validate.mjs +3 -4
- package/src/commands/workspace.mjs +2 -2
- package/src/lib/artifact-publish.mjs +4 -3
- package/src/lib/board.mjs +22 -24
- package/src/lib/config-ports.mjs +114 -0
- package/src/lib/critique.mjs +11 -1
- package/src/lib/doc-source.mjs +16 -2
- package/src/lib/doctor-capabilities.mjs +168 -0
- package/src/lib/implement-board.mjs +6 -1
- package/src/lib/implement-stream.mjs +87 -0
- package/src/lib/pr-ready.mjs +24 -11
- package/src/lib/story-graph.mjs +26 -6
- package/src/lib/tag-registry.mjs +58 -0
- package/src/lib/usage-report.mjs +15 -2
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugins/load.mjs +427 -0
- package/src/plugins/scm-github/index.mjs +71 -2
- package/src/plugins/tracker-github-projects/index.mjs +52 -10
- package/src/ports/capabilities.mjs +47 -0
- package/src/ports/index.mjs +347 -0
- package/src/ports/scm.mjs +39 -2
- package/src/ports/tracker.mjs +94 -3
- package/src/ports/types.mjs +59 -6
- package/src/setup/files.mjs +2 -2
- package/src/setup/labels.mjs +2 -2
- package/src/setup/project.mjs +2 -2
- 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
|
+
}
|
package/src/lib/pr-ready.mjs
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
|
|
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
|
|
178
|
-
link:
|
|
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})`);
|
package/src/lib/story-graph.mjs
CHANGED
|
@@ -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 =
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
301
|
-
|
|
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
|
+
}
|
package/src/lib/usage-report.mjs
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
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.
|
|
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",
|