specdojo 0.3.0 → 0.3.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 (104) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/catalog-build-references.js +144 -0
  3. package/dist/catalog-build-render.js +144 -0
  4. package/dist/catalog-build.js +13 -290
  5. package/dist/catalog-generate.js +6 -9
  6. package/dist/catalog-plan-generate.js +2 -2
  7. package/dist/catalog-plan.js +6 -6
  8. package/dist/catalog-scaffold.js +4 -4
  9. package/dist/catalog.js +2 -2
  10. package/dist/dashboard-exec-records.js +105 -0
  11. package/dist/dashboard-routines.js +255 -0
  12. package/dist/dashboard-shared.js +14 -0
  13. package/dist/dashboard-timeline.js +175 -0
  14. package/dist/dashboard.js +10 -544
  15. package/dist/deliverable-trash.js +3 -3
  16. package/dist/doc-index.js +3 -3
  17. package/dist/exec-commands.js +557 -0
  18. package/dist/exec-core.js +457 -0
  19. package/dist/exec-plans-core.js +693 -0
  20. package/dist/exec-plans-generation.js +206 -0
  21. package/dist/exec-plans-storage.js +131 -0
  22. package/dist/exec-plans.js +3 -1018
  23. package/dist/exec-repo-integration-git.js +23 -0
  24. package/dist/exec-repo-integration-sync.js +264 -0
  25. package/dist/exec-repo-integration.js +4 -281
  26. package/dist/exec-reporter-output.js +206 -0
  27. package/dist/exec-reporter.js +2 -206
  28. package/dist/exec-results.js +22 -15
  29. package/dist/exec-run-agent-pipeline.js +256 -0
  30. package/dist/exec-run-agent.js +531 -0
  31. package/dist/exec-run-in-place.js +541 -0
  32. package/dist/exec-run-job.js +717 -0
  33. package/dist/exec-run-lifecycle-commands.js +522 -0
  34. package/dist/exec-run-mode-shared.js +140 -0
  35. package/dist/exec-run-register-command.js +244 -0
  36. package/dist/exec-run-register-core.js +386 -0
  37. package/dist/exec-run-register-mode.js +206 -0
  38. package/dist/exec-run-register-resume.js +393 -0
  39. package/dist/exec-run-register-state.js +322 -0
  40. package/dist/exec-run-register-worktree.js +509 -0
  41. package/dist/exec-run-schedule-mode.js +294 -0
  42. package/dist/exec-run-schedule-prepare.js +353 -0
  43. package/dist/exec-run-schedule-task.js +572 -0
  44. package/dist/exec-run-shared.js +399 -0
  45. package/dist/exec-run.js +11 -6182
  46. package/dist/exec-shared.js +2 -2
  47. package/dist/exec-trial-commands.js +558 -0
  48. package/dist/exec-trial-core.js +371 -0
  49. package/dist/exec-trial.js +2 -921
  50. package/dist/exec-worktree-ops-commit.js +707 -0
  51. package/dist/exec-worktree-ops-lifecycle.js +292 -0
  52. package/dist/exec-worktree-ops-merge.js +303 -0
  53. package/dist/exec-worktree-ops.js +3 -1292
  54. package/dist/exec-worktree.js +32 -4
  55. package/dist/exec.js +2 -1006
  56. package/dist/frontmatter-namespace.js +2 -2
  57. package/dist/grade-apply.js +734 -0
  58. package/dist/grade-command-apply.js +250 -0
  59. package/dist/grade-command-inspect.js +138 -0
  60. package/dist/grade-command-plan.js +101 -0
  61. package/dist/grade-command-shared.js +68 -0
  62. package/dist/grade-core.js +307 -0
  63. package/dist/grade-markdown.js +274 -0
  64. package/dist/grade-pipeline-state.js +184 -0
  65. package/dist/grade-plan.js +507 -0
  66. package/dist/grade-result.js +5 -5
  67. package/dist/grade-target-discovery.js +265 -0
  68. package/dist/grade-targets.js +432 -0
  69. package/dist/grade.js +14 -3188
  70. package/dist/init-command.js +7 -7
  71. package/dist/job-definition.js +670 -0
  72. package/dist/job.js +9 -673
  73. package/dist/kata-command.js +2 -2
  74. package/dist/register-command-types.js +1 -0
  75. package/dist/register-core.js +363 -0
  76. package/dist/register-create-commands.js +245 -0
  77. package/dist/register-events.js +4 -4
  78. package/dist/register-item.js +6 -6
  79. package/dist/register-maintenance-commands.js +187 -0
  80. package/dist/register-migration.js +268 -0
  81. package/dist/register-renumber.js +314 -0
  82. package/dist/register-transition-commands.js +248 -0
  83. package/dist/register-update.js +230 -0
  84. package/dist/register-views.js +256 -0
  85. package/dist/register.js +61 -2069
  86. package/dist/review-plan.js +3 -3
  87. package/dist/routine-definition.js +401 -0
  88. package/dist/routine.js +6 -402
  89. package/dist/schedule-approach.js +2 -2
  90. package/dist/schedule-strategy-generate-document.js +273 -0
  91. package/dist/schedule-strategy-generate-scope.js +199 -0
  92. package/dist/schedule-strategy-generate.js +9 -473
  93. package/dist/schedule.js +4 -4
  94. package/dist/specdojo-config.js +3 -4
  95. package/dist/viewpoint-document-kinds-check.js +3 -3
  96. package/dist/yaml-pages.js +4 -4
  97. package/dist/yaml.js +28 -0
  98. package/docs/ja/specdojo/guides/exec-config-guide.md +6 -6
  99. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +20 -18
  100. package/docs/ja/specdojo/guides/routine-operation-guide.md +1 -1
  101. package/package.json +4 -5
  102. package/templates/antigravity/README.md +3 -3
  103. package/templates/antigravity/exec-defaults-snippet.yaml +6 -4
  104. package/templates/init-exec-defaults.yaml +3 -1
