@spec-wave/cli 1.0.2 → 1.0.4

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 (37) hide show
  1. package/package.json +1 -1
  2. package/src/api/auth.mjs +29 -1
  3. package/src/commands/code-review.mjs +3 -1
  4. package/src/commands/decompose.mjs +1 -1
  5. package/src/commands/doctor.mjs +54 -20
  6. package/src/commands/generate-bug.mjs +1 -0
  7. package/src/commands/generate-plan.mjs +1 -0
  8. package/src/commands/generate-qa-plan.mjs +1 -0
  9. package/src/commands/generate-spec.mjs +1 -0
  10. package/src/commands/implement.mjs +31 -3
  11. package/src/commands/init.mjs +4 -1
  12. package/src/commands/merge.mjs +157 -59
  13. package/src/commands/run.mjs +16 -0
  14. package/src/commands/workspace.mjs +5 -1
  15. package/src/lib/claude.mjs +14 -0
  16. package/src/lib/pr-ready.mjs +43 -21
  17. package/src/lib/workspace.mjs +64 -0
  18. package/src/plugin/.claude-plugin/plugin.json +1 -1
  19. package/src/plugin/skills/bug/model-prompt.md +2 -0
  20. package/src/plugin/skills/decompose/model-prompt.feature.md +2 -0
  21. package/src/plugin/skills/decompose/model-prompt.rfc.md +2 -0
  22. package/src/plugin/skills/merge/SKILL.md +1 -0
  23. package/src/plugin/skills/plan/model-prompt.md +2 -0
  24. package/src/plugin/skills/qa/model-prompt.md +2 -0
  25. package/src/plugin/skills/setup/SKILL.md +9 -0
  26. package/src/plugin/skills/spec/model-prompt.md +2 -0
  27. package/src/templates/skill/SKILL.md +9 -0
  28. package/src/templates/workflows/code/code-review.yml +25 -7
  29. package/src/templates/workflows/code/qa.yml +24 -6
  30. package/src/templates/workflows/code-review.yml +16 -1
  31. package/src/templates/workflows/decompose.yml +30 -2
  32. package/src/templates/workflows/generate-bug.yml +27 -1
  33. package/src/templates/workflows/generate-plan.yml +27 -1
  34. package/src/templates/workflows/generate-qa-plan.yml +28 -2
  35. package/src/templates/workflows/generate-spec.yml +27 -1
  36. package/src/templates/workflows/pr-events.yml +35 -8
  37. package/src/templates/workflows/qa.yml +15 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spec-wave/cli",
3
- "version": "1.0.2",
3
+ "version": "1.0.4",
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/api/auth.mjs CHANGED
@@ -225,9 +225,37 @@ export function describeTokenSource(cwd = process.cwd()) {
225
225
  return 'gh auth token (conta ativa)';
226
226
  }
227
227
 
