ai-engineering-loop 1.1.0 → 1.5.0

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 (57) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +5 -5
  2. package/.claude/skills/ai-engineering-loop/SKILL.md +7 -5
  3. package/.gemini/skills/ai-engineering-loop/SKILL.md +7 -5
  4. package/.grok/skills/ai-engineering-loop/SKILL.md +7 -5
  5. package/README.md +56 -6
  6. package/README.npm.md +9 -1
  7. package/SECURITY.md +8 -2
  8. package/agents/judge.md +5 -5
  9. package/agents/maker.md +6 -6
  10. package/agents/recipe-builder.md +28 -0
  11. package/bin/ai-engineering-loop.js +521 -16
  12. package/core/configuration-precedence.md +4 -4
  13. package/core/context-impact-assessment.md +1 -1
  14. package/core/controlled-workflow-runtime.md +77 -0
  15. package/core/definition-of-done.md +3 -3
  16. package/core/escalation-policy.md +2 -2
  17. package/core/goal-contract.md +2 -2
  18. package/core/iteration-policy.md +4 -4
  19. package/core/project-initialization.md +2 -2
  20. package/core/runtime-safety.md +75 -0
  21. package/core/verification-loop.md +1 -1
  22. package/core/workflow-recipes.md +140 -0
  23. package/lib/budget.js +258 -0
  24. package/lib/doctor.js +38 -2
  25. package/lib/gates.js +55 -1
  26. package/lib/node-registry.js +155 -0
  27. package/lib/package-audit.js +78 -0
  28. package/lib/recipe-builder.js +200 -0
  29. package/lib/recipe.js +495 -0
  30. package/lib/run-state.js +94 -8
  31. package/lib/runtime-files.js +54 -0
  32. package/lib/runtime-policy.js +118 -0
  33. package/lib/safe-context.js +3 -0
  34. package/lib/sandbox.js +305 -0
  35. package/lib/workflow-runtime.js +692 -0
  36. package/package.json +7 -3
  37. package/policies/finding-policy.md +2 -2
  38. package/policies/no-progress-policy.md +2 -2
  39. package/profiles/README.md +5 -5
  40. package/profiles/backend-api.md +1 -1
  41. package/profiles/library.md +1 -1
  42. package/profiles/mobile-app.md +1 -1
  43. package/profiles/monorepo.md +1 -1
  44. package/profiles/web-app.md +1 -1
  45. package/recipes/audit.json +32 -0
  46. package/recipes/bugfix.json +63 -0
  47. package/recipes/default.json +49 -0
  48. package/recipes/docs-light.json +63 -0
  49. package/recipes/high-risk.json +69 -0
  50. package/recipes/refactor.json +63 -0
  51. package/schemas/compiled-plan.schema.json +19 -0
  52. package/schemas/delivery.schema.json +2 -1
  53. package/schemas/node-definition.schema.json +33 -0
  54. package/schemas/recipe.schema.json +26 -0
  55. package/schemas/report.schema.json +17 -0
  56. package/schemas/workflow-event.schema.json +28 -0
  57. package/schemas/workflow-state.schema.json +29 -0
package/lib/doctor.js CHANGED
@@ -3,6 +3,8 @@
3
3
  const fs = require('fs');
4
4
  const path = require('path');
5
5
  const { loadEvaluationCases } = require('./evaluation.js');
6
+ const { auditPackage } = require('./package-audit.js');
7
+ const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
6
8
 
7
9
  const REQUIRED_HOST_ASSETS = [
8
10
  '.claude/skills/ai-engineering-loop/SKILL.md',
@@ -22,7 +24,13 @@ const REQUIRED_SCHEMAS = [
22
24
  'verification.schema.json',
23
25
  'finding-ledger.schema.json',
24
26
  'verdict.schema.json',
25
- 'delivery.schema.json'
27
+ 'delivery.schema.json',
28
+ 'report.schema.json',
29
+ 'recipe.schema.json',
30
+ 'node-definition.schema.json',
31
+ 'compiled-plan.schema.json',
32
+ 'workflow-state.schema.json',
33
+ 'workflow-event.schema.json'
26
34
  ];
27
35
 
28
36
  function check(id, passed, detail) {
@@ -64,6 +72,23 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
64
72
  schemaErrors.length ? schemaErrors.join('; ') : `${REQUIRED_SCHEMAS.length} schemas parse`
65
73
  ));
