@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.
@@ -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,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, githubLink } from '../plugins/scm-github/index.mjs';
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: githubLink({ owner: r.owner, repo: r.repo, role: sameRepoQue(r, hub) ? 'hub' : 'code' }),
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: githubLink({ ...r, role: sameRepoQue(pr.repo, hub) ? 'hub' : 'code' }),
179
+ link: resolveScmLink({ ...r, role: sameRepoQue(pr.repo, hub) ? 'hub' : 'code' }),
179
180
  token,
180
181
  });
181
182
  };
@@ -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.2.0",
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
+ }
@@ -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 duas checagens são baratas, e um
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}`);
@@ -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.
@@ -1,5 +1,6 @@
1
1
  import { WORKFLOW_FILES, CODE_WORKFLOW_FILES } from '../config.mjs';
2
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
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: githubLink({ owner, repo, role }), token });
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();