@spec-wave/cli 0.34.2 → 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 (52) hide show
  1. package/package.json +2 -2
  2. package/protocol/qa-result.v1.json +9 -0
  3. package/src/agent/anthropic-agent.mjs +35 -2
  4. package/src/api/github-graphql.mjs +60 -2
  5. package/src/api/github-rest.mjs +23 -0
  6. package/src/cli.mjs +23 -0
  7. package/src/commands/code-review.mjs +71 -60
  8. package/src/commands/decompose.mjs +75 -4
  9. package/src/commands/doctor.mjs +105 -4
  10. package/src/commands/implement.mjs +82 -10
  11. package/src/commands/init.mjs +147 -29
  12. package/src/commands/merge.mjs +56 -4
  13. package/src/commands/move.mjs +4 -7
  14. package/src/commands/order.mjs +2 -2
  15. package/src/commands/qa-run.mjs +140 -19
  16. package/src/commands/qa.mjs +22 -21
  17. package/src/commands/repair-stage.mjs +2 -5
  18. package/src/commands/story.mjs +2 -2
  19. package/src/commands/task.mjs +2 -2
  20. package/src/commands/triage.mjs +2 -5
  21. package/src/commands/update.mjs +31 -8
  22. package/src/commands/validate.mjs +2 -5
  23. package/src/commands/workspace.mjs +112 -0
  24. package/src/config.mjs +19 -0
  25. package/src/lib/artifact-pr.mjs +1 -1
  26. package/src/lib/bug-doc.mjs +6 -1
  27. package/src/lib/claude.mjs +4 -0
  28. package/src/lib/decomposition-doc.mjs +56 -3
  29. package/src/lib/dependency-map.mjs +3 -0
  30. package/src/lib/doc-paths.mjs +6 -1
  31. package/src/lib/flow-run.mjs +14 -3
  32. package/src/lib/pr-link.mjs +109 -0
  33. package/src/lib/pr-ready.mjs +146 -0
  34. package/src/lib/project-root.mjs +51 -0
  35. package/src/lib/qa-exec.mjs +73 -0
  36. package/src/lib/qa-report.mjs +172 -8
  37. package/src/lib/repo-role.mjs +102 -0
  38. package/src/lib/workspace.mjs +151 -0
  39. package/src/plugin/.claude-plugin/plugin.json +1 -1
  40. package/src/plugin/skills/decompose/SKILL.md +1 -0
  41. package/src/plugin/skills/decompose/model-prompt.feature.md +4 -2
  42. package/src/plugin/skills/implement/SKILL.md +2 -2
  43. package/src/plugin/skills/merge/SKILL.md +3 -2
  44. package/src/plugin/skills/qa/SKILL.md +6 -1
  45. package/src/plugin/skills/qa-executor/SKILL.md +43 -1
  46. package/src/plugin/skills/setup/SKILL.md +12 -0
  47. package/src/setup/files.mjs +35 -13
  48. package/src/templates/skill/SKILL.md +27 -5
  49. package/src/templates/skill/core.md +5 -1
  50. package/src/templates/workflows/code/code-review.yml +60 -0
  51. package/src/templates/workflows/code/qa.yml +59 -0
  52. package/src/templates/workflows/pr-events.yml +116 -0
@@ -15,9 +15,10 @@ import {
15
15
  tokenMismatchWarning, parseActiveAccount,
16
16
  } from '../api/auth.mjs';
17
17
  import { getProjectSnapshot, listProjectItems, getRateLimit } from '../api/github-graphql.mjs';
