@spec-wave/cli 0.35.0 → 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 (41) hide show
  1. package/package.json +2 -2
  2. package/src/agent/anthropic-agent.mjs +35 -2
  3. package/src/api/github-rest.mjs +23 -0
  4. package/src/cli.mjs +23 -0
  5. package/src/commands/code-review.mjs +31 -17
  6. package/src/commands/decompose.mjs +75 -4
  7. package/src/commands/doctor.mjs +43 -3
  8. package/src/commands/implement.mjs +39 -6
  9. package/src/commands/init.mjs +147 -29
  10. package/src/commands/merge.mjs +11 -8
  11. package/src/commands/move.mjs +4 -7
  12. package/src/commands/order.mjs +2 -2
  13. package/src/commands/qa.mjs +22 -21
  14. package/src/commands/repair-stage.mjs +2 -5
  15. package/src/commands/story.mjs +2 -2
  16. package/src/commands/task.mjs +2 -2
  17. package/src/commands/triage.mjs +2 -5
  18. package/src/commands/update.mjs +31 -8
  19. package/src/commands/validate.mjs +2 -5
  20. package/src/commands/workspace.mjs +112 -0
  21. package/src/config.mjs +19 -0
  22. package/src/lib/artifact-pr.mjs +1 -1
  23. package/src/lib/claude.mjs +4 -0
  24. package/src/lib/decomposition-doc.mjs +56 -3
  25. package/src/lib/dependency-map.mjs +3 -0
  26. package/src/lib/flow-run.mjs +14 -3
  27. package/src/lib/pr-link.mjs +65 -10
  28. package/src/lib/pr-ready.mjs +6 -2
  29. package/src/lib/project-root.mjs +51 -0
  30. package/src/lib/repo-role.mjs +102 -0
  31. package/src/lib/workspace.mjs +151 -0
  32. package/src/plugin/.claude-plugin/plugin.json +1 -1
  33. package/src/plugin/skills/decompose/SKILL.md +1 -0
  34. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  35. package/src/plugin/skills/implement/SKILL.md +1 -1
  36. package/src/plugin/skills/setup/SKILL.md +12 -0
  37. package/src/setup/files.mjs +35 -13
  38. package/src/templates/skill/SKILL.md +14 -1
  39. package/src/templates/workflows/code/code-review.yml +60 -0
  40. package/src/templates/workflows/code/qa.yml +59 -0
  41. package/src/templates/workflows/pr-events.yml +116 -0
@@ -8,13 +8,49 @@ import { runWizard } from '../ui/wizard.mjs';
8
8
  import { setupProject } from '../setup/project.mjs';
9
9
  import { setupLabels } from '../setup/labels.mjs';
10
10
  import { setupFiles } from '../setup/files.mjs';
11
- import { getFileContent } from '../api/github-rest.mjs';
12
- import { CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, STATUS_OPTIONS, ALL_LABELS } from '../config.mjs';
11
+ import { getFileContent, getOwnerType } from '../api/github-rest.mjs';
12
+ import {
13
+ CONFIG_FILE, AI_PROVIDERS, getProvider, DEFAULT_PROVIDER, PORTAL_URL, WORKFLOW_FILES, CODE_WORKFLOW_FILES,
14
+ ISSUE_TEMPLATE_FILES, STATUS_OPTIONS, ALL_LABELS, HUB_DISPATCH_SECRET,
15
+ } from '../config.mjs';
16
+ import { REPO_ROLES, DEFAULT_REPO_ROLE, parseRepoRef } from '../lib/repo-role.mjs';
13
17
 
14
18
  const __dir = path.dirname(fileURLToPath(import.meta.url));
15
19
  const pkg = JSON.parse(readFileSync(path.join(__dir, '..', '..', 'package.json'), 'utf-8'));
16
20
 
