@spec-wave/cli 0.34.2 → 1.0.1

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 (52) hide show
  1. package/package.json +2 -2
  2. package/protocol/qa-result.v1.json +9 -0
  3. package/src/agent/anthropic-agent.mjs +35 -2
  4. package/src/api/github-graphql.mjs +60 -2
  5. package/src/api/github-rest.mjs +23 -0
  6. package/src/cli.mjs +23 -0
  7. package/src/commands/code-review.mjs +71 -60
  8. package/src/commands/decompose.mjs +75 -4
  9. package/src/commands/doctor.mjs +105 -4
  10. package/src/commands/implement.mjs +82 -10
  11. package/src/commands/init.mjs +147 -29
  12. package/src/commands/merge.mjs +56 -4
  13. package/src/commands/move.mjs +4 -7
  14. package/src/commands/order.mjs +2 -2
  15. package/src/commands/qa-run.mjs +140 -19
  16. package/src/commands/qa.mjs +22 -21
  17. package/src/commands/repair-stage.mjs +2 -5
  18. package/src/commands/story.mjs +2 -2
  19. package/src/commands/task.mjs +2 -2
  20. package/src/commands/triage.mjs +2 -5
  21. package/src/commands/update.mjs +31 -8
  22. package/src/commands/validate.mjs +2 -5
  23. package/src/commands/workspace.mjs +112 -0
  24. package/src/config.mjs +19 -0
  25. package/src/lib/artifact-pr.mjs +1 -1
  26. package/src/lib/bug-doc.mjs +6 -1
  27. package/src/lib/claude.mjs +4 -0
  28. package/src/lib/decomposition-doc.mjs +56 -3
  29. package/src/lib/dependency-map.mjs +3 -0
  30. package/src/lib/doc-paths.mjs +6 -1
  31. package/src/lib/flow-run.mjs +14 -3
  32. package/src/lib/pr-link.mjs +109 -0
  33. package/src/lib/pr-ready.mjs +146 -0
  34. package/src/lib/project-root.mjs +51 -0
  35. package/src/lib/qa-exec.mjs +73 -0
  36. package/src/lib/qa-report.mjs +172 -8
  37. package/src/lib/repo-role.mjs +102 -0
  38. package/src/lib/workspace.mjs +151 -0
  39. package/src/plugin/.claude-plugin/plugin.json +1 -1
  40. package/src/plugin/skills/decompose/SKILL.md +1 -0
  41. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  42. package/src/plugin/skills/implement/SKILL.md +2 -2
  43. package/src/plugin/skills/merge/SKILL.md +3 -2
  44. package/src/plugin/skills/qa/SKILL.md +6 -1
  45. package/src/plugin/skills/qa-executor/SKILL.md +43 -1
  46. package/src/plugin/skills/setup/SKILL.md +12 -0
  47. package/src/setup/files.mjs +35 -13
  48. package/src/templates/skill/SKILL.md +27 -5
  49. package/src/templates/skill/core.md +5 -1
  50. package/src/templates/workflows/code/code-review.yml +60 -0
  51. package/src/templates/workflows/code/qa.yml +59 -0
  52. package/src/templates/workflows/pr-events.yml +116 -0
@@ -289,7 +289,7 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
289
289
  | `--yes` | boolean | Executa os merges. **Sem ela, só mostra o plano** (fila na ordem, retargets, avisos). |
290
290
  | `--keep-branches` | boolean | Não apaga as branches das Stories após o merge. |
291
291
 
292
- > O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** (marcar pronto é a revisão humana — o comando não pula isso). Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
292
+ > O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** — e é assim que se sabe que a Feature ainda está em desenvolvimento: quem tira do rascunho é o `implement`, ao concluir a última Story, para todos os PRs da Feature de uma vez. Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
293
293
 
294
294
  ### `@spec-wave/cli qa <issue>` — executa o plano de QA localmente (e `qa --pr-number <n>` no Action)