228
+ /**
229
+ * Token de INSTALAÇÃO de GitHub App (`ghs_…`): não tem `GET /user` nem
230
+ * `x-oauth-scopes` — as permissões vêm da App, não de escopos. É o token que
231
+ * o init server-side da UI e o step `actions/create-github-app-token` usam.
232
+ */
233
+ export function isInstallationToken(token) {
234
+ return /^ghs_/.test(String(token || ''));
235
+ }
236
+
228
237
  export async function verifyTokenScopes(token) {
229
238
  const { Octokit } = await import('@octokit/rest');
230
239
  const octokit = new Octokit({ auth: token });
240
+ if (isInstallationToken(token)) {
241
+ // Verificação FUNCIONAL: a única chamada que um token de instalação
242
+ // sempre responde. Escopos não existem aqui — o que a App pode fazer foi
243
+ // decidido nas permissões dela (Issues, Contents, Pull requests, Projects);
244
+ // uma permissão faltando aparece na primeira chamada que precisar dela.
245
+ try {
246
+ const res = await octokit.request('GET /installation/repositories', { per_page: 1 });
247
+ const total = res.data?.total_count ?? 0;
248
+ return {
249
+ login: 'GitHub App (token de instalação)',
250
+ kind: 'app',
251
+ hasProject: true, hasRepo: true, hasWorkflow: true,
252
+ scopes: [],
253
+ installationRepos: total,
254
+ };
255
+ } catch (err) {
256
+ throw new Error(`Token de instalação inválido ou expirado: ${err.message}`);
257
+ }
258
+ }
231
259
  try {
232
260
  const response = await octokit.request('GET /user');
233
261
  const scopes = response.headers['x-oauth-scopes'] || '';
@@ -237,7 +265,7 @@ export async function verifyTokenScopes(token) {
237
265
  const hasRepo = scopeList.includes('repo') || scopeList.includes('public_repo');
238
266
  // `workflow` is required to create/update files under .github/workflows/
239
267
  const hasWorkflow = scopeList.includes('workflow');
240
- return { login: response.data.login, hasProject, hasRepo, hasWorkflow, scopes: scopeList };
268
+ return { login: response.data.login, kind: 'user', hasProject, hasRepo, hasWorkflow, scopes: scopeList };
241
269
  } catch (err) {
242
270
  throw new Error(`Token verification failed: ${err.message}`);
243
271
  }
@@ -8,6 +8,7 @@ import { detectIssueType } from '../lib/issue-type.mjs';
8
8
  import { loadProjectConfig, resolveField, advanceToStage } from '../lib/board.mjs';
9
9
  import { resolveHubContext, resolvePrRepo } from '../lib/project-root.mjs';
10
10
  import { markFeaturePrsReady } from '../lib/pr-ready.mjs';
11
+ import { codeReposForItems } from '../lib/workspace.mjs';
11
12
  import { extractIssueRefs, hubIssueNumbers, resolveLinkMode, sameRepo } from '../lib/pr-link.mjs';
12
13
  import {
13
14
  STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType,
@@ -379,6 +380,7 @@ export async function codeReview({ prNumber, prRepo: prRepoOpt, resolveOnly = fa
379
380
  // impossível de mergear no GitHub. Best-effort, como o resto.
380
381
  const marcados = await markFeaturePrsReady({
381
382
  token, owner, repo, feature, stories: featureStories, linkMode,
383
+ codeRepos: codeReposForItems(cfg, { labels: feature.labels || [], children: featureStories }).repos,
382
384
  // `updated` vira a lista "Board atualizado" no comentário do PR;
383
385
  // desrascunhar não é movimento de board e ganha parágrafo próprio.
384
386
  log: { info: console.log, success: console.log, warn: console.warn },
@@ -407,7 +409,7 @@ export async function codeReview({ prNumber, prRepo: prRepoOpt, resolveOnly = fa
407
409
  if (prontos.length > 0) {
408
410
  partes.push(
409
411
  `✅ **Feature concluída — PRs prontos para revisão:** ` +
410
- `${[...new Set(prontos)].sort((a, b) => a - b).map(n => `#${n}`).join(', ')}.\n\n` +
412
+ `${[...new Set(prontos)].sort().join(', ')}.\n\n` +
411
413
  'Todas as Stories terminaram, então os PRs saíram do rascunho juntos. ' +
412
414
  'Enquanto uma feature está em desenvolvimento, os PRs dela ficam em rascunho de propósito.'
413
415
  );
@@ -385,7 +385,7 @@ async function draftDecomposition(ctx) {
385
385
  const generated = parseModelJson(await generateDocument(
386
386
  systemPromptWithTools(decomposePrompt),
387
387
  userContent,
388
- { action: 'decompose', labels, usage, maxTurns: decomposePrompt.maxTurns }
388
+ { action: 'decompose', labels, usage, maxTurns: decomposePrompt.maxTurns, issueNumber, cwd: root }
389
389
  ));
390
390
 
391
391
  markdown = renderDecompositionDoc({
@@ -129,6 +129,25 @@ async function checkRateLimit(ctx) {
129
129
  };
130
130
  }
131
131
 
132
+ /**
133
+ * Nomes dos secrets do Actions visíveis ao repo: os do repositório e os da
134
+ * organização compartilhados com ele (é onde a GitHub App da org costuma
135
+ * viver). Só NOMES — a API nunca expõe valores. Lança se nem os do repo forem
136
+ * legíveis; os de org são best-effort (a listagem exige permissão a mais).
137
+ */
138
+ async function listActionsSecretNames(token, owner, repo) {
139
+ const octokit = makeOctokit(token);
140
+ const res = await octokit.request('GET /repos/{owner}/{repo}/actions/secrets', { owner, repo });
141
+ const names = (res.data.secrets || []).map((s) => s.name);
142
+ try {
143
+ const org = await octokit.request('GET /repos/{owner}/{repo}/actions/organization-secrets', { owner, repo });
144
+ for (const s of org.data.secrets || []) if (!names.includes(s.name)) names.push(s.name);
145
+ } catch {
146
+ // repo de usuário ou sem permissão para ver os da org — fica só com os do repo
147
+ }
148
+ return names;
149
+ }
150
+
132
151
  async function checkScopes(ctx) {
133
152
  const name = 'Escopos do token';
134
153
  if (!ctx.token) {
@@ -185,18 +204,21 @@ async function checkScopes(ctx) {
185
204
  // acesso ao project não confirmado — segue sem ele
186
205
  }
187
206
  }
207
+ // Token de instalação de GitHub App (`ghs_`) cai aqui também: as permissões
208
+ // são da App, não escopos — o que dá para afirmar é o acesso funcional.
209
+ const tipo = info.kind === 'app' ? 'token de instalação de GitHub App' : 'fine-grained PAT?';
188
210
  if (functional.length > 0) {
189
211
  return {
190
212
  name,
191
213
  status: 'ok',
192
- detail: `Escopos não legíveis (fine-grained PAT?), mas acesso confirmado: ${functional.join(' e ')}.`,
214
+ detail: `Escopos não legíveis (${tipo}), mas acesso confirmado: ${functional.join(' e ')}.`,
193
215
  };
194
216
  }
195
217
  return {
196
218
  name,
197
219
  status: 'warn',
198
220
  detail:
199
- 'Escopos não legíveis (fine-grained PAT?) e sem acesso confirmável a repo/project ' +
221
+ `Escopos não legíveis (${tipo}) e sem acesso confirmável a repo/project ` +
200
222
  `(${CONFIG_FILE} ausente ou acesso negado). Confirme as permissões do token manualmente.`,
201
223
  };
202
224
  }
@@ -825,12 +847,21 @@ async function checkAi(ctx) {
825
847
  // Se o token permitir, confere os secrets do Actions no repo.
826
848
  if (ctx.token && cfg?.owner && cfg?.repo) {
827
849
  try {
828
- const res = await makeOctokit(ctx.token).request('GET /repos/{owner}/{repo}/actions/secrets', {
829
- owner: cfg.owner,
830
- repo: cfg.repo,
831
- });
832
- const secretNames = (res.data.secrets || []).map((s) => s.name);
833
- const required = [provider.secret, 'GH_PROJECT_TOKEN'];
850
+ const secretNames = await listActionsSecretNames(ctx.token, cfg.owner, cfg.repo);
851
+ // Dois modos de autenticação nos workflows: GitHub App da org
852
+ // (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY, App antes do PAT) ou os
853
+ // PATs. Com a App presente, o GH_PROJECT_TOKEN vira fallback opcional.
854
+ const appPresent = secretNames.includes('SPEC_WAVE_APP_PRIVATE_KEY') && secretNames.includes('SPEC_WAVE_APP_ID');
855
+ const appPartial = !appPresent && (secretNames.includes('SPEC_WAVE_APP_PRIVATE_KEY') || secretNames.includes('SPEC_WAVE_APP_ID'));
856
+ if (appPartial) {
857
+ status = 'warn';
858
+ notes.push('GitHub App configurada pela metade: SPEC_WAVE_APP_ID e SPEC_WAVE_APP_PRIVATE_KEY precisam existir juntos — os workflows vão cair no PAT.');
859
+ }
860
+ ctx.appSecretsPresent = appPresent;
861
+ notes.push(appPresent
862
+ ? 'Autenticação dos workflows: GitHub App da organização (SPEC_WAVE_APP_*); os PATs, se existirem, são fallback.'
863
+ : 'Autenticação dos workflows: PATs (GH_PROJECT_TOKEN, GH_PR_TOKEN). Uma GitHub App da org (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY) os substitui sem depender de uma pessoa.');
864
+ const required = appPresent ? [provider.secret] : [provider.secret, 'GH_PROJECT_TOKEN'];
834
865
  const missing = required.filter((s) => !secretNames.includes(s));
835
866
  if (missing.length > 0) {
836
867
  status = 'warn';
@@ -1404,15 +1435,16 @@ export function inspectPrPublishing({
1404
1435
  notes.push(
1405
1436
  'O GitHub Actions está proibido de criar Pull Requests neste repositório. ' +
1406
1437
  'Ligue Settings → Actions → General → "Allow GitHub Actions to create and approve ' +
1407
- `pull requests", ou defina o secret \`${prTokenSecret}\` com um PAT.`
1438
+ `pull requests", configure a GitHub App da org (SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY) ` +
1439
+ `ou defina o secret \`${prTokenSecret}\` com um PAT.`
1408
1440
  );
1409
1441
  } else if (canCreatePr === false) {
1410
- // Mitigado: o PR é aberto com o PAT, não com o GITHUB_TOKEN. Continuar
1411
- // pedindo a configuração que a pessoa ACABOU de fazer é o jeito mais rápido
1412
- // de ensinar que o doctor pode ser ignorado.
1442
+ // Mitigado: o PR é aberto com a App ou o PAT, não com o GITHUB_TOKEN.
1443
+ // Continuar pedindo a configuração que a pessoa ACABOU de fazer é o jeito
1444
+ // mais rápido de ensinar que o doctor pode ser ignorado.
1413
1445
  notes.push(
1414
- `O Actions não pode abrir PR com o GITHUB_TOKEN, mas \`${prTokenSecret}\` está ` +
1415
- 'definido e é ele que será usado — só o NOME é verificável daqui, não o valor ' +
1446
+ `O Actions não pode abrir PR com o GITHUB_TOKEN, mas a GitHub App ou \`${prTokenSecret}\` está ` +
1447
+ 'definido e é esse token que será usado — só o NOME é verificável daqui, não o valor ' +
1416
1448
  'nem as permissões.'
1417
1449
  );
1418
1450
  } else if (canCreatePr === null) {
@@ -1428,12 +1460,12 @@ export function inspectPrPublishing({
1428
1460
  `A branch default exige status check(s) obrigatório(s): ${requiredChecks.join(', ')}. ` +
1429
1461
  'Pull Request aberto pelo GITHUB_TOKEN NÃO dispara workflow, então esses checks ' +
1430
1462
  'nunca ficam verdes e nenhum PR de documento se torna mergeável — o fluxo trava no ' +
1431
- `primeiro passo. Use um PAT no secret \`${prTokenSecret}\` (PR aberto por PAT dispara ` +
1432
- 'os workflows), ou dispense os checks para as branches `spec-wave/*`.'
1463
+ `primeiro passo. Configure a GitHub App da org (SPEC_WAVE_APP_*) ou um PAT no secret \`${prTokenSecret}\` ` +
1464
+ '(PR aberto por App ou PAT dispara os workflows), ou dispense os checks para as branches `spec-wave/*`.'
1433
1465
  );
1434
1466
  } else if (requiredChecks?.length) {
1435
1467
  notes.push(
1436
- `A branch default exige ${requiredChecks.join(', ')}; como o PR é aberto por ` +
1468
+ `A branch default exige ${requiredChecks.join(', ')}; como o PR é aberto pela GitHub App ou por ` +
1437
1469
  `\`${prTokenSecret}\`, os workflows disparam e os checks podem ficar verdes.`
1438
1470
  );
1439
1471
  }
@@ -1498,9 +1530,11 @@ export async function readPrPublishingContext({ token, owner, repo, root }) {
1498
1530
  if (token && owner && repo) {
1499
1531
  const octokit = makeOctokit(token);
1500
1532
  try {
1501
- const res = await octokit.request('GET /repos/{owner}/{repo}/actions/secrets',
1502
- { owner, repo });
1503
- prTokenPresent = (res.data.secrets || []).some(sec => sec.name === 'GH_PR_TOKEN');
1533
+ // A GitHub App da org também abre PR que dispara workflows — com ela
1534
+ // presente, o GH_PR_TOKEN deixa de ser necessário.
1535
+ const names = await listActionsSecretNames(token, owner, repo);
1536
+ prTokenPresent = names.includes('GH_PR_TOKEN') ||
1537
+ (names.includes('SPEC_WAVE_APP_PRIVATE_KEY') && names.includes('SPEC_WAVE_APP_ID'));
1504
1538
  } catch {
1505
1539
  prTokenPresent = null; // sem permissão de ler secrets — não afirmar ausência
1506
1540
  }
@@ -101,6 +101,7 @@ export async function generateBug({ issueNumber }) {
101
101
  const systemPrompt = systemPromptWithTools(bugPrompt);
102
102
  const { content: bruto } = await generateDocument(systemPrompt, userContent, {
103
103
  action: 'bug',
104
+ issueNumber, cwd: root,
104
105
  maxTurns: bugPrompt.maxTurns,
105
106
  labels: issueLabels,
106
107
  lint: { lang: TARGET_LANGUAGE },
@@ -216,6 +216,7 @@ export async function generatePlan({ issueNumber }) {
216
216
  const systemPrompt = systemPromptWithTools(planPrompt);
217
217
  const { content: bruto, lintFindings } = await generateDocument(systemPrompt, userContent, {
218
218
  action: 'plan',
219
+ issueNumber, cwd: root,
219
220
  maxTurns: planPrompt.maxTurns,
220
221
  labels: issueLabels,
221
222
  lint: { lang: TARGET_LANGUAGE },
@@ -249,6 +249,7 @@ async function runDraftOrCritique(ctx) {
249
249
  userContent,
250
250
  {
251
251
  action: 'qa', maxTurns: qaPrompt.maxTurns, labels, usage,
252
+ issueNumber, cwd: root,
252
253
  lint: { lang: TARGET_LANGUAGE }, withReport: true,
253
254
  }
254
255
  );
@@ -82,6 +82,7 @@ export async function generateSpec({ issueNumber }) {
82
82
  const systemPrompt = systemPromptWithTools(specPrompt);
83
83
  const { content: bruto, lintFindings } = await generateDocument(systemPrompt, userContent, {
84
84
  action: 'spec',
85
+ issueNumber, cwd: root,
85
86
  maxTurns: specPrompt.maxTurns,
86
87
  labels: issueLabels,
87
88
  lint: { lang: TARGET_LANGUAGE },
@@ -31,7 +31,10 @@ import { renderTrailers, missingTrailers, readLocalCommitMessages } from '../lib
31
31
  import { currentGitBranch } from '../lib/repo-links.mjs';
32
32
 
33
33
  // Diretório onde montamos o arquivo de contexto entregue ao spec-kit.
34
- import { slugsForItem, resolveWorkspaceLayout, readWorkspaceOverride, renderRepoDirs } from '../lib/workspace.mjs';
34
+ import {
35
+ slugsForItem, resolveWorkspaceLayout, readWorkspaceOverride, renderRepoDirs, codeReposForItems,
36
+ } from '../lib/workspace.mjs';
37
+ import { repoSlugsFromLabels } from '../lib/repo-role.mjs';
35
38
 
36
39
  const WORK_DIR = '.spec-wave';
37
40
 
@@ -499,6 +502,20 @@ export function buildFeatureContext({
499
502
  'reaponta as bases, move o board até 🧪 QA e só apaga as branches no fim. ' +
500
503
  '**NUNCA** mergeie um PR da pilha com `--delete-branch` à mão — apagar a branch antes de reapontar o dependente fecha o PR seguinte.'
501
504
  );
505
+ // Multi-repo (RFC-005 §6.2): a pilha é por repositório. Story 1 em `api` e
506
+ // Story 2 em `web` não formam pilha — são duas raízes; e uma Story que toca
507
+ // dois repos abre dois PRs, ambos fechando a mesma issue do hub.
508
+ if (stories.some(s => repoSlugsFromLabels(s.labels).length > 0)) {
509
+ lines.push('');
510
+ lines.push(
511
+ '**Esta Feature toca mais de um repositório** (linha `Repos:` de cada Story). A pilha é **por repositório**: ' +
512
+ 'o PR de uma Story no repositório X é baseado no PR da Story anterior **no mesmo repositório X** ' +
513
+ '(`gh pr create --draft --base <branch-do-PR-anterior-em-X>`), ou na branch default de X quando nenhuma Story anterior o tocou. ' +
514
+ 'Uma Story que declara N repos abre **N PRs** (um por repo), **cada um** com ' +
515
+ `\`Closes ${closesRef(hub, '<story>')}\` no corpo — a forma qualificada é a única que o hub reconhece fora dele. ` +
516
+ 'Abra cada PR no diretório do repositório certo (`{repoDirs}` do comando; `spec-wave workspace prepare --issue <story>` monta o workspace).'
517
+ );
518
+ }
502
519
  }
503
520
  lines.push('');
504
521
  lines.push(boardRuleBlockquote());
@@ -524,6 +541,11 @@ export function buildFeatureContext({
524
541
  lines.push('');
525
542
  lines.push(depLine);
526
543
  }
544
+ const repos = repoSlugsFromLabels(s.labels);
545
+ if (repos.length > 0) {
546
+ lines.push('');
547
+ lines.push(`**Repos:** ${repos.join(', ')} — um PR em cada, empilhado na pilha desse repositório.`);
548
+ }
527
549
  if (s.body && s.body.trim()) {
528
550
  lines.push('');
529
551
  lines.push(s.body.trim());
@@ -705,7 +727,11 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
705
727
 
706
728
  const enriched = stories.map(s => ({
707
729
  number: s.number, title: s.title, nodeId: s.nodeId, body: s.body || '', dependsOn: s.dependsOn,
730
+ labels: s.labels || [],
708
731
  }));
732
+ // Repos de código da Feature (RFC-005): onde os PRs das Stories vivem além
733
+ // do hub — o desrascunho precisa olhar neles também.
734
+ const codeRepos = codeReposForItems(config, { labels: feature.labels || [], children: enriched }).repos;
709
735
 
710
736
  // F3. Etapa de cada Story no board (best-effort — sem board, nada é pulado).
711
737
  const stageOf = await fetchStagesOf(token, enriched, { warnOnSkip: true });
@@ -741,7 +767,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
741
767
  // Mesmo destravamento do lado dos PRs: a Feature está pronta para review,
742
768
  // então nenhum PR dela tem motivo para continuar em rascunho.
743
769
  await markFeaturePrsReady({
744
- token, owner, repo, dryRun,
770
+ token, owner, repo, dryRun, codeRepos,
745
771
  feature: { nodeId: feature.node_id, number: feature.number },
746
772
  stories: enriched,
747
773
  linkMode: resolveLinkMode(config),
@@ -898,7 +924,7 @@ async function implementFeature({ token, owner, repo, config, feature, featureDi
898
924
  // dizer "ainda estou trabalhando" — agora todos saem juntos, e a feature
899
925
  // inteira fica revisável no mesmo instante.
900
926
  await markFeaturePrsReady({
901
- token, owner, repo,
927
+ token, owner, repo, codeRepos,
902
928
  feature: { nodeId: feature.node_id, number: feature.number },
903
929
  stories: enriched,
904
930
  linkMode: resolveLinkMode(config),
@@ -1158,6 +1184,8 @@ export async function implement({
1158
1184
  // rascunho de uma vez e a review pode começar pela pilha inteira.
1159
1185
  await markFeaturePrsReady({
1160
1186
  token, owner, repo, dryRun,
1187
+ // União dos repos de todas as Stories: os PRs da Feature vivem neles.
1188
+ codeRepos: codeReposForItems(config, { children: [...siblingStories, { labels: issue.labels }] }).repos,
1161
1189
  feature: { nodeId: feature.nodeId, number: feature.number },
1162
1190
  stories: [...siblingStories, { number: issue.number, nodeId: issue.node_id }],
1163
1191
  linkMode: resolveLinkMode(config),
@@ -312,7 +312,7 @@ export async function init(options) {
312
312
  `\n${chalk.green('✓')} ${owner}/${repo} configurado como repositório de código do hub ${hub.owner}/${hub.repo}.\n\n` +
313
313
  ` Próximos passos:\n` +
314
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` +
315
+ ` ${configWritten ? '2' : '1'}. Autenticação do despacho para o hub: a GitHub App da org (secrets SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY, App instalada nos dois repos) ou o secret ${HUB_DISPATCH_SECRET} com um token de escrita em Contents no hub\n` +
316
316
  ` ${configWritten ? '3' : '2'}. No hub, rode \`npx @spec-wave/cli@latest update\` para instalar o pr-events.yml (recebe os despachos)\n` +
317
317
  ` ${configWritten ? '4' : '3'}. Registre este repo no hub: \`repositories: [{ "slug": "<slug>", "owner": "${owner}", "repo": "${repo}" }]\` no ${CONFIG_FILE} do hub\n` +
318
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` +
@@ -338,6 +338,9 @@ export async function init(options) {
338
338
  ? ` 1. Commite o ${CONFIG_FILE} quando quiser (git add ${CONFIG_FILE} && git commit)\n`
339
339
  : '') +
340
340
  ` ${configWritten ? '2' : '1'}. Adicione ${providerMeta.secret} como secret no repositório (provider: ${providerMeta.label})\n` +
341
+ // Dois modos de autenticação dos workflows: a App da org não depende de
342
+ // uma pessoa; os PATs continuam valendo como fallback.
343
+ ` ${chalk.dim('Autenticação dos workflows: GitHub App da org (secrets SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY) ou os PATs GH_PROJECT_TOKEN/GH_PR_TOKEN')}\n` +
341
344
  // O valor do token da assinatura não é copiável de lugar nenhum: só existe
342
345
  // depois de rodar o comando que o gera.
343
346
  (providerMeta.secret === 'CLAUDE_CODE_OAUTH_TOKEN'