@spec-wave/cli 1.3.0 → 1.5.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 +1 -1
- package/protocol/scm.v1.json +154 -0
- package/protocol/tracker.v1.json +175 -0
- package/src/api/github-rest.mjs +109 -0
- package/src/commands/audit.mjs +3 -4
- package/src/commands/code-review.mjs +11 -6
- package/src/commands/decompose.mjs +29 -9
- package/src/commands/doctor.mjs +389 -220
- package/src/commands/generate-bug.mjs +17 -7
- package/src/commands/generate-plan.mjs +21 -13
- package/src/commands/generate-qa-plan.mjs +19 -11
- package/src/commands/generate-spec.mjs +19 -6
- package/src/commands/implement.mjs +105 -49
- package/src/commands/init.mjs +36 -6
- package/src/commands/issue.mjs +6 -2
- package/src/commands/merge.mjs +31 -18
- package/src/commands/mode.mjs +18 -10
- package/src/commands/move.mjs +3 -3
- package/src/commands/order.mjs +30 -20
- package/src/commands/preflight.mjs +10 -5
- package/src/commands/qa-lead.mjs +41 -31
- package/src/commands/qa-run.mjs +83 -55
- package/src/commands/qa.mjs +10 -6
- package/src/commands/refresh.mjs +6 -3
- package/src/commands/repair-stage.mjs +1 -1
- package/src/commands/repo.mjs +7 -7
- package/src/commands/run.mjs +7 -4
- package/src/commands/story.mjs +3 -3
- package/src/commands/task.mjs +3 -3
- package/src/commands/triage.mjs +3 -3
- package/src/commands/uninstall.mjs +14 -5
- package/src/commands/update.mjs +47 -19
- package/src/commands/validate.mjs +3 -4
- package/src/commands/workspace.mjs +2 -2
- package/src/lib/artifact-publish.mjs +4 -3
- package/src/lib/board.mjs +22 -24
- package/src/lib/config-ports.mjs +114 -0
- package/src/lib/critique.mjs +11 -1
- package/src/lib/doc-source.mjs +16 -2
- package/src/lib/doctor-capabilities.mjs +168 -0
- package/src/lib/implement-board.mjs +6 -1
- package/src/lib/implement-stream.mjs +87 -0
- package/src/lib/pr-ready.mjs +24 -11
- package/src/lib/story-graph.mjs +26 -6
- package/src/lib/tag-registry.mjs +58 -0
- package/src/lib/usage-report.mjs +15 -2
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugins/load.mjs +427 -0
- package/src/plugins/scm-github/index.mjs +71 -2
- package/src/plugins/tracker-github-projects/index.mjs +52 -10
- package/src/ports/capabilities.mjs +47 -0
- package/src/ports/index.mjs +347 -0
- package/src/ports/scm.mjs +39 -2
- package/src/ports/tracker.mjs +94 -3
- package/src/ports/types.mjs +59 -6
- package/src/setup/files.mjs +2 -2
- package/src/setup/labels.mjs +2 -2
- package/src/setup/project.mjs +2 -2
- package/src/ui/wizard.mjs +76 -1
package/src/ports/types.mjs
CHANGED
|
@@ -8,8 +8,10 @@
|
|
|
8
8
|
// duas) e são o que a spec-wave-ui precisa ler para implementar as portas dela
|
|
9
9
|
// contra O MESMO contrato — não contra um parecido (RFC-007 §3.1).
|
|
10
10
|
//
|
|
11
|
-
//
|
|
12
|
-
//
|
|
11
|
+
// O normativo é `protocol/{tracker,scm}.v1.json`, DENTRO deste pacote e
|
|
12
|
+
// publicado no npm desde a RFC-006 ser aprovada (Fase 2, bloco H). O que isso
|
|
13
|
+
// muda na prática: mexer no contrato passou a ser bump de
|
|
14
|
+
// `specWaveTrackerApi`/`specWaveScmApi`, não edição de rascunho.
|
|
13
15
|
|
|
14
16
|
/**
|
|
15
17
|
* Identidade de um work item (RFC-006 §4).
|
|
@@ -21,6 +23,35 @@
|
|
|
21
23
|
* @property {string} key Identificador humano e PÚBLICO: `"123"` no GitHub,
|
|
22
24
|
* `"PROJ-123"` no Jira. É o que vai para nome de branch, corpo de PR, trailer
|
|
23
25
|
* de commit e nome de arquivo.
|
|
26
|
+
*
|
|
27
|
+
* ⚠️ **O que a PORTA devolve nunca contém `#`.** Invariante do contrato, não
|
|
28
|
+
* característica dos trackers que por acaso existem hoje — e ele já valia por
|
|
29
|
+
* omissão, que é o problema. Cobrado na carga por `checkKeyPattern`, contra o
|
|
30
|
+
* `identity.keyPattern` que o plugin declara.
|
|
31
|
+
*
|
|
32
|
+
* O escopo é a PORTA de propósito: `refKey()` é tolerante por desenho (aceita
|
|
33
|
+
* ref, número, `'#42'`, `'42'`) e NORMALIZA sem validar — `refKey('4#2')`
|
|
34
|
+
* devolve `'4#2'`. Endurecê-la seria mudar o comportamento da função mais
|
|
35
|
+
* carregada do core para tratar entrada que nenhum tracker produz. Quem
|
|
36
|
+
* garante o invariante é o plugin, na origem; `refKey` só traduz o que já
|
|
37
|
+
* chegou.
|
|
38
|
+
*
|
|
39
|
+
* Em três lugares `#` é SIGILO ou separador em texto que o fluxo gera e
|
|
40
|
+
* reanalisa depois: `refKey()` (`lib/work-item-ref.mjs`) descarta um
|
|
41
|
+
* `#` inicial porque ali ele é o prefixo da referência e não parte da chave;
|
|
42
|
+
* `Depende de: #4, #5` é escrito no corpo das Stories e lido de volta por
|
|
43
|
+
* `lib/dependencies.mjs`; e `owner/repo#n` sai no `closingKeyword` em
|
|
44
|
+
* multi-repo. Uma chave com `#` tornaria `#A#B` indistinguível de duas
|
|
45
|
+
* referências, e o estrago apareceria como dependência que some — não como
|
|
46
|
+
* erro.
|
|
47
|
+
*
|
|
48
|
+
* Isto é o irmão que faltava de `capabilities.identity.branchSafe`: aquele
|
|
49
|
+
* diz que a chave pode ir crua para um NOME DE BRANCH, com `branchToken`
|
|
50
|
+
* obrigatório quando não pode. São dois destinos com exigências diferentes,
|
|
51
|
+
* e o contrato só descrevia um. A referência TEXTUAL não ganha um par
|
|
52
|
+
* `refSafe`/`refToken` porque não há fornecedor conhecido que precise dele:
|
|
53
|
+
* proibir é mais barato que parametrizar, e a assimetria fica registrada
|
|
54
|
+
* aqui para o dia em que alguém precisar do contrário.
|
|
24
55
|
* @property {string|null} id Opaco do fornecedor (node id no GitHub). Nunca
|
|
25
56
|
* exibido, nunca escrito em documento.
|
|
26
57
|
* @property {string|null} url Endereço navegável.
|
|
@@ -281,14 +312,36 @@
|
|
|
281
312
|
* Resultado de `verify()` — diagnóstico SEM efeito, nas duas portas.
|
|
282
313
|
*
|
|
283
314
|
* `facts` é o saco de "User vs Organization", título do project, contagem de
|
|
284
|
-
* campos
|
|
285
|
-
*
|
|
286
|
-
*
|
|
315
|
+
* campos. Sacola aberta de propósito — cada fornecedor tem fatos próprios, e
|
|
316
|
+
* forçá-los num schema fechado seria inventar campo que só um deles preenche.
|
|
317
|
+
*
|
|
318
|
+
* ── Três regras, e a do meio é a que custa caro esquecer ──────────────────
|
|
319
|
+
*
|
|
320
|
+
* 1. **O valor não é só string.** O `doctor` precisa de listas (contextos de
|
|
321
|
+
* status check obrigatório, nomes de secret) e de booleanos, e serializá-los
|
|
322
|
+
* para caber num `Record<string,string>` é perder a forma na ida e adivinhá-la
|
|
323
|
+
* na volta.
|
|
324
|
+
*
|
|
325
|
+
* 2. **Ausente ≠ `null`.** Chave AUSENTE é "este fornecedor não tem essa noção";
|
|
326
|
+
* `null` é "tem, e eu NÃO CONSEGUI consultar". As duas mandam o usuário a
|
|
327
|
+
* lugares diferentes — a primeira é informação, a segunda é permissão
|
|
328
|
+
* faltando —, e um plugin que devolva `null` para as duas apaga a distinção
|
|
329
|
+
* que o bloco G inteiro existe para preservar.
|
|
330
|
+
*
|
|
331
|
+
* 3. **O plugin COLETA, o core JULGA.** Nada em `facts` é veredito: o que decide
|
|
332
|
+
* se um repositório pode publicar documento por PR é `inspectPrPublishing`,
|
|
333
|
+
* no core, sobre estes fatos. Mover o julgamento para o plugin devolveria
|
|
334
|
+
* política ao fornecedor — a mesma fronteira que a Fase 1 defendeu para o
|
|
335
|
+
* avanço de Etapa.
|
|
336
|
+
*
|
|
337
|
+
* Os fatos que o `doctor` sabe ler estão documentados em cada porta
|
|
338
|
+
* (`tracker.mjs`/`scm.mjs`, na entrada `verify`). São todos OPCIONAIS: fato que
|
|
339
|
+
* não vem vira "não verificável", jamais falha.
|
|
287
340
|
*
|
|
288
341
|
* @typedef {object} VerifyResult
|
|
289
342
|
* @property {boolean} ok
|
|
290
343
|
* @property {{remaining: number|null, limit: number|null, resetAt: string|null}} quota
|
|
291
|
-
* @property {Record<string,
|
|
344
|
+
* @property {Record<string, unknown>} facts
|
|
292
345
|
* @property {string[]} problems
|
|
293
346
|
*/
|
|
294
347
|
|
package/src/setup/files.mjs
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { WORKFLOW_FILES, CODE_WORKFLOW_FILES } from '../config.mjs';
|
|
2
|
-
import {
|
|
2
|
+
import { requireScm, resolveScmLink } from '../ports/index.mjs';
|
|
3
3
|
// readTemplate resolve {{CLI_VERSION}} — é o que fixa a versão da CLI nos
|
|
4
4
|
// workflows gravados no repo-alvo (ver src/lib/templates.mjs).
|
|
5
5
|
import { readTemplate } from '../lib/templates.mjs';
|
|
@@ -45,7 +45,7 @@ export async function setupFiles(token, owner, repo, spinner, { role = 'hub', po
|
|
|
45
45
|
// `repoFilesFor` continua no CORE: QUAL papel recebe QUAIS arquivos é regra
|
|
46
46
|
// de fluxo (RFC-005 §7.5). O que saiu para o plugin foi a gravação — e o
|
|
47
47
|
// conteúdo dos templates, que é formato de motor de automação, não de fluxo.
|
|
48
|
-
const scm =
|
|
48
|
+
const scm = await requireScm({ link: resolveScmLink({ owner, repo, role }), token, deps: { scm: port } });
|
|
49
49
|
|
|
50
50
|
spinner.message('Verificando repositório...');
|
|
51
51
|
const initialized = await scm.isInitialized();
|
package/src/setup/labels.mjs
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { allLabelsFor } from '../config.mjs';
|
|
2
|
-
import {
|
|
2
|
+
import { requireTracker } from '../ports/index.mjs';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Pausa entre criações de label.
|
|
@@ -17,7 +17,7 @@ const DELAY_MS = 120;
|
|
|
17
17
|
// vazios (o config ainda nem foi gravado) e o conjunto é só o do fluxo; quem
|
|
18
18
|
// cria as de modelo/fila depois é o `update`, que já lê o config do repo.
|
|
19
19
|
export async function setupLabels(token, owner, repo, spinner, fileAi, devAgent, { port } = {}) {
|
|
20
|
-
const tracker =
|
|
20
|
+
const tracker = await requireTracker({ token, owner, repo, deps: { tracker: port } });
|
|
21
21
|
const labels = allLabelsFor(fileAi, devAgent);
|
|
22
22
|
await tracker.ensureTags({
|
|
23
23
|
tags: labels,
|
package/src/setup/project.mjs
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
// a chama com um spinner do Clack, e trocar o formato do progresso do `init`
|
|
14
14
|
// seria mudança de comportamento numa fase que promete não ter nenhuma.
|
|
15
15
|
|
|
16
|
-
import {
|
|
16
|
+
import { requireTracker } from '../ports/index.mjs';
|
|
17
17
|
|
|
18
18
|
/**
|
|
19
19
|
* Cria o GitHub Project e os campos do RFC-001.
|
|
@@ -27,7 +27,7 @@ import { createGithubTracker } from '../plugins/tracker-github-projects/index.mj
|
|
|
27
27
|
* @returns {Promise<{projectId, projectNumber, projectUrl, fields, linkWarning?}>}
|
|
28
28
|
*/
|
|
29
29
|
export async function setupProject(token, owner, repo, projectTitle, spinner, { port } = {}) {
|
|
30
|
-
const tracker =
|
|
30
|
+
const tracker = await requireTracker({ token, owner, repo, deps: { tracker: port } });
|
|
31
31
|
const { config, warnings } = await tracker.setup({
|
|
32
32
|
provision: true,
|
|
33
33
|
title: projectTitle,
|
package/src/ui/wizard.mjs
CHANGED
|
@@ -4,10 +4,75 @@ import {
|
|
|
4
4
|
AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES,
|
|
5
5
|
STATUS_OPTIONS, CUSTOM_FIELDS, ALL_LABELS,
|
|
6
6
|
} from '../config.mjs';
|
|
7
|
+
// Bloco F (RFC-006 §9.3): as duas perguntas de fornecedor. `listPluginKinds` é o
|
|
8
|
+
// que permite NÃO perguntar quando não há escolha — ver `escolhaDeFornecedor`.
|
|
9
|
+
//
|
|
10
|
+
// Vem de `ports/index.mjs` e não de `src/plugins/load.mjs`: o wizard é CORE, e o
|
|
11
|
+
// portão da barreira pegou o import direto na primeira tentativa. Descobrir de onde
|
|
12
|
+
// vem um plugin é da entrada das portas.
|
|
13
|
+
import { listPluginKinds } from '../ports/index.mjs';
|
|
7
14
|
|
|
8
|
-
|
|
15
|
+
/**
|
|
16
|
+
* A pergunta de fornecedor de uma porta — ou a ausência dela (função quase pura:
|
|
17
|
+
* só varre diretório, via `listPluginKinds`).
|
|
18
|
+
*
|
|
19
|
+
* **Com um fornecedor só, não pergunta.** A §9.3 pede duas perguntas no `init`, e
|
|
20
|
+
* elas só fazem sentido com mais de uma resposta: um `select` de uma opção é ruído,
|
|
21
|
+
* e pior — sugere que os outros existem e que a escolha tem consequência. Foi a
|
|
22
|
+
* mesma razão que fez a §3.2 recusar espelhar `capabilities` antes de haver
|
|
23
|
+
* divergência possível.
|
|
24
|
+
*
|
|
25
|
+
* Devolve `{ kind, pergunta }`: `pergunta` é `null` quando não há o que escolher, e
|
|
26
|
+
* aí `kind` já é a resposta.
|
|
27
|
+
*
|
|
28
|
+
* @param {object} params
|
|
29
|
+
* @param {'tracker'|'scm'} params.port
|
|
30
|
+
* @param {string} params.rotulo como a pergunta se refere à porta
|
|
31
|
+
* @param {string} [params.root]
|
|
32
|
+
* @returns {{kind: string|null, pergunta: Function|null, disponiveis: object[]}}
|
|
33
|
+
*/
|
|
34
|
+
/**
|
|
35
|
+
* O `hint` de uma opção de fornecedor (função PURA).
|
|
36
|
+
*
|
|
37
|
+
* A ORIGEM entra no texto porque ela muda o que acontece DEPOIS: um plugin da fenda
|
|
38
|
+
* local não é versionado, e um repositório inicializado com ele para de funcionar na
|
|
39
|
+
* máquina de outra pessoa. Sem o aviso a escolha parece equivalente às outras, e o
|
|
40
|
+
* custo aparece longe de quem escolheu.
|
|
41
|
+
*
|
|
42
|
+
* Extraída para ser testável: o `p.select` que a consome precisa de TTY, então uma
|
|
43
|
+
* asserção sobre o texto só é possível aqui.
|
|
44
|
+
*
|
|
45
|
+
* @param {{origem: string, spec: string|null}} d
|
|
46
|
+
* @returns {string}
|
|
47
|
+
*/
|
|
48
|
+
export function hintDoFornecedor(d) {
|
|
49
|
+
if (d.origem === 'embutido') return 'embutido na CLI';
|
|
50
|
+
if (d.origem === 'local') return `${d.spec} — NÃO versionado; só funciona nesta máquina`;
|
|
51
|
+
return d.spec;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export function escolhaDeFornecedor({ port, rotulo, root }) {
|
|
55
|
+
const disponiveis = listPluginKinds({ port, root });
|
|
56
|
+
if (disponiveis.length <= 1) {
|
|
57
|
+
return { kind: disponiveis[0]?.kind ?? null, pergunta: null, disponiveis };
|
|
58
|
+
}
|
|
59
|
+
return {
|
|
60
|
+
kind: null,
|
|
61
|
+
disponiveis,
|
|
62
|
+
pergunta: () => p.select({
|
|
63
|
+
message: `Qual ${rotulo} este repositório usa?`,
|
|
64
|
+
options: disponiveis.map(d => ({ value: d.kind, label: d.kind, hint: hintDoFornecedor(d) })),
|
|
65
|
+
initialValue: disponiveis[0].kind,
|
|
66
|
+
}),
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export async function runWizard({ root } = {}) {
|
|
9
71
|
p.intro('spec-wave — configuração do fluxo spec-driven');
|
|
10
72
|
|
|
73
|
+
const tracker = escolhaDeFornecedor({ port: 'tracker', rotulo: 'tracker (board e work items)', root });
|
|
74
|
+
const scm = escolhaDeFornecedor({ port: 'scm', rotulo: 'SCM (código e Pull Requests)', root });
|
|
75
|
+
|
|
11
76
|
const answers = await p.group(
|
|
12
77
|
{
|
|
13
78
|
repo: () =>
|
|
@@ -27,6 +92,11 @@ export async function runWizard() {
|
|
|
27
92
|
placeholder: 'Meu Projeto — Spec Wave',
|
|
28
93
|
}),
|
|
29
94
|
|
|
95
|
+
// Só entram quando há o que escolher. `p.group` chama o que estiver aqui,
|
|
96
|
+
// então a ausência da chave É a ausência da pergunta.
|
|
97
|
+
...(tracker.pergunta ? { trackerKind: tracker.pergunta } : {}),
|
|
98
|
+
...(scm.pergunta ? { scmKind: scm.pergunta } : {}),
|
|
99
|
+
|
|
30
100
|
provider: () =>
|
|
31
101
|
p.select({
|
|
32
102
|
message: 'Qual provider de IA os workflows devem usar?',
|
|
@@ -96,6 +166,11 @@ export async function runWizard() {
|
|
|
96
166
|
projectTitle: answers.projectTitle,
|
|
97
167
|
provider: answers.provider,
|
|
98
168
|
model: answers.model.trim(),
|
|
169
|
+
// A resposta, ou o único fornecedor que havia. O `init` grava os dois no
|
|
170
|
+
// `.spec-wave.json` — é o que faz um repo NOVO ser explícito, enquanto os
|
|
171
|
+
// antigos seguem valendo por derivação (bloco D).
|
|
172
|
+
trackerKind: answers.trackerKind ?? tracker.kind,
|
|
173
|
+
scmKind: answers.scmKind ?? scm.kind,
|
|
99
174
|
};
|
|
100
175
|
}
|
|
101
176
|
|