@spec-wave/cli 1.7.2 → 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.2",
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,
@@ -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.2",
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