@spec-wave/cli 1.0.5 → 1.0.7
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/README.md +26 -1
- package/package.json +1 -1
- package/src/cli.mjs +5 -7
- package/src/commands/init.mjs +7 -6
- package/src/commands/install-skill.mjs +11 -12
- package/src/commands/refresh.mjs +4 -7
- package/src/lib/templates.mjs +28 -3
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugin/skills/setup/SKILL.md +9 -0
- package/src/templates/skill/SKILL.md +9 -0
package/README.md
CHANGED
|
@@ -104,12 +104,37 @@ Arquivo em `.github/config/tech_context.yml` que descreve a stack tecnológica d
|
|
|
104
104
|
## Pré-requisitos
|
|
105
105
|
|
|
106
106
|
- Node.js >= 20
|
|
107
|
+
- O repositório pertence a uma **organização**, não a uma conta pessoal — o `init` recusa conta
|
|
108
|
+
pessoal, porque a instalação de um GitHub App não alcança Projects v2 fora de uma org e metade do
|
|
109
|
+
fluxo (tudo que move card) morreria em runtime
|
|
107
110
|
- GitHub CLI (`gh`) autenticado com escopos `project`, `repo` e `workflow`:
|
|
108
111
|
```bash
|
|
109
112
|
gh auth refresh --scopes project,repo,workflow
|
|
110
113
|
```
|
|
114
|
+
- **Actions habilitado** no repositório e permitido pela política da organização
|
|
111
115
|
- Secret no repositório, conforme o provider: `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max) ou `OPENROUTER_API_KEY` (Settings → Secrets → Actions)
|
|
112
|
-
|
|
116
|
+
|
|
117
|
+
### Autenticação dos workflows: GitHub App ou PATs
|
|
118
|
+
|
|
119
|
+
O `GITHUB_TOKEN` do Actions **não** tem escopo de Projects e não alcança outro repositório. Dois
|
|
120
|
+
caminhos preenchem essa lacuna — e `spec-wave doctor` diz qual está valendo:
|
|
121
|
+
|
|
122
|
+
**GitHub App da organização (recomendado).** Crie uma App na org, instale no hub e em cada
|
|
123
|
+
repositório de código, e grave `SPEC_WAVE_APP_ID` + `SPEC_WAVE_APP_PRIVATE_KEY` (o `.pem` completo).
|
|
124
|
+
Cada execução gera o próprio token, sem depender do PAT de uma pessoa. Permissões: Issues RW,
|
|
125
|
+
Contents RW, Pull requests RW, Metadata R, Projects (org) RW — mais Workflows W só se a App também
|
|
126
|
+
for usada para rodar `init`/`update`. Prefira secret de **organização**; se a visibilidade for
|
|
127
|
+
*Selected repositories*, lembre de acrescentar cada repositório novo à lista, senão o workflow dele
|
|
128
|
+
não enxerga o secret e a falha só aparece na primeira execução.
|
|
129
|
+
|
|
130
|
+
**PATs (sem App).** `GH_PROJECT_TOKEN` com escopo `project` (mover cards), `GH_PR_TOKEN` quando a
|
|
131
|
+
organização não permite o Actions abrir PR ou a branch exige status checks, e `SPEC_WAVE_HUB_TOKEN`
|
|
132
|
+
no repositório de código (multi-repo). O PAT é de uma pessoa: quando ela sai da organização — ou o
|
|
133
|
+
token expira — os workflows param em silêncio.
|
|
134
|
+
|
|
135
|
+
Checklist completo, com o sintoma de cada item quando falta, em
|
|
136
|
+
[Configurações do GitHub](https://github.com/astratech-net-br/spec-wave-cli/blob/main/apps/docs/src/content/docs/configuracao/github.md)
|
|
137
|
+
— este README é publicado no npm, então o link é absoluto de propósito.
|
|
113
138
|
|
|
114
139
|
---
|
|
115
140
|
|
package/package.json
CHANGED
package/src/cli.mjs
CHANGED
|
@@ -6,12 +6,10 @@
|
|
|
6
6
|
// `program.commands` diretamente, em vez de parsear o texto do `--help`.
|
|
7
7
|
|
|
8
8
|
import { Command } from 'commander';
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
const __dir = path.dirname(fileURLToPath(import.meta.url));
|
|
14
|
-
const pkg = JSON.parse(readFileSync(path.join(__dir, '..', 'package.json'), 'utf-8'));
|
|
9
|
+
// A versão vem de lib/templates.mjs, que já resolve o escape de empacotamento
|
|
10
|
+
// (SPEC_WAVE_CLI_VERSION) — antes este arquivo lia o package.json por conta
|
|
11
|
+
// própria, e um bundle precisava reproduzir a árvore só por causa disto.
|
|
12
|
+
import { CLI_VERSION } from './lib/templates.mjs';
|
|
15
13
|
|
|
16
14
|
/**
|
|
17
15
|
* Monta o programa do Commander com todos os comandos (função sem efeito).
|
|
@@ -26,7 +24,7 @@ export function buildProgram() {
|
|
|
26
24
|
program
|
|
27
25
|
.name('spec-wave')
|
|
28
26
|
.description('Setup spec-driven GitHub workflow with Projects v2')
|
|
29
|
-
.version(
|
|
27
|
+
.version(CLI_VERSION)
|
|
30
28
|
// Conta do `gh` a usar nesta execução. Existe porque um GH_TOKEN exportado no
|
|
31
29
|
// shell (um `.envrc` na raiz de um diretório de projetos, por exemplo) vale
|
|
32
30
|
// para repositórios de QUALQUER org abaixo dele — e o GraphQL do GitHub
|
package/src/commands/init.mjs
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import * as p from '@clack/prompts';
|
|
2
2
|
import chalk from 'chalk';
|
|
3
3
|
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
|
|
4
|
-
import { fileURLToPath } from 'node:url';
|
|
5
4
|
import path from 'node:path';
|
|
6
5
|
import { resolveToken, verifyTokenScopes } from '../api/auth.mjs';
|
|
7
6
|
import { runWizard } from '../ui/wizard.mjs';
|
|
@@ -15,8 +14,10 @@ import {
|
|
|
15
14
|
} from '../config.mjs';
|
|
16
15
|
import { REPO_ROLES, DEFAULT_REPO_ROLE, parseRepoRef } from '../lib/repo-role.mjs';
|
|
17
16
|
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
// CLI_VERSION vem de lib/templates.mjs, que trata o escape de empacotamento
|
|
18
|
+
// (SPEC_WAVE_CLI_VERSION) — este comando roda dentro de um bundle no init
|
|
19
|
+
// server-side da UI, onde não existe package.json dois níveis acima.
|
|
20
|
+
import { CLI_VERSION } from '../lib/templates.mjs';
|
|
20
21
|
|
|
21
22
|
export async function init(options) {
|
|
22
23
|
// --- Papel (RFC-005) ---
|
|
@@ -274,7 +275,7 @@ export async function init(options) {
|
|
|
274
275
|
// campo, continua valendo sem regravação.
|
|
275
276
|
const config = role === 'code'
|
|
276
277
|
? {
|
|
277
|
-
version:
|
|
278
|
+
version: CLI_VERSION,
|
|
278
279
|
role,
|
|
279
280
|
owner,
|
|
280
281
|
repo,
|
|
@@ -282,7 +283,7 @@ export async function init(options) {
|
|
|
282
283
|
initializedAt: new Date().toISOString(),
|
|
283
284
|
}
|
|
284
285
|
: {
|
|
285
|
-
version:
|
|
286
|
+
version: CLI_VERSION,
|
|
286
287
|
role,
|
|
287
288
|
owner,
|
|
288
289
|
repo,
|
|
@@ -301,7 +302,7 @@ export async function init(options) {
|
|
|
301
302
|
};
|
|
302
303
|
writeFileSync(localConfigPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
|
|
303
304
|
configWritten = true;
|
|
304
|
-
configSpinner.stop(`${CONFIG_FILE} gravado local (spec-wave v${
|
|
305
|
+
configSpinner.stop(`${CONFIG_FILE} gravado local (spec-wave v${CLI_VERSION})`);
|
|
305
306
|
} catch (err) {
|
|
306
307
|
configSpinner.stop('');
|
|
307
308
|
p.log.warn(`Não foi possível gravar ${CONFIG_FILE}: ${err.message}`);
|
|
@@ -1,21 +1,20 @@
|
|
|
1
1
|
import * as p from '@clack/prompts';
|
|
2
2
|
import chalk from 'chalk';
|
|
3
3
|
import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
|
|
4
|
-
import { fileURLToPath } from 'node:url';
|
|
5
4
|
import { homedir } from 'node:os';
|
|
6
5
|
import path from 'node:path';
|
|
7
6
|
import { parseSkill } from '../lib/skill-file.mjs';
|
|
8
7
|
import { listPluginSkills, planPluginSkillFiles } from '../lib/plugin-skills.mjs';
|
|
8
|
+
// TEMPLATES_DIR e CLI_VERSION já tratam os escapes de empacotamento
|
|
9
|
+
// (SPEC_WAVE_TEMPLATES_DIR / SPEC_WAVE_CLI_VERSION) — ver lib/templates.mjs.
|
|
10
|
+
import { TEMPLATES_DIR, CLI_VERSION } from '../lib/templates.mjs';
|
|
9
11
|
|
|
10
|
-
const __dir = path.dirname(fileURLToPath(import.meta.url));
|
|
11
12
|
// Fonte única da skill, publicada via "files": ["src"] no package.json.
|
|
12
|
-
const SKILL_SOURCE = path.join(
|
|
13
|
-
//
|
|
14
|
-
//
|
|
15
|
-
const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
|
|
13
|
+
const SKILL_SOURCE = path.join(TEMPLATES_DIR, 'skill', 'SKILL.md');
|
|
14
|
+
// A versão da CLI é carimbada na skill instalada para detecção de
|
|
15
|
+
// desatualização (a skill é uma cópia estática; não acompanha o `npx` sozinha).
|
|
16
16
|
// Reexportados para o comando `update` (detecção de skill desatualizada).
|
|
17
|
-
export { SKILL_SOURCE };
|
|
18
|
-
export const CLI_VERSION = pkg.version;
|
|
17
|
+
export { SKILL_SOURCE, CLI_VERSION };
|
|
19
18
|
|
|
20
19
|
// Marcadores usados para gravar/atualizar a skill de forma idempotente em
|
|
21
20
|
// arquivos compartilhados (AGENTS.md) — permite reinstalar sem duplicar.
|
|
@@ -360,7 +359,7 @@ export async function installSkill(options = {}) {
|
|
|
360
359
|
// um. Sobrescrever aqui é seguro sem confirmar por arquivo: o destino é um
|
|
361
360
|
// diretório inteiro do spec-wave, não um arquivo que o usuário mantém.
|
|
362
361
|
if (dest.format === 'skills-dir') {
|
|
363
|
-
const files = planPluginSkillFiles(dest.path,
|
|
362
|
+
const files = planPluginSkillFiles(dest.path, CLI_VERSION, versionBanner);
|
|
364
363
|
if (!files.length) {
|
|
365
364
|
p.log.error(`${target.name}: nenhuma skill encontrada no plugin empacotado — pulado.`);
|
|
366
365
|
continue;
|
|
@@ -386,8 +385,8 @@ export async function installSkill(options = {}) {
|
|
|
386
385
|
|
|
387
386
|
const content =
|
|
388
387
|
dest.format === 'agents'
|
|
389
|
-
? mergeAgentsFile(dest.path, renderContent('agents', parsed,
|
|
390
|
-
: renderContent(dest.format, parsed,
|
|
388
|
+
? mergeAgentsFile(dest.path, renderContent('agents', parsed, CLI_VERSION))
|
|
389
|
+
: renderContent(dest.format, parsed, CLI_VERSION);
|
|
391
390
|
|
|
392
391
|
// Confirmar sobrescrita de arquivos "próprios" (skill/rules/mdc). Para
|
|
393
392
|
// 'agents' o merge por marcadores já é seguro (não apaga conteúdo alheio).
|
|
@@ -419,7 +418,7 @@ export async function installSkill(options = {}) {
|
|
|
419
418
|
return `${chalk.green('✓')} ${chalk.bold(w.target.name)}${suffix}\n ${chalk.dim(w.dest.path)}`;
|
|
420
419
|
})
|
|
421
420
|
.join('\n'),
|
|
422
|
-
`Skill v${
|
|
421
|
+
`Skill v${CLI_VERSION} instalada (escopo: ${scopeLabel})`,
|
|
423
422
|
);
|
|
424
423
|
p.outro(
|
|
425
424
|
'Reinicie/recarregue o agente para que ele detecte a skill. ' +
|
package/src/commands/refresh.mjs
CHANGED
|
@@ -1,15 +1,12 @@
|
|
|
1
1
|
import * as p from '@clack/prompts';
|
|
2
2
|
import chalk from 'chalk';
|
|
3
3
|
import { readFileSync, writeFileSync } from 'node:fs';
|
|
4
|
-
import { fileURLToPath } from 'node:url';
|
|
5
|
-
import path from 'node:path';
|
|
6
4
|
import { resolveToken } from '../api/auth.mjs';
|
|
7
5
|
import { CONFIG_FILE, STATUS_OPTIONS } from '../config.mjs';
|
|
8
6
|
import { findConfigPath } from '../lib/project-root.mjs';
|
|
9
7
|
import { getProjectSnapshot, updateStatusField } from '../api/github-graphql.mjs';
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
|
|
8
|
+
// Trata o escape de empacotamento (SPEC_WAVE_CLI_VERSION) — ver lib/templates.mjs.
|
|
9
|
+
import { CLI_VERSION } from '../lib/templates.mjs';
|
|
13
10
|
|
|
14
11
|
/**
|
|
15
12
|
* Plano de sincronização das opções do campo "Etapa" (função PURA).
|
|
@@ -248,7 +245,7 @@ export async function refresh(options = {}) {
|
|
|
248
245
|
const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
|
|
249
246
|
const updated = {
|
|
250
247
|
...config,
|
|
251
|
-
version:
|
|
248
|
+
version: CLI_VERSION,
|
|
252
249
|
project: {
|
|
253
250
|
...projectRest,
|
|
254
251
|
title: snapshot.title,
|
|
@@ -276,7 +273,7 @@ export async function refresh(options = {}) {
|
|
|
276
273
|
p.note(
|
|
277
274
|
`${chalk.dim('Project:')} ${snapshot.title} (#${snapshot.number})\n` +
|
|
278
275
|
`${chalk.dim('Campos:')} ${fieldNames.length ? fieldNames.join(', ') : '—'}\n` +
|
|
279
|
-
`${chalk.dim('Versão CLI:')} ${
|
|
276
|
+
`${chalk.dim('Versão CLI:')} ${CLI_VERSION}`,
|
|
280
277
|
'Configuração atualizada'
|
|
281
278
|
);
|
|
282
279
|
// O commit não é opcional: quem CLONA o repo — o dev-agent e o runner do
|
package/src/lib/templates.mjs
CHANGED
|
@@ -11,15 +11,40 @@
|
|
|
11
11
|
// resolvesse o placeholder, todo `update` veria os seis workflows como
|
|
12
12
|
// "desatualizados" para sempre.
|
|
13
13
|
|
|
14
|
+
// Dois pontos de fuga para quem EMPACOTA a CLI (o init server-side da UI leva
|
|
15
|
+
// um bundle esbuild numa Lambda, porque o pacote instalado puxa ~200 MB de
|
|
16
|
+
// OpenTelemetry). Sem eles, o bundle precisa reproduzir `src/lib/<arquivo>` +
|
|
17
|
+
// `src/templates` + `package.json` em duas alturas, só para estes dois
|
|
18
|
+
// `path.join` relativos continuarem resolvendo:
|
|
19
|
+
//
|
|
20
|
+
// • SPEC_WAVE_TEMPLATES_DIR — raiz dos templates, em vez de `../templates`;
|
|
21
|
+
// • SPEC_WAVE_CLI_VERSION — a versão, em vez de ler o package.json acima.
|
|
22
|
+
//
|
|
23
|
+
// São ESCAPES de empacotamento, não configuração de usuário: numa instalação
|
|
24
|
+
// normal (npm install -g) nenhum dos dois é definido e nada muda.
|
|
25
|
+
|
|
14
26
|
import { readFileSync } from 'node:fs';
|
|
15
27
|
import { fileURLToPath } from 'node:url';
|
|
16
28
|
import path from 'node:path';
|
|
17
29
|
|
|
18
30
|
const __dir = path.dirname(fileURLToPath(import.meta.url));
|
|
19
|
-
|
|
31
|
+
const templatesOverride = String(process.env.SPEC_WAVE_TEMPLATES_DIR || '').trim();
|
|
32
|
+
export const TEMPLATES_DIR = templatesOverride
|
|
33
|
+
? path.resolve(templatesOverride)
|
|
34
|
+
: path.join(__dir, '..', 'templates');
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Versão da CLI, para o `{{CLI_VERSION}}` dos workflows (função PURA —
|
|
38
|
+
* `env`/`read` injetáveis para teste). Um bundle define SPEC_WAVE_CLI_VERSION
|
|
39
|
+
* e nunca toca no disco; qualquer outro valor cai na leitura do package.json.
|
|
40
|
+
*/
|
|
41
|
+
export function resolveCliVersion(env = process.env, read = readFileSync) {
|
|
42
|
+
const embedded = String(env.SPEC_WAVE_CLI_VERSION || '').trim();
|
|
43
|
+
if (embedded) return embedded;
|
|
44
|
+
return JSON.parse(read(path.join(__dir, '..', '..', 'package.json'), 'utf-8')).version;
|
|
45
|
+
}
|
|
20
46
|
|
|
21
|
-
const
|
|
22
|
-
export const CLI_VERSION = pkg.version;
|
|
47
|
+
export const CLI_VERSION = resolveCliVersion();
|
|
23
48
|
|
|
24
49
|
const PLACEHOLDERS = { CLI_VERSION };
|
|
25
50
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spec-wave",
|
|
3
3
|
"displayName": "Spec Wave",
|
|
4
|
-
"version": "1.0.
|
|
4
|
+
"version": "1.0.7",
|
|
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",
|
|
@@ -54,6 +54,15 @@ Os workflows precisam de um token que atravesse repositórios e mexa no Project.
|
|
|
54
54
|
|
|
55
55
|
`init` e `doctor` aceitam token de instalação de App (`ghs_…`) — sem escopos legíveis, a verificação é funcional (acesso ao repo e ao Project).
|
|
56
56
|
|
|
57
|
+
### Rodando a CLI empacotada (bundle)
|
|
58
|
+
|
|
59
|
+
Quem roda o `init` a partir de um bundle (a Lambda do portal leva a CLI empacotada com esbuild, porque o pacote instalado puxa ~200 MB de OpenTelemetry) tem dois escapes, e **só** precisa deles — não são configuração de usuário:
|
|
60
|
+
|
|
61
|
+
- `SPEC_WAVE_TEMPLATES_DIR`: raiz dos templates (`src/templates`), no lugar do caminho relativo ao módulo. Copie a pasta para onde quiser e aponte a env.
|
|
62
|
+
- `SPEC_WAVE_CLI_VERSION`: a versão que vai no `{{CLI_VERSION}}` dos workflows e no `.spec-wave.json`, sem ler o `package.json`.
|
|
63
|
+
|
|
64
|
+
Sem essas envs nada muda (instalação normal por `npm install -g`). Com elas, o bundle não precisa reproduzir a árvore do pacote.
|
|
65
|
+
|
|
57
66
|
## Passos
|
|
58
67
|
|
|
59
68
|
1. **Já configurado?** Leia `.spec-wave.json` (Read) ou rode `npx @spec-wave/cli@latest info`. Se existir, mostre `project.url` e `version` e **confirme com o usuário** antes de reconfigurar.
|
|
@@ -578,6 +578,15 @@ Os workflows precisam de um token que atravesse repositórios e mexa no Project.
|
|
|
578
578
|
|
|
579
579
|
`init` e `doctor` aceitam token de instalação de App (`ghs_…`) — sem escopos legíveis, a verificação é funcional (acesso ao repo e ao Project).
|
|
580
580
|
|
|
581
|
+
##### Rodando a CLI empacotada (bundle)
|
|
582
|
+
|
|
583
|
+
Quem roda o `init` a partir de um bundle (a Lambda do portal leva a CLI empacotada com esbuild, porque o pacote instalado puxa ~200 MB de OpenTelemetry) tem dois escapes, e **só** precisa deles — não são configuração de usuário:
|
|
584
|
+
|
|
585
|
+
- `SPEC_WAVE_TEMPLATES_DIR`: raiz dos templates (`src/templates`), no lugar do caminho relativo ao módulo. Copie a pasta para onde quiser e aponte a env.
|
|
586
|
+
- `SPEC_WAVE_CLI_VERSION`: a versão que vai no `{{CLI_VERSION}}` dos workflows e no `.spec-wave.json`, sem ler o `package.json`.
|
|
587
|
+
|
|
588
|
+
Sem essas envs nada muda (instalação normal por `npm install -g`). Com elas, o bundle não precisa reproduzir a árvore do pacote.
|
|
589
|
+
|
|
581
590
|
#### Passos
|
|
582
591
|
|
|
583
592
|
1. **Já configurado?** Leia `.spec-wave.json` (Read) ou rode `npx @spec-wave/cli@latest info`. Se existir, mostre `project.url` e `version` e **confirme com o usuário** antes de reconfigurar.
|