@spec-wave/cli 1.2.0 → 1.3.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spec-wave/cli",
3
- "version": "1.2.0",
3
+ "version": "1.3.0",
4
4
  "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
5
5
  "type": "module",
6
6
  "bin": {
@@ -387,6 +387,21 @@ export async function updateMilestone(token, owner, repo, milestoneNumber, { tit
387
387
 
388
388
  // Atribui (ou REMOVE, com `null`) a milestone de uma issue que já existe.
389
389
  //
390
+ // Edita campos de uma issue. `campos` vai CRU para o PATCH: quem chama decide o
391
+ // que entra, e o que não entra não é tocado.
392
+ //
393
+ // A seleção mora no chamador de propósito. A parcialidade aqui é uma garantia
394
+ // de contrato — o corpo de uma Story carrega a linha `Depende de: #N` que o
395
+ // `implement` e o `merge` leem (lib/dependencies.mjs), e uma escrita que
396
+ // mandasse o corpo junto num renomear de título apagaria a dependência com
397
+ // sucesso na chamada e silêncio no efeito. Decidir aqui dentro tornaria essa
398
+ // garantia intestável: esta camada não tem mock de HTTP, e a mutação que a
399
+ // quebra passa verde. Um nível acima, o teste vê o payload.
400
+ export async function updateIssue(token, owner, repo, issueNumber, campos = {}) {
401
+ const octokit = makeOctokit(token);
402
+ await octokit.rest.issues.update({ owner, repo, issue_number: issueNumber, ...campos });
403
+ }
404
+
390
405
  // A assimetria com `createIssue` é da API e é fácil de trocar: lá `milestone:
391
406
  // null` leva 422 e por isso o campo só entra quando existe; aqui `null` é
392
407
  // justamente como se remove, e omitir o campo é que seria "não mexe". Um `...(m
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.2.0",
4
+ "version": "1.3.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",
@@ -44,6 +44,7 @@ import {
44
44
  setIssueMilestone,
45
45
  setIssueState,
46
46
  updateComment,
47
+ updateIssue,
47
48
  updateLabel,
48
49
  updateMilestone,
49
50
  updateMilestoneDescription,
@@ -82,6 +83,7 @@ export const GITHUB_TRACKER_CAPABILITIES = Object.freeze({
82
83
  hierarchy: 'native', // sub-issues
83
84
  dependencies: 'native', // API de dependencies (blocked_by)
84
85
  milestones: 'native',
86
+ reopen: 'native', // `setIssueState(..., 'open')` — sem workflow no caminho
85
87
  stages: Object.freeze({ mode: 'set', multiHop: false, reopenable: true }),
86
88
  progress: 'native', // o campo nativo "Status" do Projects v2
87
89
  fields: Object.freeze({
@@ -177,7 +179,7 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
177
179
  addBlockedBy, addLabel, commentOnIssue, countOpenIssuesWithLabel, createIssue, createLabel,
178
180
  createMilestone, deleteLabel, getIssue, getMilestone, getOwnerType, listBlockedBy,
179
181
  listIssueComments, listIssuesByMilestone, listLabels, listMilestones, removeLabel,
180
- setIssueMilestone, setIssueState, updateComment, updateLabel, updateMilestone,
182
+ setIssueMilestone, setIssueState, updateComment, updateIssue, updateLabel, updateMilestone,
181
183
  updateMilestoneDescription, getOwnerNodeId, getRepoNodeId,
182
184
  addProjectItem, addSubIssue, createProject, createSingleSelectField, createTextField,
183
185
  getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getRateLimit,
@@ -560,12 +562,29 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
560
562
  });
561
563
  },
562
564
 
565
+ // A parcialidade é decidida AQUI, e não na rota: campo ausente não entra no
566
+ // payload. É o único nível em que um teste consegue ver o que foi enviado —
567
+ // ver a nota em `updateIssue` (github-rest.mjs).
568
+ async updateWorkItem({ ref, title, body } = {}) {
569
+ const campos = {};
570
+ if (title !== undefined) campos.title = title;
571
+ if (body !== undefined) campos.body = body;
572
+ await a.updateIssue(token, owner, repo, refNumber(refKey(ref)), campos);
573
+ },
574
+
563
575
  closeWorkItem({ ref } = {}) {
564
576
  // `reason` é ignorado: no GitHub fechar é um ESTADO, e a distinção
565
577
  // rejeitado × duplicata já vive nas labels (`closeSemantics: 'state'`).
566
578
  return a.setIssueState(token, owner, repo, refNumber(ref), 'closed');
567
579
  },
568
580
 
581
+ // A mesma rota, o outro estado. O `state_reason: 'reopened'` é o GitHub que
582
+ // escreve — o contrato já o lia (`WorkItem.stateReason`) antes de existir
583
+ // qualquer forma de produzi-lo.
584
+ reopenWorkItem({ ref } = {}) {
585
+ return a.setIssueState(token, owner, repo, refNumber(ref), 'open');
586
+ },
587
+
569
588
  async addChild({ parent, child } = {}) {
570
589
  const p = await hidratar(parent);
571
590
  const c = await hidratar(child);
@@ -100,6 +100,18 @@
100
100
  * exatamente disto — e fazê-lo no core custaria um get + um set, dois
101
101
  * round-trips onde um tracker pode fazer um. Devolve `true` se escreveu.
102
102
  *
103
+ * @property {(o: {ref: WorkItemRef, title?: string, body?: string}) => Promise<void>} updateWorkItem
104
+ * PARCIAL: campo não passado não é tocado, e isso é requisito, não
105
+ * conveniência. O `body` de uma Story carrega a linha `Depende de: #N` que
106
+ * `lib/dependencies.mjs` analisa e que `implement` e `merge` leem — uma
107
+ * escrita que exigisse o corpo inteiro faria um renomear de título apagar
108
+ * dependência, com sucesso na chamada e silêncio no efeito.
109
+ *
110
+ * OBRIGATÓRIA, e sem capability que a desligue: `createWorkItem` já toma
111
+ * `title` e `body`, então todo tracker que implementa a criação sabe escrever
112
+ * os dois. Não existe fornecedor onde nascer com título seja possível e
113
+ * renomear não.
114
+ *
103
115
  * @property {() => Promise<BoardItem[]>} boardSnapshot
104
116
  * @property {(o: {ref: WorkItemRef, reason?: 'completed'|'not-planned'|'duplicate'}) => Promise<void>} closeWorkItem
105
117
  * `reason` existe porque em `closeSemantics: 'transition-and-resolution'` o
@@ -108,6 +120,26 @@
108
120
  *
109
121
  * ── CONDICIONAIS ──────────────────────────────────────────────────────────
110
122
  *
123
+ * @property {(o: {ref: WorkItemRef}) => Promise<void>} [reopenWorkItem] reopen: 'native'
124
+ * A inversa de `closeWorkItem`. O contrato já sabia LER um item reaberto —
125
+ * `WorkItem.stateReason` tem `'reopened'` no enum desde a Fase 1 — e não
126
+ * tinha como produzir um: a rota existia (`setIssueState` aceita o estado) e
127
+ * só era chamada com `'closed'`, pelo único consumidor que havia.
128
+ *
129
+ * Sem argumento de destino, e isso só é possível porque `state`, `stage` e
130
+ * `progress` são três dimensões SEPARADAS aqui: reabrir não decide para qual
131
+ * Etapa o item volta, porque a Etapa não muda. Num tracker
132
+ * `closeSemantics: 'transition-and-resolution'` o plugin transiciona para o
133
+ * status não-Done que corresponde à Etapa atual e limpa a `resolution` — a
134
+ * informação necessária já está no item.
135
+ *
136
+ * CONDICIONAL, e não obrigatória junto com `closeWorkItem`, por uma
137
+ * assimetria real: `closeSemantics` garante que fechar é sempre possível
138
+ * (todo valor do enum implica isso), mas sair de Done depende de existir a
139
+ * transição no workflow do site — no Jira isso é configuração de quem
140
+ * instalou, não do fornecedor. `reopen: 'none'` é a declaração honesta desse
141
+ * caso, e o core recusa com mensagem em vez de tentar e estourar.
142
+ *
111
143
  * @property {(o: {ref: WorkItemRef}) => Promise<Progress|null>} [getProgress] progress: 'native'
112
144
  * @property {(o: {ref: WorkItemRef, progress: Progress}) => Promise<boolean>} [setProgress]
113
145
  *
@@ -190,7 +222,7 @@
190
222
  */
191
223
  export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
192
224
  'setup', 'verify',
193
- 'createWorkItem', 'getWorkItem', 'listWorkItemsByTag',
225
+ 'createWorkItem', 'getWorkItem', 'updateWorkItem', 'listWorkItemsByTag',
194
226
  'addComment', 'listComments', 'updateComment',
195
227
  'addTag', 'removeTag', 'ensureTags', 'listTags',
196
228
  'getStage', 'setStage',
@@ -209,6 +241,7 @@ export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
209
241
  * @type {Readonly<Record<string, Readonly<string[]>>>}
210
242
  */
211
243
  export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
244
+ 'reopen=native': Object.freeze(['reopenWorkItem']),
212
245
  'progress=native': Object.freeze(['getProgress', 'setProgress']),
213
246
  'hierarchy=native': Object.freeze(['addChild', 'listChildren', 'getParent']),
214
247
  'dependencies=native': Object.freeze(['addBlockedBy', 'listBlockedBy']),
@@ -236,6 +269,9 @@ export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
236
269
  export function trackerRequiredOperations(capabilities = {}) {
237
270
  const exigidas = new Set(TRACKER_REQUIRED_OPERATIONS);
238
271
  const ligada = {
272
+ // Ausente vale `none`: um plugin que não declara reabrir não ganha a
273
+ // operação por omissão, e o core tem de perguntar antes de oferecer.
274
+ 'reopen=native': capabilities.reopen === 'native',
239
275
  'progress=native': capabilities.progress === 'native',
240
276
  'hierarchy=native': capabilities.hierarchy === 'native',
241
277
  'dependencies=native': capabilities.dependencies === 'native',