@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.
Files changed (59) hide show
  1. package/package.json +1 -1
  2. package/protocol/scm.v1.json +154 -0
  3. package/protocol/tracker.v1.json +175 -0
  4. package/src/api/github-rest.mjs +109 -0
  5. package/src/commands/audit.mjs +3 -4
  6. package/src/commands/code-review.mjs +11 -6
  7. package/src/commands/decompose.mjs +29 -9
  8. package/src/commands/doctor.mjs +389 -220
  9. package/src/commands/generate-bug.mjs +17 -7
  10. package/src/commands/generate-plan.mjs +21 -13
  11. package/src/commands/generate-qa-plan.mjs +19 -11
  12. package/src/commands/generate-spec.mjs +19 -6
  13. package/src/commands/implement.mjs +105 -49
  14. package/src/commands/init.mjs +36 -6
  15. package/src/commands/issue.mjs +6 -2
  16. package/src/commands/merge.mjs +31 -18
  17. package/src/commands/mode.mjs +18 -10
  18. package/src/commands/move.mjs +3 -3
  19. package/src/commands/order.mjs +30 -20
  20. package/src/commands/preflight.mjs +10 -5
  21. package/src/commands/qa-lead.mjs +41 -31
  22. package/src/commands/qa-run.mjs +83 -55
  23. package/src/commands/qa.mjs +10 -6
  24. package/src/commands/refresh.mjs +6 -3
  25. package/src/commands/repair-stage.mjs +1 -1
  26. package/src/commands/repo.mjs +7 -7
  27. package/src/commands/run.mjs +7 -4
  28. package/src/commands/story.mjs +3 -3
  29. package/src/commands/task.mjs +3 -3
  30. package/src/commands/triage.mjs +3 -3
  31. package/src/commands/uninstall.mjs +14 -5
  32. package/src/commands/update.mjs +47 -19
  33. package/src/commands/validate.mjs +3 -4
  34. package/src/commands/workspace.mjs +2 -2
  35. package/src/lib/artifact-publish.mjs +4 -3
  36. package/src/lib/board.mjs +22 -24
  37. package/src/lib/config-ports.mjs +114 -0
  38. package/src/lib/critique.mjs +11 -1
  39. package/src/lib/doc-source.mjs +16 -2
  40. package/src/lib/doctor-capabilities.mjs +168 -0
  41. package/src/lib/implement-board.mjs +6 -1
  42. package/src/lib/implement-stream.mjs +87 -0
  43. package/src/lib/pr-ready.mjs +24 -11
  44. package/src/lib/story-graph.mjs +26 -6
  45. package/src/lib/tag-registry.mjs +58 -0
  46. package/src/lib/usage-report.mjs +15 -2
  47. package/src/plugin/.claude-plugin/plugin.json +1 -1
  48. package/src/plugins/load.mjs +427 -0
  49. package/src/plugins/scm-github/index.mjs +71 -2
  50. package/src/plugins/tracker-github-projects/index.mjs +52 -10
  51. package/src/ports/capabilities.mjs +47 -0
  52. package/src/ports/index.mjs +347 -0
  53. package/src/ports/scm.mjs +39 -2
  54. package/src/ports/tracker.mjs +94 -3
  55. package/src/ports/types.mjs +59 -6
  56. package/src/setup/files.mjs +2 -2
  57. package/src/setup/labels.mjs +2 -2
  58. package/src/setup/project.mjs +2 -2
  59. package/src/ui/wizard.mjs +76 -1
@@ -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
- // Na Fase 2 estes tipos viram `protocol/{tracker,scm}.v1.json` publicados no
12
- // pacote. Enquanto a RFC é Proposta, o normativo é `rfc/protocol/*.v1.json`.
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: o que o `doctor` imprime e o core não interpreta. Sacola aberta de
285
- * propósito — cada fornecedor tem fatos próprios, e forçá-los num schema
286
- * fechado seria inventar campo que só um deles preenche.
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, string>} facts
344
+ * @property {Record<string, unknown>} facts
292
345
  * @property {string[]} problems
293
346
  */
294
347
 
@@ -1,5 +1,5 @@
1
1
  import { WORKFLOW_FILES, CODE_WORKFLOW_FILES } from '../config.mjs';
2
- import { createGithubScm, githubLink } from '../plugins/scm-github/index.mjs';
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 = port || createGithubScm({ link: githubLink({ owner, repo, role }), token });
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();
@@ -1,5 +1,5 @@
1
1
  import { allLabelsFor } from '../config.mjs';
2
- import { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
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 = port || createGithubTracker({ token, owner, repo });
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,
@@ -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 { createGithubTracker } from '../plugins/tracker-github-projects/index.mjs';
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 = port || createGithubTracker({ token, owner, repo });
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
- export async function runWizard() {
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