18
- import { getRepoVariable } from '../api/github-rest.mjs';
18
+ import { getRepoVariable, getOwnerType } from '../api/github-rest.mjs';
19
+ import { configuredRole } from '../lib/repo-role.mjs';
19
20
  import {
20
- CONFIG_FILE, WORKFLOW_FILES, ARTIFACT_WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER,
21
+ CONFIG_FILE, WORKFLOW_FILES, CODE_WORKFLOW_FILES, ARTIFACT_WORKFLOW_FILES, getProvider, DEFAULT_PROVIDER,
21
22
  AI_PROVIDERS, STATUS_OPTIONS,
22
23
  RETIRED_STAGES, ALL_LABELS, allLabelsFor, LABEL_NEEDS_HUMAN, LABEL_QA_READY, MODEL_LABEL_PREFIX,
23
24
  DEV_AGENT_QUEUE_PREFIX,
@@ -29,6 +30,7 @@ import { cachedSubIssues } from '../lib/story-graph.mjs';
29
30
  import { affordCheck } from '../lib/rate-budget.mjs';
30
31
  import { resolveCacheTtl } from '../lib/net-cache.mjs';
31
32
  import { QA_PLAN_FILE } from '../lib/qa-plan-doc.mjs';
33
+ import { resolveQaEvidenceConfig } from '../lib/qa-exec.mjs';
32
34
  import { findConfigPath } from '../lib/project-root.mjs';
33
35
  import { configuredMode, describeModeState, EXECUTION_VARIABLE } from '../lib/execution-mode.mjs';
34
36
  import { unguardedWorkflows } from './mode.mjs';
@@ -247,6 +249,33 @@ async function checkGhAccount(ctx) {
247
249
  };
248
250
  }
249
251
 
