@spec-wave/cli 1.0.8 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/package.json +1 -1
  2. package/src/api/github-graphql.mjs +51 -0
  3. package/src/api/github-rest.mjs +48 -0
  4. package/src/commands/audit.mjs +24 -18
  5. package/src/commands/code-review.mjs +89 -58
  6. package/src/commands/decompose.mjs +254 -218
  7. package/src/commands/generate-bug.mjs +51 -44
  8. package/src/commands/generate-plan.mjs +83 -63
  9. package/src/commands/generate-qa-plan.mjs +144 -117
  10. package/src/commands/generate-spec.mjs +33 -28
  11. package/src/commands/implement.mjs +154 -79
  12. package/src/commands/init.mjs +8 -3
  13. package/src/commands/issue.mjs +26 -39
  14. package/src/commands/merge.mjs +71 -20
  15. package/src/commands/mode.mjs +8 -4
  16. package/src/commands/move.mjs +16 -20
  17. package/src/commands/order.mjs +33 -22
  18. package/src/commands/preflight.mjs +24 -13
  19. package/src/commands/qa-lead.mjs +28 -16
  20. package/src/commands/qa-run.mjs +122 -101
  21. package/src/commands/qa.mjs +55 -44
  22. package/src/commands/refresh.mjs +24 -16
  23. package/src/commands/repair-stage.mjs +29 -16
  24. package/src/commands/repo.mjs +10 -3
  25. package/src/commands/run.mjs +23 -11
  26. package/src/commands/story.mjs +20 -25
  27. package/src/commands/task.mjs +21 -27
  28. package/src/commands/triage.mjs +33 -31
  29. package/src/commands/uninstall.mjs +7 -3
  30. package/src/commands/update.mjs +29 -21
  31. package/src/commands/validate.mjs +60 -52
  32. package/src/commands/workspace.mjs +7 -5
  33. package/src/config.mjs +7 -1
  34. package/src/lib/artifact-publish.mjs +20 -18
  35. package/src/lib/board-policy.mjs +144 -0
  36. package/src/lib/board.mjs +134 -233
  37. package/src/lib/doc-availability.mjs +10 -3
  38. package/src/lib/doc-source.mjs +9 -9
  39. package/src/lib/implement-board.mjs +23 -26
  40. package/src/lib/issue-type.mjs +5 -1
  41. package/src/lib/pr-ready.mjs +48 -10
  42. package/src/lib/pr-step.mjs +3 -1
  43. package/src/lib/qa-exec.mjs +3 -1
  44. package/src/lib/qa-lead.mjs +11 -3
  45. package/src/lib/qa-plan-doc.mjs +10 -4
  46. package/src/lib/spec-audit.mjs +1 -1
  47. package/src/lib/story-graph.mjs +62 -8
  48. package/src/lib/usage-report.mjs +8 -5
  49. package/src/lib/work-item-ref.mjs +176 -0
  50. package/src/plugin/.claude-plugin/plugin.json +1 -1
  51. package/src/plugins/scm-github/index.mjs +439 -0
  52. package/src/plugins/tracker-github-projects/fields.mjs +73 -0
  53. package/src/plugins/tracker-github-projects/index.mjs +662 -0
  54. package/src/ports/scm.mjs +197 -0
  55. package/src/ports/tracker.mjs +280 -0
  56. package/src/ports/types.mjs +295 -0
  57. package/src/setup/files.mjs +14 -12
  58. package/src/setup/labels.mjs +17 -12
  59. package/src/setup/project.mjs +40 -59
