@spec-wave/cli 1.1.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.1.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": {
@@ -550,6 +550,57 @@ export async function setItemSingleSelect(token, projectId, itemId, fieldId, opt
550
550
  `, { projectId, itemId, fieldId, optionId });
551
551
  }
552
552
 
553
+ // Define o valor de um campo TEXT para um item do Project.
554
+ //
555
+ // Rota separada da de single-select porque a mutation exige `value: { text: }`
556
+ // contra `value: { singleSelectOptionId: }` — não é o mesmo payload com outro
557
+ // argumento.
558
+ export async function setItemText(token, projectId, itemId, fieldId, text) {
559
+ const client = makeClient(token);
560
+ await client(`
561
+ mutation SetTextField($projectId: ID!, $itemId: ID!, $fieldId: ID!, $text: String!) {
562
+ updateProjectV2ItemFieldValue(input: {
563
+ projectId: $projectId
564
+ itemId: $itemId
565
+ fieldId: $fieldId
566
+ value: { text: $text }
567
+ }) {
568
+ projectV2Item { id }
569
+ }
570
+ }
571
+ `, { projectId, itemId, fieldId, text: String(text ?? '') });
572
+ }
573
+
574
+ // Lê o valor atual de um campo TEXT.
575
+ //
576
+ // Função NOVA em vez de um fragmento a mais em `getItemSingleSelectValue`: essa
577
+ // query é a leitura que o guard "a Etapa só avança" faz em todo movimento de
578
+ // board, e nenhum teste desta suíte fala GraphQL de verdade. Mexer nela para
579
+ // atender um campo que nada escreve hoje seria arriscar o caminho mais
580
+ // carregado do sistema pelo menos carregado.
581
+ export async function getItemTextValue(token, itemId, fieldId) {
582
+ const client = makeClient(token);
583
+ const result = await client(`
584
+ query ItemTextValue($itemId: ID!) {
585
+ node(id: $itemId) {
586
+ ... on ProjectV2Item {
587
+ fieldValues(first: 50) {
588
+ nodes {
589
+ ... on ProjectV2ItemFieldTextValue {
590
+ text
591
+ field { ... on ProjectV2Field { id } }
592
+ }
593
+ }
594
+ }
595
+ }
596
+ }
597
+ }
598
+ `, { itemId });
599
+ const nodes = result.node?.fieldValues?.nodes || [];
600
+ const value = nodes.find(n => n && n.field?.id === fieldId);
601
+ return value?.text ?? null;
602
+ }
603
+
553
604
  export async function createTextField(token, projectId, name) {
554
605
  const client = makeClient(token);
555
606
  const result = await client(`
@@ -351,6 +351,69 @@ export async function updateMilestoneDescription(token, owner, repo, milestoneNu
351
351
  return res.data;
352
352
  }
353
353
 
354
+ // Cria uma milestone. `dueOn` é ISO-8601 e vai como `due_on`.
355
+ //
356
+ // O GitHub recusa (422) título repetido, e isso é RESULTADO, não falha de rede:
357
+ // quem chama decide entre reusar a existente e reclamar. Devolver `null` aqui
358
+ // apagaria a diferença entre "já existe" e "não consegui falar com a API", que
359
+ // é justamente a distinção que o chamador precisa — então o 422 sobe.
360
+ export async function createMilestone(token, owner, repo, { title, description, dueOn } = {}) {
361
+ const octokit = makeOctokit(token);
362
+ const res = await octokit.rest.issues.createMilestone({
363
+ owner, repo, title,
364
+ ...(description == null ? {} : { description }),
365
+ ...(dueOn ? { due_on: dueOn } : {}),
366
+ });
367
+ return res.data;
368
+ }
369
+
370
+ // Atualiza campos de uma milestone. PATCH parcial: campo não passado não é
371
+ // tocado — por isso cada um só entra no payload quando veio.
372
+ //
373
+ // `updateMilestoneDescription` continua existindo e NÃO é um caso particular
374
+ // desta: ela promete mexer só na descrição, e é dessa promessa estreita que o
375
+ // `qa-lead` depende ao substituir o bloco de trilha.
376
+ export async function updateMilestone(token, owner, repo, milestoneNumber, { title, description, dueOn, state } = {}) {
377
+ const octokit = makeOctokit(token);
378
+ const res = await octokit.rest.issues.updateMilestone({
379
+ owner, repo, milestone_number: milestoneNumber,
380
+ ...(title == null ? {} : { title }),
381
+ ...(description == null ? {} : { description }),
382
+ ...(dueOn === undefined ? {} : { due_on: dueOn }),
383
+ ...(state == null ? {} : { state }),
384
+ });
385
+ return res.data;
386
+ }
387
+
388
+ // Atribui (ou REMOVE, com `null`) a milestone de uma issue que já existe.
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
+
405
+ // A assimetria com `createIssue` é da API e é fácil de trocar: lá `milestone:
406
+ // null` leva 422 e por isso o campo só entra quando existe; aqui `null` é
407
+ // justamente como se remove, e omitir o campo é que seria "não mexe". Um `...(m
408
+ // ? {m} : {})` copiado de lá tornaria a remoção silenciosamente inócua.
409
+ export async function setIssueMilestone(token, owner, repo, issueNumber, milestoneNumber) {
410
+ const octokit = makeOctokit(token);
411
+ await octokit.rest.issues.update({
412
+ owner, repo, issue_number: issueNumber,
413
+ milestone: milestoneNumber == null ? null : Number(milestoneNumber),
414
+ });
415
+ }
416
+
354
417
  // Issues de uma milestone (pelo NÚMERO dela), abertas e fechadas.
355
418
  //
356
419
  // `state: 'all'` de propósito: uma Feature fechada continua contando para o
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.1.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",
@@ -30,6 +30,7 @@ import {
30
30
  countOpenIssuesWithLabel,
31
31
  createIssue,
32
32
  createLabel,
33
+ createMilestone,
33
34
  deleteLabel,
34
35
  getIssue,
35
36
  getMilestone,
@@ -40,9 +41,12 @@ import {
40
41
  listLabels,
41
42
  listMilestones,
42
43
  removeLabel,
44
+ setIssueMilestone,
43
45
  setIssueState,
44
46
  updateComment,
47
+ updateIssue,
45
48
  updateLabel,
49
+ updateMilestone,
46
50
  updateMilestoneDescription,
47
51
  getOwnerNodeId,
48
52
  getRepoNodeId,
@@ -55,6 +59,8 @@ import {
55
59
  createTextField,
56
60
  getIssueParent,
57
61
  getItemSingleSelectValue,
62
+ getItemTextValue,
63
+ setItemText,
58
64
  getProjectSnapshot,
59
65
  getRateLimit,
60
66
  linkProjectToRepo,
@@ -77,6 +83,7 @@ export const GITHUB_TRACKER_CAPABILITIES = Object.freeze({
77
83
  hierarchy: 'native', // sub-issues
78
84
  dependencies: 'native', // API de dependencies (blocked_by)
79
85
  milestones: 'native',
86
+ reopen: 'native', // `setIssueState(..., 'open')` — sem workflow no caminho
80
87
  stages: Object.freeze({ mode: 'set', multiHop: false, reopenable: true }),
81
88
  progress: 'native', // o campo nativo "Status" do Projects v2
82
89
  fields: Object.freeze({
@@ -170,12 +177,13 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
170
177
 
171
178
  const a = {
172
179
  addBlockedBy, addLabel, commentOnIssue, countOpenIssuesWithLabel, createIssue, createLabel,
173
- deleteLabel, getIssue, getMilestone, getOwnerType, listBlockedBy, listIssueComments,
174
- listIssuesByMilestone, listLabels, listMilestones, removeLabel, setIssueState, updateComment,
175
- updateLabel, updateMilestoneDescription, getOwnerNodeId, getRepoNodeId,
180
+ createMilestone, deleteLabel, getIssue, getMilestone, getOwnerType, listBlockedBy,
181
+ listIssueComments, listIssuesByMilestone, listLabels, listMilestones, removeLabel,
182
+ setIssueMilestone, setIssueState, updateComment, updateIssue, updateLabel, updateMilestone,
183
+ updateMilestoneDescription, getOwnerNodeId, getRepoNodeId,
176
184
  addProjectItem, addSubIssue, createProject, createSingleSelectField, createTextField,
177
- getIssueParent, getItemSingleSelectValue, getProjectSnapshot, getRateLimit, linkProjectToRepo,
178
- listProjectItems, listSubIssues, setItemSingleSelect,
185
+ getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getRateLimit,
186
+ linkProjectToRepo, listProjectItems, listSubIssues, setItemSingleSelect, setItemText,
179
187
  resolveField,
180
188
  ...api,
181
189
  };
@@ -502,17 +510,28 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
502
510
  async setField({ ref, field, value, onlyIfEmpty = false } = {}) {
503
511
  const f = await campo(field);
504
512
  if (!f?.id) return false;
505
- const opt = optionId(f, value);
506
- if (!opt) return false;
513
+ // Dos seis campos do RFC-001, cinco são SINGLE_SELECT e `release` é TEXT
514
+ // (config.mjs). Sem este ramo, `optionId` devolvia null num campo sem
515
+ // `options` e a escrita virava `return false` — com `release: 'native'`
516
+ // declarado nas capabilities. Ninguém percebia porque nada escreve
517
+ // `release` hoje, e o chamador não distingue "recusei" de "já estava
518
+ // preenchido": os dois são `false`.
519
+ const select = Boolean(f.options && Object.keys(f.options).length);
520
+ const opt = select ? optionId(f, value) : null;
521
+ if (select && !opt) return false;
522
+
507
523
  const itemId = await itemDoBoard(ref);
508
524
  if (onlyIfEmpty) {
509
525
  // Escreve só no vazio: o tipo inferido do título é um palpite, e
510
526
  // sobrescrever o que um humano ajustou no board trocaria dado bom por
511
527
  // palpite.
512
- const atual = await a.getItemSingleSelectValue(ptk, itemId, f.id);
528
+ const atual = select
529
+ ? await a.getItemSingleSelectValue(ptk, itemId, f.id)
530
+ : await a.getItemTextValue(ptk, itemId, f.id);
513
531
  if (atual) return false;
514
532
  }
515
- await a.setItemSingleSelect(ptk, project.id, itemId, f.id, opt);
533
+ if (select) await a.setItemSingleSelect(ptk, project.id, itemId, f.id, opt);
534
+ else await a.setItemText(ptk, project.id, itemId, f.id, String(value ?? ''));
516
535
  return true;
517
536
  },
518
537
 
@@ -543,12 +562,29 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
543
562
  });
544
563
  },
545
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
+
546
575
  closeWorkItem({ ref } = {}) {
547
576
  // `reason` é ignorado: no GitHub fechar é um ESTADO, e a distinção
548
577
  // rejeitado × duplicata já vive nas labels (`closeSemantics: 'state'`).
549
578
  return a.setIssueState(token, owner, repo, refNumber(ref), 'closed');
550
579
  },
551
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
+
552
588
  async addChild({ parent, child } = {}) {
553
589
  const p = await hidratar(parent);
554
590
  const c = await hidratar(child);
@@ -617,6 +653,26 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
617
653
  const issues = await a.listIssuesByMilestone(token, owner, repo, refNumber(milestone.key));
618
654
  return (issues || []).map(toWorkItem);
619
655
  },
656
+
657
+ // `milestone: null` remove. A rota de escrita distingue os dois (ver o
658
+ // comentário em setIssueMilestone, github-rest.mjs): aqui `null` PRECISA
659
+ // chegar como null, não ser omitido.
660
+ async setMilestone({ ref, milestone = null } = {}) {
661
+ await a.setIssueMilestone(
662
+ token, owner, repo, refNumber(refKey(ref)),
663
+ milestone ? refNumber(milestone.key) : null,
664
+ );
665
+ },
666
+
667
+ async createMilestone({ title, description, dueOn = null } = {}) {
668
+ return toMilestone(await a.createMilestone(token, owner, repo, { title, description, dueOn }));
669
+ },
670
+
671
+ async updateMilestone({ key, title, description, dueOn, state } = {}) {
672
+ return toMilestone(
673
+ await a.updateMilestone(token, owner, repo, refNumber(key), { title, description, dueOn, state }),
674
+ );
675
+ },
620
676
  };
621
677
 
622
678
  return porta;
@@ -38,6 +38,7 @@
38
38
  * @typedef {import('./types.mjs').WorkItemRef} WorkItemRef
39
39
  * @typedef {import('./types.mjs').WorkItem} WorkItem
40
40
  * @typedef {import('./types.mjs').MilestoneRef} MilestoneRef
41
+ * @typedef {import('./types.mjs').MilestoneKey} MilestoneKey
41
42
  * @typedef {import('./types.mjs').CommentRef} CommentRef
42
43
  * @typedef {import('./types.mjs').BoardItem} BoardItem
43
44
  * @typedef {import('./types.mjs').FieldName} FieldName
@@ -99,6 +100,18 @@
99
100
  * exatamente disto — e fazê-lo no core custaria um get + um set, dois
100
101
  * round-trips onde um tracker pode fazer um. Devolve `true` se escreveu.
101
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
+ *
102
115
  * @property {() => Promise<BoardItem[]>} boardSnapshot
103
116
  * @property {(o: {ref: WorkItemRef, reason?: 'completed'|'not-planned'|'duplicate'}) => Promise<void>} closeWorkItem
104
117
  * `reason` existe porque em `closeSemantics: 'transition-and-resolution'` o
@@ -107,6 +120,26 @@
107
120
  *
108
121
  * ── CONDICIONAIS ──────────────────────────────────────────────────────────
109
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
+ *
110
143
  * @property {(o: {ref: WorkItemRef}) => Promise<Progress|null>} [getProgress] progress: 'native'
111
144
  * @property {(o: {ref: WorkItemRef, progress: Progress}) => Promise<boolean>} [setProgress]
112
145
  *
@@ -125,7 +158,40 @@
125
158
  * @property {() => Promise<MilestoneRef[]>} [listMilestones] milestones: 'native'
126
159
  * @property {(o: {key: string}) => Promise<MilestoneRef|null>} [getMilestone]
127
160
  * @property {(o: {key: string, description: string}) => Promise<void>} [setMilestoneDescription]
128
- * @property {(o: {milestone: MilestoneRef, state?: 'open'|'closed'|'all'}) => Promise<WorkItem[]>} [listWorkItemsByMilestone]
161
+ * ESTREITA de propósito, e não um caso particular de `updateMilestone`: o que
162
+ * ela promete é não tocar em mais nada. O `qa-lead` substitui um bloco
163
+ * delimitado dentro da descrição (`lib/qa-lead.mjs`), então precisa de uma
164
+ * escrita que não possa apagar título nem data-alvo por omissão.
165
+ * @property {(o: {milestone: MilestoneKey, state?: 'open'|'closed'|'all'}) => Promise<WorkItem[]>} [listWorkItemsByMilestone]
166
+ * @property {(o: {ref: WorkItemRef, milestone: MilestoneKey|null}) => Promise<void>} [setMilestone]
167
+ * Atribui a milestone de um item que JÁ existe; `null` remove.
168
+ *
169
+ * Toma `MilestoneKey` — `{key}` basta — e não o `MilestoneRef` inteiro, pelo
170
+ * mesmo motivo que `getParent` devolve um parcial: quem só tem a chave não
171
+ * pode ser obrigado a INVENTAR `title` para chamar. Um chamador que forja
172
+ * `{key, title: ''}` está apostando que o plugin ignora o título, e essa
173
+ * aposta é sobre um plugin específico — o próximo pode não ignorar. Endereçar
174
+ * é pela chave; `title` e `dueOn` são o que a LEITURA devolve.
175
+ *
176
+ * Operação própria, e não `setField({field: 'release'})`, por duas razões que
177
+ * não são estéticas. `setField` carrega `value: string`, e identidade de
178
+ * milestone é `MilestoneRef {key, title}` — passar por string obrigaria a
179
+ * decidir AGORA qual dos dois endereça, que é exatamente a pendência de
180
+ * identidade de milestone ainda em aberto com a `spec-wave-ui`. E `null`
181
+ * precisa significar "remove", que um campo de texto não sabe expressar:
182
+ * string vazia é um valor, não uma ausência.
183
+ * @property {(o: {title: string, description?: string, dueOn?: string|null}) => Promise<MilestoneRef>} [createMilestone]
184
+ * @property {(o: {key: string, title?: string, description?: string, dueOn?: string|null, state?: 'open'|'closed'}) => Promise<MilestoneRef>} [updateMilestone]
185
+ * PARCIAL: campo não passado não é tocado. Fechar uma entrega é
186
+ * `state: 'closed'` aqui — não existe `closeMilestone`, porque fechar é uma
187
+ * transição de estado como as outras e um verbo separado convidaria um plugin
188
+ * a implementar só ele.
189
+ *
190
+ * NÃO existe `deleteMilestone`, e a ausência é decisão registrada: o GitHub
191
+ * apaga e desassocia as issues em silêncio, enquanto o Jira não deleta uma
192
+ * Version sem que se diga o destino do que aponta para ela. Uma assinatura
193
+ * `deleteMilestone({key})` seria implementável num fornecedor e impossível no
194
+ * outro — o dia em que entrar, entra com o destino dos itens no argumento.
129
195
  *
130
196
  * @property {(o: {stages: Array<{name: string, color?: string, id?: string}>}) => Promise<{fields: object}>} [syncStages]
131
197
  * boardProvisioning: 'create'. Reescreve o vocabulário de etapas do board e
@@ -156,7 +222,7 @@
156
222
  */
157
223
  export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
158
224
  'setup', 'verify',
159
- 'createWorkItem', 'getWorkItem', 'listWorkItemsByTag',
225
+ 'createWorkItem', 'getWorkItem', 'updateWorkItem', 'listWorkItemsByTag',
160
226
  'addComment', 'listComments', 'updateComment',
161
227
  'addTag', 'removeTag', 'ensureTags', 'listTags',
162
228
  'getStage', 'setStage',
@@ -175,11 +241,19 @@ export const TRACKER_REQUIRED_OPERATIONS = Object.freeze([
175
241
  * @type {Readonly<Record<string, Readonly<string[]>>>}
176
242
  */
177
243
  export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
244
+ 'reopen=native': Object.freeze(['reopenWorkItem']),
178
245
  'progress=native': Object.freeze(['getProgress', 'setProgress']),
179
246
  'hierarchy=native': Object.freeze(['addChild', 'listChildren', 'getParent']),
180
247
  'dependencies=native': Object.freeze(['addBlockedBy', 'listBlockedBy']),
248
+ // Leitura E escrita. A lista nasceu só com as quatro de leitura porque a CLI
249
+ // nunca escreveu milestone — quem as cria aqui é humano na UI do fornecedor —
250
+ // e um contrato derivado de um consumidor read-only herda o silêncio dele, não
251
+ // uma decisão. O sintoma de que era acidente estava no próprio contrato:
252
+ // `createWorkItem` aceita `milestone`, então um item podia NASCER numa entrega
253
+ // e não ter como sair dela.
181
254
  'milestones=native': Object.freeze([
182
255
  'listMilestones', 'getMilestone', 'setMilestoneDescription', 'listWorkItemsByMilestone',
256
+ 'setMilestone', 'createMilestone', 'updateMilestone',
183
257
  ]),
184
258
  'boardProvisioning=create': Object.freeze(['syncStages']),
185
259
  'commentMarkers=false': Object.freeze(['getItemProperty', 'setItemProperty']),
@@ -195,6 +269,9 @@ export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
195
269
  export function trackerRequiredOperations(capabilities = {}) {
196
270
  const exigidas = new Set(TRACKER_REQUIRED_OPERATIONS);
197
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',
198
275
  'progress=native': capabilities.progress === 'native',
199
276
  'hierarchy=native': capabilities.hierarchy === 'native',
200
277
  'dependencies=native': capabilities.dependencies === 'native',
@@ -66,6 +66,25 @@
66
66
  * @property {string} [description]
67
67
  */
68
68
 
69
+ /**
70
+ * ENDEREÇO de uma milestone — a chave, e só.
71
+ *
72
+ * Existe para que as operações que apenas apontam para uma entrega
73
+ * (`setMilestone`, `listWorkItemsByMilestone`) não exijam o `MilestoneRef`
74
+ * inteiro. Um chamador que tem só o número — o snapshot de board devolve
75
+ * `{key, title}`, mas uma cascata Feature→Stories costuma ter só números —
76
+ * teria de FORJAR `title: ''` para satisfazer o tipo, e isso é uma aposta de
77
+ * que o plugin ignora o campo forjado. Aposta sobre um plugin específico: o
78
+ * próximo pode não ignorar, e aí o título vazio sobrescreve o de verdade.
79
+ *
80
+ * Mesma razão do parcial de `getParent`: ninguém deve inventar dado para
81
+ * conseguir chamar. Endereçar é pela chave; `title` e `dueOn` são o que a
82
+ * LEITURA devolve. Um `MilestoneRef` satisfaz `MilestoneKey` por construção.
83
+ *
84
+ * @typedef {object} MilestoneKey
85
+ * @property {string} key
86
+ */
87
+
69
88
  /**
70
89
  * @typedef {object} CommentRef
71
90
  * @property {string} id
@@ -84,6 +103,28 @@
84
103
  * que o `fieldMap` do Jira resolve (lá `storyPoints` é `customfield_1XXXX`,
85
104
  * variável por site).
86
105
  *
106
+ * ⚠️ **`release` NÃO é o milestone.** São dois eixos independentes, e um item
107
+ * pode ter os dois, um ou nenhum:
108
+ *
109
+ * - `release` é um campo ANOTADO no item, de texto livre, sem entidade própria
110
+ * — não se lista, não se cria, não tem data-alvo. Aqui ele é um campo TEXT do
111
+ * Projects v2 (`config.mjs`); na `spec-wave-ui` é uma label (`v1.2`). Três
112
+ * implementações já escolheram três mecanismos, e isso está certo: o
113
+ * mecanismo é do plugin.
114
+ * - O milestone é uma ENTIDADE do tracker, com `key`, título e `dueOn`, que se
115
+ * lista (`listMilestones`) e pela qual se filtra (`listWorkItemsByMilestone`).
116
+ * É o que `preflight`, `audit` e `qa-lead` consomem. Escreve-se com
117
+ * `setMilestone`, nunca por aqui.
118
+ *
119
+ * A distinção é normativa, e não descritiva do GitHub: sem ela, um plugin pode
120
+ * representar `release` COMO o milestone de boa-fé, e aí `setField({field:
121
+ * 'release'})` e `setMilestone()` viram dois caminhos de escrita para o mesmo
122
+ * valor, sem nada que os mantenha coerentes. Um plugin que só tenha um dos dois
123
+ * declara o outro ausente em `capabilities` — não os funde.
124
+ *
125
+ * O sintoma de confundir os dois é mudo: a escrita tem SUCESSO, o texto entra
126
+ * no campo anotado e os filtros por milestone seguem sem enxergar o item.
127
+ *
87
128
  * @typedef {'workItemType'|'priority'|'storyPoints'|'area'|'release'} FieldName
88
129
  */
89
130