package/dist/job.js CHANGED
@@ -1,680 +1,16 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { spawn, spawnSync } from "node:child_process";
3
3
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
4
- import { basename, join, relative, resolve } from "node:path";
5
- import yaml from "js-yaml";
4
+ import { join, relative, resolve } from "node:path";
6
5
  import { buildSpecdojoFrontmatter } from "./frontmatter-namespace.js";
7
6
  import { formatMarkdownFile } from "./exec-format.js";
8
7
  import { execTemplatePath, injectCommonConventions, MISSING } from "./exec-plans.js";
9
- import { expandTemplate, listFilesRecursive, readJson, writeJson } from "./exec-shared.js";
8
+ import { expandTemplate, listFilesRecursive, writeJson } from "./exec-shared.js";
10
9
  import { gitEnvironment } from "./exec-worktree.js";
11
- import { getProjectJobsPath, getProjectExecutionPath, loadConfig, loadEnv, specdojoRootDir, } from "./specdojo-config.js";
10
+ import { isJobAgentTask, isJobCommandTask, getPath, loadAllJobs, loadJobDefinition, loadJobRunRecord, parseInputValue, parseJobInputs, renderJobTemplate, resolveJobPaths, validateJobInputValue, } from "./job-definition.js";
11
+ import { specdojoRootDir } from "./specdojo-config.js";
12
12
  import { selfRunCommand } from "./spawn-self.js";
