@spec-wave/cli 1.7.1 → 1.7.3

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.7.1",
3
+ "version": "1.7.3",
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": {
@@ -40,6 +40,7 @@ import { buildDependencyMap, storiesFromAppliedDoc, DEPENDENCY_MAP_FILE } from '
40
40
  import { invalidateCache } from '../lib/net-cache.mjs';
41
41
  import { loadArtifact } from '../lib/doc-source.mjs';
42
42
  import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
43
+ import { findOpenTodos } from '../lib/open-todos.mjs';
43
44
  import { isAwaitingMerge } from '../lib/doc-source.mjs';
44
45
  import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
45
46
  import { cliRef } from '../lib/cli-ref.mjs';
@@ -158,6 +159,95 @@ export function parseModelJson(raw) {
158
159
  );
159
160
  }
160
161
 
162
+ // Começo da resposta do modelo, numa linha, para log e mensagem de erro.
163
+ function responseOpening(raw, max = 200) {
164
+ const text = String(raw ?? '').replace(/\s+/g, ' ').trim();
165
+ if (!text) return '(resposta vazia)';
166
+ return text.length > max ? `${text.slice(0, max)}…` : text;
167
+ }
168
+
169
+ /**
170
+ * Gera o rascunho e decodifica o JSON, re-pedindo quando a resposta não é JSON.
171
+ *
172
+ * O prompt declara `json.retries` no frontmatter e o loader lê, mas o comando
173
+ * parseava uma vez só: uma resposta em prosa ("Antes de gerar, preciso
174
+ * esclarecer…") derrubava a Action sem nova tentativa, e o erro — "JSON
175
+ * inválido" — escondia que o modelo tinha feito uma pergunta. Agora a nova
176
+ * tentativa leva a correção junto (a execução é automática: ninguém responde),
177
+ * e o erro final carrega o começo do que o modelo escreveu.
178
+ *
179
+ * @param {Function} gerar (system, userContent, opts) → texto do modelo
180
+ * @param {object} params
181
+ * @param {string} params.system
182
+ * @param {string} params.userContent
183
+ * @param {object} params.opts repassado a `gerar`
184
+ * @param {number} [params.retries] novas tentativas além da primeira
185
+ * @param {string} [params.shape] contrato JSON (json.shape do prompt)
186
+ * @returns {Promise<object>}
187
+ */
188
+ export async function generateDecompositionJson(gerar, { system, userContent, opts, retries = 1, shape = '' }) {
189
+ let input = userContent;
190
+ for (let attempt = 1; ; attempt++) {
191
+ const raw = await gerar(system, input, opts);
192
+ try {
193
+ return parseModelJson(raw);
194
+ } catch (err) {
195
+ const opening = responseOpening(raw);
196
+ if (attempt > retries) {
197
+ err.message = `${err.message} Início da resposta do modelo: «${opening}»`;
198
+ throw err;
199
+ }
200
+ console.warn(
201
+ `Rascunho sem JSON válido na tentativa ${attempt}/${retries + 1} (${err.message}) — ` +
202
+ `pedindo de novo. Início da resposta: «${opening}»`
203
+ );
204
+ input = [
205
+ userContent,
206
+ '\n## Correção da resposta anterior',
207
+ `Sua resposta anterior não era o JSON pedido — começava com: «${opening}».`,
208
+ 'Esta execução é automática: ninguém vai responder perguntas nem confirmar nada. ' +
209
+ 'Não explique, não peça esclarecimento: responda APENAS com o JSON do contrato de saída.',
210
+ shape ? `Formato: ${shape}` : '',
211
+ ].filter(Boolean).join('\n');
212
+ }
213
+ }
214
+ }
215
+
216
+ /**
217
+ * Bloqueio por pendências abertas na spec/plan (função PURA — testável).
218
+ *
219
+ * `[TODO: requer esclarecimento do PO …]` é decisão humana pendente: decompor
220
+ * por cima dela ou inventa a regra nas Stories ou devolve uma pergunta no lugar
221
+ * do JSON. A recusa acontece ANTES de chamar o modelo — não custa IA — e diz
222
+ * onde está cada pendência.
223
+ *
224
+ * @param {Array<{ pathRel: string, content: string|null }>} docs
225
+ * @param {{ max?: number }} [opts] quantas pendências listar no comentário
226
+ * @returns {{ message: string, comment: string }|null} null = nada pendente
227
+ */
228
+ export function openTodosBlock(docs, { max = 15 } = {}) {
229
+ const found = docs.flatMap(d =>
230
+ findOpenTodos(d.content).map(t => ({ ...t, pathRel: d.pathRel })));
231
+ if (found.length === 0) return null;
232
+
233
+ const porArquivo = docs
234
+ .map(d => [d.pathRel, found.filter(t => t.pathRel === d.pathRel).length])
235
+ .filter(([, n]) => n > 0)
236
+ .map(([p, n]) => `${n} em \`${p}\``)
237
+ .join(', ');
238
+ const message =
239
+ `${found.length} pendência(s) [TODO] aberta(s) (${porArquivo}). ` +
240
+ 'Resolva-as antes de decompor — nenhuma Story foi gerada.';
241
+ const linhas = found.slice(0, max).map(t => `- \`${t.pathRel}:${t.line}\` — ${t.excerpt}`);
242
+ if (found.length > max) linhas.push(`- … e mais ${found.length - max}.`);
243
+ const comment = [
244
+ `⏸️ **decompose parado:** ${message}`,
245
+ '',
246
+ ...linhas,
247
+ ].join('\n');
248
+ return { message, comment };
249
+ }
250
+
161
251
  // Prefixo de título das sub-issues geradas por cada tipo decompoível.
