@spec-wave/cli 1.2.0 → 1.4.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/src/api/github-rest.mjs +15 -0
- package/src/commands/audit.mjs +3 -2
- package/src/commands/code-review.mjs +3 -2
- package/src/commands/decompose.mjs +26 -7
- package/src/commands/generate-bug.mjs +16 -6
- package/src/commands/generate-plan.mjs +21 -11
- package/src/commands/generate-qa-plan.mjs +20 -10
- package/src/commands/generate-spec.mjs +18 -5
- package/src/commands/implement.mjs +91 -47
- package/src/commands/init.mjs +3 -2
- package/src/commands/merge.mjs +14 -6
- package/src/commands/mode.mjs +3 -2
- package/src/commands/order.mjs +29 -19
- package/src/commands/preflight.mjs +3 -2
- package/src/commands/qa-lead.mjs +40 -28
- package/src/commands/qa-run.mjs +68 -52
- package/src/commands/qa.mjs +3 -2
- package/src/commands/repo.mjs +3 -2
- package/src/commands/run.mjs +3 -2
- package/src/commands/uninstall.mjs +3 -2
- package/src/commands/update.mjs +3 -2
- package/src/commands/validate.mjs +3 -2
- package/src/lib/artifact-publish.mjs +3 -2
- package/src/lib/critique.mjs +11 -1
- package/src/lib/doc-source.mjs +3 -2
- package/src/lib/implement-board.mjs +5 -0
- package/src/lib/implement-stream.mjs +87 -0
- package/src/lib/pr-ready.mjs +4 -3
- package/src/lib/story-graph.mjs +9 -2
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugins/tracker-github-projects/index.mjs +20 -1
- package/src/ports/index.mjs +192 -0
- package/src/ports/tracker.mjs +88 -2
- package/src/ports/types.mjs +29 -0
- package/src/setup/files.mjs +3 -2
|
@@ -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,8 @@
|
|
|
17
17
|
// implementação, que a essa altura já está commitada.
|
|
18
18
|
|
|
19
19
|
import * as p from '@clack/prompts';
|
|
20
|
-
import { createGithubScm
|
|
20
|
+
import { createGithubScm } from '../plugins/scm-github/index.mjs';
|
|
21
|
+
import { resolveScmLink } from '../ports/index.mjs';
|
|
21
22
|
import { extractIssueRefs, hubIssueNumbers } from './pr-link.mjs';
|
|
22
23
|
|
|
23
24
|
/**
|
|
@@ -84,7 +85,7 @@ export async function collectFeaturePullRequests({
|
|
|
84
85
|
// Uma porta POR REPOSITÓRIO — é o que o contrato manda, e é a razão de
|
|
85
86
|
// `PullRequestRef` carregar o `link`: o número do PR colide entre repos.
|
|
86
87
|
const portaDe = scmDe ?? (r => createGithubScm({
|
|
87
|
-
link:
|
|
88
|
+
link: resolveScmLink({ owner: r.owner, repo: r.repo, role: sameRepoQue(r, hub) ? 'hub' : 'code' }),
|
|
88
89
|
token,
|
|
89
90
|
}));
|
|
90
91
|
|
|
@@ -175,7 +176,7 @@ export async function markFeaturePrsReady({
|
|
|
175
176
|
// `role` sai de `pr.repo`, não de `r`: o par já traz fallback no hub, e
|
|
176
177
|
// computar dali faria um `pr.repo` ausente virar 'hub' onde era 'code'.
|
|
177
178
|
return createGithubScm({
|
|
178
|
-
link:
|
|
179
|
+
link: resolveScmLink({ ...r, role: sameRepoQue(pr.repo, hub) ? 'hub' : 'code' }),
|
|
179
180
|
token,
|
|
180
181
|
});
|
|
181
182
|
};
|
package/src/lib/story-graph.mjs
CHANGED
|
@@ -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 = trackerInjetado || createGithubTracker({ token, owner, repo });
|
|
117
121
|
const cached = refresh ? null : readCacheEntry(root, subsKey, { owner, repo });
|
|
118
122
|
let allSubs;
|
|
119
123
|
let subsFrom;
|
|
@@ -257,6 +261,9 @@ function safeDocPaths(root, title) {
|
|
|
257
261
|
*/
|
|
258
262
|
export async function loadBoardSnapshot({
|
|
259
263
|
token, owner, repo, project, root, refresh = false, fresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
|
|
264
|
+
// Passthrough de porta, como `cachedSubIssues` e `loadFeatureStories`. Sem
|
|
265
|
+
// ele o `order` não tem teste de caminho: o board é a entrada dele.
|
|
266
|
+
tracker: trackerInjetado = null,
|
|
260
267
|
} = {}) {
|
|
261
268
|
const key = 'board-items';
|
|
262
269
|
if (!refresh && !fresh) {
|
|
@@ -270,7 +277,7 @@ export async function loadBoardSnapshot({
|
|
|
270
277
|
};
|
|
271
278
|
}
|
|
272
279
|
}
|
|
273
|
-
const items = (await createGithubTracker({ token, owner, repo, project }).boardSnapshot())
|
|
280
|
+
const items = (await (trackerInjetado || createGithubTracker({ token, owner, repo, project })).boardSnapshot())
|
|
274
281
|
.map(comoItemDoBoard);
|
|
275
282
|
writeCacheEntry(root, key, 'board-items', items, { projectId: project.id });
|
|
276
283
|
return {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spec-wave",
|
|
3
3
|
"displayName": "Spec Wave",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.4.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",
|
|
@@ -44,6 +44,7 @@ import {
|
|
|
44
44
|
setIssueMilestone,
|
|
45
45
|
setIssueState,
|
|
46
46
|
updateComment,
|
|
47
|
+
updateIssue,
|
|
47
48
|
updateLabel,
|
|
48
49
|
updateMilestone,
|
|
49
50
|
updateMilestoneDescription,
|
|
@@ -82,6 +83,7 @@ export const GITHUB_TRACKER_CAPABILITIES = Object.freeze({
|
|
|
82
83
|
hierarchy: 'native', // sub-issues
|
|
83
84
|
dependencies: 'native', // API de dependencies (blocked_by)
|
|
84
85
|
milestones: 'native',
|
|
86
|
+
reopen: 'native', // `setIssueState(..., 'open')` — sem workflow no caminho
|
|
85
87
|
stages: Object.freeze({ mode: 'set', multiHop: false, reopenable: true }),
|
|
86
88
|
progress: 'native', // o campo nativo "Status" do Projects v2
|
|
87
89
|
fields: Object.freeze({
|
|
@@ -177,7 +179,7 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
177
179
|
addBlockedBy, addLabel, commentOnIssue, countOpenIssuesWithLabel, createIssue, createLabel,
|
|
178
180
|
createMilestone, deleteLabel, getIssue, getMilestone, getOwnerType, listBlockedBy,
|
|
179
181
|
listIssueComments, listIssuesByMilestone, listLabels, listMilestones, removeLabel,
|
|
180
|
-
setIssueMilestone, setIssueState, updateComment, updateLabel, updateMilestone,
|
|
182
|
+
setIssueMilestone, setIssueState, updateComment, updateIssue, updateLabel, updateMilestone,
|
|
181
183
|
updateMilestoneDescription, getOwnerNodeId, getRepoNodeId,
|
|
182
184
|
addProjectItem, addSubIssue, createProject, createSingleSelectField, createTextField,
|
|
183
185
|
getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getRateLimit,
|
|
@@ -560,12 +562,29 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
|
|
|
560
562
|
});
|
|
561
563
|
},
|
|
562
564
|
|
|
565
|
+
// A parcialidade é decidida AQUI, e não na rota: campo ausente não entra no
|
|
566
|
+
// payload. É o único nível em que um teste consegue ver o que foi enviado —
|
|
567
|
+
// ver a nota em `updateIssue` (github-rest.mjs).
|
|
568
|
+
async updateWorkItem({ ref, title, body } = {}) {
|
|
569
|
+
const campos = {};
|
|
570
|
+
if (title !== undefined) campos.title = title;
|
|
571
|
+
if (body !== undefined) campos.body = body;
|
|
572
|
+
await a.updateIssue(token, owner, repo, refNumber(refKey(ref)), campos);
|
|
573
|
+
},
|
|
574
|
+
|
|
563
575
|
closeWorkItem({ ref } = {}) {
|
|
564
576
|
// `reason` é ignorado: no GitHub fechar é um ESTADO, e a distinção
|
|
565
577
|
// rejeitado × duplicata já vive nas labels (`closeSemantics: 'state'`).
|
|
566
578
|
return a.setIssueState(token, owner, repo, refNumber(ref), 'closed');
|
|
567
579
|
},
|
|
568
580
|
|
|
581
|
+
// A mesma rota, o outro estado. O `state_reason: 'reopened'` é o GitHub que
|
|
582
|
+
// escreve — o contrato já o lia (`WorkItem.stateReason`) antes de existir
|
|
583
|
+
// qualquer forma de produzi-lo.
|
|
584
|
+
reopenWorkItem({ ref } = {}) {
|
|
585
|
+
return a.setIssueState(token, owner, repo, refNumber(ref), 'open');
|
|
586
|
+
},
|
|
587
|
+
|
|
569
588
|
async addChild({ parent, child } = {}) {
|
|
570
589
|
const p = await hidratar(parent);
|
|
571
590
|
const c = await hidratar(child);
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
// A entrada única para obter uma porta — RFC-006 Fase 2, bloco 0.
|
|
2
|
+
//
|
|
3
|
+
// Hoje o core constrói `createGithubTracker`/`createGithubScm` direto em ~35
|
|
4
|
+
// arquivos, em quatro padrões de injetabilidade diferentes. O objetivo da Fase
|
|
5
|
+
// 2 é que TODOS passem por aqui, e que este arquivo seja o único que sabe de
|
|
6
|
+
// onde um plugin vem.
|
|
7
|
+
//
|
|
8
|
+
// ── Por que existe antes de ter chamador ────────────────────────────────────
|
|
9
|
+
//
|
|
10
|
+
// Este arquivo é o bloco 0 do plano (`rfc/plano-fase2-portas.md`): a assinatura
|
|
11
|
+
// congelada, sem consumidor nenhum. É o que torna o resto paralelizável, e é a
|
|
12
|
+
// mesma disciplina que salvou a Fase 1 — o shim 9a→9d evitou que a mudança de
|
|
13
|
+
// assinatura do board fanasse por 11 arquivos num commit só. Assinatura primeiro,
|
|
14
|
+
// migração depois, em levas.
|
|
15
|
+
//
|
|
16
|
+
// ── Três decisões de forma, e as razões ─────────────────────────────────────
|
|
17
|
+
//
|
|
18
|
+
// **ASSÍNCRONAS**, mesmo devolvendo hoje um plugin embutido por import estático.
|
|
19
|
+
// O bloco A troca a resolução por `import()` dinâmico (§9.2), que é assíncrono
|
|
20
|
+
// por natureza. Nascer síncrono e virar assíncrono depois obrigaria a mexer em
|
|
21
|
+
// todos os ~35 call sites uma SEGUNDA vez — exatamente o que o bloco 0 existe
|
|
22
|
+
// para evitar.
|
|
23
|
+
//
|
|
24
|
+
// **Devolvem `{ porta, error }`, nunca lançam.** É a convenção da casa para
|
|
25
|
+
// falha de configuração: `loadConfig`, `openTracker` e `loadProjectConfig` já
|
|
26
|
+
// fazem assim, e os chamadores imprimem a string e saem com código. Um throw
|
|
27
|
+
// aqui viraria stack trace no terminal de quem só esqueceu de rodar o `init`.
|
|
28
|
+
//
|
|
29
|
+
// **`deps` continua sendo o seam de teste**, com a mesma forma de
|
|
30
|
+
// `lib/artifact-publish.mjs` e dos testes de fumaça: porta já construída vence
|
|
31
|
+
// qualquer resolução. Sem isso, cada comando migrado precisaria de um seam
|
|
32
|
+
// próprio de novo.
|
|
33
|
+
//
|
|
34
|
+
// ── O que este arquivo AINDA não faz ────────────────────────────────────────
|
|
35
|
+
//
|
|
36
|
+
// A resolução é estática: devolve o plugin do GitHub, sempre. O bloco A põe
|
|
37
|
+
// aqui a ordem de resolução da §9.2 (`package` explícito → `@spec-wave/
|
|
38
|
+
// tracker-<kind>` → `spec-wave-<kind>-plugin` → caminho local), o `import()`
|
|
39
|
+
// dinâmico, a validação de `specWaveTrackerApi === 1` e a chamada de
|
|
40
|
+
// `checkTrackerPort` na carga. Os pontos estão marcados com `bloco A`.
|
|
41
|
+
//
|
|
42
|
+
// `getScm` toma um `ScmLink` já pronto de propósito: `ScmLink` é tipo do
|
|
43
|
+
// CONTRATO e qualquer plugin sabe produzir um, então a assinatura sobrevive ao
|
|
44
|
+
// bloco A. Quem o CONSTRÓI era o buraco que o plano não previa — 21 arquivos do
|
|
45
|
+
// core importavam `githubLink` do plugin —, e o bloco E0 o fechou com
|
|
46
|
+
// `resolveScmLink` (no fim deste arquivo) mais a extensão da barreira.
|
|
47
|
+
|
|
48
|
+
import { createGithubTracker, TRACKER_KIND } from '../plugins/tracker-github-projects/index.mjs';
|
|
49
|
+
import { createGithubScm, githubLink, SCM_KIND } from '../plugins/scm-github/index.mjs';
|
|
50
|
+
import { CONFIG_FILE } from '../config.mjs';
|
|
51
|
+
import { loadConfig } from '../lib/project-root.mjs';
|
|
52
|
+
|
|
53
|
+
/** @typedef {import('./tracker.mjs').TrackerPort} TrackerPort */
|
|
54
|
+
/** @typedef {import('./scm.mjs').ScmPort} ScmPort */
|
|
55
|
+
/** @typedef {import('./types.mjs').ScmLink} ScmLink */
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* A porta de tracker deste workspace.
|
|
59
|
+
*
|
|
60
|
+
* `projectToken` é separado porque quatro comandos e uma lib usam
|
|
61
|
+
* `PROJECT_TOKEN || token` SÓ para o board, com o token simples fazendo as
|
|
62
|
+
* issues no mesmo comando. Uma porta presa a uma credencial promoveria
|
|
63
|
+
* `PROJECT_TOKEN` às chamadas de issue — 403 num PAT com escopo `project` e sem
|
|
64
|
+
* `repo`, que nenhum teste desta suíte enxerga.
|
|
65
|
+
*
|
|
66
|
+
* @param {object} [params]
|
|
67
|
+
* @param {string} [params.cwd=process.cwd()] onde começar a busca do config
|
|
68
|
+
* @param {string} [params.token] credencial padrão (REST de issue)
|
|
69
|
+
* @param {string} [params.projectToken] credencial de board; ausente = `token`
|
|
70
|
+
* @param {string} [params.owner] vence o que estiver no config
|
|
71
|
+
* @param {string} [params.repo] idem
|
|
72
|
+
* @param {object} [params.deps] `deps.tracker` injeta uma porta já construída
|
|
73
|
+
* @returns {Promise<{tracker: TrackerPort|null, root: string|null, error: string|null}>}
|
|
74
|
+
*/
|
|
75
|
+
export async function getTracker({
|
|
76
|
+
cwd = process.cwd(), token, projectToken, owner, repo, deps = {},
|
|
77
|
+
} = {}) {
|
|
78
|
+
const { config, root, error: configError } = loadConfig(cwd);
|
|
79
|
+
|
|
80
|
+
// Porta injetada vence tudo, e nem o bloco `project` é exigido: quem injeta
|
|
81
|
+
// já decidiu de onde ela vem. `root` continua saindo do config porque os
|
|
82
|
+
// chamadores o usam para achar os documentos.
|
|
83
|
+
if (deps.tracker) return { tracker: deps.tracker, root, error: null };
|
|
84
|
+
|
|
85
|
+
if (configError) return { tracker: null, root, error: configError };
|
|
86
|
+
|
|
87
|
+
const project = config.project || {};
|
|
88
|
+
if (!project.id) {
|
|
89
|
+
return { tracker: null, root, error: `Project não configurado em ${CONFIG_FILE}` };
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const donoResolvido = owner || config.owner;
|
|
93
|
+
const repoResolvido = repo || config.repo;
|
|
94
|
+
if (!donoResolvido || !repoResolvido) {
|
|
95
|
+
return {
|
|
96
|
+
tracker: null,
|
|
97
|
+
root,
|
|
98
|
+
error: `owner/repo ausentes no chamador e em ${CONFIG_FILE}`,
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// bloco A: aqui entra a resolução da §9.2, a partir de `config.tracker.kind`
|
|
103
|
+
// (que o bloco D passa a derivar do bloco `project` quando ausente).
|
|
104
|
+
//
|
|
105
|
+
// O try/catch não é zelo: a fábrica de um plugin é código de TERCEIRO, e a
|
|
106
|
+
// partir do bloco A pode lançar por qualquer motivo. Um throw aqui viraria
|
|
107
|
+
// stack trace no terminal de quem só instalou um plugin quebrado, em vez de
|
|
108
|
+
// uma linha dizendo qual plugin e por quê.
|
|
109
|
+
try {
|
|
110
|
+
const tracker = createGithubTracker({
|
|
111
|
+
token,
|
|
112
|
+
projectToken,
|
|
113
|
+
owner: donoResolvido,
|
|
114
|
+
repo: repoResolvido,
|
|
115
|
+
project,
|
|
116
|
+
});
|
|
117
|
+
return { tracker, root, error: null };
|
|
118
|
+
} catch (err) {
|
|
119
|
+
return { tracker: null, root, error: `tracker "${TRACKER_KIND}" não pôde ser construído: ${err.message}` };
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* A porta de SCM de UM repositório.
|
|
125
|
+
*
|
|
126
|
+
* Toma um `ScmLink` e não um par `owner`/`repo` porque uma instância de SCM **é
|
|
127
|
+
* um repositório**, e porque o par não cabe no Azure DevOps (`org/project/repo`).
|
|
128
|
+
* Em arquivo que fala com dois repositórios, o identificador nunca é `scm`
|
|
129
|
+
* pelado — `hubScm`, `prScm`, `scmFor(link)`: uma variável errada abre PR no hub
|
|
130
|
+
* em vez do repo de código, e nenhum teste pega.
|
|
131
|
+
*
|
|
132
|
+
* `prToken` existe porque `lib/artifact-publish.mjs` usa
|
|
133
|
+
* `SPEC_WAVE_PR_TOKEN || GH_PR_TOKEN || token` SÓ para abrir PR, e a promoção
|
|
134
|
+
* dessa credencial ao resto das chamadas é invisível para a suíte.
|
|
135
|
+
*
|
|
136
|
+
* @param {object} params
|
|
137
|
+
* @param {ScmLink} params.link
|
|
138
|
+
* @param {string} [params.token]
|
|
139
|
+
* @param {string} [params.prToken] credencial de PR; ausente = `token`
|
|
140
|
+
* @param {string} [params.trackerKind] com qual tracker este SCM foi pareado —
|
|
141
|
+
* §8.1: nenhum plugin de SCM descobre isso sozinho, o core injeta
|
|
142
|
+
* @param {object} [params.deps] `deps.scm` injeta uma porta já construída
|
|
143
|
+
* @returns {Promise<{scm: ScmPort|null, error: string|null}>}
|
|
144
|
+
*/
|
|
145
|
+
export async function getScm({ link, token, prToken, trackerKind, deps = {} } = {}) {
|
|
146
|
+
if (deps.scm) return { scm: deps.scm, error: null };
|
|
147
|
+
if (!link?.kind) return { scm: null, error: 'getScm: `link` sem `kind`' };
|
|
148
|
+
|
|
149
|
+
// bloco A: resolução por `link.kind`. Até lá, só existe um fornecedor — e
|
|
150
|
+
// recusar explicitamente o que não é ele vale mais que cair num default
|
|
151
|
+
// silencioso, que é como um plugin errado entregaria a porta errada.
|
|
152
|
+
if (link.kind !== SCM_KIND) {
|
|
153
|
+
return { scm: null, error: `getScm: nenhum plugin de SCM para "${link.kind}"` };
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
// Mesmo motivo do try/catch do tracker: `createGithubScm` já lança quando o
|
|
157
|
+
// `link` não traz `config.owner`/`config.repo`, e a partir do bloco A quem
|
|
158
|
+
// lança é código de terceiro.
|
|
159
|
+
try {
|
|
160
|
+
return {
|
|
161
|
+
scm: createGithubScm({ link, token, prToken, trackerKind: trackerKind || TRACKER_KIND }),
|
|
162
|
+
error: null,
|
|
163
|
+
};
|
|
164
|
+
} catch (err) {
|
|
165
|
+
return { scm: null, error: `scm "${link.kind}" não pôde ser construído: ${err.message}` };
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Um `ScmLink` a partir do endereço de um repositório.
|
|
171
|
+
*
|
|
172
|
+
* Existia porque 21 arquivos do core importavam `githubLink` DO PLUGIN — o core
|
|
173
|
+
* nomeando um fornecedor, que é o acoplamento que as portas existem para
|
|
174
|
+
* remover. A barreira não enxergava: ela varria imports de `src/api/github-*`,
|
|
175
|
+
* e este entrava por outra porta. O bloco E0 migrou os 21 para cá e estendeu a
|
|
176
|
+
* barreira, que hoje tem um guard só para `githubLink` no core.
|
|
177
|
+
*
|
|
178
|
+
* Aqui é um forward, e é de propósito: o valor está em existir UM ponto para o
|
|
179
|
+
* bloco A trocar por "pergunte ao plugin resolvido", em vez de 21. Enquanto o
|
|
180
|
+
* `kind` não vier do config (bloco D), o default é o único fornecedor que há.
|
|
181
|
+
*
|
|
182
|
+
* @param {object} params
|
|
183
|
+
* @param {string} params.owner
|
|
184
|
+
* @param {string} params.repo
|
|
185
|
+
* @param {'hub'|'code'} [params.role]
|
|
186
|
+
* @param {string} [params.kind]
|
|
187
|
+
* @returns {ScmLink}
|
|
188
|
+
*/
|
|
189
|
+
export function resolveScmLink({ owner, repo, role = 'hub', kind = SCM_KIND }) {
|
|
190
|
+
if (kind !== SCM_KIND) throw new Error(`resolveScmLink: nenhum plugin de SCM para "${kind}"`);
|
|
191
|
+
return githubLink({ owner, repo, role });
|
|
192
|
+
}
|
package/src/ports/tracker.mjs
CHANGED
|
@@ -100,6 +100,18 @@
|
|
|
100
100
|
* exatamente disto — e fazê-lo no core custaria um get + um set, dois
|
|
101
101
|
* round-trips onde um tracker pode fazer um. Devolve `true` se escreveu.
|
|
102
102
|
*
|
|
103
|
+
* @property {(o: {ref: WorkItemRef, title?: string, body?: string}) => Promise<void>} updateWorkItem
|
|
104
|
+
* PARCIAL: campo não passado não é tocado, e isso é requisito, não
|
|
105
|
+
* conveniência. O `body` de uma Story carrega a linha `Depende de: #N` que
|
|
106
|
+
* `lib/dependencies.mjs` analisa e que `implement` e `merge` leem — uma
|
|
107
|
+
* escrita que exigisse o corpo inteiro faria um renomear de título apagar
|
|
108
|
+
* dependência, com sucesso na chamada e silêncio no efeito.
|
|
109
|
+
*
|
|
110
|
+
* OBRIGATÓRIA, e sem capability que a desligue: `createWorkItem` já toma
|
|
111
|
+
* `title` e `body`, então todo tracker que implementa a criação sabe escrever
|
|
112
|
+
* os dois. Não existe fornecedor onde nascer com título seja possível e
|
|
113
|
+
* renomear não.
|
|
114
|
+
*
|
|
103
115
|
* @property {() => Promise<BoardItem[]>} boardSnapshot
|
|
104
116
|
* @property {(o: {ref: WorkItemRef, reason?: 'completed'|'not-planned'|'duplicate'}) => Promise<void>} closeWorkItem
|
|
105
117
|
* `reason` existe porque em `closeSemantics: 'transition-and-resolution'` o
|
|
@@ -108,6 +120,26 @@
|
|
|
108
120
|
*
|
|
109
121
|
* ── CONDICIONAIS ──────────────────────────────────────────────────────────
|
|
110
122
|
*
|
|
123
|
+
* @property {(o: {ref: WorkItemRef}) => Promise<void>} [reopenWorkItem] reopen: 'native'
|
|
124
|
+
* A inversa de `closeWorkItem`. O contrato já sabia LER um item reaberto —
|
|
125
|
+
* `WorkItem.stateReason` tem `'reopened'` no enum desde a Fase 1 — e não
|
|
126
|
+
* tinha como produzir um: a rota existia (`setIssueState` aceita o estado) e
|
|
127
|
+
* só era chamada com `'closed'`, pelo único consumidor que havia.
|
|
128
|
+
*
|
|
129
|
+
* Sem argumento de destino, e isso só é possível porque `state`, `stage` e
|
|
130
|
+
* `progress` são três dimensões SEPARADAS aqui: reabrir não decide para qual
|
|
131
|
+
* Etapa o item volta, porque a Etapa não muda. Num tracker
|
|
132
|
+
* `closeSemantics: 'transition-and-resolution'` o plugin transiciona para o
|
|
133
|
+
* status não-Done que corresponde à Etapa atual e limpa a `resolution` — a
|
|
134
|
+
* informação necessária já está no item.
|
|
135
|
+
*
|
|
136
|
+
* CONDICIONAL, e não obrigatória junto com `closeWorkItem`, por uma
|
|
137
|
+
* assimetria real: `closeSemantics` garante que fechar é sempre possível
|
|
138
|
+
* (todo valor do enum implica isso), mas sair de Done depende de existir a
|
|
139
|
+
* transição no workflow do site — no Jira isso é configuração de quem
|
|
140
|
+
* instalou, não do fornecedor. `reopen: 'none'` é a declaração honesta desse
|
|
141
|
+
* caso, e o core recusa com mensagem em vez de tentar e estourar.
|
|
142
|
+
*
|
|
111
143
|
* @property {(o: {ref: WorkItemRef}) => Promise<Progress|null>} [getProgress] progress: 'native'
|
|
112
144
|
* @property {(o: {ref: WorkItemRef, progress: Progress}) => Promise<boolean>} [setProgress]
|
|
113
145
|
*
|
|
@@ -190,7 +222,7 @@
|
|
|
190
222
|
*/
|
|
191
223
|
export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
|
|
192
224
|
'setup', 'verify',
|
|
193
|
-
'createWorkItem', 'getWorkItem', 'listWorkItemsByTag',
|
|
225
|
+
'createWorkItem', 'getWorkItem', 'updateWorkItem', 'listWorkItemsByTag',
|
|
194
226
|
'addComment', 'listComments', 'updateComment',
|
|
195
227
|
'addTag', 'removeTag', 'ensureTags', 'listTags',
|
|
196
228
|
'getStage', 'setStage',
|
|
@@ -209,6 +241,7 @@ export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
|
|
|
209
241
|
* @type {Readonly<Record<string, Readonly<string[]>>>}
|
|
210
242
|
*/
|
|
211
243
|
export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
|
|
244
|
+
'reopen=native': Object.freeze(['reopenWorkItem']),
|
|
212
245
|
'progress=native': Object.freeze(['getProgress', 'setProgress']),
|
|
213
246
|
'hierarchy=native': Object.freeze(['addChild', 'listChildren', 'getParent']),
|
|
214
247
|
'dependencies=native': Object.freeze(['addBlockedBy', 'listBlockedBy']),
|
|
@@ -236,6 +269,9 @@ export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
|
|
|
236
269
|
export function trackerRequiredOperations(capabilities = {}) {
|
|
237
270
|
const exigidas = new Set(TRACKER_REQUIRED_OPERATIONS);
|
|
238
271
|
const ligada = {
|
|
272
|
+
// Ausente vale `none`: um plugin que não declara reabrir não ganha a
|
|
273
|
+
// operação por omissão, e o core tem de perguntar antes de oferecer.
|
|
274
|
+
'reopen=native': capabilities.reopen === 'native',
|
|
239
275
|
'progress=native': capabilities.progress === 'native',
|
|
240
276
|
'hierarchy=native': capabilities.hierarchy === 'native',
|
|
241
277
|
'dependencies=native': capabilities.dependencies === 'native',
|
|
@@ -252,10 +288,56 @@ export function trackerRequiredOperations(capabilities = {}) {
|
|
|
252
288
|
return [...exigidas];
|
|
253
289
|
}
|
|
254
290
|
|
|
291
|
+
/**
|
|
292
|
+
* Chaves que um `keyPattern` NUNCA pode aceitar (função PURA).
|
|
293
|
+
*
|
|
294
|
+
* `#` é sigilo ou separador em três pontos do texto que o fluxo gera e
|
|
295
|
+
* reanalisa depois: `refKey()` descarta um `#` inicial porque ali ele é o
|
|
296
|
+
* prefixo da referência e não parte da chave; `Depende de: #4, #5` é escrito no
|
|
297
|
+
* corpo das Stories e lido de volta por `lib/dependencies.mjs`; e
|
|
298
|
+
* `owner/repo#n` sai no `closingKeyword` em multi-repo. Uma chave com `#`
|
|
299
|
+
* tornaria `#A#B` indistinguível de duas referências, e o estrago apareceria
|
|
300
|
+
* como dependência que some — não como erro.
|
|
301
|
+
*
|
|
302
|
+
* `1#2` está na lista para cobrar ÂNCORA: sem `^…$` um `[0-9]+` solto casa o
|
|
303
|
+
* "1" dentro de "1#2" e `test` devolve true, e aí a proibição passaria por
|
|
304
|
+
* acidente num pattern que na verdade aceita qualquer coisa em volta.
|
|
305
|
+
*/
|
|
306
|
+
const CHAVES_PROIBIDAS = Object.freeze(['#', '1#2', '#42', 'PROJ-1#2', 'a#']);
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* O `identity.keyPattern` declarado é utilizável? (função PURA)
|
|
310
|
+
*
|
|
311
|
+
* Separada de `checkTrackerPort` para o kit de conformidade da Fase 2
|
|
312
|
+
* (`@spec-wave/plugin-conformance`) poder chamar a MESMA regra — o manifesto
|
|
313
|
+
* afirma que ele confere isto, e duas cópias da regra divergiriam. É por isso
|
|
314
|
+
* que ela é exportada apesar de ter um chamador só hoje.
|
|
315
|
+
*
|
|
316
|
+
* @param {string} [pattern]
|
|
317
|
+
* @returns {string[]} problemas; vazio = utilizável
|
|
318
|
+
*/
|
|
319
|
+
export function checkKeyPattern(pattern) {
|
|
320
|
+
if (!pattern) return ['`identity.keyPattern` ausente'];
|
|
321
|
+
let re;
|
|
322
|
+
try {
|
|
323
|
+
re = new RegExp(pattern);
|
|
324
|
+
} catch {
|
|
325
|
+
return [`\`identity.keyPattern\` não é regex válida: ${pattern}`];
|
|
326
|
+
}
|
|
327
|
+
const aceitas = CHAVES_PROIBIDAS.filter(c => re.test(c));
|
|
328
|
+
if (aceitas.length) {
|
|
329
|
+
return [
|
|
330
|
+
`\`identity.keyPattern\` ${pattern} aceita ${aceitas.map(c => `"${c}"`).join(', ')}: ` +
|
|
331
|
+
'a chave não pode conter `#`, que é o sigilo de referência em `#N`, `Depende de:` e `owner/repo#n`',
|
|
332
|
+
];
|
|
333
|
+
}
|
|
334
|
+
return [];
|
|
335
|
+
}
|
|
336
|
+
|
|
255
337
|
/**
|
|
256
338
|
* Confere um plugin de tracker contra as capabilities que ele declara.
|
|
257
339
|
*
|
|
258
|
-
* Roda na CARGA, não no meio de um comando: as
|
|
340
|
+
* Roda na CARGA, não no meio de um comando: as checagens são baratas, e um
|
|
259
341
|
* plugin publicado independentemente VAI ficar para trás do core — descobrir
|
|
260
342
|
* isso na primeira chamada de rede é o pior momento possível.
|
|
261
343
|
*
|
|
@@ -266,6 +348,10 @@ export function checkTrackerPort(port) {
|
|
|
266
348
|
const problemas = [];
|
|
267
349
|
if (!port || typeof port !== 'object') return ['porta de tracker ausente'];
|
|
268
350
|
if (!port.kind) problemas.push('porta de tracker sem `kind`');
|
|
351
|
+
// Aqui, e não só no teste da suíte: o invariante existe para os plugins que
|
|
352
|
+
// ainda não existem, e um plugin de terceiro com `keyPattern` permissivo
|
|
353
|
+
// precisa reprovar na CARGA, onde nenhum teste nosso o alcança.
|
|
354
|
+
problemas.push(...checkKeyPattern(port.capabilities?.identity?.keyPattern));
|
|
269
355
|
for (const op of trackerRequiredOperations(port.capabilities || {})) {
|
|
270
356
|
if (typeof port[op] !== 'function') {
|
|
271
357
|
problemas.push(`operação "${op}" exigida pelas capabilities e ausente na porta ${port.kind}`);
|
package/src/ports/types.mjs
CHANGED
|
@@ -21,6 +21,35 @@
|
|
|
21
21
|
* @property {string} key Identificador humano e PÚBLICO: `"123"` no GitHub,
|
|
22
22
|
* `"PROJ-123"` no Jira. É o que vai para nome de branch, corpo de PR, trailer
|
|
23
23
|
* de commit e nome de arquivo.
|
|
24
|
+
*
|
|
25
|
+
* ⚠️ **O que a PORTA devolve nunca contém `#`.** Invariante do contrato, não
|
|
26
|
+
* característica dos trackers que por acaso existem hoje — e ele já valia por
|
|
27
|
+
* omissão, que é o problema. Cobrado na carga por `checkKeyPattern`, contra o
|
|
28
|
+
* `identity.keyPattern` que o plugin declara.
|
|
29
|
+
*
|
|
30
|
+
* O escopo é a PORTA de propósito: `refKey()` é tolerante por desenho (aceita
|
|
31
|
+
* ref, número, `'#42'`, `'42'`) e NORMALIZA sem validar — `refKey('4#2')`
|
|
32
|
+
* devolve `'4#2'`. Endurecê-la seria mudar o comportamento da função mais
|
|
33
|
+
* carregada do core para tratar entrada que nenhum tracker produz. Quem
|
|
34
|
+
* garante o invariante é o plugin, na origem; `refKey` só traduz o que já
|
|
35
|
+
* chegou.
|
|
36
|
+
*
|
|
37
|
+
* Em três lugares `#` é SIGILO ou separador em texto que o fluxo gera e
|
|
38
|
+
* reanalisa depois: `refKey()` (`lib/work-item-ref.mjs`) descarta um
|
|
39
|
+
* `#` inicial porque ali ele é o prefixo da referência e não parte da chave;
|
|
40
|
+
* `Depende de: #4, #5` é escrito no corpo das Stories e lido de volta por
|
|
41
|
+
* `lib/dependencies.mjs`; e `owner/repo#n` sai no `closingKeyword` em
|
|
42
|
+
* multi-repo. Uma chave com `#` tornaria `#A#B` indistinguível de duas
|
|
43
|
+
* referências, e o estrago apareceria como dependência que some — não como
|
|
44
|
+
* erro.
|
|
45
|
+
*
|
|
46
|
+
* Isto é o irmão que faltava de `capabilities.identity.branchSafe`: aquele
|
|
47
|
+
* diz que a chave pode ir crua para um NOME DE BRANCH, com `branchToken`
|
|
48
|
+
* obrigatório quando não pode. São dois destinos com exigências diferentes,
|
|
49
|
+
* e o contrato só descrevia um. A referência TEXTUAL não ganha um par
|
|
50
|
+
* `refSafe`/`refToken` porque não há fornecedor conhecido que precise dele:
|
|
51
|
+
* proibir é mais barato que parametrizar, e a assimetria fica registrada
|
|
52
|
+
* aqui para o dia em que alguém precisar do contrário.
|
|
24
53
|
* @property {string|null} id Opaco do fornecedor (node id no GitHub). Nunca
|
|
25
54
|
* exibido, nunca escrito em documento.
|
|
26
55
|
* @property {string|null} url Endereço navegável.
|
package/src/setup/files.mjs
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { WORKFLOW_FILES, CODE_WORKFLOW_FILES } from '../config.mjs';
|
|
2
|
-
import { createGithubScm
|
|
2
|
+
import { createGithubScm } from '../plugins/scm-github/index.mjs';
|
|
3
|
+
import { resolveScmLink } from '../ports/index.mjs';
|
|
3
4
|
// readTemplate resolve {{CLI_VERSION}} — é o que fixa a versão da CLI nos
|
|
4
5
|
// workflows gravados no repo-alvo (ver src/lib/templates.mjs).
|
|
5
6
|
import { readTemplate } from '../lib/templates.mjs';
|
|
@@ -45,7 +46,7 @@ export async function setupFiles(token, owner, repo, spinner, { role = 'hub', po
|
|
|
45
46
|
// `repoFilesFor` continua no CORE: QUAL papel recebe QUAIS arquivos é regra
|
|
46
47
|
// de fluxo (RFC-005 §7.5). O que saiu para o plugin foi a gravação — e o
|
|
47
48
|
// conteúdo dos templates, que é formato de motor de automação, não de fluxo.
|
|
48
|
-
const scm = port || createGithubScm({ link:
|
|
49
|
+
const scm = port || createGithubScm({ link: resolveScmLink({ owner, repo, role }), token });
|
|
49
50
|
|
|
50
51
|
spinner.message('Verificando repositório...');
|
|
51
52
|
const initialized = await scm.isInitialized();
|