@spec-wave/cli 1.0.7 → 1.1.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 (68) hide show
  1. package/package.json +1 -1
  2. package/src/commands/audit.mjs +24 -18
  3. package/src/commands/code-review.mjs +91 -59
  4. package/src/commands/decompose.mjs +258 -221
  5. package/src/commands/doctor.mjs +16 -11
  6. package/src/commands/generate-bug.mjs +51 -44
  7. package/src/commands/generate-plan.mjs +83 -63
  8. package/src/commands/generate-qa-plan.mjs +145 -117
  9. package/src/commands/generate-spec.mjs +33 -28
  10. package/src/commands/implement.mjs +155 -79
  11. package/src/commands/info.mjs +4 -3
  12. package/src/commands/init.mjs +11 -5
  13. package/src/commands/install-skill.mjs +19 -0
  14. package/src/commands/issue.mjs +26 -39
  15. package/src/commands/merge.mjs +71 -20
  16. package/src/commands/mode.mjs +11 -6
  17. package/src/commands/move.mjs +16 -20
  18. package/src/commands/order.mjs +33 -22
  19. package/src/commands/preflight.mjs +24 -13
  20. package/src/commands/qa-lead.mjs +30 -17
  21. package/src/commands/qa-run.mjs +125 -103
  22. package/src/commands/qa.mjs +55 -44
  23. package/src/commands/refresh.mjs +24 -16
  24. package/src/commands/repair-stage.mjs +29 -16
  25. package/src/commands/repo.mjs +12 -4
  26. package/src/commands/run.mjs +23 -11
  27. package/src/commands/story.mjs +20 -25
  28. package/src/commands/task.mjs +21 -27
  29. package/src/commands/triage.mjs +33 -31
  30. package/src/commands/uninstall.mjs +7 -3
  31. package/src/commands/update.mjs +31 -22
  32. package/src/commands/validate.mjs +60 -52
  33. package/src/commands/workspace.mjs +7 -5
  34. package/src/config.mjs +7 -1
  35. package/src/lib/artifact-publish.mjs +20 -18
  36. package/src/lib/board-policy.mjs +144 -0
  37. package/src/lib/board.mjs +134 -233
  38. package/src/lib/cli-ref.mjs +75 -0
  39. package/src/lib/config-file.mjs +2 -1
  40. package/src/lib/doc-availability.mjs +10 -3
  41. package/src/lib/doc-source.mjs +9 -9
  42. package/src/lib/execution-mode.mjs +5 -3
  43. package/src/lib/implement-board.mjs +23 -26
  44. package/src/lib/issue-type.mjs +5 -1
  45. package/src/lib/plugin-skills.mjs +10 -0
  46. package/src/lib/pr-ready.mjs +48 -10
  47. package/src/lib/pr-step.mjs +3 -1
  48. package/src/lib/qa-exec.mjs +3 -1
  49. package/src/lib/qa-lead.mjs +11 -3
  50. package/src/lib/qa-plan-doc.mjs +10 -4
  51. package/src/lib/qa-report.mjs +2 -1
  52. package/src/lib/skill-compose.mjs +3 -0
  53. package/src/lib/spec-audit.mjs +1 -1
  54. package/src/lib/story-graph.mjs +62 -8
  55. package/src/lib/usage-report.mjs +8 -5
  56. package/src/lib/work-item-ref.mjs +176 -0
  57. package/src/plugin/.claude-plugin/plugin.json +1 -1
  58. package/src/plugins/scm-github/index.mjs +439 -0
  59. package/src/plugins/tracker-github-projects/fields.mjs +73 -0
  60. package/src/plugins/tracker-github-projects/index.mjs +625 -0
  61. package/src/ports/scm.mjs +197 -0
  62. package/src/ports/tracker.mjs +239 -0
  63. package/src/ports/types.mjs +254 -0
  64. package/src/setup/files.mjs +14 -12
  65. package/src/setup/labels.mjs +17 -12
  66. package/src/setup/project.mjs +40 -59
  67. package/src/templates/workflows/code/code-review.yml +1 -1
  68. package/src/templates/workflows/code/qa.yml +1 -1
@@ -21,8 +21,55 @@
21
21
  import { existsSync, readFileSync } from 'node:fs';
22
22
  import path from 'node:path';
23
23
 