162
252
  const CHILD_PREFIX = { Feature: '[STORY]', RFC: '[TASK]' };
163
253
 
@@ -376,6 +466,24 @@ async function draftDecomposition(ctx) {
376
466
  publicado = { pr: rascunho.pr, branch: rascunho.ref, unchanged: true };
377
467
  }
378
468
  } else {
469
+ // Só na GERAÇÃO: um rascunho existente já foi escrito (e é do revisor) —
470
+ // criticá-lo não depende de o PO ter fechado as pendências.
471
+ const pendencias = type === 'RFC' ? null : openTodosBlock([
472
+ { pathRel: `${dirRel}/spec.md`, content: specContent },
473
+ { pathRel: `${dirRel}/plan.md`, content: planContent },
474
+ ]);
475
+ if (pendencias) {
476
+ await tracker.removeTag({ ref: { key: String(number) }, tag: LABEL_DECOMPOSE }).catch(() => {});
477
+ await tracker.addComment({
478
+ ref: { key: String(number) },
479
+ body:
480
+ `${pendencias.comment}\n\n` +
481
+ 'Resolva as pendências (decida e reescreva o trecho sem a marcação `[TODO]`) na spec e no ' +
482
+ `plano e reaplique \`${LABEL_DECOMPOSE}\`. Na spec-wave-ui: "Analisar pendências" na ` +
483
+ 'Specification do PM e o agente da Technical Review para o plano.',
484
+ }).catch(() => {});
485
+ throw new DecomposeBlockedError(pendencias.message);
486
+ }
379
487
  console.log(`Gerando rascunho de decomposição para ${type}: ${issue.title}`);
380
488
  const userContent = type === 'RFC'
381
489
  ? [
@@ -395,11 +503,13 @@ async function draftDecomposition(ctx) {
395
503
  type === 'RFC' ? 'decompose/rfc' : 'decompose/feature',
396
504
  { cwd: root },
397
505
  );
398
- const generated = parseModelJson(await (deps.gerarDocumento ?? generateDocument)(
399
- systemPromptWithTools(decomposePrompt),
506
+ const generated = await generateDecompositionJson(deps.gerarDocumento ?? generateDocument, {
507
+ system: systemPromptWithTools(decomposePrompt),
400
508
  userContent,
401
- { action: 'decompose', labels, usage, maxTurns: decomposePrompt.maxTurns, issueNumber, cwd: root }
402
- ));
509
+ opts: { action: 'decompose', labels, usage, maxTurns: decomposePrompt.maxTurns, issueNumber, cwd: root },
510
+ retries: decomposePrompt.json?.retries ?? 1,
511
+ shape: decomposePrompt.json?.shape ?? '',
512
+ });
403
513
 
404
514
  markdown = renderDecompositionDoc({
405
515
  title: issue.title,
@@ -159,6 +159,25 @@ export function diffLabels(existing, fileAi, devAgent) {
159
159
  return { missing, changed, orphan };
160
160
  }
161
161
 
162
+ /**
163
+ * Diff de labels do repositório, por papel (RFC-005 §7.4). Num repo de CÓDIGO
164
+ * as labels são do hub — é lá que as issues vivem —, então o diff é vazio e o
165
+ * tracker nem é consultado. Sem este corte o `update` comparava o repo de
166
+ * código com as labels do fluxo: criava as 40+ num repo que nunca as teve e
167
+ * acusava as de modelo (`spec-wave:model:*`) como órfãs a remover, porque o
168
+ * config de um repo de código não tem bloco `ai`.
169
+ *
170
+ * @param {'hub'|'code'} role
171
+ * @param {() => Promise<Array<{name,color,description}>>} listTags
172
+ * @param {object} [fileAi]
173
+ * @param {object} [devAgent]
174
+ * @returns {Promise<{ missing: object[], changed: object[], orphan: object[] }>}
175
+ */
176
+ export async function repoLabelDiff(role, listTags, fileAi, devAgent) {
177
+ if (role === 'code') return { missing: [], changed: [], orphan: [] };
178
+ return diffLabels(await listTags(), fileAi, devAgent);
179
+ }
180
+
162
181
  /**
163
182
  * Decide se uma label órfã pode ser deletada (função PURA — testável sem rede).
164
183
  *
@@ -410,8 +429,12 @@ export async function update(options = {}) {
410
429
  if (remote === null) repoFiles.push({ ...f, reason: 'ausente', local });
411
430
  else if (remote !== local) repoFiles.push({ ...f, reason: 'desatualizado', local });
412
431
  }
413
- const trackerLabels = await requireTracker({ token: tk, owner, repo });
414
- labelDiff = diffLabels(await trackerLabels.listTags(), config?.ai, config?.devAgent);
432
+ labelDiff = await repoLabelDiff(
433
+ role,
434
+ async () => (await requireTracker({ token: tk, owner, repo })).listTags(),
435
+ config?.ai,
436
+ config?.devAgent,
437
+ );
415
438
  repoChecked = true;
416
439
  s.stop('Repositório comparado.');
417
440
  } catch (err) {
@@ -0,0 +1,53 @@
1
+ // Pendências abertas num documento gerado por IA (função PURA — testável).
2
+ //
3
+ // Os prompts de spec e plan mandam o modelo NÃO inventar regra de negócio e
4
+ // marcar o que falta com "[TODO: requer esclarecimento do PO — …]". São pontos
5
+ // que esperam decisão humana — e um documento com eles não está pronto para
6
+ // virar Stories: o modelo do decompose, diante deles, responde perguntando em
7
+ // vez de devolver o JSON (foi o que derrubou a Action da spec-wave-ui#382 duas
8
+ // vezes seguidas).
9
+ //
10
+ // Só a forma entre colchetes, `[TODO …]` / `[TO DO …]`, e fora de bloco de
11
+ // código: um TODO dentro de um exemplo de código não é pendência do documento.
12
+ //
13
+ // Código INLINE é diferente, e aqui a regra diverge da UI (spec-wave-ui,
14
+ // client/src/lib/todoMarkers.ts, que descarta todo código inline): o gerador
15
+ // costuma emitir a marcação INTEIRA entre crases — "`[TODO: requer … PO]`" —, e
16
+ // foi assim nos documentos da #382. Descartar esse span zerava a contagem
17
+ // justamente do caso real. Então o span inline só sai quando NÃO começa pela
18
+ // marcação (ex.: "`x = 1 // [TODO]`" continua fora).
19
+
20
+ const MARKER_RE = /\[TO\s?DO\b/i;
21
+ const START_RE = /^\s*\[TO\s?DO\b/i;
22
+ const FENCE_RE = /^\s*(```|~~~)/;
23
+ const EXCERPT_MAX = 160;
24
+
25
+ /**
26
+ * @param {string|null|undefined} content markdown do documento
27
+ * @returns {Array<{ line: number, excerpt: string }>} uma entrada por linha com
28
+ * pendência, na ordem do documento (line é 1-based)
29
+ */
30
+ export function findOpenTodos(content) {
31
+ const found = [];
32
+ let fence = null;
33
+ const lines = String(content ?? '').replace(/\r\n/g, '\n').split('\n');
34
+ lines.forEach((raw, i) => {
35
+ const opener = FENCE_RE.exec(raw);
36
+ if (opener) {
37
+ if (fence === null) fence = opener[1];
38
+ else if (opener[1] === fence) fence = null;
39
+ return;
40
+ }
41
+ if (fence !== null) return;
42
+ // O código inline decide SE há pendência; o trecho mostrado sai da linha
43
+ // crua, para a explicação não perder os nomes entre crases.
44
+ const semCodigo = raw.replace(/`([^`\n]*)`/g, (span, inner) => (START_RE.test(inner) ? inner : ''));
45
+ if (!MARKER_RE.test(semCodigo)) return;
46
+ const excerpt = raw.slice(raw.search(MARKER_RE)).replace(/\s+/g, ' ').trim();
47
+ found.push({
48
+ line: i + 1,
49
+ excerpt: excerpt.length > EXCERPT_MAX ? `${excerpt.slice(0, EXCERPT_MAX)}…` : excerpt,
50
+ });
51
+ });
52
+ return found;
53
+ }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.7.1",
4
+ "version": "1.7.3",
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",
@@ -31,6 +31,8 @@ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está ne
31
31
 
32
32
  ## Contrato de saída
33
33
 
34
+ Esta execução é automática: ninguém vai responder perguntas nem confirmar nada. Não peça esclarecimento nem anuncie o que vai fazer — se algo estiver indefinido, decomponha com o que o documento diz e registre a lacuna no `body` do item afetado.
35
+
34
36
  Responda APENAS com JSON válido neste formato:
35
37
 
36
38
  ```json
@@ -29,6 +29,8 @@ Se a entrada trouxer a seção **Workspace multi-repo**, o código NÃO está ne
29
29
  <!-- /requires-tools -->
30
30
  ## Contrato de saída
31
31
 
32
+ Esta execução é automática: ninguém vai responder perguntas nem confirmar nada. Não peça esclarecimento nem anuncie o que vai fazer — se algo estiver indefinido, decomponha com o que o documento diz e registre a lacuna no `body` do item afetado.
33
+
32
34
  Responda APENAS com JSON válido neste formato:
33
35
 
34
36
  ```json