specdojo 0.4.4 → 0.4.6

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 (66) hide show
  1. package/.github/agents/specdojo-orchestrator.md +4 -4
  2. package/CHANGELOG.md +31 -0
  3. package/dist/commands/init.js +33 -7
  4. package/dist/devcontainer/scaffold.js +5 -1
  5. package/dist/exec/evidence.js +35 -3
  6. package/dist/exec/pipeline-state.js +1 -0
  7. package/dist/exec/plans-core.js +18 -2
  8. package/dist/exec/plans-generation.js +1 -1
  9. package/dist/exec/register-resume.js +8 -4
  10. package/dist/exec/register.js +47 -14
  11. package/dist/exec/reporter.js +8 -1
  12. package/dist/exec/results.js +1 -1
  13. package/dist/exec/run/agent-pipeline.js +7 -5
  14. package/dist/exec/run/agent.js +14 -1
  15. package/dist/exec/run/in-place.js +7 -4
  16. package/dist/exec/run/register-core.js +10 -2
  17. package/dist/exec/run/register-resume.js +1 -0
  18. package/dist/exec/run/register-worktree.js +7 -1
  19. package/dist/exec/task-repos.js +11 -0
  20. package/dist/exec/worktree-ops-lifecycle.js +4 -2
  21. package/dist/kata/command.js +54 -9
  22. package/dist/register/approach.js +13 -12
  23. package/dist/register/authoring-sources.js +132 -0
  24. package/dist/register/core.js +1 -0
  25. package/dist/register/create-commands.js +84 -15
  26. package/dist/register/events.js +2 -0
  27. package/dist/register/external-project.js +29 -8
  28. package/dist/register/item.js +6 -0
  29. package/dist/register/renumber.js +3 -3
  30. package/dist/register/views.js +3 -0
  31. package/dist/shared/git.js +3 -2
  32. package/dist/shared/lefthook-scaffold.js +5 -22
  33. package/dist/shared/markdownlint-scaffold.js +67 -0
  34. package/dist/shared/provider-scaffold.js +2 -2
  35. package/dist/shared/slidev-scaffold.js +102 -0
  36. package/dist/shared/specdojo-config.js +9 -3
  37. package/docs/ja/specdojo/exec-templates/xep-recipe-authoring-template.md +7 -7
  38. package/docs/ja/specdojo/exec-templates/xep-register-template.md +5 -4
  39. package/docs/ja/specdojo/exec-templates/xep-rulebook-authoring-template.md +7 -7
  40. package/docs/ja/specdojo/exec-templates/xep-sample-authoring-template.md +7 -7
  41. package/docs/ja/specdojo/exec-templates/xep-template-authoring-template.md +7 -7
  42. package/docs/ja/specdojo/guides/exec-config-guide.md +46 -16
  43. package/docs/ja/specdojo/guides/kata-guide.md +111 -2
  44. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +6 -6
  45. package/docs/ja/specdojo/guides/quick-start-guide.md +4 -2
  46. package/docs/ja/specdojo/guides/register-operation-guide.md +2 -0
  47. package/docs/ja/specdojo/references/command-reference.md +155 -59
  48. package/docs/ja/specdojo/references/specdojo-config-reference.md +2 -0
  49. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +17 -1
  50. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +4 -3
  51. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +3 -3
  52. package/docs/specdojo/schemas/v1/register-events.schema.yaml +1 -0
  53. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +31 -3
  54. package/package.json +8 -7
  55. package/templates/antigravity/orchestrator.md +4 -4
  56. package/templates/claude/README.md +2 -0
  57. package/templates/claude/agents/specdojo-orchestrator.md +4 -4
  58. package/templates/codex/README.md +38 -9
  59. package/templates/codex/agents/codex-executor.toml +1 -1
  60. package/templates/codex/agents/codex-expert-executor.toml +1 -1
  61. package/templates/codex/agents/codex-expert-review-executor.toml +1 -1
  62. package/templates/codex/agents/codex-review-executor.toml +1 -1
  63. package/templates/codex/agents/specdojo-orchestrator.toml +5 -5
  64. package/templates/codex/orchestrator.md +4 -4
  65. package/templates/init-agent-members.yaml +85 -13
  66. package/templates/opencode/agents/specdojo-orchestrator.md +4 -4
