@spec-wave/cli 1.1.0 → 1.2.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.2.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,54 @@ 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
+ // A assimetria com `createIssue` é da API e é fácil de trocar: lá `milestone:
391
+ // null` leva 422 e por isso o campo só entra quando existe; aqui `null` é
392
+ // justamente como se remove, e omitir o campo é que seria "não mexe". Um `...(m
393
+ // ? {m} : {})` copiado de lá tornaria a remoção silenciosamente inócua.
394
+ export async function setIssueMilestone(token, owner, repo, issueNumber, milestoneNumber) {
395
+ const octokit = makeOctokit(token);
396
+ await octokit.rest.issues.update({
397
+ owner, repo, issue_number: issueNumber,
398
+ milestone: milestoneNumber == null ? null : Number(milestoneNumber),
399
+ });
400
+ }
401
+
354
402
  // Issues de uma milestone (pelo NÚMERO dela), abertas e fechadas.
355
403
  //
356
404
  // `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.2.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,11 @@ import {
40
41
  listLabels,
41
42
  listMilestones,
42
43
  removeLabel,
44
+ setIssueMilestone,
43
45
  setIssueState,
44
46
  updateComment,
45
47
  updateLabel,
48
+ updateMilestone,
46
49
  updateMilestoneDescription,
47
50
  getOwnerNodeId,
48
51
  getRepoNodeId,
