@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 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
- - Para repositórios em organizações: criar PAT com escopo `project` e adicionar como secret `GH_PROJECT_TOKEN`
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spec-wave/cli",
3
- "version": "1.0.5",
3
+ "version": "1.0.7",
4
4
  "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
5
5
  "type": "module",
6
6
  "bin": {
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
- import { fileURLToPath } from 'node:url';
10
- import path from 'node:path';
11
- import { readFileSync } from 'node:fs';
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(pkg.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
@@ -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
- const __dir = path.dirname(fileURLToPath(import.meta.url));
19
- const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
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: pkg.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: pkg.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${pkg.version})`);
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(__dir, '..', 'templates', 'skill', 'SKILL.md');
13
- // Versão da CLI que gerou a skill instalada — carimbada no arquivo para detecção
14
- // de desatualização (a skill é uma cópia estática; não acompanha o `npx` sozinha).
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, pkg.version, versionBanner);
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, pkg.version))
390
- : renderContent(dest.format, parsed, pkg.version);
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${pkg.version} instalada (escopo: ${scopeLabel})`,
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. ' +
@@ -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
- const __dir = path.dirname(fileURLToPath(import.meta.url));
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: pkg.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:')} ${pkg.version}`,
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
@@ -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
- export const TEMPLATES_DIR = path.join(__dir, '..', 'templates');
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 pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
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.5",
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.