@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 +1 -1
- package/src/commands/decompose.mjs +114 -4
- package/src/commands/update.mjs +25 -2
- package/src/lib/open-todos.mjs +53 -0
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugin/skills/decompose/model-prompt.feature.md +2 -0
- package/src/plugin/skills/decompose/model-prompt.rfc.md +2 -0
package/package.json
CHANGED
|
@@ -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 =
|
|
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,
|
package/src/commands/update.mjs
CHANGED
|
@@ -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
|
-
|
|
414
|
-
|
|
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.
|
|
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
|