@@ -20,6 +20,7 @@ import { pinnedExecutor, pinnedReporter, resolvePinnedRateLimitRunOptions, resol
20
20
  import { appendParentValidationsToExecutorEvidence, buildExecutorPrompt, executorRequirements, expandPromptRefs, extractBlockReason, loadRosterForExecutionPath, reportProtectionHandoffRecord, resolveReporterAgentCandidates, runWithRetry, } from "./agent.js";
21
21
  import { gradeBeforeReviewPlan } from "./schedule-prepare.js";
22
22
  import { pipelineRecoveryMeta, spawnBlock, spawnClaim, spawnComplete } from "./mode-shared.js";
23
+ import { configuredProductCheckouts, productRepoEnvironment, withoutInheritedRepoEnvironment, withAgentExtraRoots, } from "../task-repos.js";
23
24
  // Resolve the agent command and the actor for an in-place run, ignoring task state. Unlike the
24
25
  // worktree flow, this never requires the task to be claimable. The actor is derived the same way
25
26
  // as the worktree path (`prepareTask`): explicit --by wins, otherwise the resolved member's
@@ -102,15 +103,17 @@ export function resolveInPlaceAgentPipeline(task, roster, opts, source) {
102
103
  }
103
104
  return undefined;
104
105
  }
105
- export async function spawnAgentInPlace(command, prompt, cwd, schedulePath, executionPath, resultPath) {
106
+ export async function spawnAgentInPlace(command, prompt, cwd, schedulePath, executionPath, resultPath, provider) {
106
107
  const protectedConfigBefore = captureAgentProtectedConfigSnapshot(cwd);
107
108
  const gitStateBefore = captureAgentGitStateSnapshot(cwd);
108
- const child = spawn(command, {
109
+ const products = configuredProductCheckouts(schedulePath);
110
+ const child = spawn(withAgentExtraRoots(command, provider, products.map((product) => product.path)), {
109
111
  cwd,
110
112
  env: {
111
- ...gitEnvironment(),
113
+ ...withoutInheritedRepoEnvironment(gitEnvironment()),
112
114
  SPECDOJO_SCHEDULE_PATH: schedulePath,
113
115
  SPECDOJO_EXECUTION_PATH: executionPath,
116
+ ...productRepoEnvironment(cwd, products),
114
117
  },
115
118
  shell: true,
116
119
  stdio: ["pipe", "inherit", "inherit"],
@@ -518,7 +521,7 @@ export async function runInPlaceMode(opts) {
518
521
  }
519
522
  }
520
523
  else {
521
- exitCode = await spawnAgentInPlace(command, prompt, repoRoot, schedulePath, executionPath, resultPath);
524
+ exitCode = await spawnAgentInPlace(command, prompt, repoRoot, schedulePath, executionPath, resultPath, provider);
522
525
  }
523
526
  // Some agents (notably `claude -p`) exit 0 even when they conclude they are blocked: a
524
527
  // permission-denied tool call is fed back as a tool error and the model ends its turn
@@ -14,6 +14,8 @@ import { expandPromptRefs } from "./agent.js";
14
14
  import { runAgentPipeline } from "./agent-pipeline.js";
15
15
  import { spawnAgentInPlace } from "./in-place.js";
16
16
  import { commitSubject, repoRelativePath, spawnSelf } from "./mode-shared.js";
17
+ import { isAuthoringApproach } from "../../kata/authoring.js";
18
+ import { configuredProductCheckouts } from "../task-repos.js";
17
19
  // CLI choices are the highest-priority layer. A difficulty route only supplies omitted stage and
18
20
  // recovery options; without a matching route the historical priority-based selection is kept.
19
21
  export function applyRegisterDifficultyRouting(item, opts, execDefaults) {
@@ -254,6 +256,9 @@ export async function runSingleRegisterItem(context, opts, pjrId) {
254
256
  const { command, actor } = pipelineAgents
255
257
  ? { command: pipelineAgents.executor.command, actor: pipelineAgents.executor.actor }
256
258
  : resolveRegisterCommand(item, context.roster, opts, context.execDefaults);
259
+ const resolvedProvider = pipelineAgents
260
+ ? pipelineAgents.executor.provider
261
+ : resolveAgentMember(context.roster, actor)?.provider;
257
262
  const stem = buildInPlaceStem(pjrId.toLowerCase());
258
263
  // ID単位 commit のため、この項目が変更を生じる前の作業ツリー状態を記録する。
259
264
  const preexisting = context.registerCommit ? worktreeStatusPaths(repoRoot) : [];
@@ -285,7 +290,9 @@ export async function runSingleRegisterItem(context, opts, pjrId) {
285
290
  startedAt: new Date().toISOString(),
286
291
  stem,
287
292
  ...(item.approach ? { approach: item.approach } : {}),
288
- ...(item.targets && item.targets.length > 0 ? { targets: item.targets } : {}),
293
+ ...(item.targets && item.targets.length > 0
294
+ ? { targets: isAuthoringApproach(item.approach) ? item.targets.slice(0, 1) : item.targets }
295
+ : {}),
289
296
  });
290
297
  const resultScaffold = readResultFrontmatterSnapshot(resultPath);
291
298
  process.stdout.write(`Register item: ${item.id} — ${item.title} [${item.type}]\n`);
@@ -314,6 +321,7 @@ export async function runSingleRegisterItem(context, opts, pjrId) {
314
321
  resultPath,
315
322
  registerPaths: registerReporterManagedPaths(registerPaths),
316
323
  execDefaults: context.execDefaults,
324
+ productWorktrees: configuredProductCheckouts(schedulePath),
317
325
  providerConcurrencyGate: context.providerConcurrencyGate,
318
326
  executorRateLimitOptions: opts.executorBy
319
327
  ? resolvePinnedRateLimitRunOptions(opts, context.execDefaults, context.roster, "executor", pipelineAgents.executor)
@@ -331,7 +339,7 @@ export async function runSingleRegisterItem(context, opts, pjrId) {
331
339
  }
332
340
  else {
333
341
  process.stdout.write(`Running ${item.id} in place: ${command}\n`);
334
- exitCode = await spawnAgentInPlace(command, prompt, repoRoot, schedulePath, executionPath, resultPath);
342
+ exitCode = await spawnAgentInPlace(command, prompt, repoRoot, schedulePath, executionPath, resultPath, resolvedProvider);
335
343
  }
336
344
  // in-place 実行と同じ補助判定: agent が result 必須節を埋めずに終了コード 0 で
337
345
  // 終わった場合は block として扱う(runInPlaceMode と同じ理由)。pipeline モードでは
@@ -350,6 +350,7 @@ export async function resumeSingleRegisterItemWorktree(context, opts, pjrId, lif
350
350
  resultScaffold,
351
351
  agentResult: outcome.runResult,
352
352
  stderr: outcome.blockReason ?? "",
353
+ runnerBlockReason: outcome.blockReason,
353
354
  actor: executor.candidate.actor,
354
355
  bookkeepingPaths: bookkeepingPaths(),
355
356
  pipelineStatePath: resolve(worktree.path, outcome.stateRef),
@@ -12,6 +12,7 @@ import { commitProductWorktrees, integrateTaskRepositories, projectMergeBlockers
12
12
  import { productIntegrationTrace, recordResultTrace, refsTrailer, registerProjectMergeMessage, traceKey, withCommitTrailers, } from "../repo-trace.js";
13
13
  import { pipelineStateLocation, readPipelineState } from "../pipeline-state.js";
14
14
  import { findResumableRegisterRun } from "../register-resume.js";
15
+ import { isAuthoringApproach } from "../../kata/authoring.js";
15
16
  import { resolvePinnedRateLimitRunOptions, rateLimitRecoveryReason, } from "./shared.js";
16
17
  import { agentEnvironment, expandPromptRefs, extractBlockReason, pathInsideWorktree, reportProductWorktrees, runWithRetry, } from "./agent.js";
17
18
  import { runAgentPipeline } from "./agent-pipeline.js";
@@ -464,7 +465,9 @@ export async function runSingleRegisterItemWorktree(context, opts, pjrId, lifecy
464
465
  startedAt: new Date().toISOString(),
465
466
  stem,
466
467
  ...(item.approach ? { approach: item.approach } : {}),
467
- ...(item.targets && item.targets.length > 0 ? { targets: item.targets } : {}),
468
+ ...(item.targets && item.targets.length > 0
469
+ ? { targets: isAuthoringApproach(item.approach) ? item.targets.slice(0, 1) : item.targets }
470
+ : {}),
468
471
  });
469
472
  const resultScaffold = readResultFrontmatterSnapshot(resultPath);
470
473
  process.stdout.write(`Register item: ${item.id} — ${item.title} [${item.type}]\n`);
@@ -536,6 +539,7 @@ export async function runSingleRegisterItemWorktree(context, opts, pjrId, lifecy
536
539
  let stderr = "";
537
540
  // pipeline 実行のみ run state を持つ。統合段の記録先として Phase 3 へ渡す。
538
541
  let pipelineStatePath;
542
+ let pipelineBlockReason;
539
543
  let transitionReason;
540
544
  let completionActor = actor;
541
545
  if (pipelineAgents) {
@@ -567,6 +571,7 @@ export async function runSingleRegisterItemWorktree(context, opts, pjrId, lifecy
567
571
  });
568
572
  agentResult = pipelineOutcome.runResult;
569
573
  stderr = pipelineOutcome.blockReason ?? "";
574
+ pipelineBlockReason = pipelineOutcome.blockReason;
570
575
  pipelineStatePath = resolve(worktree.path, pipelineOutcome.stateRef);
571
576
  transitionReason = rateLimitRecoveryReason(pipelineOutcome.rateLimitEvents) || undefined;
572
577
  }
@@ -598,6 +603,7 @@ export async function runSingleRegisterItemWorktree(context, opts, pjrId, lifecy
598
603
  actor: completionActor,
599
604
  bookkeepingPaths,
600
605
  pipelineStatePath,
606
+ runnerBlockReason: pipelineBlockReason,
601
607
  transitionReason,
602
608
  });
603
609
  return lifecycleLock ? lifecycleLock.runExclusive(finalize) : finalize();
@@ -92,6 +92,17 @@ export function configuredProductRepos(schedulePath, integrationBranches) {
92
92
  }
93
93
  return [];
94
94
  }
95
+ /** Declared product repositories represented as their current in-place checkouts. */
96
+ export function configuredProductCheckouts(schedulePath) {
97
+ return configuredProductRepos(schedulePath).map((product) => ({
98
+ name: product.name,
99
+ repoRoot: product.repoRoot,
100
+ path: product.repoRoot,
101
+ branch: productIntegrationTarget(product),
102
+ created: false,
103
+ ...(product.integrationBranch ? { integrationBranch: product.integrationBranch } : {}),
104
+ }));
105
+ }
95
106
  /**
96
107
  * Run-scoped `--integration-branch` values recorded in the run checkpoint (`integration_branches`).
97
108
  * Only explicit overrides are recorded, so a run without the option keeps resolving its targets
@@ -287,8 +287,10 @@ function checkpointAndEnsureProjectWorktree(params, repoDirName, ensureSiblingWo
287
287
  typeof committed.stderr === "string" ? committed.stderr : "",
288
288
  "",
289
289
  ]);
290
- throw new Error(`Checkpoint commit failed (${params.commitMessage}); staged changes rolled back ` +
291
- `(likely a failing git hook): ${summarizeGitHookFailure(output)}`);
290
+ throw new Error(
291
+ // register の短い block_reason にも step とエラーが残るよう、補足より先に要約を置く。
292
+ `Checkpoint commit failed: ${summarizeGitHookFailure(output)} ` +
293
+ `(${params.commitMessage}; staged changes rolled back; likely a failing git hook)`);
292
294
  }
293
295
  }
294
296
  return worktree;
@@ -92,11 +92,31 @@ function pathsForConfig(config, roots) {
92
92
  function relativeFiles(root) {
93
93
  return filesBelow(root).map((filePath) => normalizeRelativePath(relative(root, filePath)));
94
94
  }
95
+ const KATA_ID_EXTENSIONS = new Set([".md", ".mdx", ".yaml", ".yml", ".json"]);
96
+ function isKataIdFile(filePath) {
97
+ return KATA_ID_EXTENSIONS.has(extname(filePath).toLowerCase());
98
+ }
99
+ // ID を読める形式は独立した kata とし、付属ファイルの候補からも除く。
100
+ function companionPaths(filePath, files) {
101
+ const stem = basename(filePath, extname(filePath));
102
+ const directory = dirname(filePath);
103
+ const companionDirectory = normalizeRelativePath(join(directory, stem)) + "/";
104
+ return files.filter((candidate) => !isKataIdFile(candidate) &&
105
+ ((dirname(candidate) === directory && basename(candidate, extname(candidate)) === stem) ||
106
+ candidate.startsWith(companionDirectory)));
107
+ }
108
+ function sameCompanions(filePath, repositoryDir, bundledDir, repositoryFiles, bundledFiles) {
109
+ const repositoryCompanions = companionPaths(filePath, repositoryFiles);
110
+ const bundledCompanions = companionPaths(filePath, bundledFiles);
111
+ return (repositoryCompanions.length === bundledCompanions.length &&
112
+ repositoryCompanions.every((companion, index) => companion === bundledCompanions[index] &&
113
+ sameContents(resolve(repositoryDir, companion), resolve(bundledDir, companion))));
114
+ }
95
115
  function enumerateConfig(config, roots) {
96
116
  const { repositoryDir, bundledDir } = pathsForConfig(config, roots);
97
- const relativePaths = [
98
- ...new Set([...relativeFiles(repositoryDir), ...relativeFiles(bundledDir)]),
99
- ];
117
+ const repositoryFiles = relativeFiles(repositoryDir);
118
+ const bundledFiles = relativeFiles(bundledDir);
119
+ const relativePaths = [...new Set([...repositoryFiles, ...bundledFiles])].filter(isKataIdFile);
100
120
  return relativePaths.sort().map((filePath) => {
101
121
  const repositoryPath = resolve(repositoryDir, filePath);
102
122
  const bundledPath = resolve(bundledDir, filePath);
@@ -116,7 +136,8 @@ function enumerateConfig(config, roots) {
116
136
  state: hasRepositoryFile ? "ejected" : "referenced",
117
137
  difference: hasRepositoryFile
118
138
  ? hasBundledFile
119
- ? sameContents(repositoryPath, bundledPath)
139
+ ? sameContents(repositoryPath, bundledPath) &&
140
+ sameCompanions(filePath, repositoryDir, bundledDir, repositoryFiles, bundledFiles)
120
141
  ? "same"
121
142
  : "modified"
122
143
  : "package-missing"
@@ -132,7 +153,9 @@ function enumerateAuthoredResources(roots) {
132
153
  const legacyDir = legacyKataKindDirectory(kind);
133
154
  const resourcesFrom = (relativeDir) => {
134
155
  const absoluteDir = resolve(repositoryRoot, relativeDir);
135
- return relativeFiles(absoluteDir).flatMap((filePath) => {
156
+ return relativeFiles(absoluteDir)
157
+ .filter(isKataIdFile)
158
+ .flatMap((filePath) => {
136
159
  const resolvedPath = resolve(absoluteDir, filePath);
137
160
  const id = resourceId(resolvedPath);
138
161
  let authority;
@@ -224,7 +247,9 @@ export function findKataResource(id, options = {}) {
224
247
  function bundledResources(configs, roots) {
225
248
  return configs.flatMap((config) => {
226
249
  const { repositoryDir, bundledDir } = pathsForConfig(config, roots);
227
- return relativeFiles(bundledDir).map((filePath) => ({
250
+ return relativeFiles(bundledDir)
251
+ .filter(isKataIdFile)
252
+ .map((filePath) => ({
228
253
  id: resourceId(resolve(bundledDir, filePath)),
229
254
  config,
230
255
  relativePath: normalizeRelativePath(join(config.relativeDir, filePath)),
@@ -233,6 +258,16 @@ function bundledResources(configs, roots) {
233
258
  }));
234
259
  });
235
260
  }
261
+ function bundledCompanions(resource) {
262
+ const sourceDir = dirname(resource.sourcePath);
263
+ const filePaths = companionPaths(basename(resource.sourcePath), relativeFiles(sourceDir));
264
+ return filePaths.map((filePath) => ({
265
+ ...resource,
266
+ relativePath: normalizeRelativePath(join(dirname(resource.relativePath), filePath)),
267
+ sourcePath: resolve(sourceDir, filePath),
268
+ destinationPath: resolve(dirname(resource.destinationPath), filePath),
269
+ }));
270
+ }
236
271
  function selectBundledById(resources, id) {
237
272
  const exact = resources.filter((resource) => resource.id === id);
238
273
  const matches = exact.length > 0 ? exact : resources.filter((resource) => localId(resource.id) === id);
@@ -268,10 +303,17 @@ export function ejectKata(id, options = {}) {
268
303
  if (!resource.config.ejectable) {
269
304
  throw new Error(`Cannot eject ${resource.config.kind} '${resource.id}': ${resource.config.relativeDir} is tied to the installed SpecDojo version and must remain package-referenced.`);
270
305
  }
271
- return copyBundledResource(resource, options);
306
+ const result = copyBundledResource(resource, options);
307
+ const companions = bundledCompanions(resource).map((companion) => copyBundledResource(companion, options));
308
+ return { ...result, companions };
272
309
  }
273
310
  export function installAllKata(options = {}) {
274
- return bundledResources(EJECTABLE_KINDS, options.roots ?? {}).map((resource) => copyBundledResource(resource, options));
311
+ const resources = bundledResources(EJECTABLE_KINDS, options.roots ?? {}).flatMap((resource) => [
312
+ resource,
313
+ ...bundledCompanions(resource),
314
+ ]);
315
+ const uniqueResources = new Map(resources.map((resource) => [resource.relativePath, resource]));
316
+ return [...uniqueResources.values()].map((resource) => copyBundledResource(resource, options));
275
317
  }
276
318
  function printCommandError(error) {
277
319
  process.stdout.write(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -340,7 +382,10 @@ export function registerKataCommands(program) {
340
382
  .option("--force", "Overwrite an existing repository file", false)
341
383
  .action((opts) => {
342
384
  try {
343
- printCopyResult(ejectKata(opts.id, { dryRun: opts.dryRun, force: opts.force }), opts.dryRun);
385
+ const result = ejectKata(opts.id, { dryRun: opts.dryRun, force: opts.force });
386
+ for (const file of [result, ...result.companions]) {
387
+ printCopyResult(file, opts.dryRun);
388
+ }
344
389
  }
345
390
  catch (error) {
346
391
  printCommandError(error);
@@ -4,10 +4,11 @@ import { collectResolvedDeliverables, loadCatalogDocs } from "../catalog/build.j
4
4
  import { resolveBasePath } from "../catalog/paths.js";
5
5
  import { collectDocIndexEntries } from "../docs/doc-index.js";
6
6
  import { readSpecdojoNamespace } from "../docs/frontmatter-namespace.js";
7
- import { getProjectCatalogPath, loadConfig, specdojoRootDir } from "../shared/specdojo-config.js";
7
+ import { getProjectCatalogPath, loadConfig, specdojoRootDir, } from "../shared/specdojo-config.js";
8
8
  import { APPROACHES } from "../shared/agent-types.js";
9
9
  import { load } from "../shared/yaml.js";
10
10
  import { assertAuthorableKataId, authoredKataExists, authoringKind } from "../kata/authoring.js";
11
+ import { resolveAuthoringSources } from "./authoring-sources.js";
11
12
  const MAINTENANCE_TARGET_KIND = {
12
13
  "rulebook-maintenance": "rulebook",
13
14
  "recipe-maintenance": "recipe",
@@ -70,6 +71,7 @@ function targetDocumentType(path) {
70
71
  export function validateRegisterApproachTargets(opts) {
71
72
  const approachText = opts.approach?.trim();
72
73
  const targets = [...new Set((opts.targets ?? []).map((target) => target.trim()).filter(Boolean))];
74
+ const sources = [...new Set((opts.sources ?? []).map((source) => source.trim()).filter(Boolean))];
73
75
  let approach;
74
76
  if (approachText !== undefined) {
75
77
  if (!APPROACHES.includes(approachText)) {
@@ -84,6 +86,9 @@ export function validateRegisterApproachTargets(opts) {
84
86
  throw new Error(`Approach "${approach}" requires the new kata id as the first --target`);
85
87
  }
86
88
  }
89
+ if (sources.length > 0 && !authoringKind(approach)) {
90
+ throw new Error("--source is only valid with a *-authoring approach");
91
+ }
87
92
  if (!approach && !opts.validateTargetsWithoutApproach)
88
93
  return;
89
94
  if (targets.length === 0)
@@ -99,7 +104,7 @@ export function validateRegisterApproachTargets(opts) {
99
104
  }
100
105
  const authoringTargetKind = authoringKind(approach);
101
106
  if (authoringTargetKind) {
102
- const [kataId, ...exampleIds] = targets;
107
+ const [kataId, ...legacySources] = targets;
103
108
  if (!kataId) {
104
109
  throw new Error(`Approach "${approach}" requires the new kata id as the first --target`);
105
110
  }
@@ -107,17 +112,11 @@ export function validateRegisterApproachTargets(opts) {
107
112
  if (entries[kataId] || authoredKataExists(kataId, opts.repoRoot)) {
108
113
  throw new Error(`Kata id ${kataId} already exists; use ${authoringTargetKind}-maintenance instead`);
109
114
  }
110
- if (exampleIds.length === 0)
115
+ const sourceRefs = [...new Set([...legacySources, ...sources])];
116
+ if (sourceRefs.length === 0)
111
117
  return;
112
- if (!opts.catalogPath) {
113
- throw new Error(`Approach "${approach}" requires catalog_path to resolve exemplar deliverables`);
114
- }
115
- const deliverableDocIds = catalogDeliverableDocIds(opts.catalogPath, opts.repoRoot, opts.projectId);
116
- for (const exampleId of exampleIds) {
117
- if (!deliverableDocIds.has(exampleId)) {
118
- throw new Error(`Approach "${approach}" requires every --target after the first to be a catalog deliverable, but ${exampleId} is not one`);
119
- }
120
- }
118
+ const project = opts.project ?? loadConfig(opts.repoRoot).config?.projects[opts.projectId] ?? {};
119
+ resolveAuthoringSources({ repoRoot: opts.repoRoot, project, sources: sourceRefs });
121
120
  return;
122
121
  }
123
122
  const expectedKind = MAINTENANCE_TARGET_KIND[approach];
@@ -155,6 +154,8 @@ export function validateRegisterApproachTargetsForProject(opts) {
155
154
  ...(catalogPath ? { catalogPath: resolve(repoRoot, catalogPath) } : {}),
156
155
  ...(opts.approach !== undefined ? { approach: opts.approach } : {}),
157
156
  ...(opts.targets !== undefined ? { targets: opts.targets } : {}),
157
+ ...(opts.sources !== undefined ? { sources: opts.sources } : {}),
158
+ project,
158
159
  ...(opts.validateTargetsWithoutApproach !== undefined
159
160
  ? { validateTargetsWithoutApproach: opts.validateTargetsWithoutApproach }
160
161
  : {}),
@@ -0,0 +1,132 @@
1
+ import { existsSync, realpathSync, statSync } from "node:fs";
2
+ import { extname, isAbsolute, posix, relative, resolve, sep } from "node:path";
3
+ import { globSync } from "tinyglobby";
4
+ import { collectDocIndexEntries } from "../docs/doc-index.js";
5
+ import { getProjectRepos, resolveRepoQualifiedRef, resolveRepoRoot, } from "../shared/specdojo-config.js";
6
+ // A bounded source set keeps generated plans reviewable and prevents a broad glob from handing an
7
+ // executor an unexpectedly large read scope. The limit applies after directory/glob expansion and
8
+ // duplicate removal, across all --source values.
9
+ export const MAX_AUTHORING_SOURCE_FILES = 100;
10
+ function normalizedRelativePath(value, label) {
11
+ const slashPath = value.trim().replaceAll("\\", "/");
12
+ if (!slashPath)
13
+ throw new Error(`${label} must not be empty`);
14
+ if (posix.isAbsolute(slashPath) || isAbsolute(slashPath) || /^[A-Za-z]:\//.test(slashPath)) {
15
+ throw new Error(`${label} must be relative: ${value}`);
16
+ }
17
+ const normalized = posix.normalize(slashPath).replace(/^\.\//, "").replace(/\/+$/, "");
18
+ if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../")) {
19
+ throw new Error(`${label} escapes its repository root: ${value}`);
20
+ }
21
+ return normalized;
22
+ }
23
+ function assertInsideRoot(root, path, ref) {
24
+ const realRoot = realpathSync(root);
25
+ const realPath = realpathSync(path);
26
+ const fromRoot = relative(realRoot, realPath);
27
+ if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
28
+ throw new Error(`Authoring source resolves outside its repository: ${ref}`);
29
+ }
30
+ }
31
+ function expandPath(root, rawPath, ref) {
32
+ if (!existsSync(root) || !statSync(root).isDirectory()) {
33
+ throw new Error(`Repository root for authoring source does not exist: ${ref}`);
34
+ }
35
+ const normalized = normalizedRelativePath(rawPath, `Authoring source path "${ref}"`);
36
+ const exact = resolve(root, normalized);
37
+ let paths;
38
+ if (existsSync(exact)) {
39
+ assertInsideRoot(root, exact, ref);
40
+ if (statSync(exact).isDirectory()) {
41
+ paths = globSync("**/*", {
42
+ cwd: exact,
43
+ onlyFiles: true,
44
+ dot: false,
45
+ followSymbolicLinks: false,
46
+ ignore: ["**/.git/**", "**/node_modules/**"],
47
+ }).map((entry) => posix.join(normalized, entry.replaceAll("\\", "/")));
48
+ }
49
+ else {
50
+ paths = [normalized];
51
+ }
52
+ }
53
+ else {
54
+ paths = globSync(normalized, {
55
+ cwd: root,
56
+ onlyFiles: true,
57
+ dot: false,
58
+ followSymbolicLinks: false,
59
+ ignore: ["**/.git/**", "**/node_modules/**"],
60
+ }).map((entry) => entry.replaceAll("\\", "/"));
61
+ }
62
+ const sorted = [...new Set(paths)].sort();
63
+ if (sorted.length === 0) {
64
+ throw new Error(`Authoring source did not match any files: ${ref}`);
65
+ }
66
+ for (const path of sorted)
67
+ assertInsideRoot(root, resolve(root, path), ref);
68
+ return sorted;
69
+ }
70
+ function looksLikeProjectPath(ref) {
71
+ const normalized = ref.replaceAll("\\", "/");
72
+ return normalized.includes("/") || extname(posix.basename(normalized)) !== "";
73
+ }
74
+ function indexedDocumentPath(repoRoot, ref) {
75
+ const indexed = collectDocIndexEntries(resolve(repoRoot, "docs"), repoRoot)[ref];
76
+ if (!indexed) {
77
+ throw new Error(`Authoring source document id is not resolvable via the document index: ${ref}`);
78
+ }
79
+ const withoutLine = indexed.replace(/:\d+$/, "");
80
+ const absolute = resolve(repoRoot, withoutLine);
81
+ if (!existsSync(absolute) || !statSync(absolute).isFile()) {
82
+ throw new Error(`Authoring source document does not exist: ${ref} (${withoutLine})`);
83
+ }
84
+ assertInsideRoot(repoRoot, absolute, ref);
85
+ return relative(repoRoot, absolute).replaceAll("\\", "/");
86
+ }
87
+ function configuredRepo(project, name) {
88
+ const repo = getProjectRepos(project).find((candidate) => candidate.name === name);
89
+ if (!repo)
90
+ throw new Error(`Unknown product repository in authoring source: ${name}`);
91
+ return repo;
92
+ }
93
+ export function resolveAuthoringSources(opts) {
94
+ const refs = [...new Set(opts.sources.map((source) => source.trim()).filter(Boolean))];
95
+ const repos = getProjectRepos(opts.project);
96
+ const resolved = [];
97
+ const seen = new Set();
98
+ const append = (source) => {
99
+ const key = `${source.repo ?? "project"}:${source.path}`;
100
+ if (seen.has(key))
101
+ return;
102
+ seen.add(key);
103
+ resolved.push(source);
104
+ if (resolved.length > MAX_AUTHORING_SOURCE_FILES) {
105
+ throw new Error(`Authoring sources expand to more than ${MAX_AUTHORING_SOURCE_FILES} files; narrow the directory or pattern`);
106
+ }
107
+ };
108
+ for (const ref of refs) {
109
+ const qualified = resolveRepoQualifiedRef(ref, repos);
110
+ if (qualified.kind === "repo") {
111
+ const repo = configuredRepo(opts.project, qualified.repo);
112
+ const root = resolveRepoRoot(opts.repoRoot, repo);
113
+ for (const path of expandPath(root, qualified.path, ref)) {
114
+ append({ ref, kind: "repo-path", repo: qualified.repo, path });
115
+ }
116
+ continue;
117
+ }
118
+ if (looksLikeProjectPath(ref)) {
119
+ for (const path of expandPath(opts.repoRoot, ref, ref)) {
120
+ append({ ref, kind: "project-path", path });
121
+ }
122
+ continue;
123
+ }
124
+ append({
125
+ ref,
126
+ kind: "document",
127
+ path: indexedDocumentPath(opts.repoRoot, ref),
128
+ documentId: ref,
129
+ });
130
+ }
131
+ return resolved;
132
+ }
@@ -377,6 +377,7 @@ export function buildRegisterItemContent(opts) {
377
377
  ticket: "-",
378
378
  ...(opts.fields.approach ? { approach: opts.fields.approach } : {}),
379
379
  ...(opts.fields.targets ? { targets: opts.fields.targets } : {}),
380
+ ...(opts.fields.sources ? { sources: opts.fields.sources } : {}),
380
381
  ...(opts.fields.derivedFrom ? { derivedFrom: opts.fields.derivedFrom } : {}),
381
382
  }));
382
383
  }