295
295
  | Flag/Arg | Tipo | Descrição |
@@ -569,6 +569,10 @@ docs/
569
569
  escrito pelo decompose --apply e atualizado por
570
570
  `order --sync`. É o que deixa order/implement/merge
571
571
  consultarem a ordem sem pagar a API por Story
572
+ qa/
573
+ cenario-<n>/ ← evidência VISUAL (vídeo/foto) do cenário N, publicada
574
+ por `spec-wave qa` (Maestro no mobile, Playwright na
575
+ web); arquivos planos, ≤ 4 MB cada. Bug: docs/bugs/<slug>/qa/
572
576
  rfcs/
573
577
  <slug-do-rfc>/
574
578
  decomposition.md ← mesmo papel, com "## Task N" (RFC não usa spec/plan)
@@ -0,0 +1,60 @@
1
+ name: Code Review
2
+
3
+ # Repositório de CÓDIGO (RFC-005 §7.1): este workflow não roda a CLI nem toca
4
+ # no board. Ele só avisa o hub — onde vivem as issues e o GitHub Project — que
5
+ # um PR foi aberto aqui. O hub recebe o aviso em pr-events.yml e faz o resto,
6
+ # dentro da trava por item que o serializa com o decompose. `concurrency` do
7
+ # GitHub é por repositório: com N repos de código, só centralizar no hub
8
+ # devolve a serialização.
9
+ #
10
+ # O hub é lido do .spec-wave.json deste repositório em tempo de execução, e
11
+ # NÃO carimbado no YAML: o `update` compara este arquivo byte a byte com o
12
+ # template empacotado, e um hub embutido o marcaria como desatualizado para
13
+ # sempre.
14
+ #
15
+ # Precisa do secret SPEC_WAVE_HUB_TOKEN: um token com permissão de escrita em
16
+ # Contents no hub (é o que o repository_dispatch exige). GITHUB_TOKEN não
17
+ # serve — ele só enxerga este repositório.
18
+ on:
19
+ pull_request:
20
+ types: [opened, reopened]
21
+
22
+ concurrency:
23
+ group: spec-wave-dispatch-${{ github.event.pull_request.number }}
24
+ cancel-in-progress: false
25
+
26
+ jobs:
27
+ dispatch:
28
+ # PR de documento (`spec-wave/*`) não é PR de implementação.
29
+ if: "!startsWith(github.event.pull_request.head.ref, 'spec-wave/')"
30
+ runs-on: ubuntu-latest
31
+ permissions:
32
+ contents: read
33
+
34
+ steps:
35
+ - uses: actions/checkout@v5
36
+
37
+ - id: hub
38
+ name: Lê o hub do .spec-wave.json
39
+ run: |
40
+ hub="$(jq -r '"\(.hub.owner // "")/\(.hub.repo // "")"' .spec-wave.json)"
41
+ if [ "$hub" = "/" ]; then
42
+ echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@latest init --role code --repo ${{ github.repository }} --hub <owner/repo>"
43
+ exit 1
44
+ fi
45
+ echo "repo=$hub" >> "$GITHUB_OUTPUT"
46
+
47
+ - name: Avisa o hub (repository_dispatch)
48
+ run: |
49
+ gh api "repos/${{ steps.hub.outputs.repo }}/dispatches" --input - <<'PAYLOAD'
50
+ {
51
+ "event_type": "spec-wave-pr",
52
+ "client_payload": {
53
+ "event": "opened",
54
+ "pr_repo": "${{ github.repository }}",
55
+ "pr_number": ${{ github.event.pull_request.number }}
56
+ }
57
+ }
58
+ PAYLOAD
59
+ env:
60
+ GH_TOKEN: ${{ secrets.SPEC_WAVE_HUB_TOKEN }}
@@ -0,0 +1,59 @@
1
+ name: QA
2
+
3
+ # Repositório de CÓDIGO (RFC-005 §7.3): despachante fino, sem CLI e sem board.
4
+ # Aprovação formal OU merge do PR viram um aviso ao hub, que move a Feature
5
+ # para 🧪 QA em pr-events.yml. Sem este arquivo nada chega a QA — os eventos
6
+ # de review e de merge acontecem SÓ aqui, no repo do PR.
7
+ #
8
+ # O hub é lido do .spec-wave.json em tempo de execução (ver code-review.yml,
9
+ # que explica por que o YAML não pode carimbá-lo). Precisa do secret
10
+ # SPEC_WAVE_HUB_TOKEN com escrita em Contents no hub.
11
+ on:
12
+ pull_request_review:
13
+ types: [submitted]
14
+ pull_request:
15
+ types: [closed]
16
+
17
+ concurrency:
18
+ group: spec-wave-dispatch-qa-${{ github.event.pull_request.number }}
19
+ cancel-in-progress: false
20
+
21
+ jobs:
22
+ dispatch:
23
+ # PR de documento (`spec-wave/*`) não é PR de implementação, e aprovar o
24
+ # PR da spec moveria a Feature para QA. A última linha aceita os dois
25
+ # eventos: review aprovada, ou PR fechado COM merge (sem merge não conta).
26
+ if: >
27
+ !startsWith(github.event.pull_request.head.ref, 'spec-wave/') &&
28
+ (github.event.review.state == 'approved' || github.event.pull_request.merged == true)
29
+ runs-on: ubuntu-latest
30
+ permissions:
31
+ contents: read
32
+
33
+ steps:
34
+ - uses: actions/checkout@v5
35
+
36
+ - id: hub
37
+ name: Lê o hub do .spec-wave.json
38
+ run: |
39
+ hub="$(jq -r '"\(.hub.owner // "")/\(.hub.repo // "")"' .spec-wave.json)"
40
+ if [ "$hub" = "/" ]; then
41
+ echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@latest init --role code --repo ${{ github.repository }} --hub <owner/repo>"
42
+ exit 1
43
+ fi
44
+ echo "repo=$hub" >> "$GITHUB_OUTPUT"
45
+
46
+ - name: Avisa o hub (repository_dispatch)
47
+ run: |
48
+ gh api "repos/${{ steps.hub.outputs.repo }}/dispatches" --input - <<'PAYLOAD'
49
+ {
50
+ "event_type": "spec-wave-pr",
51
+ "client_payload": {
52
+ "event": "qa",
53
+ "pr_repo": "${{ github.repository }}",
54
+ "pr_number": ${{ github.event.pull_request.number }}
55
+ }
56
+ }
57
+ PAYLOAD
58
+ env:
59
+ GH_TOKEN: ${{ secrets.SPEC_WAVE_HUB_TOKEN }}
@@ -0,0 +1,116 @@
1
+ name: PR Events
2
+
3
+ # Recebe, de um repositório de CÓDIGO do mesmo Project, o aviso de que um PR
4
+ # foi aberto, aprovado ou mergeado lá (RFC-005 §7.1). O despachante de lá
5
+ # manda um repository_dispatch com { event, pr_repo, pr_number }; tudo que
6
+ # toca o board roda AQUI, no hub, dentro do namespace spec-wave-item-<feature>
7
+ # que serializa com o decompose. Num hub sem repos de código este workflow
8
+ # nunca dispara e não custa nada.
9
+ #
10
+ # Tokens: GITHUB_TOKEN só enxerga este repositório, e o PR está noutro. Por
11
+ # isso a CLI recebe o GH_PROJECT_TOKEN (PAT com repo + project) também como
12
+ # GITHUB_TOKEN — é ele que lê o PR e comenta nele. Sem o secret, cai no
13
+ # GITHUB_TOKEN, que ainda lê PR de repo público mas não comenta.
14
+ on:
15
+ repository_dispatch:
16
+ types: [spec-wave-pr]
17
+
18
+ # Trava por PR de origem: o mesmo PR do mesmo repo não é processado duas
19
+ # vezes ao mesmo tempo. A trava que importa é a do job `move`, por ITEM.
20
+ concurrency:
21
+ group: spec-wave-pr-${{ github.event.client_payload.pr_repo }}-${{ github.event.client_payload.pr_number }}
22
+ cancel-in-progress: false
23
+
24
+ jobs:
25
+ # Descobre a Feature-alvo ANTES de tocar no board, para dar a chave de
26
+ # concurrency ao job seguinte — mesmo desenho do code-review.yml local.
27
+ resolve:
28
+ # Modo de execução: `spec-wave mode local` cria a variável de repositório
29
+ # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO.
30
+ if: vars.SPEC_WAVE_EXECUTION != 'local' && github.event.client_payload.event == 'opened'
31
+ runs-on: ubuntu-latest
32
+ permissions:
33
+ issues: read
34
+ pull-requests: read
35
+ contents: read
36
+ outputs:
37
+ feature: ${{ steps.resolve.outputs.feature }}
38
+ steps:
39
+ - uses: actions/checkout@v5
40
+ - uses: actions/setup-node@v5
41
+ with:
42
+ node-version: '24'
43
+
44
+ - name: Instala a CLI
45
+ run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
46
+
47
+ - id: resolve
48
+ run: >
49
+ spec-wave code-review
50
+ --pr-number ${{ github.event.client_payload.pr_number }}
51
+ --pr-repo ${{ github.event.client_payload.pr_repo }}
52
+ --resolve-only
53
+ env:
54
+ GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
55
+ GITHUB_REPOSITORY: ${{ github.repository }}
56
+
57
+ move:
58
+ needs: resolve
59
+ if: >
60
+ vars.SPEC_WAVE_EXECUTION != 'local' &&
61
+ needs.resolve.outputs.feature != ''
62
+ runs-on: ubuntu-latest
63
+ # MESMO namespace do decompose.yml e do code-review.yml: um decompose-apply
64
+ # em curso na Feature segura este job na fila em vez de disputar a
65
+ # subárvore com ele.
66
+ concurrency:
67
+ group: spec-wave-item-${{ needs.resolve.outputs.feature }}
68
+ cancel-in-progress: false
69
+ permissions:
70
+ issues: write
71
+ pull-requests: write
72
+ contents: read
73
+ steps:
74
+ - uses: actions/checkout@v5
75
+ - uses: actions/setup-node@v5
76
+ with:
77
+ node-version: '24'
78
+
79
+ - name: Instala a CLI
80
+ run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
81
+
82
+ - name: Move Feature to Code Review
83
+ run: >
84
+ spec-wave code-review
85
+ --pr-number ${{ github.event.client_payload.pr_number }}
86
+ --pr-repo ${{ github.event.client_payload.pr_repo }}
87
+ env:
88
+ GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
89
+ PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
90
+ GITHUB_REPOSITORY: ${{ github.repository }}
91
+
92
+ qa:
93
+ if: vars.SPEC_WAVE_EXECUTION != 'local' && github.event.client_payload.event == 'qa'
94
+ runs-on: ubuntu-latest
95
+ permissions:
96
+ issues: write
97
+ pull-requests: write
98
+ contents: read
99
+ steps:
100
+ - uses: actions/checkout@v5
101
+ - uses: actions/setup-node@v5
102
+ with:
103
+ node-version: '24'
104
+
105
+ - name: Instala a CLI
106
+ run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
107
+
108
+ - name: Move Feature to QA
109
+ run: >
110
+ spec-wave qa
111
+ --pr-number ${{ github.event.client_payload.pr_number }}
112
+ --pr-repo ${{ github.event.client_payload.pr_repo }}
113
+ env:
114
+ GITHUB_TOKEN: ${{ secrets.GH_PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
115
+ PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}
116
+ GITHUB_REPOSITORY: ${{ github.repository }}