13
- function isRecord(value) {
14
- return typeof value === "object" && value !== null && !Array.isArray(value);
15
- }
16
- export function isJobCommandTask(task) {
17
- return task.mode === "command";
18
- }
19
- export function isJobAgentTask(task) {
20
- return task.mode === "edit" || task.mode === "review";
21
- }
22
- function validStringList(value) {
23
- return (Array.isArray(value) &&
24
- value.length > 0 &&
25
- value.every((item) => typeof item === "string" && item.trim()));
26
- }
27
- // Same nickname shape as agent-members.schema.yaml. The roster is not loaded here, so a
28
- // definition only guarantees the format; an unknown nickname fails when the Run resolves
29
- // the agent command.
30
- function isAgentNickname(value) {
31
- return typeof value === "string" && /^[a-z0-9][a-z0-9_-]{0,62}$/.test(value.trim());
32
- }
33
- function isJobAgentDefinition(value) {
34
- return (isRecord(value) &&
35
- isAgentNickname(value.executor) &&
36
- (value.reporter === undefined || isAgentNickname(value.reporter)));
37
- }
38
- // Parses task.agent (or another nomination such as task.review.agent) and reports why it was
39
- // rejected. Unknown keys are refused so a typo (for example `reporters`) cannot silently drop
40
- // the reporter stage.
41
- function parseJobAgent(value, fieldName = "task.agent") {
42
- if (!isRecord(value)) {
43
- return { error: `${fieldName} must be a mapping with executor and optional reporter` };
44
- }
45
- const unknownKeys = Object.keys(value).filter((key) => key !== "executor" && key !== "reporter");
46
- if (unknownKeys.length > 0) {
47
- return { error: `${fieldName} has unknown key(s): ${unknownKeys.sort().join(", ")}` };
48
- }
49
- if (!isAgentNickname(value.executor)) {
50
- return { error: `${fieldName}.executor must be an agent nickname from agent-members.yaml` };
51
- }
52
- if (value.reporter !== undefined && !isAgentNickname(value.reporter)) {
53
- return { error: `${fieldName}.reporter must be an agent nickname from agent-members.yaml` };
54
- }
55
- return {
56
- agent: {
57
- executor: value.executor.trim(),
58
- ...(isAgentNickname(value.reporter) ? { reporter: value.reporter.trim() } : {}),
59
- },
60
- };
61
- }
62
- // Parses task.review. The mapping itself is the declaration; an empty mapping declares the
63
- // reviewed integration without pinning agents, which are then auto selected.
64
- function parseJobReview(value) {
65
- if (!isRecord(value)) {
66
- return { errors: ["task.review must be a mapping with an optional agent"] };
67
- }
68
- const errors = [];
69
- const unknownKeys = Object.keys(value).filter((key) => key !== "agent");
70
- if (unknownKeys.length > 0) {
71
- errors.push(`task.review has unknown key(s): ${unknownKeys.sort().join(", ")}`);
72
- }
73
- let agent;
74
- if (value.agent !== undefined) {
75
- const parsed = parseJobAgent(value.agent, "task.review.agent");
76
- if (parsed.error)
77
- errors.push(parsed.error);
78
- agent = parsed.agent;
79
- }
80
- if (errors.length > 0)
81
- return { errors };
82
- return { review: agent ? { agent } : {}, errors };
83
- }
84
- function isJobReviewDefinition(value) {
85
- return isRecord(value) && (value.agent === undefined || isJobAgentDefinition(value.agent));
86
- }
87
- /** True when the Job declares that its Run output is reviewed before integration. */
88
- export function jobDeclaresReview(definition) {
89
- return definition.task.review !== undefined;
90
- }
91
- /**
92
- * Resolves the review agent nicknames of a Job Run review. The order is the CLI flag
93
- * (`--review-by` / `--reporter-by`), then the Job's task.review.agent, then auto selection
94
- * (an undefined entry means the caller auto selects).
95
- */
96
- export function resolveJobReviewAgentNominations(cli, definition) {
97
- const nominate = (cliValue, jobValue) => {
98
- const fromCli = cliValue?.trim();
99
- if (fromCli)
100
- return { nickname: fromCli, source: "cli" };
101
- const fromJob = jobValue?.trim();
102
- if (fromJob)
103
- return { nickname: fromJob, source: "job" };
104
- return undefined;
105
- };
106
- const agent = definition.task.review?.agent;
107
- const executor = nominate(cli.reviewBy, agent?.executor);
108
- const reporter = nominate(cli.reporterBy, agent?.reporter);
109
- return {
110
- ...(executor ? { executor } : {}),
111
- ...(reporter ? { reporter } : {}),
112
- };
113
- }
114
- /**
115
- * Decides whether a Job Run takes the reviewed integration path (exec worktree, runner
116
- * commit, review, merge by verdict). The Job's task.review declaration wins over the
117
- * caller: a declared Job is always reviewed, and `--worktree` (passed by a routine with the
118
- * legacy `action.commit: true`) still opts an undeclared Job in for compatibility. The child
119
- * process that executes the Job inside the worktree never re-enters this path.
120
- */
121
- export function jobRunUsesReviewedIntegration(definition, opts) {
122
- if (opts.isWorktreeChild)
123
- return false;
124
- return jobDeclaresReview(definition) || !!opts.worktree;
125
- }
126
- function isJobRunState(value) {
127
- return value === "running" || value === "succeeded" || value === "failed" || value === "noop";
128
- }
129
- function isJobTaskDefinition(value) {
130
- if (!isRecord(value))
131
- return false;
132
- if (value.owner !== undefined && typeof value.owner !== "string")
133
- return false;
134
- if (!["targets", "paths"].every((field) => value[field] === undefined || validStringList(value[field])))
135
- return false;
136
- if (value.review !== undefined && !isJobReviewDefinition(value.review))
137
- return false;
138
- if (value.mode === "command") {
139
- return (typeof value.command === "string" &&
140
- (value.precondition === undefined ||
141
- (isRecord(value.precondition) &&
142
- typeof value.precondition.command === "string" &&
143
- (value.precondition.skip_when === "empty-output" ||
144
- (Number.isSafeInteger(value.precondition.skip_when) &&
145
- Number(value.precondition.skip_when) >= 0 &&
146
- Number(value.precondition.skip_when) <= 255)))) &&
147
- (value.analysis === undefined ||
148
- (isRecord(value.analysis) &&
149
- isAgentNickname(value.analysis.agent) &&
150
- typeof value.analysis.description === "string")));
151
- }
152
- if (value.mode !== "edit" && value.mode !== "review")
153
- return false;
154
- if (typeof value.description !== "string")
155
- return false;
156
- if (value.agent !== undefined && !isJobAgentDefinition(value.agent))
157
- return false;
158
- return ["capabilities"].every((field) => value[field] === undefined || validStringList(value[field]));
159
- }
160
- function isJobRunAttempt(value) {
161
- return (isRecord(value) &&
162
- typeof value.attempt === "number" &&
163
- typeof value.started_at === "string" &&
164
- isJobRunState(value.status) &&
165
- (value.evidence_ref === undefined || typeof value.evidence_ref === "string") &&
166
- (value.exit_code === undefined ||
167
- value.exit_code === null ||
168
- typeof value.exit_code === "number"));
169
- }
170
- function isJobRunReview(value) {
171
- return (isRecord(value) &&
172
- typeof value.plan_ref === "string" &&
173
- typeof value.result_ref === "string" &&
174
- typeof value.reviewed_at === "string" &&
175
- typeof value.branch === "string" &&
176
- (value.verdict === undefined ||
177
- [
178
- "complete",
179
- "complete-with-findings",
180
- "incomplete",
181
- "grade-stale",
182
- "grade-unavailable",
183
- "changed-during-review",
184
- ].includes(String(value.verdict))) &&
185
- (value.reason === undefined || typeof value.reason === "string"));
186
- }
187
- function isJobRunRecord(value) {
188
- if (!isRecord(value))
189
- return false;
190
- const stringFields = [
191
- "run_id",
192
- "job_id",
193
- "idempotency_key",
194
- "project_id",
195
- "scheduled_at",
196
- "created_at",
197
- "updated_at",
198
- "plan_ref",
199
- "result_ref",
200
- ];
201
- return (value.version === 1 &&
202
- stringFields.every((field) => typeof value[field] === "string") &&
203
- (value.trigger === "manual" || value.trigger === "routine" || value.trigger === "ci") &&
204
- isJobRunState(value.state) &&
205
- isRecord(value.inputs) &&
206
- isJobTaskDefinition(value.task) &&
207
- isRecord(value.checkpoint_before) &&
208
- (value.checkpoint_after === undefined || isRecord(value.checkpoint_after)) &&
209
- (value.review === undefined || isJobRunReview(value.review)) &&
210
- Array.isArray(value.attempts) &&
211
- value.attempts.every(isJobRunAttempt));
212
- }
213
- function readJobRunRecord(filePath) {
214
- const raw = readJson(filePath);
215
- if (!isJobRunRecord(raw))
216
- throw new Error(`Invalid Job Run file: ${filePath}`);
217
- return raw;
218
- }
219
- export function loadJobRunRecord(filePath) {
220
- return readJobRunRecord(filePath);
221
- }
222
- function validateJobInputValue(value, input, key) {
223
- const values = input.type === "list" ? value : [value];
224
- if (input.enum) {
225
- for (const item of values) {
226
- if (!input.enum.includes(item)) {
227
- throw new Error(`Input ${key} must be one of: ${input.enum.join(", ")}`);
228
- }
229
- }
230
- }
231
- if (input.type === "integer") {
232
- const integer = value;
233
- if (input.minimum !== undefined && integer < input.minimum) {
234
- throw new Error(`Input ${key} must be at least ${input.minimum}`);
235
- }
236
- if (input.maximum !== undefined && integer > input.maximum) {
237
- throw new Error(`Input ${key} must be at most ${input.maximum}`);
238
- }
239
- }
240
- }
241
- export function parseJobDefinition(value, fileName) {
242
- const errors = [];
243
- if (!isRecord(value))
244
- return { errors: [`${fileName}: job file must be a YAML mapping`] };
245
- const expectedId = fileName.replace(/\.(yaml|yml)$/, "");
246
- const id = typeof value.id === "string" ? value.id.trim() : "";
247
- if (!/^job-[a-z0-9][a-z0-9-]*$/.test(id))
248
- errors.push("id must match job-<slug>");
249
- if (id && id !== expectedId)
250
- errors.push(`id "${id}" must match the file name base "${expectedId}"`);
251
- const name = typeof value.name === "string" ? value.name.trim() : "";
252
- if (!name)
253
- errors.push("name is required");
254
- const inputDefinitions = {};
255
- if (value.inputs !== undefined) {
256
- if (!isRecord(value.inputs))
257
- errors.push("inputs must be a mapping");
258
- else {
259
- for (const [key, raw] of Object.entries(value.inputs)) {
260
- if (!/^[a-z][a-z0-9_]*$/.test(key)) {
261
- errors.push(`inputs.${key} must use lowercase snake_case`);
262
- continue;
263
- }
264
- if (!isRecord(raw)) {
265
- errors.push(`inputs.${key} must be a mapping`);
266
- continue;
267
- }
268
- const unknownInputKeys = Object.keys(raw).filter((field) => ![
269
- "type",
270
- "required",
271
- "default",
272
- "enum",
273
- "minimum",
274
- "maximum",
275
- "from_checkpoint",
276
- "resolve",
277
- "git_revision",
278
- ].includes(field));
279
- if (unknownInputKeys.length > 0) {
280
- errors.push(`inputs.${key} has unknown key(s): ${unknownInputKeys.sort().join(", ")}`);
281
- }
282
- const type = raw.type;
283
- if (type !== "string" && type !== "integer" && type !== "boolean" && type !== "list") {
284
- errors.push(`inputs.${key}.type must be string|integer|boolean|list`);
285
- continue;
286
- }
287
- if (raw.required !== undefined && typeof raw.required !== "boolean") {
288
- errors.push(`inputs.${key}.required must be a boolean`);
289
- }
290
- if (raw.from_checkpoint !== undefined && typeof raw.from_checkpoint !== "string") {
291
- errors.push(`inputs.${key}.from_checkpoint must be a string`);
292
- }
293
- if (raw.resolve !== undefined && raw.resolve !== "git_head") {
294
- errors.push(`inputs.${key}.resolve must be git_head`);
295
- }
296
- if (raw.git_revision !== undefined && typeof raw.git_revision !== "boolean") {
297
- errors.push(`inputs.${key}.git_revision must be a boolean`);
298
- }
299
- const enumValues = raw.enum;
300
- if (enumValues !== undefined &&
301
- (!Array.isArray(enumValues) ||
302
- enumValues.length === 0 ||
303
- new Set(enumValues).size !== enumValues.length ||
304
- enumValues.some((item) => type === "integer"
305
- ? !Number.isSafeInteger(item)
306
- : type === "boolean"
307
- ? typeof item !== "boolean"
308
- : typeof item !== "string"))) {
309
- errors.push(`inputs.${key}.enum must be a non-empty unique list of ${type === "list" ? "string" : type} values`);
310
- }
311
- if (raw.minimum !== undefined &&
312
- (type !== "integer" || !Number.isSafeInteger(raw.minimum))) {
313
- errors.push(`inputs.${key}.minimum is only allowed as an integer constraint`);
314
- }
315
- if (raw.maximum !== undefined &&
316
- (type !== "integer" || !Number.isSafeInteger(raw.maximum))) {
317
- errors.push(`inputs.${key}.maximum is only allowed as an integer constraint`);
318
- }
319
- if (Number.isSafeInteger(raw.minimum) &&
320
- Number.isSafeInteger(raw.maximum) &&
321
- Number(raw.minimum) > Number(raw.maximum)) {
322
- errors.push(`inputs.${key}.minimum must not exceed maximum`);
323
- }
324
- const definition = {
325
- type,
326
- ...(typeof raw.required === "boolean" ? { required: raw.required } : {}),
327
- ...(raw.default !== undefined ? { default: raw.default } : {}),
328
- ...(Array.isArray(enumValues)
329
- ? { enum: enumValues }
330
- : {}),
331
- ...(Number.isSafeInteger(raw.minimum) ? { minimum: Number(raw.minimum) } : {}),
332
- ...(Number.isSafeInteger(raw.maximum) ? { maximum: Number(raw.maximum) } : {}),
333
- ...(typeof raw.from_checkpoint === "string"
334
- ? { from_checkpoint: raw.from_checkpoint }
335
- : {}),
336
- ...(raw.resolve === "git_head" ? { resolve: "git_head" } : {}),
337
- ...(typeof raw.git_revision === "boolean" ? { git_revision: raw.git_revision } : {}),
338
- };
339
- if (raw.default !== undefined) {
340
- try {
341
- const parsedDefault = parseInputValue(raw.default, type, key);
342
- validateJobInputValue(parsedDefault, definition, key);
343
- }
344
- catch (error) {
345
- errors.push(`inputs.${key}.default is invalid: ${error instanceof Error ? error.message : String(error)}`);
346
- }
347
- }
348
- inputDefinitions[key] = definition;
349
- }
350
- }
351
- }
352
- let task;
353
- if (!isRecord(value.task))
354
- errors.push("task is required and must be a mapping");
355
- else {
356
- const mode = value.task.mode;
357
- const targets = validStringList(value.task.targets) ? value.task.targets : undefined;
358
- const paths = validStringList(value.task.paths) ? value.task.paths : undefined;
359
- if (value.task.targets !== undefined && !targets)
360
- errors.push("task.targets must be a non-empty string list");
361
- if (value.task.paths !== undefined && !paths)
362
- errors.push("task.paths must be a non-empty string list");
363
- if (value.task.owner !== undefined && typeof value.task.owner !== "string")
364
- errors.push("task.owner must be a string");
365
- let review;
366
- if (value.task.review !== undefined) {
367
- const parsedReview = parseJobReview(value.task.review);
368
- errors.push(...parsedReview.errors);
369
- review = parsedReview.review;
370
- }
371
- const common = {
372
- ...(targets ? { targets: targets.map((target) => target.trim()) } : {}),
373
- ...(paths ? { paths: paths.map((path) => path.trim()) } : {}),
374
- ...(typeof value.task.owner === "string" ? { owner: value.task.owner.trim() } : {}),
375
- ...(review ? { review } : {}),
376
- };
377
- if (mode === "command") {
378
- const command = typeof value.task.command === "string" ? value.task.command.trim() : "";
379
- if (!command)
380
- errors.push("task.command is required for command mode");
381
- let precondition;
382
- if (value.task.precondition !== undefined) {
383
- if (!isRecord(value.task.precondition)) {
384
- errors.push("task.precondition must be a mapping with command and skip_when");
385
- }
386
- else {
387
- const unknownPreconditionKeys = Object.keys(value.task.precondition).filter((key) => key !== "command" && key !== "skip_when");
388
- if (unknownPreconditionKeys.length > 0) {
389
- errors.push(`task.precondition has unknown key(s): ${unknownPreconditionKeys.sort().join(", ")}`);
390
- }
391
- const preconditionCommand = typeof value.task.precondition.command === "string"
392
- ? value.task.precondition.command.trim()
393
- : "";
394
- if (!preconditionCommand)
395
- errors.push("task.precondition.command is required");
396
- const skipWhen = value.task.precondition.skip_when;
397
- if (skipWhen !== "empty-output" &&
398
- (!Number.isSafeInteger(skipWhen) || Number(skipWhen) < 0 || Number(skipWhen) > 255)) {
399
- errors.push("task.precondition.skip_when must be empty-output or an exit code from 0 to 255");
400
- }
401
- if (preconditionCommand &&
402
- (skipWhen === "empty-output" || Number.isSafeInteger(skipWhen))) {
403
- precondition = {
404
- command: preconditionCommand,
405
- skip_when: skipWhen,
406
- };
407
- }
408
- }
409
- }
410
- let analysis;
411
- if (value.task.analysis !== undefined) {
412
- if (!isRecord(value.task.analysis)) {
413
- errors.push("task.analysis must be a mapping with agent and description");
414
- }
415
- else {
416
- const unknownAnalysisKeys = Object.keys(value.task.analysis).filter((key) => key !== "agent" && key !== "description");
417
- if (unknownAnalysisKeys.length > 0) {
418
- errors.push(`task.analysis has unknown key(s): ${unknownAnalysisKeys.sort().join(", ")}`);
419
- }
420
- if (!isAgentNickname(value.task.analysis.agent)) {
421
- errors.push("task.analysis.agent must be an agent nickname from agent-members.yaml");
422
- }
423
- const analysisDescription = typeof value.task.analysis.description === "string"
424
- ? value.task.analysis.description.trim()
425
- : "";
426
- if (!analysisDescription)
427
- errors.push("task.analysis.description is required");
428
- if (isAgentNickname(value.task.analysis.agent) && analysisDescription) {
429
- analysis = {
430
- agent: value.task.analysis.agent.trim(),
431
- description: analysisDescription,
432
- };
433
- }
434
- }
435
- }
436
- if (value.task.agent !== undefined)
437
- errors.push("task.agent is not allowed in command mode; use task.analysis.agent");
438
- if (value.task.description !== undefined)
439
- errors.push("task.description is not allowed in command mode; use task.analysis.description");
440
- if (value.task.capabilities !== undefined || value.task.proficiency !== undefined) {
441
- errors.push("task.capabilities and task.proficiency are not allowed in command mode");
442
- }
443
- if (command)
444
- task = {
445
- mode: "command",
446
- ...(precondition ? { precondition } : {}),
447
- command,
448
- ...(analysis ? { analysis } : {}),
449
- ...common,
450
- };
451
- }
452
- else {
453
- if (mode !== "edit" && mode !== "review") {
454
- errors.push("task.mode must be edit, review, or command");
455
- }
456
- const description = typeof value.task.description === "string" ? value.task.description.trim() : "";
457
- if (!description)
458
- errors.push("task.description is required");
459
- if (!targets && !paths)
460
- errors.push("task.targets or task.paths must be a non-empty string list");
461
- let agent;
462
- if (value.task.agent !== undefined) {
463
- const parsedAgent = parseJobAgent(value.task.agent);
464
- if (parsedAgent.error)
465
- errors.push(parsedAgent.error);
466
- agent = parsedAgent.agent;
467
- }
468
- if (value.task.analysis !== undefined ||
469
- value.task.command !== undefined ||
470
- value.task.precondition !== undefined) {
471
- errors.push("task.command, task.precondition, and task.analysis are only allowed in command mode");
472
- }
473
- if (value.task.capabilities !== undefined && !validStringList(value.task.capabilities)) {
474
- errors.push("task.capabilities must be a non-empty string list");
475
- }
476
- const proficiency = value.task.proficiency;
477
- if (proficiency !== undefined &&
478
- !["low", "normal", "high", "expert"].includes(String(proficiency))) {
479
- errors.push("task.proficiency must be low|normal|high|expert");
480
- }
481
- if ((mode === "edit" || mode === "review") && description && (targets || paths)) {
482
- task = {
483
- mode,
484
- description,
485
- ...common,
486
- ...(agent ? { agent } : {}),
487
- ...(validStringList(value.task.capabilities)
488
- ? { capabilities: value.task.capabilities }
489
- : {}),
490
- ...(proficiency !== undefined ? { proficiency: proficiency } : {}),
491
- };
492
- }
493
- }
494
- }
495
- const idempotencyKey = isRecord(value.run) && typeof value.run.idempotency_key === "string"
496
- ? value.run.idempotency_key.trim()
497
- : "";
498
- if (!idempotencyKey)
499
- errors.push("run.idempotency_key is required");
500
- let checkpoint;
501
- if (value.checkpoint !== undefined) {
502
- if (!isRecord(value.checkpoint) || !isRecord(value.checkpoint.values)) {
503
- errors.push("checkpoint.values must be a mapping");
504
- }
505
- else {
506
- const values = {};
507
- for (const [key, raw] of Object.entries(value.checkpoint.values)) {
508
- if (!/^[a-z][a-z0-9_]*$/.test(key) || typeof raw !== "string") {
509
- errors.push(`checkpoint.values.${key} must be a string with a lowercase snake_case key`);
510
- }
511
- else
512
- values[key] = raw;
513
- }
514
- const advance = value.checkpoint.advance_on;
515
- if (advance !== undefined &&
516
- (!Array.isArray(advance) || advance.some((item) => item !== "succeeded" && item !== "noop"))) {
517
- errors.push("checkpoint.advance_on must contain succeeded and/or noop");
518
- }
519
- checkpoint = {
520
- values,
521
- ...(Array.isArray(advance) ? { advance_on: advance } : {}),
522
- };
523
- }
524
- }
525
- if (errors.length > 0 || !task)
526
- return { errors: errors.map((error) => `${fileName}: ${error}`) };
527
- return {
528
- job: {
529
- id,
530
- name,
531
- ...(typeof value.description === "string" ? { description: value.description } : {}),
532
- ...(Object.keys(inputDefinitions).length ? { inputs: inputDefinitions } : {}),
533
- task,
534
- run: { idempotency_key: idempotencyKey },
535
- ...(checkpoint ? { checkpoint } : {}),
536
- },
537
- errors: [],
538
- };
539
- }
540
- function configProject(projectId) {
541
- loadEnv();
542
- const { config, configPath } = loadConfig();
543
- if (!config)
544
- throw new Error(`job commands require specdojo.config.json: ${configPath}`);
545
- const id = projectId?.trim() || process.env.SPECDOJO_PROJECT?.trim() || config.current_project;
546
- if (!id)
547
- throw new Error("Project id is required. Use --project or set current_project.");
548
- const project = config.projects[id];
549
- if (!project)
550
- throw new Error(`Unknown project: ${id}`);
551
- return { id, project };
552
- }
553
- export function resolveJobPaths(projectId) {
554
- const { id, project } = configProject(projectId);
555
- const jobsPath = getProjectJobsPath(project);
556
- if (!jobsPath)
557
- throw new Error(`jobs_path not set for project '${id}' in specdojo.config.json`);
558
- const root = specdojoRootDir();
559
- const executionPath = resolve(root, getProjectExecutionPath(project));
560
- const absoluteJobsPath = resolve(root, jobsPath);
561
- return {
562
- projectId: id,
563
- jobsPath: absoluteJobsPath,
564
- executionPath,
565
- runsPath: join(executionPath, "jobs", "runs"),
566
- statePath: join(executionPath, "jobs", "generated", "job-state.json"),
567
- };
568
- }
569
- export function loadJobDefinition(paths, jobId) {
570
- const normalized = jobId.trim();
571
- if (!/^job-[a-z0-9][a-z0-9-]*$/.test(normalized))
572
- throw new Error(`Invalid job id: ${jobId}`);
573
- const candidates = [
574
- join(paths.jobsPath, `${normalized}.yaml`),
575
- join(paths.jobsPath, `${normalized}.yml`),
576
- ];
577
- const filePath = candidates.find(existsSync);
578
- if (!filePath)
579
- throw new Error(`Job not found: ${normalized} (in ${paths.jobsPath})`);
580
- const parsed = parseJobDefinition(yaml.load(readFileSync(filePath, "utf8")), basename(filePath));
581
- if (!parsed.job)
582
- throw new Error(parsed.errors.join("\n"));
583
- return parsed.job;
584
- }
585
- export function loadAllJobs(jobsPath) {
586
- if (!existsSync(jobsPath))
587
- return { jobs: [], errors: [] };
588
- const jobs = [];
589
- const errors = [];
590
- for (const filePath of listFilesRecursive(jobsPath)
591
- .filter((path) => /(?:^|\/)job-[^/]+\.ya?ml$/.test(path))
592
- .sort()) {
593
- try {
594
- const parsed = parseJobDefinition(yaml.load(readFileSync(filePath, "utf8")), basename(filePath));
595
- errors.push(...parsed.errors);
596
- if (parsed.job)
597
- jobs.push(parsed.job);
598
- }
599
- catch (error) {
600
- errors.push(`${basename(filePath)}: ${error instanceof Error ? error.message : String(error)}`);
601
- }
602
- }
603
- return { jobs, errors };
604
- }
605
- export function parseJobInputs(raw) {
606
- const result = {};
607
- for (const token of raw === undefined ? [] : Array.isArray(raw) ? raw : [raw]) {
608
- const index = token.indexOf("=");
609
- if (index <= 0)
610
- throw new Error(`Invalid --input value: ${token}. Use key=value.`);
611
- const key = token.slice(0, index).trim();
612
- if (!/^[a-z][a-z0-9_]*$/.test(key))
613
- throw new Error(`Invalid input key: ${key}`);
614
- if (Object.hasOwn(result, key))
615
- throw new Error(`Duplicate input: ${key}`);
616
- result[key] = token.slice(index + 1);
617
- }
618
- return result;
619
- }
620
- function parseInputValue(value, type, key) {
621
- if (type === "string")
622
- return String(value);
623
- if (type === "integer") {
624
- const parsed = typeof value === "number" ? value : Number(value);
625
- if (!Number.isSafeInteger(parsed))
626
- throw new Error(`Input ${key} must be an integer`);
627
- return parsed;
628
- }
629
- if (type === "boolean") {
630
- if (value === true || value === "true")
631
- return true;
632
- if (value === false || value === "false")
633
- return false;
634
- throw new Error(`Input ${key} must be true or false`);
635
- }
636
- if (Array.isArray(value))
637
- return value.map(String);
638
- return String(value)
639
- .split(",")
640
- .map((item) => item.trim())
641
- .filter(Boolean);
642
- }
643
- function getPath(source, path) {
644
- let current = source;
645
- for (const part of path.split(".")) {
646
- if (!isRecord(current) || !Object.hasOwn(current, part))
647
- return undefined;
648
- current = current[part];
649
- }
650
- return current;
651
- }
652
- function templateValue(value) {
653
- return Array.isArray(value) ? value.join(",") : String(value ?? "");
654
- }
655
- export function renderJobTemplate(template, context) {
656
- return template.replace(/\{\{\s*([a-z_][a-z0-9_.]*)\s*\}\}/gi, (_match, path) => {
657
- if (path === "job_id")
658
- return context.job_id;
659
- if (path === "job_run_id") {
660
- if (!context.job_run_id) {
661
- throw new Error("Job template value job_run_id is unavailable before Run identity exists");
662
- }
663
- return context.job_run_id;
664
- }
665
- if (path === "project_id")
666
- return context.project_id;
667
- if (path === "specdojo")
668
- return context.specdojo;
669
- if (path === "scheduled_at")
670
- return context.scheduled_at;
671
- if (path.startsWith("inputs."))
672
- return templateValue(getPath(context.inputs, path.slice(7)));
673
- if (path.startsWith("checkpoint."))
674
- return templateValue(getPath(context.checkpoint, path.slice(11)));
675
- throw new Error(`Unknown job template value: ${path}`);
676
- });
677
- }
13
+ export { isJobAgentTask, isJobCommandTask, jobDeclaresReview, jobRunUsesReviewedIntegration, loadAllJobs, loadJobDefinition, loadJobRunRecord, parseJobDefinition, parseJobInputs, renderJobTemplate, resolveJobPaths, resolveJobReviewAgentNominations, } from "./job-definition.js";
678
14
  export function jobCheckpoint(paths, jobId) {
679
15
  return deriveJobState(paths).jobs[jobId]?.checkpoint ?? {};
680
16
  }