24
- import { listSubIssues, listProjectItems } from '../api/github-graphql.mjs';
25
- import { listBlockedBy, getIssue } from '../api/github-rest.mjs';
24
+ import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
25
+
26
+ // ── Tradução WorkItem → a forma que este módulo SEMPRE devolveu ─────────────
27
+ //
28
+ // `loadFeatureStories` espalha `{...s}` para seis comandos, e o resultado é
29
+ // CACHEADO em disco. Trocar o shape aqui obrigaria a migrar merge, doctor,
30
+ // qa-lead e order no mesmo commit — e a invalidar todo cache gravado por uma
31
+ // versão anterior. A fonte passou a ser a porta; a forma continua a mesma, e
32
+ // some quando o último consumidor migrar.
33
+ //
34
+ // `stateReason` volta à grafia do GitHub (`not_planned`) porque é assim que
35
+ // doctor e qa-plan-doc a comparam hoje. A porta normaliza para `not-planned`;
36
+ // a desnormalização vive aqui, no tradutor, e não neles.
37
+ const RAZAO_CRUA = { 'not-planned': 'not_planned', completed: 'completed', reopened: 'reopened' };
38
+
39
+ function comoSubIssue(w) {
40
+ return {
41
+ number: Number(w.ref.key),
42
+ title: w.title,
43
+ body: w.body || '',
44
+ nodeId: w.ref.id,
45
+ createdAt: w.createdAt || null,
46
+ state: w.state || null,
47
+ stateReason: RAZAO_CRUA[w.stateReason] ?? null,
48
+ milestone: w.milestone ? { number: Number(w.milestone.key), title: w.milestone.title } : null,
49
+ labels: w.tags || [],
50
+ };
51
+ }
52
+
53
+ function comoItemDoBoard(b) {
54
+ const fields = {};
55
+ if (b.stage) fields.Etapa = b.stage;
56
+ if (b.progress) fields.Status = b.progress;
57
+ for (const [canonico, valor] of Object.entries(b.fields || {})) {
58
+ if (canonico === 'workItemType') fields['Work Item Type'] = valor;
59
+ else if (canonico === 'priority') fields.Priority = valor;
60
+ else if (canonico === 'storyPoints') fields['Story Points'] = valor;
61
+ else if (canonico === 'area') fields.Area = valor;
62
+ else if (canonico === 'release') fields.Release = valor;
63
+ }
64
+ return {
65
+ number: Number(b.ref.key),
66
+ title: b.title,
67
+ state: String(b.state || '').toUpperCase(),
68
+ nodeId: b.ref.id,
69
+ milestone: b.milestone ? { number: Number(b.milestone.key), title: b.milestone.title } : null,
70
+ fields,
71
+ };
72
+ }
26
73
  import { detectIssueType } from './issue-type.mjs';
27
74
  import { featureDocPaths } from './doc-paths.mjs';
28
75
  import { parseDecompositionDoc } from './decomposition-doc.mjs';
