@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
@@ -0,0 +1,75 @@
1
+ // Como a CLI se refere a si mesma quando MANDA alguém executá-la.
2
+ //
3
+ // Duas linhas de release convivem (RFC-005 §8.3): `branch-0.35` (LTS) e a 1.x.
4
+ // **As 0.x são compatíveis entre si; a 1.x NÃO é compatível com a 0.x.** Nesse
5
+ // mundo, `npx @spec-wave/cli@latest` numa instrução é uma armadilha: um
6
+ // repositório da linha 0.35 que segue a própria mensagem — ou um agente que lê
7
+ // a skill instalada e executa literalmente — atravessa a fronteira de major sem
8
+ // ninguém pedir, e o `update` seguinte reescreve os workflows para a outra.
9
+ //
10
+ // A referência sai como a MAJOR em que o repositório está (`@spec-wave/cli@0`,
11
+ // `@spec-wave/cli@1`), não como a versão exata. É o alcance certo para uma
12
+ // instrução: dentro da major, tudo é compatível, então quem segue pega as
13
+ // correções da própria linha; a barreira fica onde de fato existe.
14
+ //
15
+ // Nos WORKFLOWS a regra é outra, e continua sendo a versão exata
16
+ // (`{{CLI_VERSION}}`, ver lib/templates.mjs): ali o que se quer é
17
+ // reprodutibilidade — uma release não pode mudar o comportamento de um pipeline
18
+ // em andamento. Instrução quer compatibilidade; pipeline quer imutabilidade.
19
+
20
+ import { readFileSync } from 'node:fs';
21
+ import { findConfigPath } from './project-root.mjs';
22
+ import { CLI_VERSION } from './templates.mjs';
23
+
24
+ export const PKG = '@spec-wave/cli';
25
+
26
+ /** Major de um semver (`1.0.7` → `1`); null quando não dá para ler. */
27
+ export function majorOf(version) {
28
+ const m = /^\s*v?(\d+)\./.exec(String(version ?? ''));
29
+ return m ? m[1] : null;
30
+ }
31
+
32
+ /**
33
+ * Major da linha em que o repositório está congelado (função PURA — `cwd`
34
+ * injetável). Nunca lança: config ausente, ilegível ou sem `version` cai na
35
+ * major da CLI em execução.
36
+ *
37
+ * @param {string} [cwd]
38
+ * @returns {string}
39
+ */
40
+ export function pinnedMajor(cwd = process.cwd()) {
41
+ const daCli = majorOf(CLI_VERSION) ?? '1';
42
+ try {
43
+ const configPath = findConfigPath(cwd);
44
+ if (!configPath) return daCli;
45
+ return majorOf(JSON.parse(readFileSync(configPath, 'utf-8')).version) ?? daCli;
46
+ } catch {
47
+ return daCli;
48
+ }
49
+ }
50
+
51
+ /**
52
+ * `@spec-wave/cli@<major>` para usar em instruções — no lugar de `@latest`.
53
+ *
54
+ * @param {string} [cwd]
55
+ * @returns {string}
56
+ */
57
+ export function cliRef(cwd = process.cwd()) {
58
+ return `${PKG}@${pinnedMajor(cwd)}`;
59
+ }
60
+
61
+ /**
62
+ * Troca `@spec-wave/cli@latest` pela major dada, em qualquer texto (função
63
+ * PURA). É o que pina as skills instaladas: o arquivo-fonte guarda `@latest`
64
+ * (legível, sem versão a manter à mão) e a CÓPIA gravada no projeto do usuário
65
+ * sai presa à major da CLI que a instalou.
66
+ *
67
+ * @param {string} text
68
+ * @param {string} version versão completa; só a major é usada
69
+ * @returns {string}
70
+ */
71
+ export function pinCliRefs(text, version) {
72
+ const major = majorOf(version);
73
+ if (!major) return String(text ?? '');
74
+ return String(text ?? '').replaceAll(`${PKG}@latest`, `${PKG}@${major}`);
75
+ }
@@ -14,6 +14,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
14
14
 
15
15
  import { CONFIG_FILE } from '../config.mjs';
16
16
  import { findConfigPath } from './project-root.mjs';
17
+ import { cliRef } from './cli-ref.mjs';
17
18
 