@@ -686,7 +22,7 @@ export function deriveJobState(paths) {
686
22
  .filter((path) => path.endsWith(".json"))
687
23
  .sort()) {
688
24
  try {
689
- const run = readJobRunRecord(filePath);
25
+ const run = loadJobRunRecord(filePath);
690
26
  if (!run.checkpoint_after || (run.state !== "succeeded" && run.state !== "noop"))
691
27
  continue;
692
28
  const current = state.jobs[run.job_id];
@@ -979,7 +315,7 @@ export async function generateJobReviewPlan(paths, definition, record, opts) {
979
315
  return { planPath, resultPath };
980
316
  }
981
317
  export function recordJobRunReview(runPath, review) {
982
- const record = readJobRunRecord(runPath);
318
+ const record = loadJobRunRecord(runPath);
983
319
  const reviewedAt = review.reviewed_at ?? new Date().toISOString();
984
320
  const updated = {
985
321
  ...record,
@@ -1040,7 +376,7 @@ export async function materializeJobRun(opts) {
1040
376
  const existingRun = existsSync(runPath);
1041
377
  let record;
1042
378
  if (existingRun) {
1043
- record = readJobRunRecord(runPath);
379
+ record = loadJobRunRecord(runPath);
1044
380
  if (record.idempotency_key !== idempotencyKey || record.job_id !== definition.id) {
1045
381
  throw new Error(`Job Run identity collision: ${runId}`);
1046
382
  }
@@ -1111,7 +447,7 @@ export async function materializeJobRun(opts) {
1111
447
  }
1112
448
  export function completeJobRun(opts) {
1113
449
  const paths = resolveJobPaths(opts.projectId);
1114
- const record = readJobRunRecord(opts.runPath);
450
+ const record = loadJobRunRecord(opts.runPath);
1115
451
  const definition = loadJobDefinition(paths, record.job_id);
1116
452
  const completedAt = new Date().toISOString();
1117
453
  const attempts = [...record.attempts];