ai-engineering-loop 1.2.1 → 1.6.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,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
+ };