18
19
  /**
19
20
  * Serialização canônica do config (função PURA).
@@ -40,7 +41,7 @@ export function updateConfig(mutator, { cwd = process.cwd() } = {}) {
40
41
  const configPath = findConfigPath(cwd);
41
42
  if (!configPath) {
42
43
  throw new Error(
43
- `${CONFIG_FILE} não encontrado — rode \`npx @spec-wave/cli@latest init\` neste repositório.`,
44
+ `${CONFIG_FILE} não encontrado — rode \`npx ${cliRef()} init\` neste repositório.`,
44
45
  );
45
46
  }
46
47
 
@@ -62,12 +62,19 @@ export function missingDocMessage({ pathRel, onRemote, fallback, pr = null, bran
62
62
  /**
63
63
  * O documento existe no remoto? Best-effort — NUNCA lança.
64
64
  *
65
+ * A porta chega como PARÂMETRO, e não por import: esta função era, antes das
66
+ * portas, o melhor seam do repositório (recebia `getFileContent` como parâmetro
67
+ * nomeado), e a migração só a deixou menor. Sem porta o resultado é `null` —
68
+ * "não consegui olhar", que é diferente de "não existe" e é o que impede o
69
+ * chamador de regerar por cima.
70
+ *
71
+ * @param {{scm?: object, pathRel: string}} params
65
72
  * @returns {Promise<boolean|null>} null quando não deu para consultar
66
73
  */