17
21
  export async function init(options) {
22
+ // --- Papel (RFC-005) ---
23
+ // hub: issues, documentos, labels, Project e os workflows do fluxo.
24
+ // code: só branch e PR — recebe os despachantes e um .spec-wave.json que
25
+ // aponta para o hub. Não há wizard para o repo de código: são duas flags.
26
+ const role = String(options.role ?? DEFAULT_REPO_ROLE).toLowerCase();
27
+ if (!REPO_ROLES.includes(role)) {
28
+ p.log.error(`--role inválido: "${options.role}". Use um de: ${REPO_ROLES.join(', ')}`);
29
+ process.exit(1);
30
+ }
31
+ let hub = null;
32
+ if (role === 'code') {
33
+ if (!options.repo || !options.hub) {
34
+ p.log.error(
35
+ 'Um repositório de código precisa de --repo <owner/repo> e --hub <owner/repo>:\n' +
36
+ ' spec-wave init --role code --repo acme/api --hub acme/hub'
37
+ );
38
+ process.exit(1);
39
+ }
40
+ hub = parseRepoRef(options.hub);
41
+ if (!hub) {
42
+ p.log.error(`Formato inválido para --hub: "${options.hub}". Use: owner/repo`);
43
+ process.exit(1);
44
+ }
45
+ if (parseRepoRef(options.repo) && options.repo.toLowerCase() === options.hub.toLowerCase()) {
46
+ p.log.error('--hub não pode ser o próprio repositório: o hub é outro repo, com role "hub".');
47
+ process.exit(1);
48
+ }
49
+ } else if (options.hub) {
50
+ p.log.error('--hub só faz sentido com --role code.');
51
+ process.exit(1);
52
+ }
53
+
18
54
  // --- Token ---
19
55
  let token;
20
56
  try {
@@ -37,7 +73,8 @@ export async function init(options) {
37
73
  }
38
74
 
39
75
  const missingScopes = [];
40
- if (!tokenInfo.hasProject) missingScopes.push('project');
76
+ // O repo de código não cria Project — o escopo `project` é do hub.
77
+ if (role !== 'code' && !tokenInfo.hasProject) missingScopes.push('project');
41
78
  if (!tokenInfo.hasRepo) missingScopes.push('repo');
42
79
  if (!tokenInfo.hasWorkflow) missingScopes.push('workflow');
43
80
 
@@ -52,7 +89,18 @@ export async function init(options) {
52
89
 
53
90
  // --- Wizard ou flags ---
54
91
  let owner, repo, projectTitle, provider, model;
55
- if (options.repo) {
92
+ if (role === 'code') {
93
+ const self = parseRepoRef(options.repo);
94
+ if (!self) {
95
+ p.log.error('Formato inválido para --repo. Use: owner/repo');
96
+ process.exit(1);
97
+ }
98
+ ({ owner, repo } = self);
99
+ provider = DEFAULT_PROVIDER;
100
+ model = getProvider(provider).defaultModel;
101
+ p.log.info(`Repositório de código: ${owner}/${repo}`);
102
+ p.log.info(`Hub: ${hub.owner}/${hub.repo}`);
103
+ } else if (options.repo) {
56
104
  if (!options.repo.includes('/')) {
57
105
  p.log.error('Formato inválido para --repo. Use: owner/repo');
58
106
  process.exit(1);
@@ -76,19 +124,56 @@ export async function init(options) {
76
124
 
77
125
  const providerMeta = getProvider(provider);
78
126
 
127
+ // --- Owner precisa ser organização ---
128
+ // O GitHub App do spec-wave só acessa Projects v2 de organizações — Projects
129
+ // v2 de conta pessoal não são suportados pela instalação do App. Repositório
130
+ // e Project pertencem sempre ao mesmo owner neste fluxo, então uma checagem
131
+ // cobre os dois. Roda mesmo em --dry-run e mesmo com --skip-project, porque
132
+ // o repositório em si também precisa estar na org.
133
+ const ownerSpinner = p.spinner();
134
+ ownerSpinner.start(`Verificando se ${owner} é uma organização...`);
135
+ let ownerType;
136
+ try {
137
+ ownerType = await getOwnerType(token, owner);
138
+ } catch (err) {
139
+ ownerSpinner.stop('');
140
+ p.log.error(`Erro ao verificar owner "${owner}": ${err.message}`);
141
+ process.exit(1);
142
+ }
143
+ if (ownerType !== 'Organization') {
144
+ ownerSpinner.stop('');
145
+ p.log.error(
146
+ `"${owner}" é uma conta pessoal do GitHub, não uma organização.\n` +
147
+ 'O spec-wave exige que o repositório e o GitHub Project pertençam a uma organização: ' +
148
+ 'o GitHub App usado pelo spec-wave só tem acesso a Projects v2 de organizações ' +
149
+ '(Projects v2 de conta pessoal não são suportados pela instalação do App).\n' +
150
+ `Crie (ou use) uma organização no GitHub, transfira o repositório para ela e rode ` +
151
+ `"spec-wave init --repo <org>/${repo}" novamente.`
152
+ );
153
+ process.exit(1);
154
+ }
155
+ ownerSpinner.stop(`${owner} é uma organização.`);
156
+
79
157
  if (options.dryRun) {
80
158
  p.log.info(chalk.yellow('Modo dry-run: nenhuma alteração será feita.'));
81
- p.log.info(` Repositório: ${owner}/${repo}`);
82
- p.log.info(` Projeto: ${projectTitle}`);
83
- p.log.info(` IA: ${providerMeta.label} · modelo ${model}`);
84
- p.log.info(' Fases: project board → labels → workflow files');
159
+ p.log.info(` Repositório: ${owner}/${repo} (role: ${role})`);
160
+ if (role === 'code') {
161
+ p.log.info(` Hub: ${hub.owner}/${hub.repo}`);
162
+ p.log.info(` Fases: despachantes (${CODE_WORKFLOW_FILES.join(', ')}) → ${CONFIG_FILE}`);
163
+ } else {
164
+ p.log.info(` Projeto: ${projectTitle}`);
165
+ p.log.info(` IA: ${providerMeta.label} · modelo ${model}`);
166
+ p.log.info(' Fases: project board → labels → workflow files');
167
+ }
85
168
  p.outro('Dry-run concluído.');
86
169
  return;
87
170
  }
88
171
 
89
172
  // --- Phase 1: Project Board ---
90
173
  let projectUrl, projectId, projectNumber, projectFields;
91
- if (options.skipProject) {
174
+ if (role === 'code') {
175
+ p.log.info('Repositório de código: sem GitHub Project nem labels — ficam no hub.');
176
+ } else if (options.skipProject) {
92
177
  p.log.info('Pulando criação do GitHub Project (--skip-project).');
93
178
  // Preserva o bloco project do .spec-wave.json existente (se houver).
94
179
  // Prefere o arquivo local; recorre ao remoto para repos configurados por
@@ -136,7 +221,9 @@ export async function init(options) {
136
221
  }
137
222
 
138
223
  // --- Phase 2: Labels ---
139
- if (options.skipLabels) {
224
+ if (role === 'code') {
225
+ // Labels são do hub — é lá que as issues vivem.
226
+ } else if (options.skipLabels) {
140
227
  p.log.info('Pulando criação das labels (--skip-labels).');
141
228
  } else {
142
229
  const labelSpinner = p.spinner();
@@ -159,8 +246,12 @@ export async function init(options) {
159
246
  const filesSpinner = p.spinner();
160
247
  filesSpinner.start('Criando arquivos no repositório...');
161
248
  try {
162
- await setupFiles(token, owner, repo, filesSpinner);
163
- filesSpinner.stop(`Arquivos criados (${WORKFLOW_FILES.length} workflows + ${ISSUE_TEMPLATE_FILES.length} issue templates)`);
249
+ await setupFiles(token, owner, repo, filesSpinner, { role });
250
+ filesSpinner.stop(
251
+ role === 'code'
252
+ ? `Despachantes criados (${CODE_WORKFLOW_FILES.join(', ')})`
253
+ : `Arquivos criados (${WORKFLOW_FILES.length} workflows + ${ISSUE_TEMPLATE_FILES.length} issue templates)`
254
+ );
164
255
  } catch (err) {
165
256
  filesSpinner.stop('');
166
257
  p.log.error(`Erro ao criar arquivos: ${err.message}`);
@@ -178,23 +269,36 @@ export async function init(options) {
178
269
  const configSpinner = p.spinner();
179
270
  configSpinner.start(`Gravando ${CONFIG_FILE} local...`);
180
271
  try {
181
- const config = {
182
- version: pkg.version,
183
- owner,
184
- repo,
185
- project: {
186
- title: projectTitle,
187
- url: projectUrl ?? null,
188
- id: projectId ?? null,
189
- number: projectNumber ?? null,
190
- fields: projectFields ?? null,
191
- },
192
- ai: {
193
- provider: providerMeta.value,
194
- model,
195
- },
196
- initializedAt: new Date().toISOString(),
197
- };
272
+ // `role` é gravado nos dois casos. No hub ele é redundante (ausência já
273
+ // significa hub), mas explícito é legível — e um config antigo, sem o
274
+ // campo, continua valendo sem regravação.
275
+ const config = role === 'code'
276
+ ? {
277
+ version: pkg.version,
278
+ role,
279
+ owner,
280
+ repo,
281
+ hub: { owner: hub.owner, repo: hub.repo },
282
+ initializedAt: new Date().toISOString(),
283
+ }
284
+ : {
285
+ version: pkg.version,
286
+ role,
287
+ owner,
288
+ repo,
289
+ project: {
290
+ title: projectTitle,
291
+ url: projectUrl ?? null,
292
+ id: projectId ?? null,
293
+ number: projectNumber ?? null,
294
+ fields: projectFields ?? null,
295
+ },
296
+ ai: {
297
+ provider: providerMeta.value,
298
+ model,
299
+ },
300
+ initializedAt: new Date().toISOString(),
301
+ };
198
302
  writeFileSync(localConfigPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
199
303
  configWritten = true;
200
304
  configSpinner.stop(`${CONFIG_FILE} gravado local (spec-wave v${pkg.version})`);
@@ -203,6 +307,20 @@ export async function init(options) {
203
307
  p.log.warn(`Não foi possível gravar ${CONFIG_FILE}: ${err.message}`);
204
308
  }
205
309
 
310
+ if (role === 'code') {
311
+ p.outro(
312
+ `\n${chalk.green('✓')} ${owner}/${repo} configurado como repositório de código do hub ${hub.owner}/${hub.repo}.\n\n` +
313
+ ` Próximos passos:\n` +
314
+ (configWritten ? ` 1. Commite o ${CONFIG_FILE} (git add ${CONFIG_FILE} && git commit) — os despachantes o leem em runtime\n` : '') +
315
+ ` ${configWritten ? '2' : '1'}. Adicione o secret ${HUB_DISPATCH_SECRET} neste repositório: um token com escrita em Contents no hub\n` +
316
+ ` ${configWritten ? '3' : '2'}. No hub, rode \`npx @spec-wave/cli@latest update\` para instalar o pr-events.yml (recebe os despachos)\n` +
317
+ ` ${configWritten ? '4' : '3'}. Registre este repo no hub: \`repositories: [{ "slug": "<slug>", "owner": "${owner}", "repo": "${repo}" }]\` no ${CONFIG_FILE} do hub\n` +
318
+ ` ${chalk.dim('(o slug vai na label repo:<slug> das Stories — minúsculas, [a-z0-9-], até 39 caracteres, e não muda depois)')}\n\n` +
319
+ ` Nos PRs deste repo, vincule a Story com \`Closes ${hub.owner}/${hub.repo}#<n>\` — a forma qualificada é a que o hub reconhece.`
320
+ );
321
+ return;
322
+ }
323
+
206
324
  p.note(
207
325
  `As ${STATUS_OPTIONS.length} colunas do RFC-001 foram criadas no campo "Etapa".\n` +
208
326
  'Para usá-las como colunas do board:\n' +
@@ -28,12 +28,13 @@ import { listIssuePullRequests, listOpenPullRequests } from '../api/github-graph
28
28
  import { missingTrailers } from '../lib/commit-trailers.mjs';
29
29
  import { detectIssueType } from '../lib/issue-type.mjs';
30
30
  import { orderStories } from '../lib/dependencies.mjs';
31
- import { resolveRepoContext, loadConfig } from '../lib/project-root.mjs';
31
+ import { resolveHubContext, loadConfig } from '../lib/project-root.mjs';
32
+ import { extractIssueRefs, hubIssueNumbers, resolveLinkMode } from '../lib/pr-link.mjs';
32
33
  import { loadFeatureStories } from '../lib/story-graph.mjs';
33
34
  import { resolveCacheTtl, invalidateCache } from '../lib/net-cache.mjs';
34
35
  import { CONFIG_FILE } from '../config.mjs';
35
36
  import { acquireLock, releaseLock } from './run.mjs';
36
- import { codeReview, extractIssueNumbers } from './code-review.mjs';
37
+ import { codeReview } from './code-review.mjs';
37
38
  import { qa } from './qa.mjs';
38
39
 
39
40
  /**
@@ -125,18 +126,20 @@ export function planMerge({ sorted = [], byNumber = new Map(), prsByStory = new
125
126
  * @param {object} params
126
127
  * @param {number[]} params.sorted ordem topológica (números de Story)
127
128
  * @param {Map<number, Array>} params.prsByStory vínculos nativos já coletados
128
- * @param {Array<{number, body}>} params.openPrs PRs abertos do repositório
129
+ * @param {Array<{number, body}>} params.openPrs PRs abertos do hub
130
+ * @param {{owner:string, repo:string}} params.hub o repositório das Stories —
131
+ * um `#N` solto nesses PRs é issue do hub, e um `outro/repo#N` não é Story
129
132
  * @param {'explicit'|'any-mention'} [params.linkMode]
130
133
  * @returns {{ prsByStory: Map<number, Array>, adicionados: Array<{story:number, pr:number}> }}
131
134
  */
132
- export function complementWithBodyLinks({ sorted = [], prsByStory = new Map(), openPrs = [], linkMode = 'explicit' } = {}) {
135
+ export function complementWithBodyLinks({ sorted = [], prsByStory = new Map(), openPrs = [], hub, linkMode = 'explicit' } = {}) {
133
136
  const out = new Map(prsByStory);
134
137
  const adicionados = [];
135
138
  const faltantes = new Set(sorted.filter(s => (out.get(s) || []).length === 0));
136
139
  if (faltantes.size === 0) return { prsByStory: out, adicionados };
137
140
 
138
141
  for (const pr of openPrs) {
139
- for (const n of extractIssueNumbers(pr.body || '', { linkMode })) {
142
+ for (const n of hubIssueNumbers(extractIssueRefs(pr.body || '', { prRepo: hub, linkMode }), hub)) {
140
143
  if (!faltantes.has(n)) continue;
141
144
  out.set(n, [...(out.get(n) || []), pr]);
142
145
  adicionados.push({ story: n, pr: pr.number });
@@ -164,7 +167,7 @@ export async function merge({
164
167
  return;
165
168
  }
166
169
 
167
- const { owner, repo, root } = resolveRepoContext();
170
+ const { owner, repo, root } = resolveHubContext();
168
171
  if (!owner || !repo) {
169
172
  p.log.error(
170
173
  'Não foi possível determinar owner/repo.\n' +
@@ -269,8 +272,8 @@ export async function merge({
269
272
  // (`Closes #N`) é a fonte que o autor de fato escreveu.
270
273
  if (sorted.some(story => (prsByStory.get(story) || []).length === 0)) {
271
274
  const abertos = await listOpenPullRequests(token, owner, repo).catch(() => []);
272
- const linkMode = fileConfig?.codeReview?.linkMode === 'any-mention' ? 'any-mention' : 'explicit';
273
- const comp = complementWithBodyLinks({ sorted, prsByStory, openPrs: abertos, linkMode });
275
+ const linkMode = resolveLinkMode(fileConfig);
276
+ const comp = complementWithBodyLinks({ sorted, prsByStory, openPrs: abertos, hub: { owner, repo }, linkMode });
274
277
  prsByStory = comp.prsByStory;
275
278
  if (comp.adicionados.length > 0) {
276
279
  p.log.info(chalk.dim(
@@ -17,7 +17,7 @@ import { getIssue } from '../api/github-rest.mjs';
17
17
  import { addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
18
18
  import { detectIssueType } from '../lib/issue-type.mjs';
19
19
  import { loadProjectConfig, resolveField, advanceToStage, resolveStageName } from '../lib/board.mjs';
20
- import { loadConfig } from '../lib/project-root.mjs';
20
+ import { resolveHubContext } from '../lib/project-root.mjs';
21
21
  import {
22
22
  CONFIG_FILE, PROGRESS_TODO, PROGRESS_IN_PROGRESS, PROGRESS_DONE,
23
23
  isManualStageType, MANUAL_STAGE_TYPES, isStageInTrack, STAGE_TRACKS,
@@ -117,12 +117,9 @@ export async function move({ issue: issueArg, stage: stageArg, status: statusArg
117
117
  return;
118
118
  }
119
119
 
120
- // owner/repo: env GITHUB_REPOSITORY (padrão dos comandos de Action) com
121
- // fallback no .spec-wave.json, procurado subindo na árvore.
122
- const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
123
- const { config, root } = loadConfig();
124
- const owner = envOwner || config?.owner;
125
- const repo = envRepo || config?.repo;
120
+ // owner/repo do hub: env GITHUB_REPOSITORY (padrão dos comandos de Action)
121
+ // com fallback no .spec-wave.json, procurado subindo na árvore.
122
+ const { owner, repo, config, root } = resolveHubContext();
126
123
  if (!owner || !repo) {
127
124
  p.log.error(
128
125
  'Não foi possível determinar owner/repo.\n' +
@@ -29,7 +29,7 @@ import { listSubIssues } from '../api/github-graphql.mjs';
29
29
  import { detectIssueType } from '../lib/issue-type.mjs';
30
30
  import { parseDependencies, orderStories } from '../lib/dependencies.mjs';
31
31
  import { loadProjectConfig, selectOpenFeatures } from '../lib/board.mjs';
32
- import { resolveRepoContext, loadConfig } from '../lib/project-root.mjs';
32
+ import { resolveHubContext, loadConfig } from '../lib/project-root.mjs';
33
33
  import { featureDocPaths } from '../lib/doc-paths.mjs';
34
34
  import { parseDecompositionDoc, renderDecompositionDoc } from '../lib/decomposition-doc.mjs';
35
35
  import {
@@ -273,7 +273,7 @@ export async function order({
273
273
  return;
274
274
  }
275
275
 
276
- const { owner, repo } = resolveRepoContext();
276
+ const { owner, repo } = resolveHubContext();
277
277
  if (!owner || !repo) {
278
278
  emitError(opts,
279
279
  'Não foi possível determinar owner/repo.\n' +
@@ -3,23 +3,13 @@ import { getIssue, getPR, commentOnIssue } from '../api/github-rest.mjs';
3
3
  import { getIssueParent } from '../api/github-graphql.mjs';
4
4
  import { detectIssueType } from '../lib/issue-type.mjs';
5
5
  import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
6
- import { loadConfig } from '../lib/project-root.mjs';
6
+ import { resolveHubContext, resolvePrRepo } from '../lib/project-root.mjs';
7
+ import { extractIssueRefs, hubIssueNumbers, resolveLinkMode } from '../lib/pr-link.mjs';
7
8
  import { STATUS_OPTIONS, PROGRESS_TODO } from '../config.mjs';
8
9
 
9
10
  const QA_STAGE = STATUS_OPTIONS.find(s => s.name.includes('QA'))?.name;
10
11
  const TODO_STATUS = PROGRESS_TODO;
11
12
 
12
- function extractIssueNumbers(body) {
13
- if (!body) return [];
14
- const nums = new Set();
15
- const re = /(?:closes?|fixes?|resolves?)\s+#(\d+)|(?<![/\w#])#(\d+)/gi;
16
- for (const m of body.matchAll(re)) {
17
- const n = parseInt(m[1] || m[2], 10);
18
- if (n) nums.add(n);
19
- }
20
- return [...nums];
21
- }
22
-
23
13
  async function resolveFeatureIssue(token, owner, repo, issueNumber) {
24
14
  let issue;
25
15
  try {
@@ -42,13 +32,13 @@ async function resolveFeatureIssue(token, owner, repo, issueNumber) {
42
32
  return null;
43
33
  }
44
34
 
45
- export async function qa({ prNumber }) {
35
+ export async function qa({ prNumber, prRepo: prRepoOpt }) {
46
36
  const token = await resolveToken();
47
37
  const projectToken = process.env.PROJECT_TOKEN || token;
48
- const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
49
- const { config: cfg } = loadConfig();
50
- const owner = envOwner || cfg?.owner;
51
- const repo = envRepo || cfg?.repo;
38
+ // Mesma separação do code-review: o comando roda no hub (dono das issues) e
39
+ // o PR pode estar num repo de código — `--pr-repo` diz qual.
40
+ const ctx = resolveHubContext();
41
+ const { owner, repo, config: cfg } = ctx;
52
42
 
53
43
  if (!owner || !repo) {
54
44
  throw new Error(
@@ -56,12 +46,23 @@ export async function qa({ prNumber }) {
56
46
  'Defina GITHUB_REPOSITORY=owner/repo ou rode dentro de um repositório com .spec-wave.json.'
57
47
  );
58
48
  }
49
+ const hub = { owner, repo };
50
+ const prRepo = resolvePrRepo(prRepoOpt, ctx);
51
+ const prNum = parseInt(prNumber, 10);
59
52
 
60
- const pr = await getPR(token, owner, repo, parseInt(prNumber, 10));
61
- const issueNums = extractIssueNumbers(pr.body || '');
53
+ const pr = await getPR(token, prRepo.owner, prRepo.repo, prNum);
54
+ // Mesmo parser e mesma régua do code-review: o vínculo que levou a Story a
55
+ // 👀 Code Review é o que a leva a 🧪 QA. Antes o qa tinha um parser próprio,
56
+ // mais frouxo (qualquer `#N`), que o code-review já havia abandonado.
57
+ const linkMode = resolveLinkMode(cfg);
58
+ const issueNums = hubIssueNumbers(extractIssueRefs(pr.body || '', { prRepo, linkMode }), hub);
62
59
 
63
60
  if (issueNums.length === 0) {
64
- console.log('PR sem referências a issues — nenhuma Feature atualizada.');
61
+ console.log(
62
+ linkMode === 'explicit'
63
+ ? 'PR sem vínculo explícito (Closes/Fixes/Resolves/Implements #N) com issue do hub — board não atualizado.'
64
+ : 'PR sem referências a issues — nenhuma Feature atualizada.'
65
+ );
65
66
  return;
66
67
  }
67
68
 
@@ -124,7 +125,7 @@ export async function qa({ prNumber }) {
124
125
 
125
126
  if (updated.length > 0) {
126
127
  await commentOnIssue(
127
- token, owner, repo, parseInt(prNumber, 10),
128
+ token, prRepo.owner, prRepo.repo, prNum,
128
129
  `🧪 **PR aprovado — QA iniciado**\n\n` +
129
130
  `Item(ns) movido(s) para **${QA_STAGE}**:\n\n` +
130
131
  updated.map(f => `- ${f}`).join('\n')
@@ -23,7 +23,7 @@ import { getIssue, commentOnIssue } from '../api/github-rest.mjs';
23
23
  import { verifyTokenScopes } from '../api/auth.mjs';
24
24
  import { detectIssueType } from '../lib/issue-type.mjs';
25
25
  import { loadProjectConfig, resolveField, setItemStage, resolveStageName } from '../lib/board.mjs';
26
- import { loadConfig } from '../lib/project-root.mjs';
26
+ import { resolveHubContext } from '../lib/project-root.mjs';
27
27
  import { resolveProgressName } from './move.mjs';
28
28
  import { CONFIG_FILE } from '../config.mjs';
29
29
 
@@ -130,10 +130,7 @@ export async function repairStage(issuesArg, stageArg, options = {}) {
130
130
  return;
131
131
  }
132
132
 
133
- const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
134
- const { config, root } = loadConfig();
135
- const owner = envOwner || config?.owner;
136
- const repo = envRepo || config?.repo;
133
+ const { owner, repo, config, root } = resolveHubContext();
137
134
  if (!owner || !repo) {
138
135
  p.log.error(
139
136
  'Não foi possível determinar owner/repo.\n' +
@@ -12,7 +12,7 @@ import { getIssue } from '../api/github-rest.mjs';
12
12
  import { addProjectItem, getItemSingleSelectValue } from '../api/github-graphql.mjs';
13
13
  import { detectIssueType } from '../lib/issue-type.mjs';
14
14
  import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
15
- import { resolveRepoContext } from '../lib/project-root.mjs';
15
+ import { resolveHubContext } from '../lib/project-root.mjs';
16
16
  import { CONFIG_FILE, STAGE_CODE_REVIEW, PROGRESS_TODO } from '../config.mjs';
17
17
 
18
18
  export async function story({ action, issue: issueArg }) {
@@ -32,7 +32,7 @@ export async function story({ action, issue: issueArg }) {
32
32
  return;
33
33
  }
34
34
 
35
- const { owner, repo } = resolveRepoContext();
35
+ const { owner, repo } = resolveHubContext();
36
36
  if (!owner || !repo) {
37
37
  p.log.error(
38
38
  'Não foi possível determinar owner/repo.\n' +
@@ -15,7 +15,7 @@ import { getIssue } from '../api/github-rest.mjs';
15
15
  import { addProjectItem, getIssueParent, listSubIssues, getItemSingleSelectValue } from '../api/github-graphql.mjs';
16
16
  import { detectIssueType } from '../lib/issue-type.mjs';
17
17
  import { loadProjectConfig, resolveField, advanceToStage, setItemStatus } from '../lib/board.mjs';
18
- import { resolveRepoContext } from '../lib/project-root.mjs';
18
+ import { resolveHubContext } from '../lib/project-root.mjs';
19
19
  import {
20
20
  CONFIG_FILE, STAGE_DEVELOPMENT, STAGE_DONE,
21
21
  PROGRESS_IN_PROGRESS, PROGRESS_DONE,
@@ -53,7 +53,7 @@ export async function task({ action, issue: issueArg }) {
53
53
  return;
54
54
  }
55
55
 
56
- const { owner, repo } = resolveRepoContext();
56
+ const { owner, repo } = resolveHubContext();
57
57
  if (!owner || !repo) {
58
58
  p.log.error(
59
59
  'Não foi possível determinar owner/repo.\n' +
@@ -16,7 +16,7 @@ import {
16
16
  } from '../api/github-rest.mjs';
17
17
  import { detectIssueType } from '../lib/issue-type.mjs';
18
18
  import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
19
- import { loadConfig } from '../lib/project-root.mjs';
19
+ import { resolveHubContext } from '../lib/project-root.mjs';
20
20
  import { resolveTriageAction, canAcceptBug } from '../lib/bug-triage.mjs';
21
21
  import {
22
22
  CONFIG_FILE, STAGE_READY, PROGRESS_TODO, PRIORITY_LABELS,
@@ -45,10 +45,7 @@ export async function triage({ action: actionArg, issue: issueArg, reason, of, s
45
45
  return;
46
46
  }
47
47
 
48
- const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
49
- const { config, root } = loadConfig();
50
- const owner = envOwner || config?.owner;
51
- const repo = envRepo || config?.repo;
48
+ const { owner, repo, config, root } = resolveHubContext();
52
49
  if (!owner || !repo) {
53
50
  p.log.error(
54
51
  'Não foi possível determinar owner/repo.\n' +
@@ -4,7 +4,7 @@ import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
4
4
  import { homedir } from 'node:os';
5
5
  import path from 'node:path';
6
6
  import { resolveToken } from '../api/auth.mjs';
7
- import { CONFIG_FILE, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS, allLabelsFor } from '../config.mjs';
7
+ import { CONFIG_FILE, WORKFLOW_FILES, CODE_WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS, allLabelsFor } from '../config.mjs';
8
8
  import { getProjectSnapshot } from '../api/github-graphql.mjs';
9
9
  import {
10
10
  getFileContent, upsertFile, listLabels, createLabel, updateLabel, deleteLabel,
@@ -25,6 +25,7 @@ import {
25
25
  } from './install-skill.mjs';
26
26
  import { planPluginSkillFiles } from '../lib/plugin-skills.mjs';
27
27
  import { findConfigPath } from '../lib/project-root.mjs';
28
+ import { configuredRole } from '../lib/repo-role.mjs';
28
29
  import { currentGitBranch } from '../lib/repo-links.mjs';
29
30
 
30
31
  // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
@@ -33,6 +34,16 @@ const REPO_FILES = [
33
34
  ...ISSUE_TEMPLATE_FILES.map(f => ({ repoPath: `.github/ISSUE_TEMPLATE/${f}`, template: ['issue', f] })),
34
35
  ];
35
36
 
37
+ // Por papel (RFC-005 §7.4): num repo de código o update NÃO pode subir os
38
+ // workflows do fluxo nem os issue templates — isso o converteria em hub. O que
39
+ // ele recebe são só os despachantes (templates/workflows/code/).
40
+ const CODE_REPO_FILES = CODE_WORKFLOW_FILES.map(f => ({
41
+ repoPath: `.github/workflows/${f}`, template: ['workflows', 'code', f],
42
+ }));
43
+ function repoFilesFor(role) {
44
+ return role === 'code' ? CODE_REPO_FILES : REPO_FILES;
45
+ }
46
+
36
47
  // Detecta se a skill instalada em cada agente diverge da versão atual da CLI.
37
48
  // Retorna os alvos desatualizados (conteúdo diferente ou ausente).
38
49
  function detectSkill(parsed, baseDir, isGlobal) {
@@ -186,6 +197,10 @@ export function shouldDeleteOrphanLabel({ inUse, forceLabels = false }) {
186
197
  * @returns {Promise<{ content: string|null, error: string|null }>}
187
198
  */
188
199
  async function buildConfigContent(token, config) {
200
+ // Repo de código: nada a consultar — o Project é do hub. Só a versão muda.
201
+ if (configuredRole(config) === 'code') {
202
+ return { content: `${JSON.stringify({ ...config, version: CLI_VERSION }, null, 2)}\n`, error: null };
203
+ }
189
204
  const snapshot = await getProjectSnapshot(token, config.project.id);
190
205
  if (!snapshot) return { content: null, error: 'Project não encontrado' };
191
206
  const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
@@ -306,8 +321,15 @@ export async function update(options = {}) {
306
321
  }
307
322
  }
308
323
 
324
+ // Papel do repo (RFC-005): num repo de código não há labels, issue templates
325
+ // nem Project a consultar — só o config (versão) e a skill.
326
+ const role = configuredRole(config);
327
+ if (role === 'code') {
328
+ p.log.info(`${CONFIG_FILE} declara role "code": labels e workflows do fluxo ficam no hub ${config?.hub?.owner ?? '?'}/${config?.hub?.repo ?? '?'}.`);
329
+ }
330
+
309
331
  const doConfig = !options.skipConfig && !!config;
310
- const doRepo = !options.skipRepo && !!config?.owner && !!config?.repo;
332
+ const doRepo = !options.skipRepo && !!config?.owner && !!config?.repo && repoFilesFor(role).length > 0;
311
333
 
312
334
  // Token resolvido sob demanda (necessário só para repo/config remoto).
313
335
  let token;
@@ -325,11 +347,12 @@ export async function update(options = {}) {
325
347
  // 2a) Config desatualizado? (versão divergente ou formato legado).
326
348
  let configStale = null;
327
349
  if (doConfig) {
328
- const legacy = !config.project?.fields;
350
+ // Repo de código não tem bloco `project` — o teste de formato legado é do hub.
351
+ const legacy = role !== 'code' && !config.project?.fields;
329
352
  if (config.version !== CLI_VERSION || legacy) {
330
353
  configStale = {
331
354
  reason: legacy ? 'formato legado (sem project.fields)' : `versão ${config.version ?? '?'} ≠ ${CLI_VERSION}`,
332
- canApply: !!config.project?.id,
355
+ canApply: role === 'code' || !!config.project?.id,
333
356
  };
334
357
  }
335
358
  }
@@ -349,7 +372,7 @@ export async function update(options = {}) {
349
372
  p.log.warn(`Sem token do GitHub (${tokenError?.message ?? 'indisponível'}); pulando verificação do repo.`);
350
373
  } else {
351
374
  try {
352
- for (const f of REPO_FILES) {
375
+ for (const f of repoFilesFor(role)) {
353
376
  const remote = await getFileContent(tk, owner, repo, f.repoPath);
354
377
  const local = readTemplate(...f.template);
355
378
  if (remote === null) repoFiles.push({ ...f, reason: 'ausente', local });
@@ -624,12 +647,12 @@ export async function update(options = {}) {
624
647
  if (!configStale.canApply) {
625
648
  p.log.warn(`${CONFIG_FILE}: sem project.id — pulei. Rode \`npx @spec-wave/cli@latest init\` (sem --skip-project).`);
626
649
  } else {
627
- const tk = await getToken();
628
- if (!tk) {
650
+ const tk = role === 'code' ? null : await getToken();
651
+ if (role !== 'code' && !tk) {
629
652
  p.log.warn(`${CONFIG_FILE}: sem token — pulei. (${tokenError?.message ?? ''})`);
630
653
  } else {
631
654
  const s = p.spinner();
632
- s.start('Consultando o Project para atualizar o .spec-wave.json...');
655
+ s.start(role === 'code' ? `Atualizando a versão do ${CONFIG_FILE}...` : 'Consultando o Project para atualizar o .spec-wave.json...');
633
656
  try {
634
657
  const { content, error } = await buildConfigContent(tk, config);
635
658
  if (error) throw new Error(error);
@@ -9,7 +9,7 @@ import {
9
9
  import { findIncompleteDocSigns } from '../lib/doc-completeness.mjs';
10
10
  import { bugDocPaths, describeMissingSections } from '../lib/bug-doc.mjs';
11
11
  import { detectIssueType } from '../lib/issue-type.mjs';
12
- import { loadConfig } from '../lib/project-root.mjs';
12
+ import { resolveHubContext } from '../lib/project-root.mjs';
13
13
  import { executionMode } from '../lib/flow-run.mjs';
14
14
  import { docBlobUrl } from '../lib/repo-links.mjs';
15
15
  import { loadArtifact } from '../lib/doc-source.mjs';
@@ -161,10 +161,7 @@ export function renderMissingSection(doc, { section, found }) {
161
161
  */
162
162
  export async function validate({ issueNumber }) {
163
163
  const token = await resolveToken();
164
- const [envOwner, envRepo] = (process.env.GITHUB_REPOSITORY || '').split('/');
165
- const { config: cfg, root } = loadConfig();
166
- const owner = envOwner || cfg?.owner;
167
- const repo = envRepo || cfg?.repo;
164
+ const { owner, repo, config: cfg, root } = resolveHubContext();
168
165
 
169
166
  if (!owner || !repo) {
170
167
  throw new Error(