@@ -0,0 +1,176 @@
1
+ // Identidade de um work item (RFC-006 §4) — módulo PURO, sem imports.
2
+ //
3
+ // Hoje a identidade é `issueNumber: number`, e ela atravessa tudo: assinatura
4
+ // de ~30 comandos, `spec-wave/<n>-<sufixo>`, `Closes #N`, `Depende de: #4, #5`,
5
+ // os trailers de commit, `.git/spec-wave/run-<n>.lock`, `.spec-wave/qa-<n>.md`.
6
+ // Num tracker que não seja o GitHub a chave não é número: no Jira é `PROJ-123`.
7
+ //
8
+ // As três partes, e por que são três:
9
+ //
10
+ // • `key` — o identificador HUMANO e PÚBLICO. É o que vai para nome de
11
+ // branch, corpo de PR, trailer de commit e nome de arquivo. É **string
12
+ // inclusive no GitHub**: manter `number` aqui e `string` no Jira duplicaria
13
+ // cada comparação e cada chave de mapa do core, que é exatamente o custo que
14
+ // esta fase existe para não pagar duas vezes.
15
+ //
16
+ // • `id` — o OPACO do fornecedor (node id `I_kwDO…` no GitHub, id numérico
17
+ // no Jira). Nunca exibido, nunca escrito em documento. Existe porque o
18
+ // vínculo nativo PR↔item do GitHub consome o node id, não o número — sem um
19
+ // lugar para guardá-lo, `findPullRequestsReferencing` perderia a precisão
20
+ // que tem hoje.
21
+ //
22
+ // • `url` — o endereço navegável. É o que entra no corpo do PR de artefato,
23
+ // justamente para NÃO entrar um `#N` que fecharia a issue no merge.
24
+ //
25
+ // Por que tudo aqui é puro e sem import: é o mesmo motivo de `artifact-pr.mjs`
26
+ // e `pr-branch.mjs` — a suíte não tem mock de HTTP, então as DECISÕES ficam
27
+ // separadas das chamadas de rede. Aqui não há nem o que decidir sobre rede.
28
+
29
+ /** Uma chave é numérica? (é o `identity.keyIsNumeric` do manifesto) */
30
+ const NUMERICA = /^\d+$/;
31
+
32
+ /**
33
+ * Normaliza a chave vinda de qualquer entrada humana ou de máquina.
34
+ *
35
+ * Tolerante de propósito: o número chega como argumento de CLI (`42`), como
36
+ * `#42` digitado por gente, e como string de payload de evento do Actions. Os
37
+ * três são a mesma issue, e obrigar o chamador a normalizar é como o `#` acabou
38
+ * vazando para dentro de nome de branch mais de uma vez.
39
+ *
40
+ * NÃO faz parse numérico: `parseInt` transformaria `1.5` em `1` e `42abc` em
41
+ * `42`, isto é, apontaria para OUTRO work item sem nenhum sinal. Quem precisa
42
+ * de número pede `refNumber`, que recusa o que não for chave numérica inteira.
43
+ *
44
+ * MAS zero à esquerda é insignificante numa chave numérica, e não normalizá-lo
45
+ * aqui é o mesmo bug que o `#` teve: `'007'` e `7` são a mesma issue e comparam
46
+ * diferente, então viram DUAS entradas em qualquer Map e DOIS nomes de arquivo.
47
+ * Foi assim que `run 007` abriu um segundo lock para a issue que `run 7` já
48
+ * estava processando. Só para chave puramente numérica: `PROJ-007` fica intacta,
49
+ * porque ali o zero pode ser parte do identificador do fornecedor.
50
+ *
51
+ * @param {WorkItemRef|string|number|null|undefined} valor
52
+ * @returns {string} chave normalizada; '' quando não há nada aproveitável
53
+ */
54
+ export function refKey(valor) {
55
+ if (valor == null) return '';
56
+ // Já é um ref: a chave dele já passou por aqui.
57
+ const bruta = typeof valor === 'object'
58
+ ? String(valor.key ?? '').trim()
59
+ : String(valor).trim().replace(/^#/, '').trim();
60
+ // `'000'` vira `'0'`, não `''`: uma chave inválida tem de continuar existindo
61
+ // para `isNumericKey` recusá-la com o valor que o usuário digitou.
62
+ if (NUMERICA.test(bruta)) return bruta.replace(/^0+(?=\d)/, '');
63
+ return bruta;
64
+ }
65
+
66
+ /**
67
+ * A chave é um inteiro positivo? (função PURA)
68
+ *
69
+ * É o predicado por trás de `capabilities.identity.keyIsNumeric`. No GitHub é
70
+ * sempre true, e é o que autoriza o core a continuar aceitando `#N` na entrada
71
+ * e a ordenar numericamente.
72
+ *
73
+ * @param {WorkItemRef|string|number|null} valor
74
+ * @returns {boolean}
75
+ */
76
+ export function isNumericKey(valor) {
77
+ const k = refKey(valor);
78
+ return NUMERICA.test(k) && Number.parseInt(k, 10) > 0;
79
+ }
80
+
81
+ /**
82
+ * Constrói um WorkItemRef normalizado (função PURA).
83
+ *
84
+ * @param {object} params
85
+ * @param {string|number} params.key chave pública; `#42`, `42` e `'42'` são a mesma
86
+ * @param {string|null} [params.id] opaco do fornecedor
87
+ * @param {string|null} [params.url] endereço navegável
88
+ * @returns {{key: string, id: string|null, url: string|null}}
89
+ * @throws {Error} chave vazia — um ref sem chave não endereça nada, e deixá-lo
90
+ * nascer só adia o erro para o nome de branch ou para a chamada de rede.
91
+ */
92
+ export function workItemRef({ key, id = null, url = null } = {}) {
93
+ const k = refKey(key);
94
+ if (!k) {
95
+ throw new Error(`Chave de work item inválida: ${JSON.stringify(key)}.`);
96
+ }
97
+ return { key: k, id: id ?? null, url: url ?? null };
98
+ }
99
+
100
+ /**
101
+ * A chave como NÚMERO — a ponte para as APIs do GitHub (função PURA).
102
+ *
103
+ * Toda a REST de issues do GitHub fala `issue_number: number`. Esta função é o
104
+ * único ponto onde a conversão acontece, e ela RECUSA o que não for chave
105
+ * numérica em vez de devolver `NaN`: um `NaN` chegando na API vira 404, e um
106
+ * 404 aqui seria lido como "a issue não existe" em vez de "este tracker não usa
107
+ * chave numérica".
108
+ *
109
+ * @param {WorkItemRef|string|number} valor
110
+ * @returns {number}
111
+ * @throws {Error} quando a chave não é um inteiro positivo
112
+ */
113
+ export function refNumber(valor) {
114
+ const k = refKey(valor);
115
+ if (!isNumericKey(k)) {
116
+ throw new Error(
117
+ `A chave "${k || valor}" não é numérica, e esta operação é do GitHub, ` +
118
+ 'que endereça issues por número. Se o tracker não usa chave numérica, ' +
119
+ 'a operação precisa passar pela porta (capabilities.identity.keyIsNumeric).'
120
+ );
121
+ }
122
+ return Number.parseInt(k, 10);
123
+ }
124
+
125
+ /**
126
+ * A chave como o usuário a lê: `#42` no GitHub, `PROJ-123` no Jira (PURA).
127
+ *
128
+ * A forma `#N` é sintaxe do GitHub, não do spec-wave — por isso ela só é
129
+ * aplicada a chave numérica. Uma chave que já carrega o projeto (`PROJ-123`)
130
+ * seria deformada por um `#` na frente, e é essa deformação que apareceria em
131
+ * comentário de issue e em mensagem de erro.
132
+ *
133
+ * @param {WorkItemRef|string|number} valor
134
+ * @returns {string} '' quando não há chave
135
+ */
136
+ export function formatRef(valor) {
137
+ const k = refKey(valor);
138
+ if (!k) return '';
139
+ return isNumericKey(k) ? `#${k}` : k;
140
+ }
141
+
142
+ /**
143
+ * Duas referências apontam para o mesmo work item? (função PURA)
144
+ *
145
+ * Compara pela `key`, nunca pelo `id`: o mesmo item lido por caminhos
146
+ * diferentes pode vir com `id` preenchido de um lado e null do outro (a busca
147
+ * por tag devolve o node id; um `#N` digitado pelo usuário não devolve nada).
148
+ *
149
+ * @param {WorkItemRef|string|number} a
150
+ * @param {WorkItemRef|string|number} b
151
+ * @returns {boolean}
152
+ */
153
+ export function sameWorkItem(a, b) {
154
+ const ka = refKey(a);
155
+ return Boolean(ka) && ka === refKey(b);
156
+ }
157
+
158
+ /**
159
+ * Comparador de ordenação para chaves de work item (função PURA).
160
+ *
161
+ * Numérico quando as duas chaves são numéricas, lexicográfico no resto. Existe
162
+ * porque `a.number - b.number` está espalhado pelo core e, em string, `'9'`
163
+ * vem depois de `'10'` — a ordem do board sairia embaralhada sem nenhum erro.
164
+ *
165
+ * @param {WorkItemRef|string|number} a
166
+ * @param {WorkItemRef|string|number} b
167
+ * @returns {number}
168
+ */
169
+ export function compareKeys(a, b) {
170
+ const ka = refKey(a);
171
+ const kb = refKey(b);
172
+ if (isNumericKey(ka) && isNumericKey(kb)) {
173
+ return Number.parseInt(ka, 10) - Number.parseInt(kb, 10);
174
+ }
175
+ return ka < kb ? -1 : ka > kb ? 1 : 0;
176
+ }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.0.8",
4
+ "version": "1.2.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,439 @@
1
+ // Porta de SCM sobre o GitHub.
2
+ //
3
+ // ⚠️ REGRA DA FASE 1: `src/api/github-*.mjs` NÃO É EDITADO. Toda operação aqui
4
+ // é um forward de ≤3 linhas para um export que já existe. É o que torna
5
+ // "nenhuma mudança de comportamento" verificável em vez de esperançoso — a
6
+ // camada HTTP é literalmente os mesmos bytes, e todo o diff desta fase é sobre
7
+ // quem chama quem.
8
+ //
9
+ // Dois corolários que valem grep:
10
+ // • sem memoização que altere CONTAGEM de chamadas (mudaria retry, cota e
11
+ // net-cache de um jeito que nenhum teste enxerga);
12
+ // • sem reuso de instância Octokit — `makeOctokit(token)` continua nascendo
13
+ // por chamada, lá dentro.
14
+ //
15
+ // **Uma instância é UM repositório.** Em arquivo que lida com mais de um
16
+ // (`merge`, `code-review`, `qa`, `pr-ready`), identificador `scm` pelado é
17
+ // proibido: `hubScm`, `prScm`, `scmFor(link)`. Uma variável errada abre PR no
18
+ // repositório errado, e isso nenhum teste pega.
19
+
20
+ import { Octokit } from '@octokit/rest';
21
+
22
+ import {
23
+ commitFilesToBranch,
24
+ compareBranches,
25
+ deleteBranch,
26
+ deleteFile,
27
+ ensurePullRequest,
28
+ getBranchHead,
29
+ getFileContent,
30
+ getPR,
31
+ getRepoDefaultBranch,
32
+ getRepoNodeId,
33
+ getRepoVariable,
34
+ deleteRepoVariable,
35
+ isRepoInitialized,
36
+ listPullRequestCommitMessages,
37
+ listPullRequestReviews,
38
+ mergePR,
39
+ findOpenPR,
40
+ setRepoVariable,
41
+ updatePRBase,
42
+ upsertFile,
43
+ } from '../../api/github-rest.mjs';
44
+ import {
45
+ getPRClosingIssues,
46
+ getRateLimit,
47
+ listIssuePullRequests,
48
+ listOpenPullRequests,
49
+ markPullRequestReadyForReview,
50
+ } from '../../api/github-graphql.mjs';
51
+ import { refKey, refNumber } from '../../lib/work-item-ref.mjs';
52
+
53
+ /** @typedef {import('../../ports/types.mjs').ScmLink} ScmLink */
54
+ /** @typedef {import('../../ports/scm.mjs').ScmPort} ScmPort */
55
+
56
+ /** `kind` deste plugin — o valor gravado em `scm.kind` do .spec-wave.json. */
57
+ export const SCM_KIND = 'github';
58
+
59
+ /**
60
+ * O que o GitHub sabe fazer, na forma do `rfc/protocol/scm.v1.json`.
61
+ *
62
+ * Congelado: o core LÊ isto para degradar, e uma capability que pudesse ser
63
+ * mutada em runtime seria um plugin ganhando poder depois da carga.
64
+ */
65
+ export const GITHUB_SCM_CAPABILITIES = Object.freeze({
66
+ fileWrites: Object.freeze({
67
+ mode: 'tree-commit-ref',
68
+ atomicMultiFile: true,
69
+ concurrentPublishRetry: true,
70
+ }),
71
+ pullRequests: Object.freeze({
72
+ draft: true,
73
+ retarget: true,
74
+ mergeStrategies: Object.freeze(['merge', 'squash', 'rebase']),
75
+ reviewModel: 'decision',
76
+ referenceSearch: true,
77
+ }),
78
+ variables: 'repo',
79
+ automation: 'github-actions',
80
+ remoteDispatch: Object.freeze({ mechanism: 'repository-dispatch' }),
81
+ identity: Object.freeze({
82
+ configKeys: Object.freeze(['owner', 'repo']),
83
+ branchNameConstraints: Object.freeze({ maxLength: 255 }),
84
+ }),
85
+ });
86
+
87
+ /**
88
+ * Monta o `ScmLink` de um par owner/repo (função PURA).
89
+ *
90
+ * O `id` é a chave estável do core para mapa, cache e deduplicação de PR. Leva
91
+ * o `kind` na frente porque um dia vão conviver dois fornecedores no mesmo
92
+ * workspace, e `acme/api` sozinho não diz de qual.
93
+ *
94
+ * @param {{owner: string, repo: string, role?: 'hub'|'code'}} params
95
+ * @returns {ScmLink}
96
+ */
97
+ export function githubLink({ owner, repo, role = 'hub' }) {
98
+ return {
99
+ id: `${SCM_KIND}:${owner}/${repo}`,
100
+ kind: SCM_KIND,
101
+ role,
102
+ label: `${owner}/${repo}`,
103
+ config: { owner, repo },
104
+ };
105
+ }
106
+
107
+ /** Normaliza o PR devolvido pela REST (`getPR`, `findOpenPR`). */
108
+ function prFromRest(raw, link) {
109
+ if (!raw) return null;
110
+ return {
111
+ id: raw.node_id || String(raw.id || ''),
112
+ number: String(raw.number),
113
+ url: raw.html_url || null,
114
+ title: raw.title || '',
115
+ body: raw.body || '',
116
+ state: raw.merged_at ? 'merged' : String(raw.state || 'open').toLowerCase(),
117
+ draft: Boolean(raw.draft),
118
+ baseRef: raw.base?.ref ?? raw.base ?? null,
119
+ headRef: raw.head?.ref ?? null,
120
+ createdAt: raw.created_at ?? null,
121
+ link,
122
+ };
123
+ }
124
+
125
+ /** Normaliza o PR devolvido pelo GraphQL (`listOpenPullRequests`, `listIssuePullRequests`). */
126
+ function prFromGraphql(raw, link) {
127
+ if (!raw) return null;
128
+ return {
129
+ id: raw.id,
130
+ number: String(raw.number),
131
+ url: raw.url || null,
132
+ title: raw.title || '',
133
+ body: raw.body || '',
134
+ state: raw.merged ? 'merged' : String(raw.state || 'open').toLowerCase(),
135
+ draft: Boolean(raw.isDraft),
136
+ baseRef: raw.baseRefName || null,
137
+ headRef: raw.headRefName || null,
138
+ createdAt: raw.createdAt ?? null,
139
+ link,
140
+ };
141
+ }
142
+
143
+ /**
144
+ * Normaliza uma run de workflow do Actions (função PURA — exportada p/ teste).
145
+ *
146
+ * `AutomationRun` é o tipo que uma pipeline do Azure DevOps também precisa
147
+ * caber; por isso `conclusion` é normalizada para o enum do contrato e o que
148
+ * não couber vira null em vez de vazar a string do fornecedor.
149
+ */
150
+ export function toAutomationRun(raw) {
151
+ const CONCLUSOES = ['success', 'failure', 'cancelled', 'skipped', 'timed_out', 'action_required'];
152
+ // `startup_failure` é o workflow que nem chegou a começar (YAML inválido,
153
+ // permissão faltando). É falha, e o remédio é o mesmo — um valor próprio
154
+ // significando "falhou, só que antes" não mudaria decisão nenhuma.
155
+ const SINONIMOS = { startup_failure: 'failure' };
156
+ const cru = String(raw?.conclusion || '').toLowerCase();
157
+ const conclusion = SINONIMOS[cru] || cru;
158
+ const status = String(raw?.status || '').toLowerCase();
159
+ return {
160
+ id: String(raw?.id ?? ''),
161
+ name: raw?.name || raw?.workflow_id || '',
162
+ status: ['queued', 'in_progress', 'completed'].includes(status) ? status : 'queued',
163
+ // `neutral` e `stale` caem aqui de propósito: "terminou sem veredito" já é
164
+ // o que `completed` + null diz, e inventar valor para eles só espalharia
165
+ // um caso que ninguém trata.
166
+ conclusion: CONCLUSOES.includes(conclusion) ? conclusion : null,
167
+ createdAt: raw?.created_at || '',
168
+ url: raw?.html_url || null,
169
+ headBranch: raw?.head_branch || null,
170
+ };
171
+ }
172
+
173
+ /**
174
+ * A cláusula de fechamento que liga um PR ao work item (função PURA).
175
+ *
176
+ * Duas regras, e as duas já existem no fluxo de hoje:
177
+ *
178
+ * • Tracker de outro fornecedor ⇒ `null`. `Closes #N` é sintaxe do GitHub, e o
179
+ * GitHub não fecha uma issue do Jira. Nesse caso o fechamento passa a ser
180
+ * explícito, pela porta de tracker — mais verboso e mais previsível que o
181
+ * efeito hoje implícito.
182
+ * • PR fora do hub ⇒ forma QUALIFICADA `owner/repo#n`. Com um hub e N repos de
183
+ * código (RFC-005) a issue vive no hub e o PR não; `#N` solto ali aponta
184
+ * para uma issue do repo de código — outra issue, ou nenhuma.
185
+ *
186
+ * @param {{ref: object, trackerKind: string, prLink: ScmLink, hubLink: ScmLink}} params
187
+ * @returns {string|null}
188
+ */
189
+ export function githubClosingKeyword({ ref, trackerKind, prLink, hubLink } = {}) {
190
+ if (trackerKind !== 'github-projects') return null;
191
+ const key = refKey(ref);
192
+ if (!key) return null;
193
+ const mesmoRepo = !prLink || !hubLink || prLink.id === hubLink.id;
194
+ return mesmoRepo ? `Closes #${key}` : `Closes ${hubLink.label}#${key}`;
195
+ }
196
+
197
+ /**
198
+ * Cria a porta de SCM do GitHub presa a UM repositório.
199
+ *
200
+ * @param {object} params
201
+ * @param {ScmLink} params.link repositório desta instância (ver githubLink)
202
+ * @param {string} params.token credencial padrão
203
+ * @param {string} [params.prToken] credencial usada SÓ para abrir Pull Request.
204
+ * Existe porque `GH_PR_TOKEN`/`SPEC_WAVE_PR_TOKEN` é o contorno de "Allow
205
+ * GitHub Actions to create and approve pull requests" desligado: o commit vai
206
+ * com o token do job, o PR não pode. Colapsar os dois quebraria a publicação
207
+ * de documento em toda organização com essa opção fechada.
208
+ * @param {string} [params.trackerKind] com qual tracker esta instância foi
209
+ * pareada. Injetado pelo CORE: nenhum plugin de SCM sabe isso sozinho, e é
210
+ * disso que `closingKeyword` e o vínculo nativo dependem.
211
+ * @param {object} [params.api] injeção para teste — mesmo seam do `deps = {}`
212
+ * que `lib/artifact-publish.mjs` já usa.
213
+ * @returns {ScmPort}
214
+ */
215
+ export function createGithubScm({ link, token, prToken, trackerKind = 'github-projects', api = {} } = {}) {
216
+ if (!link?.config?.owner || !link?.config?.repo) {
217
+ throw new Error('createGithubScm: `link` precisa de config.owner e config.repo (ver githubLink).');
218
+ }
219
+ const { owner, repo } = link.config;
220
+ const tk = prToken || token;
221
+
222
+ const a = {
223
+ commitFilesToBranch, compareBranches, deleteBranch, deleteFile, ensurePullRequest,
224
+ getBranchHead, getFileContent, getPR, getRepoDefaultBranch, getRepoNodeId,
225
+ getRepoVariable, deleteRepoVariable, isRepoInitialized, listPullRequestCommitMessages,
226
+ listPullRequestReviews, mergePR, findOpenPR, setRepoVariable, updatePRBase, upsertFile,
227
+ getPRClosingIssues, getRateLimit, listIssuePullRequests, listOpenPullRequests,
228
+ markPullRequestReadyForReview,
229
+ ...api,
230
+ };
231
+
232
+ return {
233
+ kind: SCM_KIND,
234
+ link,
235
+ capabilities: GITHUB_SCM_CAPABILITIES,
236
+
237
+ async setup() {
238
+ // O GitHub não precisa de provisionamento de repositório: ele já existe
239
+ // (é onde o comando roda). A automação é publicada por installAutomation.
240
+ return { warnings: [] };
241
+ },
242
+
243
+ async verify() {
244
+ const problems = [];
245
+ const facts = {};
246
+ // Sonda de alcance: é o que `commands/repo.mjs` já faz hoje, chamando
247
+ // getRepoNodeId e descartando o retorno. O que importa é o 404/403.
248
+ try {
249
+ facts.repoNodeId = await a.getRepoNodeId(token, owner, repo);
250
+ } catch (err) {
251
+ problems.push(`repositório ${link.label} inacessível: ${err.message}`);
252
+ }
253
+ const quota = (await a.getRateLimit(token)) || {};
254
+ return {
255
+ ok: problems.length === 0,
256
+ quota: {
257
+ remaining: quota.remaining ?? null,
258
+ limit: quota.limit ?? null,
259
+ resetAt: quota.resetAt ?? null,
260
+ },
261
+ facts,
262
+ problems,
263
+ };
264
+ },
265
+
266
+ defaultBranch() {
267
+ return a.getRepoDefaultBranch(token, owner, repo);
268
+ },
269
+
270
+ isInitialized() {
271
+ return a.isRepoInitialized(token, owner, repo);
272
+ },
273
+
274
+ readFile({ path: p, ref } = {}) {
275
+ return a.getFileContent(token, owner, repo, p, ref);
276
+ },
277
+
278
+ writeFiles({ branch, base, files, message } = {}) {
279
+ return a.commitFilesToBranch(token, owner, repo, {
280
+ branch, base, message,
281
+ files: (files || []).map(f => ({ path: f.path, content: f.content })),
282
+ });
283
+ },
284
+
285
+ deleteFile({ path: p, message } = {}) {
286
+ return a.deleteFile(token, owner, repo, p, message);
287
+ },
288
+
289
+ branchHead({ branch } = {}) {
290
+ return a.getBranchHead(token, owner, repo, branch);
291
+ },
292
+
293
+ compare({ base, head } = {}) {
294
+ return a.compareBranches(token, owner, repo, base, head);
295
+ },
296
+
297
+ deleteBranch({ branch } = {}) {
298
+ return a.deleteBranch(token, owner, repo, branch);
299
+ },
300
+
301
+ async findOpenPullRequest({ branch } = {}) {
302
+ const pr = await a.findOpenPR(token, owner, repo, branch);
303
+ // findOpenPR devolve {number, url, title, base} — forma enxuta própria.
304
+ return pr ? prFromRest({ ...pr, base: pr.base, html_url: pr.url }, link) : null;
305
+ },
306
+
307
+ async ensurePullRequest({ branch, base, title, body, draft = false } = {}) {
308
+ // prToken e SÓ aqui: é a única chamada que a política de credencial de PR
309
+ // cobre. Ver o parâmetro `prToken` acima.
310
+ const res = await a.ensurePullRequest(tk, owner, repo, { branch, base, title, body, draft });
311
+ if (!res) return { pr: null, created: false };
312
+ return {
313
+ pr: prFromRest({ ...res, html_url: res.url, base: res.base }, link),
314
+ created: Boolean(res.created),
315
+ };
316
+ },
317
+
318
+ async getPullRequest({ number } = {}) {
319
+ return prFromRest(await a.getPR(token, owner, repo, Number(number)), link);
320
+ },
321
+
322
+ listPullRequestCommitMessages({ number } = {}) {
323
+ return a.listPullRequestCommitMessages(token, owner, repo, Number(number));
324
+ },
325
+
326
+ async listPullRequestReviews({ number } = {}) {
327
+ const cruas = await a.listPullRequestReviews(token, owner, repo, Number(number));
328
+ // CRU por revisor: quem agrega é reviewDecision(), no core. Um plugin que
329
+ // normalizasse aqui faria dois plugins `vote` decidirem diferente.
330
+ return (cruas || []).map(r => ({
331
+ reviewer: r.user?.login || '',
332
+ submittedAt: r.submitted_at || null,
333
+ state: String(r.state || '').toUpperCase(),
334
+ }));
335
+ },
336
+
337
+ async listOpenPullRequests() {
338
+ const prs = await a.listOpenPullRequests(token, owner, repo);
339
+ return (prs || []).map(p => prFromGraphql(p, link));
340
+ },
341
+
342
+ mergePullRequest({ number, strategy = 'merge' } = {}) {
343
+ return a.mergePR(token, owner, repo, Number(number), { method: strategy });
344
+ },
345
+
346
+ closingKeyword({ ref, trackerKind: tkind, prLink, hubLink } = {}) {
347
+ return githubClosingKeyword({ ref, trackerKind: tkind ?? trackerKind, prLink, hubLink });
348
+ },
349
+
350
+ fileUrl({ ref, pathRel } = {}) {
351
+ // A ref NÃO é escapada de propósito: branch com `/` (feat/x) funciona crua
352
+ // na URL do GitHub, e encodeURIComponent a quebraria.
353
+ return `https://github.com/${owner}/${repo}/blob/${ref}/${pathRel}`;
354
+ },
355
+
356
+ async listAutomationRuns({ branch, limit = 20 } = {}) {
357
+ const octokit = new Octokit({ auth: token });
358
+ const res = await octokit.request('GET /repos/{owner}/{repo}/actions/runs', {
359
+ owner, repo, per_page: limit, ...(branch ? { branch } : {}),
360
+ });
361
+ return (res.data?.workflow_runs || []).map(toAutomationRun);
362
+ },
363
+
364
+ markReadyForReview({ id } = {}) {
365
+ // Só existe em GraphQL: a REST ignora o PATCH de `draft` em silêncio, que
366
+ // é pior que recusar.
367
+ return a.markPullRequestReadyForReview(token, id);
368
+ },
369
+
370
+ setPullRequestBase({ number, base } = {}) {
371
+ return a.updatePRBase(token, owner, repo, Number(number), base);
372
+ },
373
+
374
+ async findPullRequestsReferencing({ ref } = {}) {
375
+ // Vínculo NATIVO quando o tracker também é GitHub — é o
376
+ // `closedByPullRequestsReferences` alimentado por `Closes #N`, e é o que
377
+ // dá a precisão de hoje (zero regressão). Consome o NODE ID, que é a
378
+ // razão de WorkItemRef carregar um opaco.
379
+ if (trackerKind === 'github-projects' && ref?.id) {
380
+ const prs = await a.listIssuePullRequests(token, ref.id);
381
+ return (prs || []).map(p => prFromGraphql(p, link));
382
+ }
383
+ // Qualquer outra combinação: busca nos PRs abertos e casamento da chave,
384
+ // sob a política de `codeReview.linkMode` que já existe.
385
+ const key = refKey(ref);
386
+ if (!key) return [];
387
+ const abertos = await a.listOpenPullRequests(token, owner, repo);
388
+ return (abertos || [])
389
+ .filter(p => new RegExp(`#${key}\\b`).test(p.body || ''))
390
+ .map(p => prFromGraphql(p, link));
391
+ },
392
+
393
+ /**
394
+ * Os work items que o GitHub reconhece como fechados por este PR — a
395
+ * inversa de findPullRequestsReferencing, pela mesma fonte de vínculo.
396
+ */
397
+ async getPullRequestClosingWorkItems({ number } = {}) {
398
+ const nums = await a.getPRClosingIssues(token, owner, repo, Number(number));
399
+ return (nums || []).map(n => String(n));
400
+ },
401
+
402
+ getVariable({ name } = {}) {
403
+ return a.getRepoVariable(token, owner, repo, name);
404
+ },
405
+
406
+ setVariable({ name, value } = {}) {
407
+ return a.setRepoVariable(token, owner, repo, name, value);
408
+ },
409
+
410
+ deleteVariable({ name } = {}) {
411
+ return a.deleteRepoVariable(token, owner, repo, name);
412
+ },
413
+
414
+ async installAutomation({ files = [], log } = {}) {
415
+ // upsertFile e não writeFiles de propósito: o `init` commita DIRETO na
416
+ // branch default, um commit por arquivo. Trocar por um commit atômico
417
+ // mudaria o histórico observável do init — e esta fase não muda
418
+ // comportamento. A unificação é da Fase 2.
419
+ const written = [];
420
+ for (let i = 0; i < files.length; i++) {
421
+ const f = files[i];
422
+ log?.({ index: i, total: files.length, path: f.path });
423
+ await a.upsertFile(token, owner, repo, f.path, f.content, f.message);
424
+ written.push(f.path);
425
+ }
426
+ return { written, skipped: [] };
427
+ },
428
+
429
+ async dispatch({ action, key } = {}) {
430
+ const octokit = new Octokit({ auth: token });
431
+ await octokit.request('POST /repos/{owner}/{repo}/dispatches', {
432
+ owner, repo, event_type: action, client_payload: { action, key: refKey(key) },
433
+ });
434
+ },
435
+ };
436
+ }
437
+
438
+ /** Reexportado para quem precisa converter chave → número na fronteira. */
439
+ export { refNumber };
@@ -0,0 +1,73 @@
1
+ // Endereçamento de campo do GitHub Projects v2 — o que SAI do core.
2
+ //
3
+ // O core fala nomes CANÔNICOS (`workItemType`); o Projects v2 endereça por
4
+ // rótulo de exibição ("Work Item Type"), id de campo e id de OPÇÃO. Traduzir é
5
+ // o que um `fieldMap` de Jira faria, e é por isso que esta tradução mora no
6
+ // plugin e não em `lib/board.mjs`.
7
+ //
8
+ // Aqui também vive `resolveField`, que saiu de `lib/board.mjs:49` sem mudar de
9
+ // corpo, incluindo o caminho LEGADO (`etapaFieldId`/`stageOptions`). Esse
10
+ // caminho não é código morto: é o formato que o `init` da 0.16.4 gravou, e o
11
+ // spec-wave-agent ainda tem um `.spec-wave.json` daquela época.
12
+
13
+ import { getSingleSelectField } from '../../api/github-graphql.mjs';
14
+
15
+ /**
16
+ * Nome canônico → rótulo de exibição do campo no board.
17
+ *
18
+ * `stage` e `progress` entram aqui mesmo não sendo `FieldName`: os três são
19
+ * endereçados do mesmo jeito no Projects v2 (single-select com opções), e
20
+ * separá-los criaria duas tabelas com a mesma forma.
21
+ */
22
+ export const FIELD_LABEL = Object.freeze({
23
+ stage: 'Etapa',
24
+ progress: 'Status',
25
+ workItemType: 'Work Item Type',
26
+ priority: 'Priority',
27
+ storyPoints: 'Story Points',
28
+ area: 'Area',
29
+ release: 'Release',
30
+ });
31
+
32
+ /** Rótulo de exibição → nome canônico (o inverso, para ler o snapshot). */
33
+ export const FIELD_CANONICAL = Object.freeze(
34
+ Object.fromEntries(Object.entries(FIELD_LABEL).map(([canonico, rotulo]) => [rotulo, canonico]))
35
+ );
36
+
37
+ /**
38
+ * Resolve um campo SINGLE_SELECT pelo nome canônico.
39
+ *
40
+ * Três fontes, nesta ordem — e a ordem é a razão de a função existir:
41
+ * 1. os ids gravados em `project.fields` pelo `init`/`refresh` (sem rede);
42
+ * 2. o formato LEGADO `etapaFieldId`/`stageOptions`, só para "Etapa";
43
+ * 3. a API, como último recurso.
44
+ *
45
+ * @param {object} params
46
+ * @param {string} params.token credencial com escopo de project
47
+ * @param {object} params.project bloco `project` do .spec-wave.json
48
+ * @param {string} params.field nome canônico (chave de FIELD_LABEL)
49
+ * @returns {Promise<{id: string, options: Record<string,string>}|null>}
50
+ */
51
+ export async function resolveField({ token, project, field }) {
52
+ const rotulo = FIELD_LABEL[field] || field;
53
+ if (project?.fields?.[rotulo]) return project.fields[rotulo];
54
+ if (rotulo === 'Etapa' && project?.etapaFieldId) {
55
+ return { id: project.etapaFieldId, options: project.stageOptions || {} };
56
+ }
57
+ return await getSingleSelectField(token, project.id, rotulo);
58
+ }
59
+
60
+ /**
61
+ * O id da opção `valor` dentro de um campo (função PURA).
62
+ *
63
+ * Devolve null quando a opção não existe — quem chama decide se isso é board
64
+ * divergente (a Etapa, onde é erro nomeado) ou campo opcional (o resto, onde
65
+ * é no-op).
66
+ *
67
+ * @param {{options?: Record<string,string>}|null} campo
68
+ * @param {string} valor
69
+ * @returns {string|null}
70
+ */
71
+ export function optionId(campo, valor) {
72
+ return campo?.options?.[valor] ?? null;
73
+ }