@spec-wave/cli 1.3.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.3.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",
@@ -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
+ }
@@ -288,10 +288,56 @@ export function trackerRequiredOperations(capabilities = {}) {
288
288
  return [...exigidas];
289
289
  }
290
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
+
291
337
  /**
292
338
  * Confere um plugin de tracker contra as capabilities que ele declara.
293
339
  *
294
- * 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
295
341
  * plugin publicado independentemente VAI ficar para trás do core — descobrir
296
342
  * isso na primeira chamada de rede é o pior momento possível.
297
343
  *
@@ -302,6 +348,10 @@ export function checkTrackerPort(port) {
302
348
  const problemas = [];
303
349
  if (!port || typeof port !== 'object') return ['porta de tracker ausente'];
304
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));
305
355
  for (const op of trackerRequiredOperations(port.capabilities || {})) {
306
356
  if (typeof port[op] !== 'function') {
307
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();