66
74
 
75
+ try {
76
+ const recipes = listRecipes(rootDir).filter(({ source }) => source === 'builtin');
77
+ const recipeErrors = recipes.flatMap(({ id }) => {
78
+ const { recipe } = loadRecipe(rootDir, id);
79
+ return recipe.compatibleModes.flatMap((mode) => (
80
+ validateRecipe(recipe, { mode }).errors.map((error) => `${id} (${mode}): ${error}`)
81
+ ));
82
+ });
83
+ checks.push(check(
84
+ 'workflow-recipes',
85
+ recipes.length > 0 && recipeErrors.length === 0,
86
+ recipeErrors.length ? recipeErrors.join('; ') : `${recipes.length} built-in recipes validate`
87
+ ));
88
+ } catch (cause) {
89
+ checks.push(check('workflow-recipes', false, cause.message));
90
+ }
91
+
67
92
  try {
68
93
  const fixtures = loadEvaluationCases(path.join(rootDir, 'evals', 'cases'));
69
94
  checks.push(check('evaluation-catalog', fixtures.length === 20, `${fixtures.length} valid cases; required 20`));
@@ -72,7 +97,7 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
72
97
  }
73
98
 
74
99
  const packageFiles = new Set(pkg.files || []);
75
- const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'schemas/', 'evals/'];
100
+ const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/'];
76
101
  const missingPackageEntries = requiredPackageEntries.filter((entry) => !packageFiles.has(entry));
77
102
  checks.push(check(
78
103
  'package-assets',
@@ -80,6 +105,17 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
80
105
  missingPackageEntries.length ? `not packed: ${missingPackageEntries.join(', ')}` : 'runtime assets are allowlisted'
81
106
  ));
82
107
 
108
+ try {
109
+ const audit = auditPackage(rootDir);
110
+ checks.push(check(
111
+ 'package-privacy',
112
+ audit.ok,
113
+ audit.ok ? `${audit.filesScanned} packaged files scanned` : audit.findings.map((item) => `${item.file}: ${item.reason}`).join('; ')
114
+ ));
115
+ } catch (cause) {
116
+ checks.push(check('package-privacy', false, cause.message));
117
+ }
118
+
83
119
  const binPath = path.join(rootDir, 'bin', 'ai-engineering-loop.js');
84
120
  const executable = fs.existsSync(binPath) &&
85
121
  (process.platform === 'win32' || (fs.statSync(binPath).mode & 0o111) !== 0);
package/lib/gates.js CHANGED
@@ -10,18 +10,23 @@ const {
10
10
  } = require('./orchestration.js');
11
11
  const {
12
12
  RUN_STATES,
13
+ RUN_MODES,
13
14
  getCurrentRun,
14
15
  getGitRevision,
15
16
  loadRun,
16
17
  runsDir,
17
18
  transitionRun
18
19
  } = require('./run-state.js');
20
+ const {
21
+ assertModeAllowed
22
+ } = require('./runtime-policy.js');
19
23
  const {
20
24
  enforceVerdictTier
21
25
  } = require('./escalation.js');
22
26
 
23
27
  const GATE_FILES = Object.freeze({
24
28
  goal: 'goal-contract.json',
29
+ report: 'report.json',
25
30
  maker: 'diff.patch',
26
31
  verification: 'verification.json',
27
32
  review: 'findings.json',
@@ -181,6 +186,8 @@ function applyGate(rootDir, gate, { runId } = {}) {
181
186
  throw gateError(`Unknown gate: ${gate}. Use ${Object.keys(GATE_FILES).join('|')}`);
182
187
  }
183
188
  const run = resolveRun(rootDir, runId);
189
+ const mode = run.mode || RUN_MODES.ASSISTED;
190
+ const policy = assertModeAllowed(rootDir, mode);
184
191
 
185
192
  if (gate === 'goal') {
186
193
  const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal);
@@ -193,7 +200,29 @@ function applyGate(rootDir, gate, { runId } = {}) {
193
200
  });
194
201
  }
195
202
 
