@spec-wave/cli 1.0.1 → 1.0.2

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spec-wave/cli",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
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
@@ -372,6 +372,25 @@ Re-teste após o fix: qa <story> --only <cenário> (não duplica Bug — comenta
372
372
 
373
373
  Docs: https://astratech-net-br.github.io/spec-wave-cli/guia/qa/`);
374
374
 
375
+ program
376
+ .command('repo')
377
+ .description('Vincula (link), desvincula (unlink) ou lista (list) os repositórios de código do hub — repositories[] do .spec-wave.json (RFC-005)')
378
+ .argument('<acao>', 'link | unlink | list')
379
+ .argument('[slug]', 'Slug do repositório: minúsculas, [a-z0-9-], até 39 caracteres — vai na label repo:<slug> e não muda depois')
380
+ .argument('[repo]', 'No link: o repositório de código, como owner/repo')
381
+ .option('--dry-run', 'Mostra o que mudaria sem gravar o arquivo nem criar label')
382
+ .option('--json', 'No list: saída em JSON')
383
+ .action(async (acao, slug, repo, options) => {
384
+ const { repoCommand } = await import('./commands/repo.mjs');
385
+ await repoCommand({ action: acao, slug, repo, ...options })
386
+ .catch(err => { console.error(err.message); process.exit(1); });
387
+ })
388
+ .addHelpText('after', `
389
+ Edita só o .spec-wave.json LOCAL do hub (commite depois — os workflows leem a branch default) e cria a
390
+ label repo:<slug> no hub. O slug é imutável depois do primeiro vínculo: o mesmo slug só aceita o mesmo
391
+ repositório, e um repositório já vinculado não ganha um segundo slug. unlink não toca nas labels já
392
+ aplicadas. A UI grava o mesmo repositories[] — este comando é o caminho de quem não a usa.`);
393
+
375
394
  program
376
395
  .command('workspace')
377
396
  .description('Monta o workspace multi-repo de uma issue (RFC-005): mapeia ou clona, ao lado do hub, os repositórios que ela declara com repo:<slug>')
@@ -22,7 +22,7 @@ import {
22
22
  getIssue, createIssue, createLabel, removeLabel, addLabel, commentOnIssue, addBlockedBy, listIssueComments,
23
23
  getRepoDefaultBranch,
24
24
  } from '../api/github-rest.mjs';
25
- import { codeRepositories, repoLabel } from '../lib/repo-role.mjs';
25
+ import { codeRepositories, repoLabel, repoLabelSpec } from '../lib/repo-role.mjs';
26
26
  import { addSubIssue, listSubIssues, getProjectSnapshot } from '../api/github-graphql.mjs';
27
27
  import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
28
28
  import { generateDocument } from '../lib/claude.mjs';
@@ -818,12 +818,12 @@ async function resolveRepoLabels({ token, owner, repo, config }, doc) {
818
818
  }
819
819
 
820
820
  for (const slug of slugs) {
821
- const name = repoLabel(slug);
821
+ const spec = repoLabelSpec(slug);
822
822
  try {
823
823
  // createLabel já engole o 422 de "já existe".
824
- await createLabel(token, owner, repo, { name, color: '0e8a16', description: `Story toca o repositório ${slug}` });
824
+ await createLabel(token, owner, repo, spec);
825
825
  } catch (err) {
826
- console.warn(` Não consegui garantir a label ${name}: ${err.message}`);
826
+ console.warn(` Não consegui garantir a label ${spec.name}: ${err.message}`);
827
827
  }
828
828
  }
829
829
  for (const story of doc.stories || []) {
@@ -0,0 +1,103 @@
1
+ // `spec-wave repo link|unlink|list` — o vínculo hub ↔ repositório de código
2
+ // pelo lado da CLI (RFC-005). A UI grava o mesmo `repositories[]` no
3
+ // .spec-wave.json do hub via Contents API; este comando é o caminho de quem
4
+ // não usa a UI. Só edita o arquivo LOCAL (o dev commita, como no init) e cria
5
+ // a label `repo:<slug>` no hub, best-effort — o decompose --apply a garante de
6
+ // novo se faltar.
7
+ import * as p from '@clack/prompts';
8
+ import chalk from 'chalk';
9
+ import { resolveToken } from '../api/auth.mjs';
10
+ import { getRepoNodeId, createLabel } from '../api/github-rest.mjs';
11
+ import { resolveHubContext } from '../lib/project-root.mjs';
12
+ import { updateConfig } from '../lib/config-file.mjs';
13
+ import {
14
+ codeRepositories, linkRepository, unlinkRepository, parseRepoRef, repoLabelSpec,
15
+ } from '../lib/repo-role.mjs';
16
+ import { CONFIG_FILE } from '../config.mjs';
17
+
18
+ export async function repoCommand({ action, slug, repo: repoArg, dryRun = false, json = false } = {}) {
19
+ if (!['link', 'unlink', 'list'].includes(action)) {
20
+ throw new Error(`Ação inválida: "${action}". Use \`repo link <slug> <owner/repo>\`, \`repo unlink <slug>\` ou \`repo list\`.`);
21
+ }
22
+
23
+ const ctx = resolveHubContext();
24
+ if (ctx.role === 'code') {
25
+ throw new Error(
26
+ `${ctx.self.owner}/${ctx.self.repo} é um repositório de código; o vínculo é registrado no hub` +
27
+ (ctx.owner && ctx.repo ? ` ${ctx.owner}/${ctx.repo}.` : '.')
28
+ );
29
+ }
30
+ if (!ctx.root || !ctx.config) {
31
+ throw new Error(`Rode dentro do hub (diretório com ${CONFIG_FILE}) — ${ctx.error || 'config não encontrado'}.`);
32
+ }
33
+
34
+ if (action === 'list') {
35
+ const repos = codeRepositories(ctx.config);
36
+ if (json) { console.log(JSON.stringify({ hub: { owner: ctx.owner, repo: ctx.repo }, repositories: repos }, null, 2)); return repos; }
37
+ if (repos.length === 0) {
38
+ p.log.info(`Nenhum repositório de código vinculado ao hub ${ctx.owner}/${ctx.repo} (mono-repo).`);
39
+ return repos;
40
+ }
41
+ p.log.info(`Hub ${ctx.owner}/${ctx.repo} — ${repos.length} repositório(s) de código:`);
42
+ for (const r of repos) p.log.message(` ${chalk.cyan(r.slug)} → ${r.owner}/${r.repo} (label repo:${r.slug})`);
43
+ return repos;
44
+ }
45
+
46
+ if (!slug) throw new Error(`Informe o slug: \`spec-wave repo ${action} <slug>${action === 'link' ? ' <owner/repo>' : ''}\`.`);
47
+
48
+ if (action === 'unlink') {
49
+ const preview = unlinkRepository(ctx.config, slug);
50
+ if (preview.error) throw new Error(preview.error);
51
+ if (dryRun) {
52
+ p.log.info(`Dry-run: ${slug} sairia de repositories[] do ${CONFIG_FILE}. As labels repo:${slug} já aplicadas ficam.`);
53
+ return preview.config;
54
+ }
55
+ const { changed } = updateConfig(cfg => unlinkRepository(cfg, slug).config, { cwd: ctx.root });
56
+ p.log.success(`${slug} desvinculado (${CONFIG_FILE}${changed ? ' atualizado' : ' já estava assim'}).`);
57
+ p.log.warn(`As labels repo:${slug} já aplicadas em issues não foram tocadas — são histórico. Commite o ${CONFIG_FILE}.`);
58
+ return null;
59
+ }
60
+
61
+ // link
62
+ const target = parseRepoRef(repoArg);
63
+ if (!target) throw new Error(`Informe o repositório como owner/repo: \`spec-wave repo link ${slug} <owner/repo>\`.`);
64
+ const preview = linkRepository(ctx.config, { slug, ...target });
65
+ if (preview.error) throw new Error(preview.error);
66
+ if (!preview.changed) {
67
+ p.log.info(`${slug} → ${target.owner}/${target.repo} já está vinculado. Nada a fazer.`);
68
+ return preview.config;
69
+ }
70
+
71
+ // O repo precisa existir e ser legível pelo token — um slug apontando para
72
+ // o nada só apareceria na primeira Story, dentro do apply.
73
+ const token = await resolveToken();
74
+ try {
75
+ await getRepoNodeId(token, target.owner, target.repo);
76
+ } catch (err) {
77
+ throw new Error(`Não consegui ler ${target.owner}/${target.repo}: ${err.status === 404 ? 'não existe ou o token não o enxerga' : err.message}.`);
78
+ }
79
+
80
+ if (dryRun) {
81
+ p.log.info(`Dry-run: ${slug} → ${target.owner}/${target.repo} entraria em repositories[] do ${CONFIG_FILE}; label repo:${slug} seria criada no hub.`);
82
+ return preview.config;
83
+ }
84
+
85
+ const { changed } = updateConfig(cfg => linkRepository(cfg, { slug, ...target }).config, { cwd: ctx.root });
86
+ p.log.success(`${chalk.cyan(slug)} → ${target.owner}/${target.repo} vinculado (${CONFIG_FILE}${changed ? ' atualizado' : ' já estava assim'}).`);
87
+
88
+ const spec = repoLabelSpec(slug);
89
+ try {
90
+ await createLabel(token, ctx.owner, ctx.repo, spec);
91
+ p.log.success(`Label ${spec.name} garantida em ${ctx.owner}/${ctx.repo}.`);
92
+ } catch (err) {
93
+ p.log.warn(`Não consegui criar a label ${spec.name}: ${err.message} — o decompose --apply tenta de novo.`);
94
+ }
95
+
96
+ p.note(
97
+ `1. Commite o ${CONFIG_FILE} (os workflows do hub leem repositories[] da branch default).\n` +
98
+ `2. No repositório de código: npx @spec-wave/cli@latest init --role code --repo ${target.owner}/${target.repo} --hub ${ctx.owner}/${ctx.repo}\n` +
99
+ `3. Nas Stories, declare \`**Repos:** ${slug}\` no decomposition.md (vira a label ${spec.name}).`,
100
+ 'Próximos passos'
101
+ );
102
+ return null;
103
+ }
@@ -85,6 +85,73 @@ export function repoLabel(slug) {
85
85
  return `${REPO_LABEL_PREFIX}${slug}`;
86
86
  }
87
87
 
88
+ /** Cor e descrição únicas: `repo link`, `decompose --apply` e a UI criam a mesma label. */
89
+ export function repoLabelSpec(slug) {
90
+ return { name: repoLabel(slug), color: '0e8a16', description: `Story toca o repositório ${slug}` };
91
+ }
92
+
93
+ /**
94
+ * Vincula um repositório de código ao hub (função PURA — devolve um config
95
+ * novo). Recusa o que a label tornaria irreversível: o slug é IMUTÁVEL depois
96
+ * do primeiro vínculo, então o mesmo slug só aceita o MESMO repo; e um repo já
97
+ * vinculado sob outro slug não ganha um segundo nome.
98
+ *
99
+ * @param {object} config .spec-wave.json do hub
100
+ * @param {{slug: string, owner: string, repo: string}} entry
101
+ * @returns {{ config: object, changed: boolean, error: string|null }}
102
+ */
103
+ export function linkRepository(config, { slug, owner, repo }) {
104
+ if (isCodeRepo(config)) {
105
+ return { config, changed: false, error: 'este repositório é de código (role "code"); o vínculo é registrado no hub.' };
106
+ }
107
+ if (!isValidRepoSlug(slug)) {
108
+ return { config, changed: false, error: `slug inválido "${slug}": minúsculas, [a-z0-9-], até 39 caracteres, começando por letra ou dígito.` };
109
+ }
110
+ if (!owner || !repo) return { config, changed: false, error: 'informe o repositório como owner/repo.' };
111
+ const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase();
112
+ if (config?.owner && config?.repo && same(config.owner, owner) && same(config.repo, repo)) {
113
+ return { config, changed: false, error: `${owner}/${repo} é o próprio hub — o hub não se vincula a si mesmo.` };
114
+ }
115
+ const current = codeRepositories(config);
116
+ const bySlug = current.find(r => r.slug === slug);
117
+ if (bySlug && same(bySlug.owner, owner) && same(bySlug.repo, repo)) {
118
+ return { config, changed: false, error: null };
119
+ }
120
+ if (bySlug) {
121
+ return {
122
+ config, changed: false,
123
+ error: `o slug "${slug}" já aponta para ${bySlug.owner}/${bySlug.repo} e é imutável (está nas labels repo:${slug}). Use outro slug ou desvincule antes.`,
124
+ };
125
+ }
126
+ const byRepo = current.find(r => same(r.owner, owner) && same(r.repo, repo));
127
+ if (byRepo) {
128
+ return { config, changed: false, error: `${owner}/${repo} já está vinculado como "${byRepo.slug}".` };
129
+ }
130
+ // Preserva as entradas como estão no arquivo (a UI pode gravar campos além
131
+ // de slug/owner/repo); `current` serviu só para as checagens.
132
+ const raw = Array.isArray(config?.repositories) ? config.repositories : [];
133
+ return {
134
+ config: { ...config, repositories: [...raw, { slug, owner, repo }] },
135
+ changed: true,
136
+ error: null,
137
+ };
138
+ }
139
+
140
+ /**
141
+ * Desvincula pelo slug (função PURA). As labels `repo:<slug>` já aplicadas em
142
+ * issues NÃO são tocadas — são histórico, e o `update` nunca as classifica
143
+ * como órfãs (§3.3).
144
+ *
145
+ * @returns {{ config: object, changed: boolean, error: string|null }}
146
+ */
147
+ export function unlinkRepository(config, slug) {
148
+ if (!codeRepositories(config).some(r => r.slug === slug)) {
149
+ return { config, changed: false, error: `não há repositório vinculado com o slug "${slug}".` };
150
+ }
151
+ const raw = Array.isArray(config?.repositories) ? config.repositories : [];
152
+ return { config: { ...config, repositories: raw.filter(r => r?.slug !== slug) }, changed: true, error: null };
153
+ }
154
+
88
155
  /**
89
156
  * Slugs declarados pelas labels de uma issue, na ordem em que aparecem.
90
157
  * A label é a fonte de verdade (§3.3) — o campo do board é só espelho.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.0.1",
4
+ "version": "1.0.2",
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",
@@ -36,7 +36,14 @@ Um Project tem **um** hub (issues, docs, labels, Project, workflows do fluxo) e
36
36
  npx @spec-wave/cli@latest init --role code --repo <owner/api> --hub <owner/hub>
37
37
  ```
38
38
 
39
- Isso grava **só** dois despachantes (`code-review.yml`, `qa.yml`, que avisam o hub por `repository_dispatch`) e um `.spec-wave.json` com `role: "code"` e `hub`. Nada de labels, Project, issue templates ou secret de IA. Depois: o secret `SPEC_WAVE_HUB_TOKEN` no repo de código (token com escrita em Contents no hub), `spec-wave update` no hub (instala o `pr-events.yml`), e o registro em `repositories[]` do `.spec-wave.json` do hub — `{ slug, owner, repo }`, slug em `[a-z0-9-]`, imutável. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
39
+ Isso grava **só** dois despachantes (`code-review.yml`, `qa.yml`, que avisam o hub por `repository_dispatch`) e um `.spec-wave.json` com `role: "code"` e `hub`. Nada de labels, Project, issue templates ou secret de IA. Depois: o secret `SPEC_WAVE_HUB_TOKEN` no repo de código (token com escrita em Contents no hub), `spec-wave update` no hub (instala o `pr-events.yml`), e o registro do vínculo **no hub**:
40
+
41
+ ```bash
42
+ npx @spec-wave/cli@latest repo link <slug> <owner/api> # dentro do hub
43
+ npx @spec-wave/cli@latest repo list
44
+ ```
45
+
46
+ `repo link` grava `{ slug, owner, repo }` em `repositories[]` do `.spec-wave.json` local do hub (commite depois — os workflows leem a branch default) e cria a label `repo:<slug>`. Slug em `[a-z0-9-]`, até 39 caracteres, **imutável** depois do primeiro vínculo; `repo unlink <slug>` remove a entrada sem tocar nas labels já aplicadas. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
40
47
 
41
48
  ## Passos
42
49
 
@@ -560,7 +560,14 @@ Um Project tem **um** hub (issues, docs, labels, Project, workflows do fluxo) e
560
560
  npx @spec-wave/cli@latest init --role code --repo <owner/api> --hub <owner/hub>
561
561
  ```
562
562
 
563
- Isso grava **só** dois despachantes (`code-review.yml`, `qa.yml`, que avisam o hub por `repository_dispatch`) e um `.spec-wave.json` com `role: "code"` e `hub`. Nada de labels, Project, issue templates ou secret de IA. Depois: o secret `SPEC_WAVE_HUB_TOKEN` no repo de código (token com escrita em Contents no hub), `spec-wave update` no hub (instala o `pr-events.yml`), e o registro em `repositories[]` do `.spec-wave.json` do hub — `{ slug, owner, repo }`, slug em `[a-z0-9-]`, imutável. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
563
+ Isso grava **só** dois despachantes (`code-review.yml`, `qa.yml`, que avisam o hub por `repository_dispatch`) e um `.spec-wave.json` com `role: "code"` e `hub`. Nada de labels, Project, issue templates ou secret de IA. Depois: o secret `SPEC_WAVE_HUB_TOKEN` no repo de código (token com escrita em Contents no hub), `spec-wave update` no hub (instala o `pr-events.yml`), e o registro do vínculo **no hub**:
564
+
565
+ ```bash
566
+ npx @spec-wave/cli@latest repo link <slug> <owner/api> # dentro do hub
567
+ npx @spec-wave/cli@latest repo list
568
+ ```
569
+
570
+ `repo link` grava `{ slug, owner, repo }` em `repositories[]` do `.spec-wave.json` local do hub (commite depois — os workflows leem a branch default) e cria a label `repo:<slug>`. Slug em `[a-z0-9-]`, até 39 caracteres, **imutável** depois do primeiro vínculo; `repo unlink <slug>` remove a entrada sem tocar nas labels já aplicadas. Os PRs do repo de código vinculam a Story com `Closes <owner>/<hub>#<n>`.
564
571
 
565
572
  #### Passos
566
573