252
+ async function checkOwnerType(ctx) {
253
+ const name = 'Owner é organização';
254
+ const owner = ctx.cfg?.owner;
255
+ if (!owner) {
256
+ return { name, status: 'ok', detail: `Sem owner no ${CONFIG_FILE} para verificar.` };
257
+ }
258
+ if (!ctx.token) {
259
+ return { name, status: 'warn', detail: 'Sem token resolvido — verificação pulada.' };
260
+ }
261
+ try {
262
+ const type = await getOwnerType(ctx.token, owner);
263
+ if (type === 'Organization') {
264
+ return { name, status: 'ok', detail: `${owner} é uma organização.` };
265
+ }
266
+ return {
267
+ name,
268
+ status: 'fail',
269
+ detail:
270
+ `${owner} é uma conta pessoal do GitHub, não uma organização. ` +
271
+ 'O GitHub App do spec-wave só acessa Projects v2 de organizações — transfira o ' +
272
+ `repositório e o Project para uma organização e rode \`init\` novamente apontando para ela.`,
273
+ };
274
+ } catch (err) {
275
+ return { name, status: 'warn', detail: `Não foi possível verificar o tipo de conta de ${owner}: ${err.message}` };
276
+ }
277
+ }
278
+
250
279
  async function checkConfig(ctx) {
251
280
  const name = `Configuração (${CONFIG_FILE})`;
252
281
  if (!ctx.configPath) {
@@ -1117,12 +1146,64 @@ export function inspectQaLead({ lead = null, dockerOk = null, schemasOk = true }
1117
1146
  return { warn, notes };
1118
1147
  }
1119
1148
 
1149
+ /**
1150
+ * Checks da evidência visual do QA (função PURA — testável sem PATH).
1151
+ *
1152
+ * `qa.platform` ausente é `web` (compatibilidade); a ferramenta configurada
1153
+ * mas fora do PATH é AVISO, não erro — o `qa` roda igual e só deixa de gravar
1154
+ * vídeo/foto (o executor omite `evidenceFiles`). Quando a evidência existe só
1155
+ * por default (nada declarado), ferramenta ausente é NOTA, não aviso: um
1156
+ * repositório que nunca configurou isso não pode passar a ver um `!` no doctor.
1157
+ *
1158
+ * @param {object} params
1159
+ * @param {{platform:string, tool:string|null, appId?:string|null, explicit?:boolean}} params.evidence saída de resolveQaEvidenceConfig()
1160
+ * @param {(tool: string) => boolean|null} [params.hasTool] a ferramenta está no PATH? (null = não verificável)
1161
+ * @returns {{ warn: boolean, notes: string[] }}
1162
+ */
1163
+ export function inspectQaEvidence({ evidence, hasTool = () => null } = {}) {
1164
+ const notes = [];
1165
+ let warn = false;
1166
+ const platform = evidence?.platform || 'web';
1167
+ const tool = evidence?.tool || null;
1168
+ if (!tool) {
1169
+ notes.push(`Evidência visual: plataforma ${platform}, gravação desligada (qa.${platform}.evidence = none).`);
1170
+ return { warn, notes };
1171
+ }
1172
+ if (platform === 'mobile' && !evidence?.appId) {
1173
+ warn = true;
1174
+ notes.push('Evidência visual: `qa.mobile.appId` ausente — o executor precisa dele para abrir o app no Maestro.');
1175
+ }
1176
+ const found = hasTool(tool);
1177
+ if (found === false) {
1178
+ if (evidence?.explicit) warn = true;
1179
+ notes.push(
1180
+ `Evidência visual: plataforma ${platform}, ferramenta ${tool}${evidence?.explicit ? '' : ' (padrão)'} ` +
1181
+ `NÃO encontrada no PATH — o \`qa\` executa igual, só sem vídeo/foto. Instale-a ou desligue com ` +
1182
+ `"qa": { "${platform}": { "evidence": "none" } }.`
1183
+ );
1184
+ } else {
1185
+ notes.push(`Evidência visual: plataforma ${platform}, ferramenta ${tool}${found ? ' (no PATH)' : ''} — publica em docs/…/qa/cenario-<n>/ (teto 4 MB por arquivo).`);
1186
+ }
1187
+ return { warn, notes };
1188
+ }
1189
+
1190
+ // A ferramenta de gravação está no PATH (ou no node_modules do projeto)?
1191
+ function evidenceToolOnPath(root, tool) {
1192
+ try {
1193
+ if (tool === 'playwright' && root && existsSync(path.join(root, 'node_modules', '.bin', 'playwright'))) return true;
1194
+ execSync(`command -v ${tool}`, { stdio: ['ignore', 'pipe', 'pipe'], shell: '/bin/sh' });
1195
+ return true;
1196
+ } catch {
1197
+ return false;
1198
+ }
1199
+ }
1200
+
1120
1201
  // QA (rfc/spec-qa-skill.md + rfc/spec-qa-lead.md): executor configurado,
1121
1202
  // Features em 🧪 QA com plano, e a configuração do orquestrador de trilha.
1122
1203
  // As labels novas e o workflow generate-qa-plan.yml são cobertos pelos checks
1123
1204
  // existentes (higiene de labels e workflows), que leem as listas do config.mjs.
1124
1205
  async function checkQa(ctx) {
1125
- const name = 'QA (qa.command, planos das Features em 🧪 QA e qa-lead)';
1206
+ const name = 'QA (qa.command, evidência visual, planos das Features em 🧪 QA e qa-lead)';
1126
1207
  const notes = [];
1127
1208
  let status = 'ok';
1128
1209
 
@@ -1147,6 +1228,14 @@ async function checkQa(ctx) {
1147
1228
  );
1148
1229
  }
1149
1230
 
1231
+ // Evidência visual (vídeo/foto por cenário): plataforma + ferramenta no PATH.
1232
+ const evidenceCheck = inspectQaEvidence({
1233
+ evidence: resolveQaEvidenceConfig(ctx.cfg?.qa),
1234
+ hasTool: tool => evidenceToolOnPath(ctx.root, tool),
1235
+ });
1236
+ if (evidenceCheck.warn) status = 'warn';
1237
+ notes.push(...evidenceCheck.notes);
1238
+
1150
1239
  if (ctx.token && ctx.cfg?.project?.id && ctx.root) {
1151
1240
  try {
1152
1241
  const items = await listProjectItems(ctx.token, ctx.cfg.project.id);
@@ -1462,7 +1551,11 @@ async function checkWorkflows(ctx) {
1462
1551
  };
1463
1552
  }
1464
1553
  const present = readdirSync(dir);
1465
- const missing = WORKFLOW_FILES.filter((f) => !present.includes(f));
1554
+ // Repo de código (RFC-005): só os despachantes, que não chamam a CLI — as
1555
+ // checagens de versão fixada e de secret de IA abaixo são do hub.
1556
+ const role = configuredRole(ctx.cfg);
1557
+ const expected = role === 'code' ? CODE_WORKFLOW_FILES : WORKFLOW_FILES;
1558
+ const missing = expected.filter((f) => !present.includes(f));
1466
1559
  if (missing.length > 0) {
1467
1560
  return {
1468
1561
  name,
@@ -1470,6 +1563,13 @@ async function checkWorkflows(ctx) {
1470
1563
  detail: `Workflows faltando em .github/workflows/: ${missing.join(', ')} — rode \`npx @spec-wave/cli@latest update\`.`,
1471
1564
  };
1472
1565
  }
1566
+ if (role === 'code') {
1567
+ return {
1568
+ name,
1569
+ status: 'ok',
1570
+ detail: `Despachantes presentes (${CODE_WORKFLOW_FILES.join(', ')}); o fluxo roda no hub ${ctx.cfg?.hub?.owner ?? '?'}/${ctx.cfg?.hub?.repo ?? '?'}.`,
1571
+ };
1572
+ }
1473
1573
 
1474
1574
  // Versão da CLI fixada nos workflows: um `@latest` deixa uma release mudar o
1475
1575
  // comportamento de pipelines já em andamento.
@@ -1544,6 +1644,7 @@ export async function doctor(options = {}) {
1544
1644
  checkRateLimit,
1545
1645
  checkScopes,
1546
1646
  checkGhAccount,
1647
+ checkOwnerType,
1547
1648
  checkConfig,
1548
1649
  checkRepoAccess,
1549
1650
  checkBoardHygiene,
@@ -20,6 +20,8 @@ import { slugify } from '../lib/slugify.mjs';
20
20
  import { parseDependencies, orderStories, formatDependencyLine } from '../lib/dependencies.mjs';
21
21
  import { loadProjectConfig } from '../lib/board.mjs';
22
22
  import { planBoardMoves, applyBoardMoves } from '../lib/implement-board.mjs';
23
+ import { markFeaturePrsReady } from '../lib/pr-ready.mjs';
24
+ import { resolveLinkMode } from '../lib/pr-link.mjs';
23
25
  import { extractPathsFromPlan, buildCodeDigest } from '../lib/code-digest.mjs';
24
26
  import { findConfigPath, resolveFromRoot, loadConfig } from '../lib/project-root.mjs';
25
27
  import { loadFeatureStories, loadBoardSnapshot, cachedSubIssues } from '../lib/story-graph.mjs';
@@ -29,6 +31,8 @@ import { renderTrailers, missingTrailers, readLocalCommitMessages } from '../lib
29
31
  import { currentGitBranch } from '../lib/repo-links.mjs';
30
32
 
31
33
  // Diretório onde montamos o arquivo de contexto entregue ao spec-kit.
34
+ import { slugsForItem, resolveWorkspaceLayout, readWorkspaceOverride, renderRepoDirs } from '../lib/workspace.mjs';
35
+
32
36
  const WORK_DIR = '.spec-wave';
33
37
 
34
38
  // Caps dos comentários anexados ao contexto (por issue).
@@ -174,9 +178,17 @@ function pushDigestSpecPlan(lines, { codeDigest, spec, plan, specPath, planPath
174
178
  }
175
179
 
176
180
  // Monta o markdown de contexto que será entregue ao spec-kit implement.
181
+ // Referência de fechamento no corpo do PR. Qualificada com o hub (RFC-005
182
+ // §3.4): um PR num repo de código com `Closes #12` apontaria para a issue 12
183
+ // DESSE repo, e a forma `owner/hub#12` é a única que o hub reconhece. No
184
+ // mono-repo a forma qualificada continua válida para o GitHub.
185
+ export function closesRef(hub, number) {
186
+ return hub?.owner && hub?.repo ? `${hub.owner}/${hub.repo}#${number}` : `#${number}`;
187
+ }
188
+
177
189
  export function buildContext({
178
190
  type, issue, tasks, feature, siblingStories = [], spec, plan, specPath, planPath,
179
- comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack',
191
+ comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack', hub = null,
180
192
  }) {
181
193
  const lines = [];
182
194
  lines.push(`# Contexto de implementação — ${type} #${issue.number}`);
@@ -245,9 +257,10 @@ export function buildContext({
245
257
  // Draft de propósito: numa pilha de Stories (um PR baseado no anterior),
246
258
  // cada rebase em cascata dispararia o CI inteiro em PRs que ninguém vai
247
259
  // mergear naquele estado. Rascunho não mergeia (o GitHub bloqueia) e o
248
- // required check continua valendo: quem revisa marca o PR como pronto, o
249
- // `ready_for_review` dispara o CI, e só então o merge destrava.
250
- lines.push(` 2. Abra o **Pull Request** da Story #${issue.number} **como rascunho** (\`gh pr create --draft\`) — o CI não roda em rascunho; quem revisa marca o PR como pronto e é aí que os checks disparam.`);
260
+ // required check continua valendo. Quem tira do rascunho é o próprio
261
+ // implement, quando a ÚLTIMA Story da Feature entra em Code Review (ver
262
+ // lib/pr-ready.mjs): até lá o rascunho diz "feature em andamento".
263
+ lines.push(` 2. Abra o **Pull Request** da Story #${issue.number} **como rascunho** (\`gh pr create --draft\`), **com \`Closes ${closesRef(hub, issue.number)}\` no corpo** — é esse vínculo que localiza o PR da Story. Deixe em rascunho: o \`spec-wave implement\` marca TODOS os PRs da Feature como prontos de uma vez quando a última Story concluir, e é aí que os checks disparam. **Não marque como pronto manualmente.**`);
251
264
  }
252
265
  lines.push(
253
266
  ` 3. **Avance a Etapa da Story #${issue.number} para ${STAGE_CODE_REVIEW}** ` +
@@ -400,7 +413,7 @@ export function planFeatureImplementation(stories, {
400
413
  export function buildFeatureContext({
401
414
  feature, stories, skipped = [],
402
415
  spec, plan, specPath, planPath,
403
- comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack',
416
+ comments = [], codeDigest = null, blockedByWarnings = [], mode = 'pr-stack', hub = null,
404
417
  }) {
405
418
  const lines = [];
406
419
  lines.push(`# Contexto de implementação — Feature #${feature.number}`);
@@ -447,8 +460,9 @@ export function buildFeatureContext({
447
460
  } else {
448
461
  lines.push(
449
462
  `3. **Ao concluir TODAS as Tasks da Story:** faça o **commit** (assunto livre; rodapé com os trailers abaixo), ` +
450
- `abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\` — o CI não roda em rascunho; ` +
451
- `quem revisa marca o PR como pronto e os checks disparam) e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`
463
+ `abra o **Pull Request** da Story **como rascunho** (\`gh pr create --draft\`), **com \`Closes ${closesRef(hub, '<story>')}\` no corpo** — ` +
464
+ `é esse vínculo que o \`merge\`, o \`code-review\` e o desrascunho usam para achar o PR da Story — ` +
465
+ `e **avance a Etapa da Story para ${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}).`
452
466
  );
453
467
  }
454
468
  lines.push(' ```');
@@ -459,7 +473,13 @@ export function buildFeatureContext({
459
473
  lines.push(
460
474
  `**Feature #${feature.number}:** avance-a para a Etapa **${STAGE_CODE_REVIEW}** (Status ${PROGRESS_TODO}) ` +
461
475
  `**somente após concluir a ÚLTIMA Story da lista**${skipped.length > 0 ? ' (as Stories já implementadas listadas abaixo não precisam ser refeitas)' : ''}. ` +
462
- `Enquanto houver Story pendente, a Feature permanece em ${STAGE_DEVELOPMENT}.`
476
+ `Enquanto houver Story pendente, a Feature permanece em ${STAGE_DEVELOPMENT}.` +
477
+ // Só na pilha existem PRs de Story para deixar em rascunho; no modo agent o
478
+ // único PR é o do daemon, aberto por ele mesmo depois de tudo pronto.
479
+ (mode === 'agent' ? '' :
480
+ ' Os PRs ficam **em rascunho até o fim**: quando a última Story concluir, o próprio ' +
481
+ '`spec-wave implement` marca todos como prontos para revisão de uma vez — ' +
482
+ '**não tire nenhum PR do rascunho manualmente**, é esse rascunho que avisa que a feature ainda está em andamento.')
463
483
  );
464
484
  lines.push('');
465
485
  if (mode === 'agent') {
@@ -718,6 +738,14 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
718
738
  await applyBoardMoves({ token, dryRun, moves: planBoardMoves('success', {
719
739
  feature: { nodeId: feature.node_id, number: feature.number },
720
740
  }) });
741
+ // Mesmo destravamento do lado dos PRs: a Feature está pronta para review,
742
+ // então nenhum PR dela tem motivo para continuar em rascunho.
743
+ await markFeaturePrsReady({
744
+ token, owner, repo, dryRun,
745
+ feature: { nodeId: feature.node_id, number: feature.number },
746
+ stories: enriched,
747
+ linkMode: resolveLinkMode(config),
748
+ });
721
749
  p.outro(`Todas as ${stories.length} story(ies) da Feature #${feature.number} já estão implementadas — nada a fazer.`);
722
750
  return;
723
751
  }
@@ -822,9 +850,11 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
822
850
  codeDigest,
823
851
  blockedByWarnings,
824
852
  mode,
853
+ hub: { owner, repo },
825
854
  });
826
855
  await writeContextAndRunSpecKit({
827
856
  config,
857
+ repoSlugs: slugsForItem({ labels: feature.labels || [], children: pending }),
828
858
  issueNumber: feature.number,
829
859
  type: 'Feature',
830
860
  title: feature.title,
@@ -863,6 +893,16 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
863
893
  await applyBoardMoves({ token, moves: planBoardMoves('success', {
864
894
  feature: { nodeId: feature.node_id, number: feature.number },
865
895
  }) });
896
+ // A Feature avançou de Etapa; os PRs precisam contar a mesma história.
897
+ // Enquanto as Stories eram implementadas, cada PR nasceu em rascunho para
898
+ // dizer "ainda estou trabalhando" — agora todos saem juntos, e a feature
899
+ // inteira fica revisável no mesmo instante.
900
+ await markFeaturePrsReady({
901
+ token, owner, repo,
902
+ feature: { nodeId: feature.node_id, number: feature.number },
903
+ stories: enriched,
904
+ linkMode: resolveLinkMode(config),
905
+ });
866
906
  },
867
907
  });
868
908
  }
@@ -1069,11 +1109,13 @@ export async function implement({
1069
1109
  const context = buildContext({
1070
1110
  type, issue, tasks, feature, siblingStories, ...specPlan,
1071
1111
  comments, codeDigest, blockedByWarnings, mode,
1112
+ hub: { owner, repo },
1072
1113
  });
1073
1114
  await writeContextAndRunSpecKit({
1074
1115
  config, issueNumber, type, title: issue.title, specPlan, context, dryRun,
1075
1116
  mode, repoRoot, expectedBranch: currentBranch,
1076
1117
  verifyCommits,
1118
+ repoSlugs: slugsForItem({ labels: issue.labels, children: tasks }),
1077
1119
  expectedTrailers: {
1078
1120
  stories: type === 'Story' ? [issue.number] : [],
1079
1121
  tasks: tasks.map(t => t.number),
@@ -1109,6 +1151,17 @@ export async function implement({
1109
1151
  await applyBoardMoves({ token, dryRun, moves: planBoardMoves('success', {
1110
1152
  feature: { nodeId: feature.nodeId, number: feature.number },
1111
1153
  }) });
1154
+ // Chegou aqui = era a última Story pendente. É ESTE o momento que o
1155
+ // rascunho dos PRs estava esperando: enquanto o dev-agent ia de Story em
1156
+ // Story, cada PR aberto em rascunho sinalizava "feature em andamento, não
1157
+ // revise nem mergeie ainda". Com a feature completa, todos saem do
1158
+ // rascunho de uma vez e a review pode começar pela pilha inteira.
1159
+ await markFeaturePrsReady({
1160
+ token, owner, repo, dryRun,
1161
+ feature: { nodeId: feature.nodeId, number: feature.number },
1162
+ stories: [...siblingStories, { number: issue.number, nodeId: issue.node_id }],
1163
+ linkMode: resolveLinkMode(config),
1164
+ });
1112
1165
  },
1113
1166
  });
1114
1167
  }
@@ -1118,13 +1171,30 @@ export async function implement({
1118
1171
  async function writeContextAndRunSpecKit({
1119
1172
  config, issueNumber, type, title, specPlan, context, dryRun, outroSuccess, onSuccess,
1120
1173
  mode = 'pr-stack', repoRoot = null, expectedBranch = null,
1121
- verifyCommits = false, expectedTrailers = null,
1174
+ verifyCommits = false, expectedTrailers = null, repoSlugs = [],
1122
1175
  }) {
1123
1176
  mkdirSync(WORK_DIR, { recursive: true });
1124
1177
  const tasksFile = path.join(WORK_DIR, `implement-${issueNumber}.md`);
1125
1178
  writeFileSync(tasksFile, context);
1126
1179
  p.log.success(`Contexto montado em ${chalk.cyan(tasksFile)}.`);
1127
1180
 
1181
+ // Multi-repo (RFC-005): o mesmo layout do `workspace prepare`, sem clonar —
1182
+ // aqui só se lê; repo ausente vira aviso apontando o comando que o cria.
1183
+ const hubRoot = repoRoot || process.cwd();
1184
+ const layout = resolveWorkspaceLayout({
1185
+ root: hubRoot, config, slugs: repoSlugs, override: readWorkspaceOverride(hubRoot),
1186
+ });
1187
+ const ausentes = layout.repos.filter(r => !r.present);
1188
+ if (layout.unknown.length > 0) {
1189
+ p.log.warn(`Repositório(s) declarado(s) na issue e desconhecido(s) do hub: ${layout.unknown.join(', ')} — registre em repositories[] do ${CONFIG_FILE}.`);
1190
+ }
1191
+ if (ausentes.length > 0) {
1192
+ p.log.warn(
1193
+ `Repositório(s) ausente(s) no workspace: ${ausentes.map(r => `${r.slug} (${r.dir})`).join(', ')} — ` +
1194
+ `rode \`spec-wave workspace prepare --issue ${issueNumber}\` antes.`
1195
+ );
1196
+ }
1197
+
1128
1198
  const template = process.env.SPEC_WAVE_IMPLEMENT_CMD || config.specKit?.command;
1129
1199
  const vars = {
1130
1200
  tasksFile,
@@ -1133,6 +1203,8 @@ async function writeContextAndRunSpecKit({
1133
1203
  issue: String(issueNumber),
1134
1204
  type,
1135
1205
  title,
1206
+ workspaceDir: layout.workspaceDir,
1207
+ repoDirs: renderRepoDirs(layout.repos),
1136
1208
  };
1137
1209
 
1138
1210
  // O dry-run é decidido ANTES do early return de "spec-kit não configurado":
@@ -1156,7 +1228,7 @@ async function writeContextAndRunSpecKit({
1156
1228
  `Configure em ${CONFIG_FILE}:\n` +
1157
1229
  ` "specKit": { "command": "<comando do spec-kit com placeholders>" }\n` +
1158
1230
  'ou defina a env SPEC_WAVE_IMPLEMENT_CMD.\n\n' +
1159
- 'Placeholders: {tasksFile} {specFile} {planFile} {issue} {type} {title}',
1231
+ 'Placeholders: {tasksFile} {specFile} {planFile} {issue} {type} {title} {workspaceDir} {repoDirs}',
1160
1232
  'Como acionar o spec-kit'
1161
1233
  );
1162
1234
  p.outro(`Contexto pronto em ${tasksFile}. Acione o spec-kit manualmente com esse arquivo.`);
@@ -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' +