@spec-wave/cli 1.0.8 → 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 (57) hide show
  1. package/package.json +1 -1
  2. package/src/commands/audit.mjs +24 -18
  3. package/src/commands/code-review.mjs +89 -58
  4. package/src/commands/decompose.mjs +254 -218
  5. package/src/commands/generate-bug.mjs +51 -44
  6. package/src/commands/generate-plan.mjs +83 -63
  7. package/src/commands/generate-qa-plan.mjs +144 -117
  8. package/src/commands/generate-spec.mjs +33 -28
  9. package/src/commands/implement.mjs +154 -79
  10. package/src/commands/init.mjs +8 -3
  11. package/src/commands/issue.mjs +26 -39
  12. package/src/commands/merge.mjs +71 -20
  13. package/src/commands/mode.mjs +8 -4
  14. package/src/commands/move.mjs +16 -20
  15. package/src/commands/order.mjs +33 -22
  16. package/src/commands/preflight.mjs +24 -13
  17. package/src/commands/qa-lead.mjs +28 -16
  18. package/src/commands/qa-run.mjs +122 -101
  19. package/src/commands/qa.mjs +55 -44
  20. package/src/commands/refresh.mjs +24 -16
  21. package/src/commands/repair-stage.mjs +29 -16
  22. package/src/commands/repo.mjs +10 -3
  23. package/src/commands/run.mjs +23 -11
  24. package/src/commands/story.mjs +20 -25
  25. package/src/commands/task.mjs +21 -27
  26. package/src/commands/triage.mjs +33 -31
  27. package/src/commands/uninstall.mjs +7 -3
  28. package/src/commands/update.mjs +29 -21
  29. package/src/commands/validate.mjs +60 -52
  30. package/src/commands/workspace.mjs +7 -5
  31. package/src/config.mjs +7 -1
  32. package/src/lib/artifact-publish.mjs +20 -18
  33. package/src/lib/board-policy.mjs +144 -0
  34. package/src/lib/board.mjs +134 -233
  35. package/src/lib/doc-availability.mjs +10 -3
  36. package/src/lib/doc-source.mjs +9 -9
  37. package/src/lib/implement-board.mjs +23 -26
  38. package/src/lib/issue-type.mjs +5 -1
  39. package/src/lib/pr-ready.mjs +48 -10
  40. package/src/lib/pr-step.mjs +3 -1
  41. package/src/lib/qa-exec.mjs +3 -1
  42. package/src/lib/qa-lead.mjs +11 -3
  43. package/src/lib/qa-plan-doc.mjs +10 -4
  44. package/src/lib/spec-audit.mjs +1 -1
  45. package/src/lib/story-graph.mjs +62 -8
  46. package/src/lib/usage-report.mjs +8 -5
  47. package/src/lib/work-item-ref.mjs +176 -0
  48. package/src/plugin/.claude-plugin/plugin.json +1 -1
  49. package/src/plugins/scm-github/index.mjs +439 -0
  50. package/src/plugins/tracker-github-projects/fields.mjs +73 -0
  51. package/src/plugins/tracker-github-projects/index.mjs +625 -0
  52. package/src/ports/scm.mjs +197 -0
  53. package/src/ports/tracker.mjs +239 -0
  54. package/src/ports/types.mjs +254 -0
  55. package/src/setup/files.mjs +14 -12
  56. package/src/setup/labels.mjs +17 -12
  57. package/src/setup/project.mjs +40 -59
