@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 +1 -1
- package/src/cli.mjs +19 -0
- package/src/commands/decompose.mjs +4 -4
- package/src/commands/repo.mjs +103 -0
- package/src/lib/repo-role.mjs +67 -0
- package/src/plugin/.claude-plugin/plugin.json +1 -1
- package/src/plugin/skills/setup/SKILL.md +8 -1
- package/src/templates/skill/SKILL.md +8 -1
package/package.json
CHANGED
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
|
|
821
|
+
const spec = repoLabelSpec(slug);
|
|
822
822
|
try {
|
|
823
823
|
// createLabel já engole o 422 de "já existe".
|
|
824
|
-
await createLabel(token, owner, repo,
|
|
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
|
+
}
|
package/src/lib/repo-role.mjs
CHANGED
|
@@ -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.
|
|
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
|
|
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
|
|
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
|
|