@@ -55,6 +58,8 @@ import {
55
58
  createTextField,
56
59
  getIssueParent,
57
60
  getItemSingleSelectValue,
61
+ getItemTextValue,
62
+ setItemText,
58
63
  getProjectSnapshot,
59
64
  getRateLimit,
60
65
  linkProjectToRepo,
@@ -170,12 +175,13 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
170
175
 
171
176
  const a = {
172
177
  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,
178
+ createMilestone, deleteLabel, getIssue, getMilestone, getOwnerType, listBlockedBy,
179
+ listIssueComments, listIssuesByMilestone, listLabels, listMilestones, removeLabel,
180
+ setIssueMilestone, setIssueState, updateComment, updateLabel, updateMilestone,
181
+ updateMilestoneDescription, getOwnerNodeId, getRepoNodeId,
176
182
  addProjectItem, addSubIssue, createProject, createSingleSelectField, createTextField,
177
- getIssueParent, getItemSingleSelectValue, getProjectSnapshot, getRateLimit, linkProjectToRepo,
178
- listProjectItems, listSubIssues, setItemSingleSelect,
183
+ getIssueParent, getItemSingleSelectValue, getItemTextValue, getProjectSnapshot, getRateLimit,
184
+ linkProjectToRepo, listProjectItems, listSubIssues, setItemSingleSelect, setItemText,
179
185
  resolveField,
180
186
  ...api,
181
187
  };
@@ -502,17 +508,28 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
502
508
  async setField({ ref, field, value, onlyIfEmpty = false } = {}) {
503
509
  const f = await campo(field);
504
510
  if (!f?.id) return false;
505
- const opt = optionId(f, value);
506
- if (!opt) return false;
511
+ // Dos seis campos do RFC-001, cinco são SINGLE_SELECT e `release` é TEXT
512
+ // (config.mjs). Sem este ramo, `optionId` devolvia null num campo sem
513
+ // `options` e a escrita virava `return false` — com `release: 'native'`
514
+ // declarado nas capabilities. Ninguém percebia porque nada escreve
515
+ // `release` hoje, e o chamador não distingue "recusei" de "já estava
516
+ // preenchido": os dois são `false`.
517
+ const select = Boolean(f.options && Object.keys(f.options).length);
518
+ const opt = select ? optionId(f, value) : null;
519
+ if (select && !opt) return false;
520
+
507
521
  const itemId = await itemDoBoard(ref);
508
522
  if (onlyIfEmpty) {
509
523
  // Escreve só no vazio: o tipo inferido do título é um palpite, e
510
524
  // sobrescrever o que um humano ajustou no board trocaria dado bom por
511
525
  // palpite.
512
- const atual = await a.getItemSingleSelectValue(ptk, itemId, f.id);
526
+ const atual = select
527
+ ? await a.getItemSingleSelectValue(ptk, itemId, f.id)
528
+ : await a.getItemTextValue(ptk, itemId, f.id);
513
529
  if (atual) return false;
514
530
  }
515
- await a.setItemSingleSelect(ptk, project.id, itemId, f.id, opt);
531
+ if (select) await a.setItemSingleSelect(ptk, project.id, itemId, f.id, opt);
532
+ else await a.setItemText(ptk, project.id, itemId, f.id, String(value ?? ''));
516
533
  return true;
517
534
  },
518
535
 
@@ -617,6 +634,26 @@ export function createGithubTracker({ token, projectToken, owner, repo, project
617
634
  const issues = await a.listIssuesByMilestone(token, owner, repo, refNumber(milestone.key));
618
635
  return (issues || []).map(toWorkItem);
619
636
  },
637
+
638
+ // `milestone: null` remove. A rota de escrita distingue os dois (ver o
639
+ // comentário em setIssueMilestone, github-rest.mjs): aqui `null` PRECISA
640
+ // chegar como null, não ser omitido.
641
+ async setMilestone({ ref, milestone = null } = {}) {
642
+ await a.setIssueMilestone(
643
+ token, owner, repo, refNumber(refKey(ref)),
644
+ milestone ? refNumber(milestone.key) : null,
645
+ );
646
+ },
647
+
648
+ async createMilestone({ title, description, dueOn = null } = {}) {
649
+ return toMilestone(await a.createMilestone(token, owner, repo, { title, description, dueOn }));
650
+ },
651
+
652
+ async updateMilestone({ key, title, description, dueOn, state } = {}) {
653
+ return toMilestone(
654
+ await a.updateMilestone(token, owner, repo, refNumber(key), { title, description, dueOn, state }),
655
+ );
656
+ },
620
657
  };
621
658
 
622
659
  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
@@ -125,7 +126,40 @@
125
126
  * @property {() => Promise<MilestoneRef[]>} [listMilestones] milestones: 'native'
126
127
  * @property {(o: {key: string}) => Promise<MilestoneRef|null>} [getMilestone]
127
128
  * @property {(o: {key: string, description: string}) => Promise<void>} [setMilestoneDescription]
128
- * @property {(o: {milestone: MilestoneRef, state?: 'open'|'closed'|'all'}) => Promise<WorkItem[]>} [listWorkItemsByMilestone]
129
+ * ESTREITA de propósito, e não um caso particular de `updateMilestone`: o que
130
+ * ela promete é não tocar em mais nada. O `qa-lead` substitui um bloco
131
+ * delimitado dentro da descrição (`lib/qa-lead.mjs`), então precisa de uma
132
+ * escrita que não possa apagar título nem data-alvo por omissão.
133
+ * @property {(o: {milestone: MilestoneKey, state?: 'open'|'closed'|'all'}) => Promise<WorkItem[]>} [listWorkItemsByMilestone]
134
+ * @property {(o: {ref: WorkItemRef, milestone: MilestoneKey|null}) => Promise<void>} [setMilestone]
135
+ * Atribui a milestone de um item que JÁ existe; `null` remove.
136
+ *
137
+ * Toma `MilestoneKey` — `{key}` basta — e não o `MilestoneRef` inteiro, pelo
138
+ * mesmo motivo que `getParent` devolve um parcial: quem só tem a chave não
139
+ * pode ser obrigado a INVENTAR `title` para chamar. Um chamador que forja
140
+ * `{key, title: ''}` está apostando que o plugin ignora o título, e essa
141
+ * aposta é sobre um plugin específico — o próximo pode não ignorar. Endereçar
142
+ * é pela chave; `title` e `dueOn` são o que a LEITURA devolve.
143
+ *
144
+ * Operação própria, e não `setField({field: 'release'})`, por duas razões que
145
+ * não são estéticas. `setField` carrega `value: string`, e identidade de
146
+ * milestone é `MilestoneRef {key, title}` — passar por string obrigaria a
147
+ * decidir AGORA qual dos dois endereça, que é exatamente a pendência de
148
+ * identidade de milestone ainda em aberto com a `spec-wave-ui`. E `null`
149
+ * precisa significar "remove", que um campo de texto não sabe expressar:
150
+ * string vazia é um valor, não uma ausência.
151
+ * @property {(o: {title: string, description?: string, dueOn?: string|null}) => Promise<MilestoneRef>} [createMilestone]
152
+ * @property {(o: {key: string, title?: string, description?: string, dueOn?: string|null, state?: 'open'|'closed'}) => Promise<MilestoneRef>} [updateMilestone]
153
+ * PARCIAL: campo não passado não é tocado. Fechar uma entrega é
154
+ * `state: 'closed'` aqui — não existe `closeMilestone`, porque fechar é uma
155
+ * transição de estado como as outras e um verbo separado convidaria um plugin
156
+ * a implementar só ele.
157
+ *
158
+ * NÃO existe `deleteMilestone`, e a ausência é decisão registrada: o GitHub
159
+ * apaga e desassocia as issues em silêncio, enquanto o Jira não deleta uma
160
+ * Version sem que se diga o destino do que aponta para ela. Uma assinatura
161
+ * `deleteMilestone({key})` seria implementável num fornecedor e impossível no
162
+ * outro — o dia em que entrar, entra com o destino dos itens no argumento.
129
163
  *
130
164
  * @property {(o: {stages: Array<{name: string, color?: string, id?: string}>}) => Promise<{fields: object}>} [syncStages]
131
165
  * boardProvisioning: 'create'. Reescreve o vocabulário de etapas do board e
@@ -178,8 +212,15 @@ export const TRACKER_CONDITIONAL_OPERATIONS = Object.freeze({
178
212
  'progress=native': Object.freeze(['getProgress', 'setProgress']),
179
213
  'hierarchy=native': Object.freeze(['addChild', 'listChildren', 'getParent']),
180
214
  'dependencies=native': Object.freeze(['addBlockedBy', 'listBlockedBy']),
215
+ // Leitura E escrita. A lista nasceu só com as quatro de leitura porque a CLI
216
+ // nunca escreveu milestone — quem as cria aqui é humano na UI do fornecedor —
217
+ // e um contrato derivado de um consumidor read-only herda o silêncio dele, não
218
+ // uma decisão. O sintoma de que era acidente estava no próprio contrato:
219
+ // `createWorkItem` aceita `milestone`, então um item podia NASCER numa entrega
220
+ // e não ter como sair dela.
181
221
  'milestones=native': Object.freeze([
182
222
  'listMilestones', 'getMilestone', 'setMilestoneDescription', 'listWorkItemsByMilestone',
223
+ 'setMilestone', 'createMilestone', 'updateMilestone',
183
224
  ]),
184
225
  'boardProvisioning=create': Object.freeze(['syncStages']),
185
226
  'commentMarkers=false': Object.freeze(['getItemProperty', 'setItemProperty']),
@@ -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