ai-engineering-loop 1.2.1 → 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.
@@ -0,0 +1,140 @@
1
+ # Declarative Workflow Recipes
2
+
3
+ Workflow recipes describe a directed acyclic graph of engineering stages in JSON. They are an additive authoring layer over the existing AI Engineering Loop: `recipe` commands provide deterministic validation and inspection, while `run --recipe` opts into the controlled runtime. Runs without a recipe keep their established behavior.
4
+
5
+ This separation is deliberate. A visual editor or an AI agent may eventually author the JSON, but the compiler—not the authoring interface—owns safety invariants.
6
+
7
+ ## Sources and precedence
8
+
9
+ Recipes are loaded from two locations:
10
+
11
+ 1. Package presets in `recipes/*.json`
12
+ 2. Project recipes in `.ai-engineering-loop/recipes/*.json`
13
+
14
+ Built-in IDs are reserved and cannot be shadowed by a project file. Recipe IDs and node IDs use lowercase letters, numbers, and hyphens. Recipe files and the project recipe directory must be regular filesystem entries; symlinks are rejected.
15
+
16
+ The package includes:
17
+
18
+ | Recipe | Purpose | Modes |
19
+ | --- | --- | --- |
20
+ | `default` | Existing production safety loop | `ASSISTED`, `UNATTENDED` |
21
+ | `audit` | Read-only structured analysis | `REPORT_ONLY` |
22
+ | `bugfix` | Root-cause-first repair | `ASSISTED`, `UNATTENDED` |
23
+ | `docs-light` | Bounded documentation change | `ASSISTED`, `UNATTENDED` |
24
+ | `high-risk` | Blast-radius analysis and pre-mutation approval | `ASSISTED`, `UNATTENDED` |
25
+ | `refactor` | Behavior-baseline-first refactor | `ASSISTED`, `UNATTENDED` |
26
+
27
+ ## Safety backbone
28
+
29
+ The graph compiler fails closed.
30
+
31
+ - `REPORT_ONLY` requires `goal-contract → ... → report` and rejects every mutation or remote-side-effect node.
32
+ - `ASSISTED` and `UNATTENDED` require the ordered backbone `goal-contract → maker → verification → devil-advocate → judge → delivery`.
33
+ - `ASSISTED` additionally requires human approval after Judge and before delivery.
34
+ - Required safety nodes cannot be conditional.
35
+ - `report` and `delivery` are graph terminals. Every node must lead to one terminal.
36
+ - Cycles, duplicate singleton safety nodes, missing dependencies, unknown node types, and incompatible modes are invalid.
37
+
38
+ Dependencies may include additional nodes between required stages. A custom analysis node before `maker`, for example, does not weaken the mandatory backbone.
39
+
40
+ ## Node catalog
41
+
42
+ | Type | Intended use | Model | Repository mutation | Remote side effect |
43
+ | --- | --- | ---: | ---: | ---: |
44
+ | `goal-contract` | Acceptance contract | No | No | No |
45
+ | `agent` | Bounded structured analysis | Yes | No | No |
46
+ | `command` | Trusted repository executable | No | No | No |
47
+ | `condition` | Structured branch predicate | No | No | No |
48
+ | `approval` | Human checkpoint | No | No | No |
49
+ | `artifact-check` | Deterministic artifact assertion | No | No | No |
50
+ | `maker` | Implementation | Yes | Yes | No |
51
+ | `verification` | Evidence collection | No | No | No |
52
+ | `devil-advocate` | Adversarial review | Yes | No | No |
53
+ | `judge` | Independent verdict | Yes | No | No |
54
+ | `report` | Read-only terminal | No | No | No |
55
+ | `delivery` | Delivery terminal | No | No | Yes |
56
+
57
+ An `agent` node must declare a role, bounded `maxFiles` and `maxTokens`, and a repository-relative output schema. A `command` node must use a bare executable name, an argument array, a bounded timeout, and expected exit codes. Shells and general-purpose interpreters are rejected; command nodes are for trusted repository tools, not arbitrary script text.
58
+
59
+ ## Authoring example
60
+
61
+ Project recipe:
62
+
63
+ ```json
64
+ {
65
+ "schemaVersion": 1,
66
+ "id": "api-bugfix",
67
+ "version": 1,
68
+ "description": "Analyze an API regression before entering the standard repair loop.",
69
+ "compatibleModes": ["ASSISTED"],
70
+ "nodes": [
71
+ { "id": "goal", "type": "goal-contract" },
72
+ {
73
+ "id": "api-analysis",
74
+ "type": "agent",
75
+ "dependsOn": ["goal"],
76
+ "role": "api-regression-analyst",
77
+ "context": { "maxFiles": 25, "maxTokens": 8000 },
78
+ "output": {
79
+ "artifact": "api-analysis",
80
+ "schema": "schemas/report.schema.json"
81
+ }
82
+ },
83
+ { "id": "maker", "type": "maker", "dependsOn": ["api-analysis"] },
84
+ { "id": "verification", "type": "verification", "dependsOn": ["maker"] },
85
+ { "id": "review", "type": "devil-advocate", "dependsOn": ["verification"] },
86
+ { "id": "judge", "type": "judge", "dependsOn": ["review"] },
87
+ {
88
+ "id": "approval",
89
+ "type": "approval",
90
+ "dependsOn": ["judge"],
91
+ "message": "Approve delivery."
92
+ },
93
+ { "id": "delivery", "type": "delivery", "dependsOn": ["approval"] }
94
+ ]
95
+ }
96
+ ```
97
+
98
+ Validate and inspect it:
99
+
100
+ ```bash
101
+ ai-engineering-loop recipe validate api-bugfix --mode assisted
102
+ ai-engineering-loop recipe explain api-bugfix --mode assisted
103
+ ai-engineering-loop recipe graph api-bugfix --mode assisted
104
+ ai-engineering-loop recipe simulate api-bugfix --mode assisted
105
+ ```
106
+
107
+ `simulate` compiles the graph and reports capability counts. It never calls a model, mutates the repository, executes a command, or performs delivery.
108
+
109
+ ## AI-assisted authoring protocol
110
+
111
+ Until a visual editor exists, an AI agent can safely act as the recipe builder:
112
+
113
+ 1. Ask the user for the outcome, allowed run modes, required checkpoints, context limits, and delivery risk.
114
+ 2. Start from the closest built-in preset rather than a blank graph.
115
+ 3. Add only nodes that change the workflow meaningfully.
116
+ 4. Write the candidate to `.ai-engineering-loop/recipes/<id>.json`.
117
+ 5. Run `recipe validate`, `recipe explain`, `recipe graph`, and `recipe simulate`.
118
+ 6. Present the explanation, graph hash, warnings, and capability counts for human confirmation.
119
+ 7. Do not claim execution from validation or simulation. Execution is proven only by a recipe-bound run and its validated event chain.
120
+
121
+ Machine consumers should use `--json`. The compiled plan includes a canonical source hash and graph hash so execution and audit logs bind to the exact graph reviewed by the user. Runtime behavior is specified in `core/controlled-workflow-runtime.md`.
122
+
123
+ The CLI supports safe scaffolding and installation:
124
+
125
+ ```bash
126
+ ai-engineering-loop recipe create api-bugfix --from bugfix
127
+ ai-engineering-loop recipe inspect api-bugfix --json
128
+ ai-engineering-loop recipe diff bugfix api-bugfix
129
+ ai-engineering-loop recipe install candidate-v2.json --replace
130
+ ```
131
+
132
+ Creation never overwrites an existing recipe. Installation validates before writing, reserves built-in IDs, requires `--replace` plus a strictly higher version, and stores the previous document under `.ai-engineering-loop/recipes/.history/<id>/`. Candidate paths and recipe stores reject filesystem escape and symlink traversal.
133
+
134
+ ## Schemas
135
+
136
+ - `schemas/recipe.schema.json`: top-level authoring document
137
+ - `schemas/node-definition.schema.json`: node shape and type catalog
138
+ - `schemas/compiled-plan.schema.json`: deterministic compiler output
139
+
140
+ Semantic safety checks are stricter than JSON Schema and are enforced by `recipe validate` and the compiler.
package/lib/budget.js CHANGED
@@ -69,6 +69,9 @@ function readUsageFile(filePath) {
69
69
  throw new Error('totalTokens does not equal inputTokens + outputTokens');
70
70
  }