@@ -0,0 +1,144 @@
1
+ // A POLÍTICA do board — pura, sem rede, sem fornecedor.
2
+ //
3
+ // Saiu de `lib/board.mjs` sem mudar de corpo. A separação é a fronteira do
4
+ // RFC-006 §3.2: o core decide PARA ONDE e SE o item anda; o plugin sabe COMO
5
+ // escrever isso no fornecedor.
6
+ //
7
+ // O invariante que justifica o arquivo existir separado: **direção de fluxo
8
+ // nunca é decisão de plugin.** Um tracker que pudesse recusar ou inverter um
9
+ // avanço de etapa transformaria a regra central do RFC-001 em comportamento por
10
+ // fornecedor — a mesma Feature andaria diferente em dois clientes.
11
+
12
+ import { STAGE_ORDER, STATUS_OPTIONS, STAGE_DONE } from '../config.mjs';
13
+
14
+ /**
15
+ * A Etapa pode avançar de `current` para `target`? (função PURA)
16
+ *
17
+ * Regra do board: a Etapa só AVANÇA. Três casos param o movimento:
18
+ * • já está no destino ou adiante na ordem canônica;
19
+ * • a etapa ATUAL não está em STAGE_ORDER (coluna criada à mão no board, ou
20
+ * resíduo de uma versão anterior do config). Antes esse caso caía no
21
+ * `curIdx === -1` e DESLIGAVA o guard, permitindo retrocesso — sem saber onde
22
+ * o item está na ordem, o certo é não mexer;
23
+ * • a etapa de DESTINO não está em STAGE_ORDER (nome inválido).
24
+ *
25
+ * @param {string|null} current etapa atual do item (null = ainda sem etapa)
26
+ * @param {string} target etapa de destino
27
+ * @returns {boolean} true se deve escrever a nova Etapa
28
+ */
29
+ export function shouldAdvanceStage(current, target) {
30
+ const tgtIdx = STAGE_ORDER.indexOf(target);
31
+ if (tgtIdx === -1) return false;
32
+ if (!current) return true; // item ainda sem Etapa definida
33
+ const curIdx = STAGE_ORDER.indexOf(current);
34
+ if (curIdx === -1) return false; // etapa atual desconhecida — não arrisca retroceder
35
+ return curIdx < tgtIdx;
36
+ }
37
+
38
+ /**
39
+ * O movimento de etapa, decidido (função PURA).
40
+ *
41
+ * Mesma decisão de `shouldAdvanceStage`, com o MOTIVO junto. O motivo é o que
42
+ * permite a quem chama distinguir "já estava adiante" (normal, e o fluxo segue)
43
+ * de "não sei onde o item está" (board divergente, e alguém precisa olhar) —
44
+ * hoje os dois chegam como o mesmo `false`.
45
+ *
46
+ * Deliberadamente NÃO avisa sobre trilha (`isStageInTrack`): `advanceToStage`
47
+ * nunca avisou, e acrescentar saída nova aqui seria mudança de comportamento
48
+ * numa fase que promete não ter nenhuma. Quem quiser o aviso chama
49
+ * `isStageInTrack` no call site, como `move` já faz.
50
+ *
51
+ * @param {object} params
52
+ * @param {string|null} params.current
53
+ * @param {string} params.target
54
+ * @returns {{advance: boolean, reason: 'ok'|'ja-adiante'|'atual-desconhecida'|'destino-invalido'}}
55
+ */
56
+ export function planStageMove({ current, target }) {
57
+ if (STAGE_ORDER.indexOf(target) === -1) return { advance: false, reason: 'destino-invalido' };
58
+ if (!current) return { advance: true, reason: 'ok' };
59
+ if (STAGE_ORDER.indexOf(current) === -1) return { advance: false, reason: 'atual-desconhecida' };
60
+ return shouldAdvanceStage(current, target)
61
+ ? { advance: true, reason: 'ok' }
62
+ : { advance: false, reason: 'ja-adiante' };
63
+ }
64
+
65
+ // Normaliza para comparação: sem emoji/pontuação, minúsculo, espaços colapsados.
66
+ // "👀 Code Review" e "code review" precisam casar.
67
+ function stageKey(value) {
68
+ return String(value ?? '')
69
+ .normalize('NFD')
70
+ .replace(/[̀-ͯ]/g, '') // acentos (após NFD)
71
+ .replace(/[^\p{Letter}\p{Number}]+/gu, ' ') // emoji e pontuação
72
+ .trim()
73
+ .toLowerCase();
74
+ }
75
+
76
+ /**
77
+ * Resolve o nome canônico de uma Etapa a partir de entrada humana (função PURA).
78
+ *
79
+ * Aceita o nome com ou sem emoji, com qualquer caixa e sem acento
80
+ * ("code review", "Homologacao", "🚧 Desenvolvimento"). Casa primeiro exato,
81
+ * depois por prefixo; prefixo que casa com mais de uma etapa é AMBÍGUO e vira
82
+ * erro listando as candidatas — melhor recusar que mover para a coluna errada.
83
+ *
84
+ * @param {string} input entrada do usuário
85
+ * @returns {{ stage: string|null, error: string|null }}
86
+ */
87
+ export function resolveStageName(input) {
88
+ const key = stageKey(input);
89
+ const options = STATUS_OPTIONS.map(s => ({ name: s.name, key: stageKey(s.name) }));
90
+ const list = () => STATUS_OPTIONS.map(s => `"${s.name}"`).join(', ');
91
+
92
+ if (!key) {
93
+ return { stage: null, error: `Etapa não informada. Use uma destas: ${list()}.` };
94
+ }
95
+
96
+ const exact = options.find(o => o.key === key);
97
+ if (exact) return { stage: exact.name, error: null };
98
+
99
+ const partial = options.filter(o => o.key.startsWith(key));
100
+ if (partial.length === 1) return { stage: partial[0].name, error: null };
101
+ if (partial.length > 1) {
102
+ return {
103
+ stage: null,
104
+ error:
105
+ `Etapa "${input}" é ambígua — casa com ${partial.map(o => `"${o.name}"`).join(' e ')}. ` +
106
+ 'Seja mais específico.',
107
+ };
108
+ }
109
+
110
+ return { stage: null, error: `Etapa "${input}" não existe. Use uma destas: ${list()}.` };
111
+ }
112
+
113
+ /**
114
+ * Índice do board por número de issue (função PURA).
115
+ *
116
+ * @param {Array<{number:number}>} items saída de listProjectItems
117
+ * @returns {Map<number, object>}
118
+ */
119
+ export function indexBoardItems(items) {
120
+ return new Map((items || []).filter(i => i?.number).map(i => [i.number, i]));
121
+ }
122
+
123
+ /**
124
+ * As Features que ainda têm trabalho (função PURA).
125
+ *
126
+ * "Ainda tem trabalho" = issue aberta e Etapa diferente de 🎉 Done. É este o
127
+ * conjunto do `order` sem argumento: o mapa de quem depende de quem quando o
128
+ * trabalho de uma onda inteira está espalhado por várias Features.
129
+ *
130
+ * O tipo sai do campo "Work Item Type", com FALLBACK no prefixo do título: o
131
+ * campo ficou vazio em todo item criado pelo apply até a v0.21.0, e um board com
132
+ * esse buraco não pode virar um mapa vazio em silêncio.
133
+ *
134
+ * @param {Array<object>} items saída de listProjectItems
135
+ * @returns {Array<object>} Features, em ordem crescente de número
136
+ */
137
+ export function selectOpenFeatures(items) {
138
+ return (items || [])
139
+ .filter(i => i?.number
140
+ && String(i.state || '').toUpperCase() !== 'CLOSED'
141
+ && (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
142
+ && i.fields?.Etapa !== STAGE_DONE)
143
+ .sort((a, b) => a.number - b.number);
144
+ }
package/src/lib/board.mjs CHANGED
@@ -1,12 +1,37 @@
1
- // Helpers compartilhados de manipulação do board (GitHub Projects v2).
2
- // Extraídos de code-review.mjs/qa.mjs para uso também pelos comandos de CLI
3
- // (task/story/order). Ver a distinção Etapa × Status em config.mjs.
4
- import { addProjectItem, setItemSingleSelect, getSingleSelectField, getItemSingleSelectValue } from '../api/github-graphql.mjs';
5
- import { CONFIG_FILE, STAGE_ORDER, STATUS_OPTIONS, WORK_ITEM_TYPES, STAGE_DONE } from '../config.mjs';
1
+ // O SERVIÇO de fluxo do board.
2
+ //
3
+ // A política (quem pode andar para onde) saiu para `board-policy.mjs`; o
4
+ // endereçamento (ids de campo, ids de opção, item do project) saiu para
5
+ // `src/plugins/tracker-github-projects/`. O que sobra aqui é a ORQUESTRAÇÃO, e
6
+ // ela é a parte que não pode virar comportamento por fornecedor:
7
+ //
8
+ // ler a etapa atual → consultar a política → só então mandar escrever.
9
+ //
10
+ // Este é o único módulo do core autorizado a chamar `tracker.setStage`. Quando
11
+ // essa chamada acontece, o guard JÁ rodou — o plugin nunca recebe a pergunta
12
+ // "pode avançar?".
13
+ //
14
+ // Ver a distinção Etapa × Status em config.mjs: `stage` é a coluna, `progress`
15
+ // é o Todo/In Progress/Done DENTRO dela, e os dois são dimensões separadas.
16
+
17
+ import { CONFIG_FILE, WORK_ITEM_TYPES } from '../config.mjs';
18
+ import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
6
19
  import { loadConfig } from './project-root.mjs';
7
20
  import { invalidateCache } from './net-cache.mjs';
8
-
9
- // Toda ESCRITA de board passa por advanceToStage/setItemStage/setItemStatus —
21
+ import { planStageMove } from './board-policy.mjs';
22
+
23
+ // A política continua exportada daqui: era daqui que ~10 módulos e 6 testes a
24
+ // importavam, e trocar o caminho de import em todos eles no mesmo commit em que
25
+ // o corpo muda de casa tornaria o diff impossível de conferir.
26
+ export {
27
+ indexBoardItems,
28
+ planStageMove,
29
+ resolveStageName,
30
+ selectOpenFeatures,
31
+ shouldAdvanceStage,
32
+ } from './board-policy.mjs';
33
+
34
+ // Toda ESCRITA de board passa por advanceToStage/forceStage/setProgress —
10
35
  // invalidar aqui cobre todos os comandos de uma vez (move, qa, code-review,
11
36
  // merge, implement…): o snapshot cacheado (`board-items`, lib/net-cache.mjs)
12
37
  // não pode sobreviver a uma Etapa que acabou de mudar. Best-effort por
@@ -22,9 +47,6 @@ function dropBoardCache() {
22
47
  * @param {object} [opts]
23
48
  * @param {string} [opts.cwd=process.cwd()] diretório onde começar a busca
24
49
  * @returns {{ project: object|null, root: string|null, error: string|null }}
25
- * project = bloco com id/fields; root = diretório do config;
26
- * error = motivo legível quando project é null (compõe os avisos
27
- * "… — board não atualizado." dos chamadores).
28
50
  */
29
51
  export function loadProjectConfig({ cwd = process.cwd() } = {}) {
30
52
  const { config, root, error } = loadConfig(cwd);
@@ -37,142 +59,76 @@ export function loadProjectConfig({ cwd = process.cwd() } = {}) {
37
59
  }
38
60
 
39
61
  /**
40
- * Resolve um campo SINGLE_SELECT do Project pelo nome: usa os IDs gravados no
41
- * .spec-wave.json (bloco `fields`, ou o formato legado etapaFieldId/
42
- * stageOptions para "Etapa") e cai na API GraphQL como fallback.
43
- *
44
- * @param {string} token
45
- * @param {object} project bloco project do .spec-wave.json (precisa de .id)
46
- * @param {string} name nome do campo (ex.: 'Etapa', 'Status')
47
- * @returns {Promise<{ id: string, options: Record<string,string> }|null>}
48
- */
49
- export async function resolveField(token, project, name) {
50
- if (project.fields?.[name]) return project.fields[name];
51
- if (name === 'Etapa' && project.etapaFieldId) {
52
- return { id: project.etapaFieldId, options: project.stageOptions || {} };
53
- }
54
- return await getSingleSelectField(token, project.id, name);
55
- }
56
-
57
- /**
58
- * A Etapa pode avançar de `current` para `target`? (função PURA — testável).
62
+ * Há um tracker utilizável a partir daqui? (só leitura de config)
59
63
  *
60
- * Regra do board: a Etapa só AVANÇA. Três casos param o movimento:
61
- * • já está no destino ou adiante na ordem canônica;
62
- * • a etapa ATUAL não está em STAGE_ORDER (coluna criada à mão no board, ou
63
- * resíduo de uma versão anterior do config). Antes esse caso caía no
64
- * `curIdx === -1` e DESLIGAVA o guard, permitindo retrocesso — sem saber onde
65
- * o item está na ordem, o certo é não mexer;
66
- * • a etapa de DESTINO não está em STAGE_ORDER (nome inválido).
64
+ * Substitui o uso de `loadProjectConfig` por quem só queria a STRING DE ERRO —
65
+ * `run`, `implement`, `qa-lead` e `order` a usavam assim, e nenhum deles
66
+ * precisa saber que existe um bloco `project` com ids do Projects v2.
67
67
  *
68
- * @param {string|null} current etapa atual do item (null = ainda sem etapa)
69
- * @param {string} target etapa de destino
70
- * @returns {boolean} true se deve escrever a nova Etapa
68
+ * @param {object} [opts]
69
+ * @param {string} [opts.cwd=process.cwd()]
70
+ * @returns {{ ok: boolean, root: string|null, error: string|null }}
71
71
  */
72
- export function shouldAdvanceStage(current, target) {
73
- const tgtIdx = STAGE_ORDER.indexOf(target);
74
- if (tgtIdx === -1) return false;
75
- if (!current) return true; // item ainda sem Etapa definida
76
- const curIdx = STAGE_ORDER.indexOf(current);
77
- if (curIdx === -1) return false; // etapa atual desconhecida — não arrisca retroceder
78
- return curIdx < tgtIdx;
79
- }
80
-
81
- // Normaliza para comparação: sem emoji/pontuação, minúsculo, espaços colapsados.
82
- // "👀 Code Review" e "code review" precisam casar.
83
- function stageKey(value) {
84
- return String(value ?? '')
85
- .normalize('NFD')
86
- .replace(/[̀-ͯ]/g, '') // acentos (após NFD)
87
- .replace(/[^\p{Letter}\p{Number}]+/gu, ' ') // emoji e pontuação
88
- .trim()
89
- .toLowerCase();
72
+ export function trackerAvailable({ cwd = process.cwd() } = {}) {
73
+ const { project, root, error } = loadProjectConfig({ cwd });
74
+ return { ok: Boolean(project), root, error };
90
75
  }
91
76
 
92
77
  /**
93
- * Resolve o nome canônico de uma Etapa a partir de entrada humana (função PURA).
94
- *
95
- * Aceita o nome com ou sem emoji, com qualquer caixa e sem acento
96
- * ("code review", "Homologacao", "🚧 Desenvolvimento"). Casa primeiro exato,
97
- * depois por prefixo; prefixo que casa com mais de uma etapa é AMBÍGUO e vira
98
- * erro listando as candidatas — melhor recusar que mover para a coluna errada.
99
- *
100
- * @param {string} input entrada do usuário
101
- * @returns {{ stage: string|null, error: string|null }}
78
+ * Monta a porta de tracker a partir do config, com a credencial de board.
79
+ *
80
+ * `projectToken` é separado porque quatro comandos e uma lib usam
81
+ * `PROJECT_TOKEN || token` SÓ para Projects v2 — ver a nota em
82
+ * `src/plugins/tracker-github-projects/index.mjs`.
83
+ *
84
+ * @param {object} params
85
+ * @param {string} params.token
86
+ * @param {string} [params.projectToken]
87
+ * @param {string} params.owner
88
+ * @param {string} params.repo
89
+ * @param {string} [params.cwd]
90
+ * @param {object} [params.tracker] porta JÁ construída — é o seam dos testes de
91
+ * fumaça (`deps.tracker`). Quando vem, o bloco `project` do config nem é
92
+ * exigido: quem injeta a porta já decidiu de onde ela vem. `root` continua
93
+ * saindo do config, porque os chamadores o usam para achar os documentos.
94
+ * @returns {{ tracker: object|null, root: string|null, error: string|null }}
102
95
  */
103
- export function resolveStageName(input) {
104
- const key = stageKey(input);
105
- const options = STATUS_OPTIONS.map(s => ({ name: s.name, key: stageKey(s.name) }));
106
- const list = () => STATUS_OPTIONS.map(s => `"${s.name}"`).join(', ');
107
-
108
- if (!key) {
109
- return { stage: null, error: `Etapa não informada. Use uma destas: ${list()}.` };
110
- }
111
-
112
- const exact = options.find(o => o.key === key);
113
- if (exact) return { stage: exact.name, error: null };
114
-
115
- const partial = options.filter(o => o.key.startsWith(key));
116
- if (partial.length === 1) return { stage: partial[0].name, error: null };
117
- if (partial.length > 1) {
118
- return {
119
- stage: null,
120
- error:
121
- `Etapa "${input}" é ambígua — casa com ${partial.map(o => `"${o.name}"`).join(' e ')}. ` +
122
- 'Seja mais específico.',
123
- };
96
+ export function openTracker({ token, projectToken, owner, repo, cwd = process.cwd(), tracker: injetado = null } = {}) {
97
+ const { config, root, error: configError } = loadConfig(cwd);
98
+ if (injetado) return { tracker: injetado, root, error: null };
99
+ if (configError) return { tracker: null, root, error: configError };
100
+ const project = config.project || {};
101
+ if (!project.id) {
102
+ return { tracker: null, root, error: `Project não configurado em ${CONFIG_FILE}` };
124
103
  }
125
-
126
- return { stage: null, error: `Etapa "${input}" não existe. Use uma destas: ${list()}.` };
104
+ // owner/repo caem no config quando o chamador não os tem: `loadProjectConfig`
105
+ // nunca precisou deles (o board é endereçado por `project.id`), mas a porta
106
+ // também faz REST de issue, que é endereçada por repositório. Quem TEM o par
107
+ // resolvido — os comandos, via resolveHubContext — passa o dele e vence.
108
+ return {
109
+ tracker: createGithubTracker({
110
+ token,
111
+ projectToken,
112
+ owner: owner || config.owner,
113
+ repo: repo || config.repo,
114
+ project,
115
+ }),
116
+ root,
117
+ error: null,
118
+ };
127
119
  }
128
120
 
129
121
  /**
130
- * Índice do board por número de issue (função PURA).
122
+ * Preenche um campo do item quando ele está VAZIO (best-effort).
131
123
  *
132
- * @param {Array<{number:number}>} items saída de listProjectItems
133
- * @returns {Map<number, object>}
134
- */
135
- export function indexBoardItems(items) {
136
- return new Map((items || []).filter(i => i?.number).map(i => [i.number, i]));
137
- }
138
-
139
- /**
140
- * As Features que ainda têm trabalho (função PURA).
141
- *
142
- * "Ainda tem trabalho" = issue aberta e Etapa diferente de 🎉 Done. É este o
143
- * conjunto do `order` sem argumento: o mapa de quem depende de quem quando o
144
- * trabalho de uma onda inteira está espalhado por várias Features.
124
+ * O "Work Item Type" existe no board desde o `init`, mas só o comando `issue` o
125
+ * escrevia: toda issue nascida do `decompose --apply` (dezenas por Feature)
126
+ * ficava com o tipo em branco, e as telas que agrupam por ele as perdiam.
145
127
  *
146
- * O tipo sai do campo "Work Item Type", com FALLBACK no prefixo do título: o
147
- * campo ficou vazio em todo item criado pelo apply até a v0.21.0, e um board com
148
- * esse buraco não pode virar um mapa vazio em silêncio.
149
- *
150
- * @param {Array<object>} items saída de listProjectItems
151
- * @returns {Array<object>} Features, em ordem crescente de número
152
- */
153
- export function selectOpenFeatures(items) {
154
- return (items || [])
155
- .filter(i => i?.number
156
- && String(i.state || '').toUpperCase() !== 'CLOSED'
157
- && (i.fields?.['Work Item Type'] === 'Feature' || /^\s*\[FEATURE\]/i.test(i.title || ''))
158
- && i.fields?.Etapa !== STAGE_DONE)
159
- .sort((a, b) => a.number - b.number);
160
- }
161
-
162
- /**
163
- * Preenche o "Work Item Type" do item quando ele está VAZIO (best-effort).
164
- *
165
- * O campo existe no board desde o `init`, mas só o comando `issue` o escrevia:
166
- * toda issue nascida do `decompose --apply` (dezenas por Feature) e todo item
167
- * que entrou no board por outro caminho ficavam com o tipo em branco, e as
168
- * telas que agrupam por Work Item Type os perdiam. Não é configuração faltando:
169
- * os mesmos ids, project e token escrevem o campo sem falha quando alguém o faz
170
- * à mão. O `move` também não o reparava, então nem passar pelo fluxo corrigia.
171
- *
172
- * Escreve só no vazio, de propósito: o tipo do título ("[STORY] …") é uma
173
- * inferência, e sobrescrever um valor que um humano ajustou no board seria
128
+ * Escreve só no vazio, de propósito: o tipo inferido do título ("[STORY] …") é
129
+ * uma inferência, e sobrescrever um valor que um humano ajustou no board seria
174
130
  * trocar um dado bom por um palpite. Por isso também roda ANTES do guard de
175
- * avanço de Etapa — item já adiante não avança, mas continua merecendo o reparo.
131
+ * avanço — item já adiante não avança, mas continua merecendo o reparo.
176
132
  *
177
133
  * Nunca lança: campo ausente, opção inexistente ou falha de rede viram `false`.
178
134
  * O tipo é informação de organização; derrubar por causa dele um comando que
@@ -180,16 +136,17 @@ export function selectOpenFeatures(items) {
180
136
  *
181
137
  * @returns {Promise<boolean>} true se escreveu o campo agora
182
138
  */
183
- export async function ensureWorkItemType(token, project, typeField, itemId, itemType) {
184
- if (!typeField?.id || !itemType) return false;
139
+ export async function ensureWorkItemType(tracker, ref, itemType) {
140
+ if (!tracker || !ref || !itemType) return false;
141
+ // O vocabulário é do RFC-001, não do fornecedor: quem decide que "Story" é um
142
+ // tipo e "Bugzinho" não é o core. Deixar a recusa por conta do plugin — que
143
+ // só sabe dizer "não tenho essa opção" — amarraria a regra ao board em uso: um
144
+ // board com uma opção extra passaria a aceitar tipo fora do vocabulário, e o
145
+ // `setField` é genérico para TODO campo, então não é lugar de conhecer o
146
+ // vocabulário de um deles.
185
147
  if (!WORK_ITEM_TYPES.includes(itemType)) return false;
186
- const optionId = typeField.options?.[itemType];
187
- if (!optionId) return false;
188
148
  try {
189
- const current = await getItemSingleSelectValue(token, itemId, typeField.id);
190
- if (current) return false; // já tem tipo — nunca sobrescreve
191
- await setItemSingleSelect(token, project.id, itemId, typeField.id, optionId);
192
- return true;
149
+ return await tracker.setField({ ref, field: 'workItemType', value: itemType, onlyIfEmpty: true });
193
150
  } catch (err) {
194
151
  // Avisa em vez de calar: foi o silêncio que deixou 120 itens sem tipo por
195
152
  // seis features seguidas sem ninguém perceber.
@@ -199,57 +156,31 @@ export async function ensureWorkItemType(token, project, typeField, itemId, item
199
156
  }
200
157
 
201
158
  /**
202
- * Avança um item do board para `targetStage` (Etapa) e define o Status para
203
- * `targetStatus`. Uma issue só AVANÇA: se já estiver em `targetStage` ou em uma
204
- * etapa posterior (pela ordem canônica STAGE_ORDER), não é tocada.
159
+ * Avança um item para `stage` e, opcionalmente, escreve o progresso.
205
160
  *
206
- * @param {string} token token com scope project
207
- * @param {object} project bloco project (precisa de .id)
208
- * @param {{id,options}|null} etapaField campo "Etapa" (ver resolveField)
209
- * @param {{id,options}|null} statusField campo nativo "Status"
210
- * @param {string} nodeId node id da issue
211
- * @param {string} targetStage nome da etapa de destino
212
- * @param {string} targetStatus valor do Status (Todo/In Progress/Done)
213
- * @param {object} [opts]
214
- * @param {{id,options}|null} [opts.typeField] campo "Work Item Type" (ver resolveField)
215
- * @param {string} [opts.itemType] tipo do item ('Story', 'Task', …) — escrito
216
- * apenas se o campo estiver vazio (ver ensureWorkItemType)
161
+ * A POLÍTICA é aplicada aqui, antes de qualquer escrita: lê a etapa atual,
162
+ * consulta `planStageMove` (pura) e só então manda escrever.
163
+ *
164
+ * @param {object} params
165
+ * @param {object} params.tracker porta de tracker
166
+ * @param {object|string|number} params.ref work item
167
+ * @param {string} params.stage etapa de destino
168
+ * @param {string|null} [params.progress] Todo / In Progress / Done
169
+ * @param {string|null} [params.itemType] escrito só se o campo estiver vazio
217
170
  * @returns {Promise<boolean>} true se avançou; false se já estava adiante
218
171
  */
219
- export async function advanceToStage(
220
- token, project, etapaField, statusField, nodeId, targetStage, targetStatus, opts = {}
221
- ) {
222
- const itemId = await addProjectItem(token, project.id, nodeId);
223
- // Antes do guard de avanço: item que não avança também precisa do reparo.
224
- await ensureWorkItemType(token, project, opts.typeField, itemId, opts.itemType);
225
-
226
- if (etapaField?.id && targetStage) {
227
- // Nunca retroceder — a decisão vive em shouldAdvanceStage (pura, testada).
228
- const current = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
229
- if (!shouldAdvanceStage(current, targetStage)) return false;
230
- const optionId = etapaField.options?.[targetStage];
231
- // Opção que não resolve é board divergente (coluna renomeada, init de outra
232
- // versão) — pular a escrita e devolver true fazia o chamador imprimir ✅
233
- // sem nada ter sido escrito. Melhor falhar nomeando o que faltou.
234
- if (!optionId) {
235
- throw new Error(
236
- `A Etapa "${targetStage}" não existe no board (opções: ` +
237
- `${Object.keys(etapaField.options || {}).join(', ') || 'nenhuma'}). ` +
238
- 'O board divergiu da config — rode `spec-wave refresh` ou renomeie a coluna de volta.'
239
- );
240
- }
241
- await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
172
+ export async function advanceToStage({ tracker, ref, stage, progress = null, itemType = null }) {
173
+ // Antes do guard: item que não avança também precisa do reparo de tipo.
174
+ await ensureWorkItemType(tracker, ref, itemType);
175
+
176
+ if (stage) {
177
+ const current = await tracker.getStage({ ref }).catch(() => null);
178
+ if (!planStageMove({ current, target: stage }).advance) return false;
179
+ await tracker.setStage({ ref, stage });
242
180
  dropBoardCache();
243
181
  }
244
- if (statusField?.id && targetStatus) {
245
- const optionId = statusField.options?.[targetStatus];
246
- if (!optionId) {
247
- throw new Error(
248
- `O Status "${targetStatus}" não existe no board (opções: ` +
249
- `${Object.keys(statusField.options || {}).join(', ') || 'nenhuma'}).`
250
- );
251
- }
252
- await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
182
+ if (progress) {
183
+ await tracker.setProgress({ ref, progress });
253
184
  dropBoardCache();
254
185
  }
255
186
  return true;
@@ -262,65 +193,35 @@ export async function advanceToStage(
262
193
  * escape hatch: a Etapa só avança. Esta função existe porque a automação erra —
263
194
  * uma corrida entre o `decompose-apply` e o `code-review` já pôs duas Stories e
264
195
  * duas Tasks em 🎉 Done no nascimento — e a única saída era mutação GraphQL
265
- * crua: sem trava, sem confirmação e sem rastro. Um caminho com as três é
266
- * melhor que a mão livre.
196
+ * crua: sem trava, sem confirmação e sem rastro.
267
197
  *
268
198
  * Quem chama (`repair-stage`) é responsável pela confirmação e pelo registro na
269
199
  * issue. Aqui só se escreve.
270
200
  *
271
- * @param {string} token token com scope project
272
- * @param {object} project bloco project (precisa de .id)
273
- * @param {{id,options}|null} etapaField campo "Etapa" (ver resolveField)
274
- * @param {{id,options}|null} statusField campo nativo "Status"
275
- * @param {string} nodeId node id da issue
276
- * @param {string} targetStage etapa de destino (precisa existir em STAGE_ORDER)
277
- * @param {string} [targetStatus] valor do Status; omitido = não mexe no Status
278
- * @param {object} [opts] mesmo `{ typeField, itemType }` de advanceToStage
279
201
  * @returns {Promise<{ from: string|null }>} etapa em que o item estava
280
202
  */
281
- export async function setItemStage(
282
- token, project, etapaField, statusField, nodeId, targetStage, targetStatus, opts = {}
283
- ) {
284
- if (!etapaField?.id) throw new Error('Campo "Etapa" não encontrado no Project — nada a reparar.');
285
- if (STAGE_ORDER.indexOf(targetStage) === -1) {
286
- throw new Error(`Etapa "${targetStage}" não faz parte do fluxo (${STAGE_ORDER.join(' → ')}).`);
287
- }
288
- const optionId = etapaField.options?.[targetStage];
289
- if (!optionId) {
290
- throw new Error(
291
- `A opção "${targetStage}" não existe no campo Etapa deste Project. ` +
292
- 'Rode `spec-wave refresh --config` para sincronizar os ids.'
293
- );
294
- }
295
- const itemId = await addProjectItem(token, project.id, nodeId);
296
- await ensureWorkItemType(token, project, opts.typeField, itemId, opts.itemType);
297
- const from = await getItemSingleSelectValue(token, itemId, etapaField.id).catch(() => null);
298
- await setItemSingleSelect(token, project.id, itemId, etapaField.id, optionId);
299
- if (statusField?.id && targetStatus) {
300
- const statusOption = statusField.options?.[targetStatus];
301
- if (statusOption) await setItemSingleSelect(token, project.id, itemId, statusField.id, statusOption);
203
+ export async function forceStage({ tracker, ref, stage, progress = null, itemType = null }) {
204
+ const { reason } = planStageMove({ current: null, target: stage });
205
+ if (reason === 'destino-invalido') {
206
+ throw new Error(`Etapa "${stage}" não faz parte do fluxo.`);
302
207
  }
208
+ await ensureWorkItemType(tracker, ref, itemType);
209
+ const from = await tracker.getStage({ ref }).catch(() => null);
210
+ await tracker.setStage({ ref, stage, force: true });
211
+ if (progress) await tracker.setProgress({ ref, progress }).catch(() => false);
303
212
  dropBoardCache();
304
213
  return { from };
305
214
  }
306
215
 
307
216
  /**
308
- * Define APENAS o Status nativo (Todo/In Progress/Done) de um item, sem tocar
309
- * na Etapa — usado para marcar progresso dentro da etapa atual.
217
+ * Define APENAS o progresso (Todo/In Progress/Done), sem tocar na Etapa —
218
+ * usado para marcar trabalho em curso DENTRO da etapa atual.
310
219
  *
311
- * @param {string} token token com scope project
312
- * @param {object} project bloco project (precisa de .id)
313
- * @param {{id,options}|null} statusField campo nativo "Status"
314
- * @param {string} nodeId node id da issue
315
- * @param {string} status valor de destino (Todo/In Progress/Done)
316
- * @returns {Promise<boolean>} true se definiu; false se campo/opção ausentes
220
+ * @returns {Promise<boolean>} true se definiu
317
221
  */
318
- export async function setItemStatus(token, project, statusField, nodeId, status) {
319
- if (!statusField?.id) return false;
320
- const optionId = statusField.options?.[status];
321
- if (!optionId) return false;
322
- const itemId = await addProjectItem(token, project.id, nodeId);
323
- await setItemSingleSelect(token, project.id, itemId, statusField.id, optionId);
324
- dropBoardCache();
325
- return true;
222
+ export async function setProgress({ tracker, ref, progress }) {
223
+ if (!progress) return false;
224
+ const ok = await tracker.setProgress({ ref, progress }).catch(() => false);
225
+ if (ok) dropBoardCache();
226
+ return ok;
326
227
  }
@@ -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
  }