203
+ if (gate === 'report') {
204
+ if (mode !== RUN_MODES.REPORT_ONLY) {
205
+ throw gateError('Report gate is only available in REPORT_ONLY mode');
206
+ }
207
+ const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.report);
208
+ requireRunMetadata(value, run, 'report');
209
+ const reportErrors = [];
210
+ if (!String(value.summary || '').trim()) reportErrors.push('summary is required');
211
+ if (!Array.isArray(value.recommendations)) reportErrors.push('recommendations must be an array');
212
+ else if (value.recommendations.some((item) => !String(item || '').trim())) {
213
+ reportErrors.push('recommendations must contain non-empty strings');
214
+ }
215
+ if (reportErrors.length) throw gateError('Report gate failed', reportErrors);
216
+ return transitionRun(rootDir, run.runId, RUN_STATES.REPORTED, {
217
+ gate,
218
+ artifacts: { report: descriptor(rootDir, filePath) }
219
+ });
220
+ }
221
+
196
222
  if (gate === 'maker') {
223
+ if (mode === RUN_MODES.REPORT_ONLY) {
224
+ throw gateError('REPORT_ONLY mode cannot enter the Maker stage; finish with the report gate');
225
+ }
197
226
  const filePath = artifactPath(rootDir, run.runId, GATE_FILES.maker);
198
227
  let diff;
199
228
  try {
@@ -202,9 +231,31 @@ function applyGate(rootDir, gate, { runId } = {}) {
202
231
  throw gateError(`Missing ${GATE_FILES.maker}: ${cause.message}`);
203
232
  }
204
233
  if (!diff.trim()) throw gateError('Maker gate failed: diff.patch is empty');
234
+ const artifacts = { diff: descriptor(rootDir, filePath) };
235
+ if (mode === RUN_MODES.UNATTENDED && policy.requireSandboxForUnattended) {
236
+ const { filePath: sandboxFile, value: evidence } = readJsonArtifact(
237
+ rootDir,
238
+ run.runId,
239
+ 'sandbox-evidence.json'
240
+ );
241
+ const sandboxErrors = [];
242
+ requireRunMetadata(evidence, run, 'sandbox evidence');
243
+ if (evidence.sandboxed !== true) sandboxErrors.push('sandboxed must be true');
244
+ if (!/^[a-f0-9]{40,64}$/.test(String(evidence.baseRevision || ''))) {
245
+ sandboxErrors.push('baseRevision must be a Git revision');
246
+ }
247
+ if (evidence.baseRevision !== run.startedRevision) {
248
+ sandboxErrors.push('baseRevision does not match the run starting revision');
249
+ }
250
+ if (evidence.diffSha256 !== hashFile(filePath)) {
251
+ sandboxErrors.push('diffSha256 does not match the captured Maker diff');
252
+ }
253
+ if (sandboxErrors.length) throw gateError('Unattended Maker sandbox evidence failed', sandboxErrors);
254
+ artifacts.sandboxEvidence = descriptor(rootDir, sandboxFile);
255
+ }
205
256
  return transitionRun(rootDir, run.runId, RUN_STATES.MAKER_COMPLETE, {
206
257
  gate,
207
- artifacts: { diff: descriptor(rootDir, filePath) }
258
+ artifacts
208
259
  });
209
260
  }
210
261
 
@@ -295,6 +346,9 @@ function applyGate(rootDir, gate, { runId } = {}) {
295
346
  const deliveryErrors = [];
296
347
  if (!String(value.destination || '').trim()) deliveryErrors.push('destination is required');
297
348
  if (!String(value.summary || '').trim()) deliveryErrors.push('summary is required');
349
+ if (mode === RUN_MODES.ASSISTED && value.humanApproved !== true) {
350
+ deliveryErrors.push('humanApproved must be true for ASSISTED delivery');
351
+ }
298
352
  if (deliveryErrors.length) throw gateError('Delivery gate failed', deliveryErrors);
299
353
  return transitionRun(rootDir, run.runId, RUN_STATES.DELIVERED, {
300
354
  gate,
@@ -0,0 +1,155 @@
1
+ 'use strict';
2
+
3
+ const NODE_TYPES = Object.freeze({
4
+ 'goal-contract': Object.freeze({
5
+ label: 'Goal Contract',
6
+ category: 'safety',
7
+ builtIn: true,
8
+ mutation: false,
9
+ sideEffect: false,
10
+ modelRequired: false,
11
+ legacyGate: 'goal'
12
+ }),
13
+ agent: Object.freeze({
14
+ label: 'Agent Analysis',
15
+ category: 'custom',
16
+ builtIn: false,
17
+ mutation: false,
18
+ sideEffect: false,
19
+ modelRequired: true
20
+ }),
21
+ command: Object.freeze({
22
+ label: 'Deterministic Command',
23
+ category: 'custom',
24
+ builtIn: false,
25
+ mutation: true,
26
+ sideEffect: false,
27
+ modelRequired: false
28
+ }),
29
+ condition: Object.freeze({
30
+ label: 'Condition',
31
+ category: 'control',
32
+ builtIn: false,
33
+ mutation: false,
34
+ sideEffect: false,
35
+ modelRequired: false
36
+ }),
37
+ approval: Object.freeze({
38
+ label: 'Human Approval',
39
+ category: 'safety',
40
+ builtIn: false,
41
+ mutation: false,
42
+ sideEffect: false,
43
+ modelRequired: false
44
+ }),
45
+ 'artifact-check': Object.freeze({
46
+ label: 'Artifact Check',
47
+ category: 'control',
48
+ builtIn: false,
49
+ mutation: false,
50
+ sideEffect: false,
51
+ modelRequired: false
52
+ }),
53
+ maker: Object.freeze({
54
+ label: 'Maker',
55
+ category: 'safety',
56
+ builtIn: true,
57
+ mutation: true,
58
+ sideEffect: false,
59
+ modelRequired: true,
60
+ legacyGate: 'maker'
61
+ }),
62
+ verification: Object.freeze({
63
+ label: 'Verification',
64
+ category: 'safety',
65
+ builtIn: true,
66
+ mutation: false,
67
+ sideEffect: false,
68
+ modelRequired: false,
69
+ legacyGate: 'verification'
70
+ }),
71
+ 'devil-advocate': Object.freeze({
72
+ label: "Devil's Advocate",
73
+ category: 'safety',
74
+ builtIn: true,
75
+ mutation: false,
76
+ sideEffect: false,
77
+ modelRequired: true,
78
+ legacyGate: 'review'
79
+ }),
80
+ judge: Object.freeze({
81
+ label: 'Judge',
82
+ category: 'safety',
83
+ builtIn: true,
84
+ mutation: false,
85
+ sideEffect: false,
86
+ modelRequired: true,
87
+ legacyGate: 'judge'
88
+ }),
89
+ report: Object.freeze({
90
+ label: 'Report',
91
+ category: 'terminal',
92
+ builtIn: true,
93
+ mutation: false,
94
+ sideEffect: false,
95
+ modelRequired: false,
96
+ legacyGate: 'report'
97
+ }),
98
+ delivery: Object.freeze({
99
+ label: 'Delivery',
100
+ category: 'terminal',
101
+ builtIn: true,
102
+ mutation: false,
103
+ sideEffect: true,
104
+ modelRequired: false,
105
+ legacyGate: 'delivery'
106
+ })
107
+ });
108
+
109
+ const CONDITION_OPERATORS = Object.freeze([
110
+ 'equals',
111
+ 'notEquals',
112
+ 'contains',
113
+ 'matchesAny',
114
+ 'exists',
115
+ 'isEmpty',
116
+ 'greaterThan',
117
+ 'lessThan'
118
+ ]);
119
+
120
+ const CONDITION_FIELDS = Object.freeze([
121
+ 'run.mode',
122
+ 'run.state',
123
+ 'run.iteration',
124
+ 'run.task'
125
+ ]);
126
+
127
+ const FORBIDDEN_COMMANDS = new Set([
128
+ 'sh',
129
+ 'bash',
130
+ 'zsh',
131
+ 'fish',
132
+ 'cmd',
133
+ 'cmd.exe',
134
+ 'powershell',
135
+ 'powershell.exe',
136
+ 'pwsh',
137
+ 'node',
138
+ 'node.exe',
139
+ 'python',
140
+ 'python3',
141
+ 'ruby',
142
+ 'perl'
143
+ ]);
144
+
145
+ function getNodeType(type) {
146
+ return NODE_TYPES[type] || null;
147
+ }
148
+
149
+ module.exports = {
150
+ NODE_TYPES,
151
+ CONDITION_OPERATORS,
152
+ CONDITION_FIELDS,
153
+ FORBIDDEN_COMMANDS,
154
+ getNodeType
155
+ };
@@ -0,0 +1,78 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ const TEXT_EXTENSIONS = new Set(['.js', '.json', '.md', '.yml', '.yaml', '.txt']);
7
+ const LOCAL_FILE_URL = new RegExp(`file:${'/'.repeat(3)}`, 'i');
8
+ const MAC_HOME = /\/Users\/(?!\.\.\.\/|<[^>]+>\/)[a-z0-9._-]+\//i;
9
+ const LINUX_HOME = /\/home\/(?!\.\.\.\/|<[^>]+>\/)[a-z0-9._-]+\//i;
10
+ const WINDOWS_HOME = /[a-z]:\\Users\\(?!\.\.\.\\|<[^>]+>\\)[^\\\r\n]+\\/i;
11
+ const PRIVATE_KEY = /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/;
12
+
13
+ const PRIVACY_PATTERNS = Object.freeze([
14
+ { label: 'local file URL', pattern: LOCAL_FILE_URL },
15
+ { label: 'macOS user home', pattern: MAC_HOME },
16
+ { label: 'Linux user home', pattern: LINUX_HOME },
17
+ { label: 'Windows user home', pattern: WINDOWS_HOME },
18
+ { label: 'private key material', pattern: PRIVATE_KEY }
19
+ ]);
20
+
21
+ function walkFiles(rootDir, relativePath, files) {
22
+ const absolute = path.join(rootDir, relativePath);
23
+ if (!fs.existsSync(absolute)) return;
24
+ const stat = fs.lstatSync(absolute);
25
+ if (stat.isSymbolicLink()) return;
26
+ if (stat.isFile()) {
27
+ files.add(relativePath.split(path.sep).join('/'));
28
+ return;
29
+ }
30
+ if (!stat.isDirectory()) return;
31
+ for (const entry of fs.readdirSync(absolute)) {
32
+ walkFiles(rootDir, path.join(relativePath, entry), files);
33
+ }
34
+ }
35
+
36
+ function listPackageFiles(rootDir) {
37
+ const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'));
38
+ const files = new Set(['package.json']);
39
+ for (const entry of pkg.files || []) {
40
+ walkFiles(rootDir, entry.replace(/\/$/, ''), files);
41
+ }
42
+ for (const entry of fs.readdirSync(rootDir)) {
43
+ if (/^(?:readme|license|licence|security|support)(?:\.|$)/i.test(entry)) {
44
+ walkFiles(rootDir, entry, files);
45
+ }
46
+ }
47
+ return [...files].sort();
48
+ }
49
+
50
+ function auditText(content, relativePath) {
51
+ const findings = [];
52
+ for (const { label, pattern } of PRIVACY_PATTERNS) {
53
+ if (pattern.test(content)) findings.push({ file: relativePath, reason: label });
54
+ }
55
+ return findings;
56
+ }
57
+
58
+ function auditPackage(rootDir) {
59
+ const files = listPackageFiles(rootDir);
60
+ const findings = [];
61
+ for (const relativePath of files) {
62
+ if (!TEXT_EXTENSIONS.has(path.extname(relativePath).toLowerCase())) continue;
63
+ const content = fs.readFileSync(path.join(rootDir, relativePath), 'utf8');
64
+ findings.push(...auditText(content, relativePath));
65
+ }
66
+ return {
67
+ ok: findings.length === 0,
68
+ filesScanned: files.length,
69
+ findings
70
+ };
71
+ }
72
+
73
+ module.exports = {
74
+ PRIVACY_PATTERNS,
75
+ listPackageFiles,
76
+ auditText,
77
+ auditPackage
78
+ };
@@ -0,0 +1,200 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const crypto = require('crypto');
6
+ const { NODE_TYPES } = require('./node-registry.js');
7
+ const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
8
+ const {
9
+ RECIPE_ID,
10
+ canonicalJson,
11
+ compileRecipe,
12
+ listRecipes,
13
+ loadRecipe,
14
+ sha256,
15
+ validateRecipe
16
+ } = require('./recipe.js');
17
+
18
+ function builderError(message, code = 'RECIPE_BUILDER_FAILED', details = []) {
19
+ const error = new Error(message);
20
+ error.code = code;
21
+ error.details = details;
22
+ return error;
23
+ }
24
+
25
+ function recipeDirectory(rootDir) {
26
+ return path.join(rootDir, '.ai-engineering-loop', 'recipes');
27
+ }
28
+
29
+ function assertSafeDirectory(rootDir, directory) {
30
+ const relative = path.relative(rootDir, directory);
31
+ let current = rootDir;
32
+ for (const segment of relative.split(path.sep).filter(Boolean)) {
33
+ current = path.join(current, segment);
34
+ if (!fs.existsSync(current)) continue;
35
+ const stat = fs.lstatSync(current);
36
+ if (stat.isSymbolicLink() || !stat.isDirectory()) {
37
+ throw builderError(`${path.relative(rootDir, current)} must be a regular directory`, 'UNSAFE_RECIPE_PATH');
38
+ }
39
+ }
40
+ }
41
+
42
+ function atomicWriteJson(filePath, value, { replace = false } = {}) {
43
+ if (!replace && fs.existsSync(filePath)) {
44
+ throw builderError(`Recipe already exists: ${path.basename(filePath, '.json')}`, 'RECIPE_EXISTS');
45
+ }
46
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
47
+ const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
48
+ try {
49
+ fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
50
+ fs.renameSync(temporary, filePath);
51
+ } finally {
52
+ try { fs.unlinkSync(temporary); } catch {}
53
+ }
54
+ }
55
+
56
+ function assertProjectId(rootDir, id) {
57
+ if (!RECIPE_ID.test(String(id || ''))) throw builderError(`Invalid recipe id: ${id || '(empty)'}`, 'INVALID_RECIPE');
58
+ if (listRecipes(rootDir).some((entry) => entry.id === id && entry.source === 'builtin')) {
59
+ throw builderError(`Built-in recipe id is reserved: ${id}`, 'RESERVED_RECIPE_ID');
60
+ }
61
+ }
62
+
63
+ function validateCandidate(recipe) {
64
+ const result = validateRecipe(recipe);
65
+ if (!result.valid) throw builderError(`Recipe ${recipe?.id || '(unknown)'} is invalid`, 'INVALID_RECIPE', result.errors);
66
+ return result;
67
+ }
68
+
69
+ function cloneRecipe(rootDir, sourceId, targetId, { description } = {}) {
70
+ assertProjectId(rootDir, targetId);
71
+ const source = loadRecipe(rootDir, sourceId).recipe;
72
+ const candidate = {
73
+ ...JSON.parse(JSON.stringify(source)),
74
+ id: targetId,
75
+ version: 1,
76
+ description: description || `Project workflow based on ${sourceId}.`
77
+ };
78
+ validateCandidate(candidate);
79
+ ensurePrivateRuntimeIgnores(rootDir);
80
+ const directory = recipeDirectory(rootDir);
81
+ assertSafeDirectory(rootDir, directory);
82
+ const filePath = path.join(directory, `${targetId}.json`);
83
+ atomicWriteJson(filePath, candidate);
84
+ return { recipe: candidate, path: filePath, sourceHash: sha256(candidate) };
85
+ }
86
+
87
+ function readCandidate(rootDir, candidatePath) {
88
+ const absolute = path.resolve(rootDir, candidatePath);
89
+ if (path.relative(rootDir, absolute).split(path.sep).includes('..')) {
90
+ throw builderError('Candidate must stay inside the repository', 'UNSAFE_RECIPE_PATH');
91
+ }
92
+ assertSafeDirectory(rootDir, path.dirname(absolute));
93
+ const realRoot = fs.realpathSync(rootDir);
94
+ const realFile = fs.realpathSync(absolute);
95
+ if (!realFile.startsWith(`${realRoot}${path.sep}`)) {
96
+ throw builderError('Candidate must stay inside the repository', 'UNSAFE_RECIPE_PATH');
97
+ }
98
+ const stat = fs.lstatSync(absolute);
99
+ if (stat.isSymbolicLink() || !stat.isFile()) {
100
+ throw builderError('Candidate must be a regular file', 'UNSAFE_RECIPE_PATH');
101
+ }
102
+ try {
103
+ return JSON.parse(fs.readFileSync(absolute, 'utf8'));
104
+ } catch (cause) {
105
+ throw builderError(`Candidate JSON is invalid: ${cause.message}`, 'INVALID_RECIPE_JSON');
106
+ }
107
+ }
108
+
109
+ function installRecipe(rootDir, candidatePath, { replace = false } = {}) {
110
+ const candidate = readCandidate(rootDir, candidatePath);
111
+ assertProjectId(rootDir, candidate.id);
112
+ validateCandidate(candidate);
113
+ ensurePrivateRuntimeIgnores(rootDir);
114
+ const directory = recipeDirectory(rootDir);
115
+ assertSafeDirectory(rootDir, directory);
116
+ const destination = path.join(directory, `${candidate.id}.json`);
117
+ let previous = null;
118
+ if (fs.existsSync(destination)) {
119
+ previous = loadRecipe(rootDir, candidate.id).recipe;
120
+ if (!replace) throw builderError(`Recipe already exists: ${candidate.id}`, 'RECIPE_EXISTS');
121
+ if (candidate.version <= previous.version) {
122
+ throw builderError(
123
+ `Replacement version must be greater than ${previous.version}`,
124
+ 'RECIPE_VERSION_NOT_INCREMENTED'
125
+ );
126
+ }
127
+ const history = path.join(directory, '.history', candidate.id, `${previous.version}.json`);
128
+ assertSafeDirectory(rootDir, path.dirname(history));
129
+ if (!fs.existsSync(history)) atomicWriteJson(history, previous);
130
+ }
131
+ atomicWriteJson(destination, candidate, { replace: Boolean(previous) });
132
+ return {
133
+ recipe: candidate,
134
+ path: destination,
135
+ sourceHash: sha256(candidate),
136
+ replacedVersion: previous?.version || null
137
+ };
138
+ }
139
+
140
+ function recipeCatalog() {
141
+ return Object.entries(NODE_TYPES).map(([type, definition]) => ({
142
+ type,
143
+ label: definition.label,
144
+ category: definition.category,
145
+ capabilities: {
146
+ repositoryMutation: definition.mutation,
147
+ remoteSideEffect: definition.sideEffect,
148
+ modelRequired: definition.modelRequired
149
+ },
150
+ executable: type !== 'command'
151
+ }));
152
+ }
153
+
154
+ function inspectRecipe(rootDir, id) {
155
+ const loaded = loadRecipe(rootDir, id);
156
+ const plans = loaded.recipe.compatibleModes.map((mode) => compileRecipe(loaded.recipe, { mode }));
157
+ return {
158
+ id,
159
+ source: loaded.source,
160
+ version: loaded.recipe.version,
161
+ description: loaded.recipe.description,
162
+ sourceHash: sha256(loaded.recipe),
163
+ modes: plans.map((plan) => ({
164
+ mode: plan.mode,
165
+ graphHash: plan.graphHash,
166
+ nodes: plan.nodes.length,
167
+ modelCalls: plan.nodes.filter((node) => node.capabilities.modelRequired).length,
168
+ mutations: plan.nodes.filter((node) => node.capabilities.repositoryMutation).length,
169
+ remoteSideEffects: plan.nodes.filter((node) => node.capabilities.remoteSideEffect).length,
170
+ approvals: plan.nodes.filter((node) => node.type === 'approval').length,
171
+ declaredTokenCeiling: plan.nodes.reduce((sum, node) => sum + (node.context?.maxTokens || 0), 0)
172
+ }))
173
+ };
174
+ }
175
+
176
+ function diffRecipes(rootDir, leftId, rightId) {
177
+ const left = loadRecipe(rootDir, leftId).recipe;
178
+ const right = loadRecipe(rootDir, rightId).recipe;
179
+ const leftNodes = new Map(left.nodes.map((node) => [node.id, node]));
180
+ const rightNodes = new Map(right.nodes.map((node) => [node.id, node]));
181
+ return {
182
+ left: { id: left.id, version: left.version, sourceHash: sha256(left) },
183
+ right: { id: right.id, version: right.version, sourceHash: sha256(right) },
184
+ metadataChanged: left.description !== right.description ||
185
+ canonicalJson(left.compatibleModes) !== canonicalJson(right.compatibleModes),
186
+ added: [...rightNodes.keys()].filter((id) => !leftNodes.has(id)),
187
+ removed: [...leftNodes.keys()].filter((id) => !rightNodes.has(id)),
188
+ changed: [...rightNodes.keys()].filter((id) => (
189
+ leftNodes.has(id) && canonicalJson(leftNodes.get(id)) !== canonicalJson(rightNodes.get(id))
190
+ ))
191
+ };
192
+ }
193
+
194
+ module.exports = {
195
+ cloneRecipe,
196
+ installRecipe,
197
+ recipeCatalog,
198
+ inspectRecipe,
199
+ diffRecipes
200
+ };