71
71
  validateModel(entry.model);
72
+ if (entry.nodeId != null && !/^[a-z][a-z0-9-]{0,63}$/.test(entry.nodeId)) {
73
+ throw new Error('nodeId is invalid');
74
+ }
72
75
  if (typeof entry.recordedAt !== 'string' || Number.isNaN(Date.parse(entry.recordedAt))) {
73
76
  throw new Error('recordedAt is invalid');
74
77
  }
@@ -107,7 +110,7 @@ function resolveRun(rootDir, runId) {
107
110
  return current;
108
111
  }
109
112
 
110
- function budgetStatus(rootDir, { runId, estimatedTokens = 0, now = new Date() } = {}) {
113
+ function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new Date() } = {}) {
111
114
  validateTokenCount('estimatedTokens', estimatedTokens);
112
115
  const run = resolveRun(rootDir, runId);
113
116
  const policy = loadPolicy(rootDir);
@@ -120,6 +123,30 @@ function budgetStatus(rootDir, { runId, estimatedTokens = 0, now = new Date() }
120
123
  const projectedToday = spentToday + estimatedTokens;
121
124
  const projectedThisRun = spentThisRun + estimatedTokens;
122
125
  const reasons = [];
126
+ let node = null;
127
+ let spentThisNode = 0;
128
+ let nodeTokenLimit = null;
129
+ if (nodeId) {
130
+ const { workflowStatus, NODE_STATES } = require('./workflow-runtime.js');
131
+ const workflow = workflowStatus(rootDir, { runId: run.runId });
132
+ node = workflow.plan.nodes.find((candidate) => candidate.id === nodeId);
133
+ if (!node) throw usageError(`Unknown workflow node: ${nodeId}`);
134
+ if (!node.capabilities.modelRequired) reasons.push(`node ${nodeId} does not permit model usage`);
135
+ const status = workflow.state.nodes[nodeId].status;
136
+ if (![NODE_STATES.READY, NODE_STATES.RUNNING].includes(status)) {
137
+ reasons.push(`node ${nodeId} is ${status}, not READY`);
138
+ }
139
+ nodeTokenLimit = node.context?.maxTokens || null;
140
+ spentThisNode = allEntries
141
+ .filter((entry) => entry.runId === run.runId && entry.nodeId === nodeId)
142
+ .reduce((sum, entry) => sum + entry.totalTokens, 0);
143
+ if (nodeTokenLimit != null && spentThisNode + estimatedTokens > nodeTokenLimit) {
144
+ reasons.push(`node ${nodeId} token limit would be exceeded`);
145
+ }
146
+ if (nodeTokenLimit != null && estimatedTokens === 0 && spentThisNode >= nodeTokenLimit) {
147
+ reasons.push(`node ${nodeId} token limit is exhausted`);
148
+ }
149
+ }
123
150
  if (policy.killSwitch) reasons.push('kill switch is active');
124
151
  if (projectedThisRun > policy.perRunTokenLimit) reasons.push('per-run token limit would be exceeded');
125
152
  if (projectedToday > policy.dailyTokenLimit) reasons.push('daily token limit would be exceeded');
@@ -143,7 +170,13 @@ function budgetStatus(rootDir, { runId, estimatedTokens = 0, now = new Date() }
143
170
  spentToday,
144
171
  dailyTokenLimit: policy.dailyTokenLimit,
145
172
  remainingToday: Math.max(0, policy.dailyTokenLimit - spentToday),
146
- estimatedTokens
173
+ estimatedTokens,
174
+ ...(node ? {
175
+ nodeId,
176
+ spentThisNode,
177
+ nodeTokenLimit,
178
+ remainingThisNode: nodeTokenLimit == null ? null : Math.max(0, nodeTokenLimit - spentThisNode)
179
+ } : {})
147
180
  };
148
181
  }
149
182
 
@@ -182,7 +215,7 @@ function appendPrivateLine(rootDir, filePath, line) {
182
215
 
183
216
  function recordTokenUsage(
184
217
  rootDir,
185
- { runId, inputTokens, outputTokens, model, now = new Date() } = {}
218
+ { runId, nodeId, inputTokens, outputTokens, model, now = new Date() } = {}
186
219
  ) {
187
220
  const run = resolveRun(rootDir, runId);
188
221
  validateTokenCount('inputTokens', inputTokens);
@@ -197,10 +230,15 @@ function recordTokenUsage(
197
230
  outputTokens,
198
231
  totalTokens,
199
232
  model: normalizedModel,
233
+ ...(nodeId ? { nodeId } : {}),
200
234
  recordedAt: now.toISOString()
201
235
  };
236
+ if (nodeId) budgetStatus(rootDir, { runId: run.runId, nodeId, now });
202
237
  appendPrivateLine(rootDir, usagePath(rootDir, now), `${JSON.stringify(entry)}\n`);
203
- return { entry, status: budgetStatus(rootDir, { runId: run.runId, now }) };
238
+ return {
239
+ entry,
240
+ status: budgetStatus(rootDir, { runId: run.runId, nodeId, now })
241
+ };
204
242
  }
205
243
 
206
244
  function setKillSwitch(rootDir, active) {
package/lib/doctor.js CHANGED
@@ -4,6 +4,7 @@ const fs = require('fs');
4
4
  const path = require('path');
5
5
  const { loadEvaluationCases } = require('./evaluation.js');
6
6
  const { auditPackage } = require('./package-audit.js');
7
+ const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
7
8
 
8
9
  const REQUIRED_HOST_ASSETS = [
9
10
  '.claude/skills/ai-engineering-loop/SKILL.md',
@@ -24,7 +25,12 @@ const REQUIRED_SCHEMAS = [
24
25
  'finding-ledger.schema.json',
25
26
  'verdict.schema.json',
26
27
  'delivery.schema.json',
27
- 'report.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'
28
34
  ];
29
35
 
30
36
  function check(id, passed, detail) {
@@ -66,6 +72,23 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
66
72
  schemaErrors.length ? schemaErrors.join('; ') : `${REQUIRED_SCHEMAS.length} schemas parse`
67
73
  ));
68
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
+
69
92
  try {
70
93
  const fixtures = loadEvaluationCases(path.join(rootDir, 'evals', 'cases'));
71
94
  checks.push(check('evaluation-catalog', fixtures.length === 20, `${fixtures.length} valid cases; required 20`));
@@ -74,7 +97,7 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
74
97
  }
75
98
 
76
99
  const packageFiles = new Set(pkg.files || []);
77
- const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'schemas/', 'evals/'];
100
+ const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/'];
78
101
  const missingPackageEntries = requiredPackageEntries.filter((entry) => !packageFiles.has(entry));
79
102
  checks.push(check(
80
103
  'package-assets',
@@ -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,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
+ };