67
- export async function existsOnRemote({ getFileContent, token, owner, repo, pathRel }) {
68
- if (!token || !owner || !repo) return null;
74
+ export async function existsOnRemote({ scm, pathRel }) {
75
+ if (!scm) return null;
69
76
  try {
70
- return (await getFileContent(token, owner, repo, pathRel)) != null;
77
+ return (await scm.readFile({ path: pathRel })) != null;
71
78
  } catch {
72
79
  return null;
73
80
  }
@@ -20,7 +20,7 @@
20
20
  import { existsSync, readFileSync } from 'node:fs';
21
21
  import path from 'node:path';
22
22
 
23
- import { getFileContent, findOpenPR } from '../api/github-rest.mjs';
23
+ import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
24
24
  import { artifactBranch } from './artifact-pr.mjs';
25
25
 
26
26
  /**
@@ -75,14 +75,13 @@ export function isAwaitingMerge(state) {
75
75
  * @param {string} params.doc chave de ARTIFACT_DOCS
76
76
  * @param {number|string} params.issueNumber
77
77
  * @param {string|null} [params.base] branch base (null = deixa a API escolher)
78
- * @param {object} [params.deps] injeção para teste
78
+ * @param {object} [params.scm] porta de SCM; ausente = uma do GitHub
79
79
  * @returns {Promise<{content: string|null, state: DocState, ref: string|null,
80
80
  * pr: {number: number, url: string}|null}>}
81
81
  */
82
82
  export async function loadArtifact({
83
- token, owner, repo, root, pathRel, doc, issueNumber, base = null, deps = {},
83
+ token, owner, repo, root, pathRel, doc, issueNumber, base = null, scm = null,
84
84
  }) {
85
- const api = { getFileContent, findOpenPR, ...deps };
86
85
 
87
86
  const abs = path.resolve(root || process.cwd(), pathRel);
88
87
  if (existsSync(abs)) {
@@ -94,10 +93,11 @@ export async function loadArtifact({
94
93
  if (!token || !owner || !repo) {
95
94
  return { content: null, state: 'unknown', ref: null, pr: null };
96
95
  }
96
+ const porta = scm || createGithubScm({ link: githubLink({ owner, repo }), token });
97
97
 
98
98
  let naBase;
99
99
  try {
100
- naBase = await api.getFileContent(token, owner, repo, pathRel, base || undefined);
100
+ naBase = await porta.readFile({ path: pathRel, ref: base || undefined });
101
101
  } catch {
102
102
  return { content: null, state: 'unknown', ref: null, pr: null };
103
103
  }
@@ -115,7 +115,7 @@ export async function loadArtifact({
115
115
 
116
116
  let naBranch;
117
117
  try {
118
- naBranch = await api.getFileContent(token, owner, repo, pathRel, branch);
118
+ naBranch = await porta.readFile({ path: pathRel, ref: branch });
119
119
  } catch {
120
120
  return { content: null, state: 'unknown', ref: null, pr: null };
121
121
  }
@@ -126,7 +126,7 @@ export async function loadArtifact({
126
126
  // é o REMÉDIO, não a existência.
127
127
  let pr;
128
128
  try {
129
- pr = await api.findOpenPR(token, owner, repo, branch);
129
+ pr = await porta.findOpenPullRequest({ branch });
130
130
  } catch {
131
131
  // O documento existe; não saber se há PR não pode rebaixá-lo a inexistente,
132
132
  // que é o estado que autoriza regerar por cima.
@@ -149,12 +149,12 @@ export async function loadArtifact({
149
149
  * @returns {Promise<Record<string, {state: DocState, pr: object|null}>>}
150
150
  */
151
151
  export async function artifactStates({
152
- token, owner, repo, root, docs = [], issueNumber, base = null, deps = {},
152
+ token, owner, repo, root, docs = [], issueNumber, base = null, scm = null,
153
153
  }) {
154
154
  const out = {};
155
155
  for (const { doc, pathRel } of docs) {
156
156
  const { state, pr } = await loadArtifact({
157
- token, owner, repo, root, pathRel, doc, issueNumber, base, deps,
157
+ token, owner, repo, root, pathRel, doc, issueNumber, base, scm,
158
158
  });
159
159
  out[doc] = { state, pr };
160
160
  }
@@ -16,6 +16,8 @@
16
16
  // "onde este processo está rodando AGORA" (GITHUB_ACTIONS); este responde "onde
17
17
  // o repositório decidiu que o fluxo roda".
18
18
 
19
+ import { cliRef } from './cli-ref.mjs';
20
+
19
21
  export const EXECUTION_MODES = ['actions', 'local'];
20
22
  export const DEFAULT_EXECUTION_MODE = 'actions';
21
23
 
@@ -105,14 +107,14 @@ export function describeModeState({ configured, variable, unguardedWorkflows = [
105
107
  `Modo local, mas \`${EXECUTION_VARIABLE}\` ${variable === null ? 'não existe' : `vale "${variable}"`} ` +
106
108
  'no repositório — os workflows CONTINUAM disparando e consumindo minutos.'
107
109
  );
108
- fixes.push('Rode `npx @spec-wave/cli@latest mode local` (ou defina a variável em Settings → Actions → Variables).');
110
+ fixes.push(`Rode \`npx ${cliRef()} mode local\` (ou defina a variável em Settings → Actions → Variables).`);
109
111
  } else {
110
112
  status = 'problem';
111
113
  notes.push(
112
114
  `Modo actions, mas \`${EXECUTION_VARIABLE}\`="${variable}" está setada — os workflows ` +
113
115
  'são pulados e nada roda até alguém rodar o comando local.'
114
116
  );
115
- fixes.push('Rode `npx @spec-wave/cli@latest mode actions` para remover a variável.');
117
+ fixes.push(`Rode \`npx ${cliRef()} mode actions\` para remover a variável.`);
116
118
  }
117
119
 
118
120
  if (configured === 'local' && unguardedWorkflows.length > 0) {
@@ -121,7 +123,7 @@ export function describeModeState({ configured, variable, unguardedWorkflows = [
121
123
  `Workflows instalados sem a guarda \`${EXECUTION_GUARD}\`: ${unguardedWorkflows.join(', ')} — ` +
122
124
  'esses vão rodar de qualquer jeito.'
123
125
  );
124
- fixes.push('Rode `npx @spec-wave/cli@latest update` para publicar os workflows com a guarda.');
126
+ fixes.push(`Rode \`npx ${cliRef()} update\` para publicar os workflows com a guarda.`);
125
127
  }
126
128
 
127
129
  const summary = configured === 'local'
@@ -8,7 +8,7 @@
8
8
  // implementação (warn e segue).
9
9
 
10
10
  import * as p from '@clack/prompts';
11
- import { loadProjectConfig, resolveField, advanceToStage, setItemStatus } from './board.mjs';
11
+ import { openTracker, advanceToStage, setProgress } from './board.mjs';
12
12
  import {
13
13
  STAGE_DEVELOPMENT, STAGE_CODE_REVIEW, STAGE_DONE,
14
14
  PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
@@ -37,37 +37,37 @@ export function planBoardMoves(phase, {
37
37
  const moves = [];
38
38
  if (phase === 'start') {
39
39
  if (feature?.nodeId) {
40
- moves.push({ nodeId: feature.nodeId, label: `Feature #${feature.number}`, type: 'Feature',
40
+ moves.push({ nodeId: feature.nodeId, number: feature.number, label: `Feature #${feature.number}`, type: 'Feature',
41
41
  stage: STAGE_DEVELOPMENT, status: PROGRESS_IN_PROGRESS, statusFallback: true });
42
42
  }
43
43
  if (story?.nodeId) {
44
- moves.push({ nodeId: story.nodeId, label: `Story #${story.number}`, type: 'Story',
44
+ moves.push({ nodeId: story.nodeId, number: story.number, label: `Story #${story.number}`, type: 'Story',
45
45
  stage: STAGE_DEVELOPMENT, status: PROGRESS_IN_PROGRESS, statusFallback: true });
46
46
  }
47
47
  // Bug é folha e não tem Feature-pai a arrastar: um defeito em correção não
48
48
  // deve puxar a Feature inteira de volta para Desenvolvimento.
49
49
  if (bug?.nodeId) {
50
- moves.push({ nodeId: bug.nodeId, label: `Bug #${bug.number}`, type: 'Bug',
50
+ moves.push({ nodeId: bug.nodeId, number: bug.number, label: `Bug #${bug.number}`, type: 'Bug',
51
51
  stage: STAGE_DEVELOPMENT, status: PROGRESS_IN_PROGRESS, statusFallback: true });
52
52
  }
53
53
  for (const t of tasks) {
54
54
  if (!t?.nodeId) continue;
55
- moves.push({ nodeId: t.nodeId, label: `Task #${t.number}`, type: 'Task',
55
+ moves.push({ nodeId: t.nodeId, number: t.number, label: `Task #${t.number}`, type: 'Task',
56
56
  stage: STAGE_DEVELOPMENT, status: tasksStartStatus,
57
57
  statusFallback: tasksStartStatus === PROGRESS_IN_PROGRESS });
58
58
  }
59
59
  } else if (phase === 'success') {
60
60
  for (const t of tasks) {
61
61
  if (!t?.nodeId) continue;
62
- moves.push({ nodeId: t.nodeId, label: `Task #${t.number}`, type: 'Task',
62
+ moves.push({ nodeId: t.nodeId, number: t.number, label: `Task #${t.number}`, type: 'Task',
63
63
  stage: STAGE_DONE, status: PROGRESS_DONE, statusFallback: false });
64
64
  }
65
65
  if (story?.nodeId) {
66
- moves.push({ nodeId: story.nodeId, label: `Story #${story.number}`, type: 'Story',
66
+ moves.push({ nodeId: story.nodeId, number: story.number, label: `Story #${story.number}`, type: 'Story',
67
67
  stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
68
68
  }
69
69
  if (bug?.nodeId) {
70
- moves.push({ nodeId: bug.nodeId, label: `Bug #${bug.number}`, type: 'Bug',
70
+ moves.push({ nodeId: bug.nodeId, number: bug.number, label: `Bug #${bug.number}`, type: 'Bug',
71
71
  stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
72
72
  }
73
73
  // Feature: só o modo Feature passa `feature` aqui, e só depois de TODAS as
@@ -77,7 +77,7 @@ export function planBoardMoves(phase, {
77
77
  // num branch único e não abre PR), a Feature ficava presa em
78
78
  // Desenvolvimento com todas as Stories já em Code Review.
79
79
  if (feature?.nodeId) {
80
- moves.push({ nodeId: feature.nodeId, label: `Feature #${feature.number}`, type: 'Feature',
80
+ moves.push({ nodeId: feature.nodeId, number: feature.number, label: `Feature #${feature.number}`, type: 'Feature',
81
81
  stage: STAGE_CODE_REVIEW, status: PROGRESS_TODO, statusFallback: false });
82
82
  }
83
83
  }
@@ -105,31 +105,28 @@ export async function applyBoardMoves({
105
105
  return;
106
106
  }
107
107
  try {
108
- const { project, error } = loadProjectConfig({ cwd });
108
+ // PROJECT_TOKEN é a credencial do board — ver a tabela em
109
+ // src/plugins/tracker-github-projects/index.mjs.
110
+ const { tracker, error } = openTracker({
111
+ token, projectToken: process.env.PROJECT_TOKEN || token, cwd,
112
+ });
109
113
  if (error) {
110
114
  log.warn(`board: ${error} — Etapas não atualizadas.`);
111
115
  return;
112
116
  }
113
- const projectToken = process.env.PROJECT_TOKEN || token;
114
- const etapaField = await resolveField(projectToken, project, 'Etapa').catch(() => null);
115
- const statusField = await resolveField(projectToken, project, 'Status').catch(() => null);
116
- // Repara o Work Item Type vazio de passagem — o tipo de cada movimento é
117
- // conhecido por construção (planBoardMoves). Ver ensureWorkItemType.
118
- const typeField = await resolveField(projectToken, project, 'Work Item Type').catch(() => null);
119
- if (!etapaField?.id) {
120
- log.warn('board: campo Etapa não resolvido — Etapas não atualizadas.');
121
- return;
122
- }
123
117
  for (const m of moves) {
118
+ const ref = { key: String(m.number ?? ''), id: m.nodeId };
124
119
  try {
125
- const advanced = await advanceToStage(
126
- projectToken, project, etapaField, statusField, m.nodeId, m.stage, m.status,
127
- { typeField, itemType: m.type });
120
+ // `itemType` repara o Work Item Type vazio de passagem — o tipo de cada
121
+ // movimento é conhecido por construção (planBoardMoves).
122
+ const advanced = await advanceToStage({
123
+ tracker, ref, stage: m.stage, progress: m.status, itemType: m.type,
124
+ });
128
125
  if (advanced) {
129
126
  log.info(`board: ${m.label} → ${m.stage} (${m.status})`);
130
- } else if (m.statusFallback && statusField?.id) {
131
- // Etapa já está nessa fase ou adiante: ao menos alinha o Status.
132
- await setItemStatus(projectToken, project, statusField, m.nodeId, m.status);
127
+ } else if (m.statusFallback) {
128
+ // Etapa já está nessa fase ou adiante: ao menos alinha o progresso.
129
+ await setProgress({ tracker, ref, progress: m.status });
133
130
  log.info(`board: ${m.label} já em ${m.stage}+ — Status → ${m.status}`);
134
131
  }
135
132
  } catch (err) {
@@ -26,7 +26,11 @@ export function detectIssueType(issue) {
26
26
  }
27
27
 
28
28
  // 2. Fallback: varrer as labels da issue procurando um dos prefixos de tipo.
29
- const labels = Array.isArray(issue.labels) ? issue.labels : [];
29
+ // `tags` é a forma canônica do WorkItem (RFC-006); `labels` é a issue crua da
30
+ // REST, que ainda circula. As duas valem — ver labelNames em config.mjs.
31
+ const labels = Array.isArray(issue.tags)
32
+ ? issue.tags
33
+ : (Array.isArray(issue.labels) ? issue.labels : []);
30
34
  for (const label of labels) {
31
35
  const name = (typeof label === 'string' ? label : label?.name) || '';
32
36
  const type = TAG_TO_TYPE[name.toUpperCase()];
@@ -23,6 +23,7 @@
23
23
  import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
24
24
  import path from 'node:path';
25
25
  import { fileURLToPath } from 'node:url';
26
+ import { pinCliRefs } from './cli-ref.mjs';
26
27
 
27
28
  const __dir = path.dirname(fileURLToPath(import.meta.url));
28
29
 
@@ -86,7 +87,16 @@ export function listPluginSkills(skillsDir = PLUGIN_SKILLS_DIR) {
86
87
  * @param {(v: string) => string} banner
87
88
  * @returns {string}
88
89
  */
90
+ // A saída passa inteira por `pinCliRefs` — inclusive frontmatter e banner, pelo
91
+ // mesmo motivo do install-skill: a cópia instalada fica presa à MAJOR de quem a
92
+ // instalou, e o `allowed-tools` casa com os comandos que a skill manda rodar.
93
+ // Vale para TODO arquivo da skill, não só o SKILL.md: os supporting files
94
+ // também trazem comandos.
89
95
  export function renderPluginSkillFile(relPath, raw, version, banner) {
96
+ return pinCliRefs(renderPluginSkillFileRaw(relPath, raw, version, banner), version);
97
+ }
98
+
99
+ function renderPluginSkillFileRaw(relPath, raw, version, banner) {
90
100
  if (relPath !== 'SKILL.md') return raw;
91
101
  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
92
102
  if (!match) return `${banner(version)}\n\n${raw.trim()}\n`;
@@ -17,7 +17,7 @@
17
17
  // implementação, que a essa altura já está commitada.
18
18
 
19
19
  import * as p from '@clack/prompts';
20
- import { listIssuePullRequests, listOpenPullRequests, markPullRequestReadyForReview } from '../api/github-graphql.mjs';
20
+ import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
21
21
  import { extractIssueRefs, hubIssueNumbers } from './pr-link.mjs';
22
22
 
23
23
  /**
@@ -36,8 +36,13 @@ import { extractIssueRefs, hubIssueNumbers } from './pr-link.mjs';
36
36
  */
37
37
  export function planPrsToReady(prs = []) {
38
38
  const out = new Map();
39
+ // Duas formas: a crua do GraphQL (`isDraft`, `merged`) e a do contrato
40
+ // (`draft`, `state: 'merged'`). Ler só a primeira faz `!pr.isDraft` ser
41
+ // sempre verdadeiro — e aí nenhum PR sai do rascunho, em silêncio.
42
+ const emRascunho = pr => pr.isDraft ?? pr.draft;
43
+ const mergeado = pr => Boolean(pr.merged) || pr.state === 'merged';
39
44
  for (const pr of prs) {
40
- if (!pr?.id || !pr.isDraft || pr.merged) continue;
45
+ if (!pr?.id || !emRascunho(pr) || mergeado(pr)) continue;
41
46
  if (pr.state && pr.state !== 'open') continue;
42
47
  // Chave = node id: o número colide entre repositórios (PR #42 do `api` e
43
48
  // #42 do `web`), o id não.
@@ -65,6 +70,7 @@ export function planPrsToReady(prs = []) {
65
70
  */
66
71
  export async function collectFeaturePullRequests({
67
72
  token, owner, repo, issueNumbers = [], issueNodes = [], linkMode = 'explicit', codeRepos = [],
73
+ scmDe = null,
68
74
  }) {
69
75
  const alvo = new Set(issueNumbers);
70
76
  const byKey = new Map();
@@ -75,26 +81,44 @@ export async function collectFeaturePullRequests({
75
81
  // onde foi listado — o número colide entre repos, o par não. Um `#N` solto
76
82
  // é issue do repo do PR; só o que aponta para o hub é desta Feature.
77
83
  const hub = { owner, repo };
84
+ // Uma porta POR REPOSITÓRIO — é o que o contrato manda, e é a razão de
85
+ // `PullRequestRef` carregar o `link`: o número do PR colide entre repos.
86
+ const portaDe = scmDe ?? (r => createGithubScm({
87
+ link: githubLink({ owner: r.owner, repo: r.repo, role: sameRepoQue(r, hub) ? 'hub' : 'code' }),
88
+ token,
89
+ }));
90
+
78
91
  for (const r of [hub, ...codeRepos]) {
79
- const abertos = await listOpenPullRequests(token, r.owner, r.repo).catch(() => []);
80
- for (const raw of abertos) {
81
- const pr = { ...raw, repo: { owner: r.owner, repo: r.repo } };
92
+ const abertos = await portaDe(r).listOpenPullRequests().catch(() => []);
93
+ for (const bruto of abertos) {
94
+ const pr = { ...bruto, repo: { owner: r.owner, repo: r.repo } };
82
95
  const fecha = hubIssueNumbers(extractIssueRefs(pr.body || '', { prRepo: pr.repo, linkMode }), hub);
83
96
  if (fecha.some(n => alvo.has(n))) byKey.set(keyOf(pr), pr);
84
97
  }
85
98
  }
86
99
 
87
- // Vínculo nativo: só existe no hub (o GitHub não fecha issue entre repos).
100
+ // Vínculo NATIVO: só existe no hub (o GitHub não fecha issue entre repos).
101
+ const hubScm = portaDe(hub);
88
102
  for (const node of issueNodes) {
89
103
  if (!node?.nodeId) continue;
90
- for (const raw of await listIssuePullRequests(token, node.nodeId).catch(() => [])) {
91
- const pr = { ...raw, repo: raw.repo || hub };
104
+ const achados = await hubScm
105
+ .findPullRequestsReferencing({ ref: { key: String(node.number), id: node.nodeId } })
106
+ .catch(() => []);
107
+ for (const bruto of achados) {
108
+ const pr = { ...bruto, repo: hub };
92
109
  if (!byKey.has(keyOf(pr))) byKey.set(keyOf(pr), pr);
93
110
  }
94
111
  }
95
112
  return [...byKey.values()];
96
113
  }
97
114
 
115
+ /** Dois endereços de repositório são o mesmo? (case-insensitive) */
116
+ function sameRepoQue(a, b) {
117
+ return Boolean(a && b)
118
+ && a.owner.toLowerCase() === b.owner.toLowerCase()
119
+ && a.repo.toLowerCase() === b.repo.toLowerCase();
120
+ }
121
+
98
122
  /** `#12` no hub, `acme/api#12` fora dele. */
99
123
  export function prLabel(pr, hub) {
100
124
  const r = pr.repo;
@@ -119,12 +143,13 @@ export function prLabel(pr, hub) {
119
143
  */
120
144
  export async function markFeaturePrsReady({
121
145
  token, owner, repo, feature, stories = [], dryRun = false, log = p.log, linkMode = 'explicit', codeRepos = [],
146
+ scmDe = null,
122
147
  }) {
123
148
  if (!token || !owner || !repo || !feature?.number) return [];
124
149
  const hub = { owner, repo };
125
150
  try {
126
151
  const prs = await collectFeaturePullRequests({
127
- token, owner, repo, linkMode, codeRepos,
152
+ token, owner, repo, linkMode, codeRepos, scmDe,
128
153
  issueNumbers: [feature.number, ...stories.map(s => s.number)].filter(Boolean),
129
154
  issueNodes: [feature, ...stories],
130
155
  });
@@ -141,11 +166,24 @@ export async function markFeaturePrsReady({
141
166
 
142
167
  // Devolve os rótulos (`#12`, `acme/api#12`), não os números: fora do hub o
143
168
  // número sozinho não identifica o PR.
169
+ // O PR pode estar em qualquer repo da Feature: a porta é a DELE, não a do
170
+ // hub. Marcar um PR de repo de código com a porta do hub é 404 — ou pior,
171
+ // o PR de mesmo número no hub.
172
+ const portaDoPr = (pr) => {
173
+ const r = { owner: pr.repo?.owner ?? owner, repo: pr.repo?.repo ?? repo };
174
+ if (scmDe) return scmDe(r);
175
+ // `role` sai de `pr.repo`, não de `r`: o par já traz fallback no hub, e
176
+ // computar dali faria um `pr.repo` ausente virar 'hub' onde era 'code'.
177
+ return createGithubScm({
178
+ link: githubLink({ ...r, role: sameRepoQue(pr.repo, hub) ? 'hub' : 'code' }),
179
+ token,
180
+ });
181
+ };
144
182
  const marcados = [];
145
183
  const falhas = [];
146
184
  for (const pr of alvos) {
147
185
  try {
148
- await markPullRequestReadyForReview(token, pr.id);
186
+ await portaDoPr(pr).markReadyForReview({ id: pr.id });
149
187
  marcados.push(prLabel(pr, hub));
150
188
  } catch (err) {
151
189
  falhas.push(`${prLabel(pr, hub)} (${err.message})`);
@@ -27,7 +27,9 @@ export function reviewVerdict(reviews = []) {
27
27
  for (const review of reviews) {
28
28
  const state = String(review?.state || '').toUpperCase();
29
29
  if (!relevant.includes(state)) continue; // COMMENTED/PENDING não são veredito
30
- const autor = review?.user?.login || review?.author || '(desconhecido)';
30
+ // `reviewer` é o nome CANÔNICO (Review, ports/types.mjs); `user.login` e
31
+ // `author` são as formas cruas que ainda circulam.
32
+ const autor = review?.reviewer || review?.user?.login || review?.author || '(desconhecido)';
31
33
  porAutor.set(autor, state);
32
34
  }
33
35
 
@@ -378,7 +378,9 @@ export function buildQaContext({
378
378
  lines.push('## Pull Requests vinculados');
379
379
  lines.push('');
380
380
  for (const pr of pullRequests) {
381
- lines.push(`- PR #${pr.number} — ${pr.merged ? 'mergeado' : pr.state}`);
381
+ // `merged` é a forma crua do GraphQL; no contrato o merge é um ESTADO.
382
+ const mergeado = Boolean(pr.merged) || pr.state === 'merged';
383
+ lines.push(`- PR #${pr.number} — ${mergeado ? 'mergeado' : pr.state}`);
382
384
  }
383
385
  }
384
386
 
@@ -78,10 +78,18 @@ export function qaTrailDir(milestoneTitle, cycle) {
78
78
  * @returns {{ milestone?: object, error?: string }}
79
79
  */
80
80
  export function resolveMilestoneRef(milestones = [], ref) {
81
+ // `key` (MilestoneRef, o que a porta devolve) e `number` (a milestone crua)
82
+ // valem as duas. Sem isso a busca por número deixaria de achar e o comando
83
+ // responderia "não existe" para uma milestone que existe.
84
+ // Comparação NUMÉRICA, não textual: a chave vinda da API nunca tem zero à
85
+ // esquerda, mas a digitada pode ter, e `'007' === '7'` é false. Um comando que
86
+ // responde "não existe" para uma milestone que existe é o pior dos dois
87
+ // mundos. Mesmo tratamento que `dependency-map.mjs` já dá.
88
+ const chave = m => Number(m?.key ?? m?.number);
81
89
  const text = String(ref ?? '').trim();
82
90
  if (/^#?\d+$/.test(text)) {
83
- const number = parseInt(text.replace('#', ''), 10);
84
- const found = milestones.find(m => m.number === number);
91
+ const number = text.replace('#', '');
92
+ const found = milestones.find(m => chave(m) === Number(number));
85
93
  return found
86
94
  ? { milestone: found }
87
95
  : { error: `Milestone #${number} não existe. Existem: ${listMilestoneTitles(milestones)}.` };
@@ -90,7 +98,7 @@ export function resolveMilestoneRef(milestones = [], ref) {
90
98
  if (matches.length === 1) return { milestone: matches[0] };
91
99
  if (matches.length > 1) {
92
100
  return {
93
- error: `Título "${text}" é ambíguo: ${matches.map(m => `#${m.number}`).join(', ')}. Use o número.`,
101
+ error: `Título "${text}" é ambíguo: ${matches.map(m => `#${chave(m)}`).join(', ')}. Use o número.`,
94
102
  };
95
103
  }
96
104
  return { error: `Milestone "${text}" não encontrada. Existem: ${listMilestoneTitles(milestones)}.` };
@@ -267,7 +267,13 @@ export function renderQaPlanDoc({ title = '', issueNumber = null, scenarios = []
267
267
  */
268
268
  export function validateQaPlan({ doc, stories = [], content = '' } = {}) {
269
269
  const errors = [];
270
- const byNumber = new Map(stories.map(s => [s.number, s]));
270
+ // A Story chega em duas formas: a crua (`number`, `stateReason: 'not_planned'`)
271
+ // e a do contrato (`ref.key`, `stateReason: 'not-planned'`). Ler só uma delas
272
+ // faz TODO cenário ser acusado de não pertencer à Feature.
273
+ const numeroDa = st => Number(st?.ref?.key ?? st?.number);
274
+ const descartadaNoRescopo = st => st?.state === 'closed'
275
+ && ['not_planned', 'not-planned'].includes(st?.stateReason);
276
+ const byNumber = new Map(stories.map(s => [numeroDa(s), s]));
271
277
 
272
278
  for (const s of doc?.scenarios || []) {
273
279
  if (!byNumber.has(s.story)) {
@@ -287,10 +293,10 @@ export function validateQaPlan({ doc, stories = [], content = '' } = {}) {
287
293
  // Story descartada no rescopo não precisa de cenário; as demais, sim.
288
294
  const covered = new Set((doc?.scenarios || []).map(s => s.story));
289
295
  for (const story of stories) {
290
- const descartada = story.state === 'closed' && story.stateReason === 'not_planned';
291
- if (!descartada && !covered.has(story.number)) {
296
+ const descartada = descartadaNoRescopo(story);
297
+ if (!descartada && !covered.has(numeroDa(story))) {
292
298
  errors.push(
293
- `A Story #${story.number}${story.title ? ` (${story.title})` : ''} não tem nenhum cenário — ` +
299
+ `A Story #${numeroDa(story)}${story.title ? ` (${story.title})` : ''} não tem nenhum cenário — ` +
294
300
  'toda Story da Feature precisa de ao menos um.'
295
301
  );
296
302
  }
@@ -8,6 +8,7 @@
8
8
 
9
9
  import { createHash } from 'node:crypto';
10
10
  import { REQUIRED_BUG_SECTIONS, QA_BLOCKED_REASONS } from '../config.mjs';
11
+ import { cliRef } from './cli-ref.mjs';
11
12
 
12
13
  export const QA_REPORT_VERSION = 1;
13
14
 
@@ -551,7 +552,7 @@ export function renderQaBugDoc({
551
552
  `Re-executar o cenário reprovado após o fix:`,
552
553
  '',
553
554
  '```bash',
554
- `npx @spec-wave/cli@latest qa ${scenario.story} --only ${scenario.numero}`,
555
+ `npx ${cliRef()} qa ${scenario.story} --only ${scenario.numero}`,
555
556
  '```',
556
557
  '',
557
558
  `O veredito precisa ser **pass** com o mesmo esperado: ${scenario.esperado || '—'}`,
@@ -167,6 +167,9 @@ export function renderSummarySection(skills) {
167
167
  '',
168
168
  'Cada uma existe como skill dedicada do plugin (`/spec-wave:<nome>`) — e os',
169
169
  'utilitários de board estão flag a flag na *Referência da CLI* acima. Rode',
170
+ // `@latest` PERMANECE aqui: este texto vai para o SKILL.md FONTE, que é
171
+ // commitado. Quem pina é a instalação (install-skill → pinCliRefs), com a
172
+ // major de quem instalou — não a de quem rodou `skill:gen`.
170
173
  '`npx @spec-wave/cli@latest <comando> --help` para os parâmetros.',
171
174
  '',
172
175
  ];
@@ -373,7 +373,7 @@ export function auditMilestone({
373
373
  feature: f.number,
374
374
  dep: d,
375
375
  featureMilestone: f.milestone?.title || `#${f.milestone?.number ?? '?'}`,
376
- depMilestone: dep.milestone.title || `#${dep.milestone.number}`,
376
+ depMilestone: dep.milestone.title || `#${dep.milestone.key ?? dep.milestone.number}`,
377
377
  });
378
378
  }
379
379
  }