@@ -66,6 +113,7 @@ export async function loadFeatureStories({
66
113
 
67
114
  // ── sub-issues (com body!) — cache subissues-<n> ───────────────────────────
68
115
  const subsKey = `subissues-${feature.number}`;
116
+ const tracker = createGithubTracker({ token, owner, repo });
69
117
  const cached = refresh ? null : readCacheEntry(root, subsKey, { owner, repo });
70
118
  let allSubs;
71
119
  let subsFrom;
@@ -75,7 +123,7 @@ export async function loadFeatureStories({
75
123
  subsFrom = 'cache';
76
124
  fetchedAt = cached.fetchedAt;
77
125
  } else {
78
- allSubs = await listSubIssues(token, nodeId);
126
+ allSubs = (await tracker.listChildren({ ref: { key: String(feature.number), id: nodeId } })).map(comoSubIssue);
79
127
  subsFrom = 'api';
80
128
  fetchedAt = new Date().toISOString();
81
129
  writeCacheEntry(root, subsKey, 'sub-issues', allSubs, { owner, repo });
@@ -134,7 +182,8 @@ export async function loadFeatureStories({
134
182
  continue;
135
183
  }
136
184
  try {
137
- const deps = (await listBlockedBy(token, owner, repo, s.number)).map(b => b.number);
185
+ const deps = (await tracker.listBlockedBy({ ref: { key: String(s.number) } }))
186
+ .map(b => Number(b.ref.key));
138
187
  remoteEdges.push({ number: s.number, dependsOn: deps });
139
188
  writeCacheEntry(root, key, 'blocked-by', deps, { owner, repo });
140
189
  } catch (err) {
@@ -166,13 +215,16 @@ export async function loadFeatureStories({
166
215
  */
167
216
  export async function cachedSubIssues({
168
217
  token, owner, repo, root, parent, refresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
218
+ tracker = null,
169
219
  } = {}) {
170
220
  const key = `subissues-${parent.number}`;
171
221
  if (!refresh) {
172
222
  const hit = readCacheEntry(root, key, { owner, repo });
173
223
  if (hit && isFresh(hit, ttlSec)) return { subs: hit.data, fromCache: true, fetchedAt: hit.fetchedAt };
174
224
  }
175
- const subs = await listSubIssues(token, parent.nodeId || parent.node_id);
225
+ const subs = (await (tracker ?? createGithubTracker({ token, owner, repo })).listChildren({
226
+ ref: { key: String(parent.number), id: parent.nodeId || parent.node_id },
227
+ })).map(comoSubIssue);
176
228
  writeCacheEntry(root, key, 'sub-issues', subs, { owner, repo });
177
229
  return { subs, fromCache: false, fetchedAt: new Date().toISOString() };
178
230
  }
@@ -204,7 +256,7 @@ function safeDocPaths(root, title) {
204
256
  * @returns {Promise<{items:Array, index:Map<number,object>, fetchedAt:string, fromCache:boolean}>}
205
257
  */
206
258
  export async function loadBoardSnapshot({
207
- token, project, root, refresh = false, fresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
259
+ token, owner, repo, project, root, refresh = false, fresh = false, ttlSec = DEFAULT_CACHE_TTL_SEC,
208
260
  } = {}) {
209
261
  const key = 'board-items';
210
262
  if (!refresh && !fresh) {
@@ -218,7 +270,8 @@ export async function loadBoardSnapshot({
218
270
  };
219
271
  }
220
272
  }
221
- const items = await listProjectItems(token, project.id);
273
+ const items = (await createGithubTracker({ token, owner, repo, project }).boardSnapshot())
274
+ .map(comoItemDoBoard);
222
275
  writeCacheEntry(root, key, 'board-items', items, { projectId: project.id });
223
276
  return {
224
277
  items,
@@ -244,7 +297,8 @@ export async function externalIssueInfo({
244
297
  const hit = readCacheEntry(root, key, { owner, repo });
245
298
  if (hit && isFresh(hit, ttlSec)) return { ...hit.data, fromCache: true };
246
299
  }
247
- const issue = await getIssue(token, owner, repo, number).catch(() => null);
300
+ const issue = await createGithubTracker({ token, owner, repo })
301
+ .getWorkItem({ ref: { key: String(number) } }).catch(() => null);
248
302
  if (!issue) {
249
303
  // Falha não entra no cache: "não foi possível ler" com cara de fresco por
250
304
  // 10 minutos esconderia uma issue que voltou a ser legível.
@@ -9,7 +9,7 @@
9
9
  // Contrato: registrar uso NUNCA derruba o fluxo principal — recordUsage é
10
10
  // best-effort e engole qualquer erro com um console.warn.
11
11
 
12
- import { listIssueComments, updateComment, commentOnIssue } from '../api/github-rest.mjs';
12
+ import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
13
13
 
14
14
  // Marcador HTML invisível que identifica o comentário de uso na issue.
15
15
  export const USAGE_MARKER = '<!-- spec-wave:usage -->';
@@ -145,11 +145,14 @@ export function renderUsageComment(entries) {
145
145
  * @param {string} params.repo nome do repo
146
146
  * @param {number} params.issueNumber número da issue
147
147
  * @param {Array<object>} params.entries novas entradas de uso
148
+ * @param {object} [params.tracker] porta de tracker; ausente = uma do GitHub
148
149
  */
149
- export async function recordUsage({ token, owner, repo, issueNumber, entries } = {}) {
150
+ export async function recordUsage({ token, owner, repo, issueNumber, entries, tracker = null } = {}) {
150
151
  if (!Array.isArray(entries) || entries.length === 0) return;
152
+ const porta = tracker || createGithubTracker({ token, owner, repo });
153
+ const ref = { key: String(issueNumber) };
151
154
  try {
152
- const comments = await listIssueComments(token, owner, repo, issueNumber);
155
+ const comments = await porta.listComments({ ref });
153
156
  const existing = comments.find(c => (c.body || '').includes(USAGE_MARKER));
154
157
 
155
158
  // Comentário antigo irreconhecível → recomeça só com as novas entradas.
@@ -157,9 +160,9 @@ export async function recordUsage({ token, owner, repo, issueNumber, entries } =
157
160
  const body = renderUsageComment([...(previous || []), ...entries]);
158
161
 
159
162
  if (existing?.id) {
160
- await updateComment(token, owner, repo, existing.id, body);
163
+ await porta.updateComment({ ref, commentId: existing.id, body });
161
164
  } else {
162
- await commentOnIssue(token, owner, repo, issueNumber, body);
165
+ await porta.addComment({ ref, body });
163
166
  }
164
167
  } catch (err) {
165
168
  console.warn('Não foi possível registrar uso de IA:', err.message);
@@ -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.7",
4
+ "version": "1.1.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",