ai-engineering-loop 1.7.0 → 1.8.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.
- package/README.md +149 -353
- package/bin/ai-engineering-loop.js +2 -2
- package/core/local-workflow-studio.md +28 -7
- package/docs/images/studio-hero.svg +124 -0
- package/lib/gates.js +3 -2
- package/lib/goal-runtime.js +130 -0
- package/lib/recipe-builder.js +27 -1
- package/lib/recipe-graph.js +92 -0
- package/lib/recipe.js +137 -7
- package/lib/run-history.js +193 -0
- package/lib/run-state.js +90 -5
- package/lib/studio-runtime.js +65 -0
- package/lib/studio-server.js +154 -2
- package/lib/workflow-runtime.js +79 -5
- package/package.json +2 -2
- package/schemas/edge-definition.schema.json +13 -0
- package/schemas/node-definition.schema.json +74 -1
- package/schemas/recipe.schema.json +5 -0
- package/studio/app.js +856 -59
- package/studio/index.html +95 -7
- package/studio/styles.css +20 -10
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Local Workflow Studio
|
|
2
2
|
|
|
3
|
-
Workflow Studio is a localhost-only visual control plane for declarative recipes and recipe-bound runs. It does not execute models, shell commands,
|
|
3
|
+
Workflow Studio is a localhost-only visual control plane for declarative recipes and recipe-bound runs. It can create a named run and start the controlled local workflow runtime after an audited Goal Freeze. It does not execute models, shell commands, arbitrary node code, or inject prompts into an external AI conversation. The existing recipe compiler and controlled workflow runtime remain the source of truth.
|
|
4
4
|
|
|
5
5
|
## Start
|
|
6
6
|
|
|
@@ -18,17 +18,25 @@ The canvas loads built-in and project recipes through the same APIs as the CLI:
|
|
|
18
18
|
|
|
19
19
|
1. Select a recipe.
|
|
20
20
|
2. Fork a protected built-in by changing its ID.
|
|
21
|
-
3. Drag allowlisted node types from the library or
|
|
22
|
-
4. Move
|
|
23
|
-
5.
|
|
24
|
-
6.
|
|
25
|
-
7.
|
|
21
|
+
3. Drag allowlisted node types from the library, use the global Add Node control, or use the contextual output `+` to create and connect a successor.
|
|
22
|
+
4. Move or multi-select nodes, drag an output port to connect existing nodes, and remove a connection from its midpoint control.
|
|
23
|
+
5. Edit a node Display Name inline without changing its stable Technical ID.
|
|
24
|
+
6. Import validated JSON through an explicit Replace, Merge with deterministic conflict renaming, or Cancel preview; export the current workflow as JSON.
|
|
25
|
+
7. Pan, lasso, zoom, fit, auto-layout, and use undo/redo without changing recipe semantics.
|
|
26
|
+
8. Review graph validation and hashes for every compatible mode.
|
|
27
|
+
9. Install only after explicit confirmation.
|
|
26
28
|
|
|
27
29
|
Installation writes a private temporary candidate, invokes the existing atomic installer, and removes the candidate. Built-ins cannot be overwritten. Replacing a project recipe still requires the version policy enforced by `recipe install --replace`.
|
|
28
30
|
|
|
29
31
|
Canvas positions and viewport state are not recipe fields and never contribute to the graph hash. Studio stores them under private `.ai-engineering-loop/studio-layouts/` files, validates IDs and coordinate bounds, rejects symlinks, and writes atomically. This keeps visual organization independent from execution semantics.
|
|
30
32
|
|
|
31
|
-
Visual connections are
|
|
33
|
+
Visual connections are first-class `edges[]` with stable Edge IDs and Technical ID endpoints. Legacy `dependsOn` recipes migrate in memory without modifying their source; Save or Export emits the current Edge representation. The compiler projects Edges back to runtime dependencies so legacy and migrated recipes retain the same execution order and graph hash. Studio rejects duplicate, dangling, self-referential, and cyclic Edges, then applies the complete safety-backbone and mode validation before installation.
|
|
34
|
+
|
|
35
|
+
## Custom Agents
|
|
36
|
+
|
|
37
|
+
**Create Custom Agent** adds an `agent` node with a basic prompt, explicit capability and MCP references, input/output artifact contracts, token limit, timeout, and retry policy. Unsupported authority, arbitrary shell fields, raw secret values, and unsafe schema paths are rejected.
|
|
38
|
+
|
|
39
|
+
A Custom Agent reaching `READY` waits for an external operator. Studio can mark it running, record redacted activity, retry it, or complete it with a valid run-bound evidence artifact. Readiness is not represented as independent model execution.
|
|
32
40
|
|
|
33
41
|
## Stage 8 delivery adapter
|
|
34
42
|
|
|
@@ -38,6 +46,10 @@ An adapter belongs to the project, not to one delivery node. For a custom adapte
|
|
|
38
46
|
|
|
39
47
|
## Live execution
|
|
40
48
|
|
|
49
|
+
The trigger/root node owns the task input and local Execute control. Studio first creates a Run with an immutable Technical ID and human-readable Display Name. A deterministic task-derived name is used when no safe proposal is available. The Goal Contract must contain numbered acceptance criteria with evidence and failure cases and must pass an explicit Goal Freeze before Execute can start the local runtime.
|
|
50
|
+
|
|
51
|
+
Goal Freeze records actor, timestamp, version, and content hash. Unfreeze requires an actor and reason, increments the Goal version, resets the workflow to its Goal gate, and leaves previous evidence bound to the previous version.
|
|
52
|
+
|
|
41
53
|
For a recipe-bound current run, Studio polls a small live snapshot rather than reloading the recipe catalog. It displays:
|
|
42
54
|
|
|
43
55
|
- current node states and the append-only event stream;
|
|
@@ -53,6 +65,12 @@ ai-engineering-loop node activity <node-id> \
|
|
|
53
65
|
|
|
54
66
|
Activity can only be attached to a `RUNNING` node. It is capped at 240 printable characters, secret-redacted before persistence, and added to the integrity-bound workflow event chain.
|
|
55
67
|
|
|
68
|
+
## Run History
|
|
69
|
+
|
|
70
|
+
The separate **Runs** workspace reads every valid persisted Run rather than replacing Workflows with execution records. It supports text, status, mode, and date filters and shows human-readable names, technical IDs, Goal state, decisions, events, evidence presence, and bounded artifacts. Corrupt Run records are isolated so valid siblings remain available.
|
|
71
|
+
|
|
72
|
+
Run History is read-only. Artifact inspection accepts only regular files inside the owning Run, rejects path traversal and symlinks, enforces a size bound, and redacts recognized secrets before returning content.
|
|
73
|
+
|
|
56
74
|
## Decision memory
|
|
57
75
|
|
|
58
76
|
Studio can record a concise decision and rationale against the current run. Decision memory is private runtime data under the run directory, is bounded to 100 entries, and is redacted before persistence. It becomes part of exported handoffs so the next developer or agent receives the “why,” not only the final state.
|
|
@@ -82,9 +100,12 @@ Inspection accepts only regular files smaller than 1 MiB inside the repository,
|
|
|
82
100
|
Studio improves authoring and observability; it does not weaken runtime gates:
|
|
83
101
|
|
|
84
102
|
- graph validation does not imply execution permission;
|
|
103
|
+
- local execution requires exactly one permitted trigger/root and an audited frozen Goal;
|
|
85
104
|
- command nodes remain disabled;
|
|
105
|
+
- Custom Agents wait for an external operator and cannot grant undeclared authority;
|
|
86
106
|
- approvals remain explicit state transitions;
|
|
87
107
|
- connector edits cannot bypass the required safety backbone;
|
|
108
|
+
- Run History cannot mutate persisted runs or artifacts;
|
|
88
109
|
- delivery adapters cannot run before Judge `PASS`;
|
|
89
110
|
- token data comes only from the provider-recorded usage ledger;
|
|
90
111
|
- handoff integrity proves the bundle has not changed after export, not that every original claim was true.
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
|
|
2
|
+
<title id="title">AI Engineering Loop Workflow Studio</title>
|
|
3
|
+
<desc id="desc">A polished dark workflow canvas showing a task moving through goal, maker, review, and delivery nodes.</desc>
|
|
4
|
+
<defs>
|
|
5
|
+
<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
|
|
6
|
+
<stop stop-color="#111512"/>
|
|
7
|
+
<stop offset="1" stop-color="#080a09"/>
|
|
8
|
+
</linearGradient>
|
|
9
|
+
<linearGradient id="glow" x1="0" y1="0" x2="1" y2="1">
|
|
10
|
+
<stop stop-color="#28ad00" stop-opacity=".28"/>
|
|
11
|
+
<stop offset="1" stop-color="#28ad00" stop-opacity="0"/>
|
|
12
|
+
</linearGradient>
|
|
13
|
+
<filter id="shadow" x="-30%" y="-30%" width="160%" height="160%">
|
|
14
|
+
<feDropShadow dx="0" dy="18" stdDeviation="24" flood-color="#000" flood-opacity=".45"/>
|
|
15
|
+
</filter>
|
|
16
|
+
<filter id="soft">
|
|
17
|
+
<feGaussianBlur stdDeviation="55"/>
|
|
18
|
+
</filter>
|
|
19
|
+
<pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse">
|
|
20
|
+
<path d="M32 0H0V32" fill="none" stroke="#fff" stroke-opacity=".035"/>
|
|
21
|
+
</pattern>
|
|
22
|
+
<marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
|
|
23
|
+
<path d="M0 0L10 5L0 10Z" fill="#5b625d"/>
|
|
24
|
+
</marker>
|
|
25
|
+
<style>
|
|
26
|
+
.ui{font-family:Inter,ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
|
|
27
|
+
.mono{font-family:"SFMono-Regular",Consolas,monospace}
|
|
28
|
+
.eyebrow{font-size:14px;font-weight:700;letter-spacing:2.4px;fill:#7f8881}
|
|
29
|
+
.node-title{font-size:22px;font-weight:700;fill:#f4f6f4}
|
|
30
|
+
.node-copy{font-size:14px;fill:#888f8a}
|
|
31
|
+
.tiny{font-size:12px;fill:#707873}
|
|
32
|
+
.flow{fill:none;stroke:#5b625d;stroke-width:3;marker-end:url(#arrow)}
|
|
33
|
+
</style>
|
|
34
|
+
</defs>
|
|
35
|
+
|
|
36
|
+
<rect width="1600" height="900" fill="url(#bg)"/>
|
|
37
|
+
<circle cx="1240" cy="70" r="330" fill="#28ad00" opacity=".12" filter="url(#soft)"/>
|
|
38
|
+
<circle cx="280" cy="880" r="260" fill="#28ad00" opacity=".08" filter="url(#soft)"/>
|
|
39
|
+
|
|
40
|
+
<g class="ui">
|
|
41
|
+
<text x="110" y="112" font-size="16" font-weight="800" letter-spacing="2" fill="#83db69">AI ENGINEERING LOOP</text>
|
|
42
|
+
<text x="110" y="188" font-size="64" font-weight="750" letter-spacing="-2.8" fill="#f7f9f7">From idea to trusted code.</text>
|
|
43
|
+
<text x="112" y="232" font-size="21" fill="#9da49f">Your AI handles the workflow. You keep the clarity and control.</text>
|
|
44
|
+
</g>
|
|
45
|
+
|
|
46
|
+
<g filter="url(#shadow)">
|
|
47
|
+
<rect x="105" y="290" width="1390" height="510" rx="24" fill="#151816" stroke="#303632"/>
|
|
48
|
+
<rect x="105" y="290" width="1390" height="64" rx="24" fill="#1b1f1c"/>
|
|
49
|
+
<path d="M105 330V354H1495V330" fill="#1b1f1c"/>
|
|
50
|
+
<circle cx="140" cy="322" r="6" fill="#4d544f"/>
|
|
51
|
+
<circle cx="160" cy="322" r="6" fill="#4d544f"/>
|
|
52
|
+
<circle cx="180" cy="322" r="6" fill="#28ad00"/>
|
|
53
|
+
<rect x="680" y="307" width="240" height="30" rx="15" fill="#111411"/>
|
|
54
|
+
<circle cx="704" cy="322" r="6" fill="#28ad00"/>
|
|
55
|
+
<text class="ui tiny" x="720" y="326">Workflow Studio</text>
|
|
56
|
+
|
|
57
|
+
<rect x="105" y="354" width="72" height="446" fill="#101311"/>
|
|
58
|
+
<rect x="123" y="381" width="36" height="36" rx="10" fill="#28ad00"/>
|
|
59
|
+
<path d="M135 393h12v12h-12zM139 389v20M131 399h20" fill="none" stroke="#fff" stroke-width="2"/>
|
|
60
|
+
<circle cx="141" cy="449" r="15" fill="#252a26"/>
|
|
61
|
+
<path d="M134 449h14M141 442v14" stroke="#818982" stroke-width="2"/>
|
|
62
|
+
<circle cx="141" cy="500" r="15" fill="#252a26"/>
|
|
63
|
+
<path d="M134 497h14M134 503h10" stroke="#818982" stroke-width="2"/>
|
|
64
|
+
|
|
65
|
+
<rect x="177" y="354" width="1318" height="446" fill="#111411"/>
|
|
66
|
+
<rect x="177" y="354" width="1318" height="446" fill="url(#grid)"/>
|
|
67
|
+
<ellipse cx="1220" cy="410" rx="300" ry="210" fill="url(#glow)"/>
|
|
68
|
+
|
|
69
|
+
<text class="ui eyebrow" x="222" y="397">WORKFLOW / PRODUCT LAUNCH</text>
|
|
70
|
+
<rect x="1180" y="375" width="262" height="42" rx="9" fill="#1d221e" stroke="#343a35"/>
|
|
71
|
+
<circle cx="1206" cy="396" r="6" fill="#28ad00"/>
|
|
72
|
+
<text class="ui tiny" x="1221" y="400">Goal frozen · ready to run</text>
|
|
73
|
+
|
|
74
|
+
<path class="flow" d="M468 555C515 555 510 486 565 486H596"/>
|
|
75
|
+
<path class="flow" d="M858 486C906 486 900 585 956 585H990"/>
|
|
76
|
+
<path class="flow" d="M1252 585C1304 585 1295 492 1343 492"/>
|
|
77
|
+
|
|
78
|
+
<g>
|
|
79
|
+
<rect x="238" y="470" width="230" height="170" rx="16" fill="#1c211d" stroke="#3b433d"/>
|
|
80
|
+
<rect x="238" y="470" width="6" height="170" rx="3" fill="#28ad00"/>
|
|
81
|
+
<text class="ui eyebrow" x="268" y="503">01 · GOAL</text>
|
|
82
|
+
<text class="ui node-title" x="268" y="543">Define success</text>
|
|
83
|
+
<text class="ui node-copy" x="268" y="572">Clear outcomes, edge cases,</text>
|
|
84
|
+
<text class="ui node-copy" x="268" y="594">and proof before coding.</text>
|
|
85
|
+
<rect x="268" y="612" width="92" height="8" rx="4" fill="#28ad00" opacity=".65"/>
|
|
86
|
+
</g>
|
|
87
|
+
|
|
88
|
+
<g>
|
|
89
|
+
<rect x="596" y="401" width="262" height="170" rx="16" fill="#1c211d" stroke="#3b433d"/>
|
|
90
|
+
<text class="ui eyebrow" x="626" y="434">02 · MAKE</text>
|
|
91
|
+
<text class="ui node-title" x="626" y="474">Build the right thing</text>
|
|
92
|
+
<text class="ui node-copy" x="626" y="503">Your agent plans, implements,</text>
|
|
93
|
+
<text class="ui node-copy" x="626" y="525">and verifies the result.</text>
|
|
94
|
+
<circle cx="816" cy="433" r="8" fill="#28ad00"/>
|
|
95
|
+
</g>
|
|
96
|
+
|
|
97
|
+
<g>
|
|
98
|
+
<rect x="990" y="500" width="262" height="170" rx="16" fill="#1c211d" stroke="#3b433d"/>
|
|
99
|
+
<text class="ui eyebrow" x="1020" y="533">03 · REVIEW</text>
|
|
100
|
+
<text class="ui node-title" x="1020" y="573">Challenge every claim</text>
|
|
101
|
+
<text class="ui node-copy" x="1020" y="602">Independent checks compare</text>
|
|
102
|
+
<text class="ui node-copy" x="1020" y="624">promises with real evidence.</text>
|
|
103
|
+
<rect x="1020" y="642" width="72" height="8" rx="4" fill="#28ad00" opacity=".65"/>
|
|
104
|
+
</g>
|
|
105
|
+
|
|
106
|
+
<g>
|
|
107
|
+
<rect x="1343" y="422" width="112" height="140" rx="16" fill="#28ad00"/>
|
|
108
|
+
<text class="ui" x="1399" y="461" text-anchor="middle" font-size="12" font-weight="800" letter-spacing="1.5" fill="#dff8d7">04</text>
|
|
109
|
+
<path d="M1378 491l14 14 30-34" fill="none" stroke="#fff" stroke-width="7" stroke-linecap="round" stroke-linejoin="round"/>
|
|
110
|
+
<text class="ui" x="1399" y="535" text-anchor="middle" font-size="14" font-weight="750" fill="#fff">DELIVER</text>
|
|
111
|
+
</g>
|
|
112
|
+
|
|
113
|
+
<rect x="224" y="730" width="1218" height="44" rx="12" fill="#191d1a" stroke="#2b312c"/>
|
|
114
|
+
<text class="mono tiny" x="248" y="757">Task</text>
|
|
115
|
+
<text class="ui" x="300" y="757" font-size="14" fill="#c7ccc8">Ship a reliable feature without babysitting every command</text>
|
|
116
|
+
<rect x="1306" y="739" width="118" height="26" rx="7" fill="#28ad00"/>
|
|
117
|
+
<text class="ui" x="1365" y="757" text-anchor="middle" font-size="12" font-weight="750" fill="#fff">EXECUTE</text>
|
|
118
|
+
</g>
|
|
119
|
+
|
|
120
|
+
<g class="ui">
|
|
121
|
+
<text x="112" y="852" font-size="15" fill="#6f7771">Visual workflows · human-friendly runs · evidence you can trust</text>
|
|
122
|
+
<text x="1488" y="852" text-anchor="end" font-size="15" font-weight="700" fill="#28ad00">OPEN SOURCE</text>
|
|
123
|
+
</g>
|
|
124
|
+
</svg>
|
package/lib/gates.js
CHANGED
|
@@ -181,7 +181,7 @@ function resolveRun(rootDir, runId) {
|
|
|
181
181
|
return current;
|
|
182
182
|
}
|
|
183
183
|
|
|
184
|
-
function applyGate(rootDir, gate, { runId } = {}) {
|
|
184
|
+
function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
|
|
185
185
|
if (!Object.hasOwn(GATE_FILES, gate)) {
|
|
186
186
|
throw gateError(`Unknown gate: ${gate}. Use ${Object.keys(GATE_FILES).join('|')}`);
|
|
187
187
|
}
|
|
@@ -196,7 +196,8 @@ function applyGate(rootDir, gate, { runId } = {}) {
|
|
|
196
196
|
if (!check.valid) throw gateError('Goal Contract gate failed', check.errors);
|
|
197
197
|
return transitionRun(rootDir, run.runId, RUN_STATES.GOAL_FROZEN, {
|
|
198
198
|
gate,
|
|
199
|
-
artifacts: { goalContract: descriptor(rootDir, filePath) }
|
|
199
|
+
artifacts: { goalContract: descriptor(rootDir, filePath) },
|
|
200
|
+
...transitionOptions
|
|
200
201
|
});
|
|
201
202
|
}
|
|
202
203
|
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
const { validateGoalContract, hashFile } = require('./gates.js');
|
|
6
|
+
const {
|
|
7
|
+
RUN_STATES,
|
|
8
|
+
atomicWriteJson,
|
|
9
|
+
loadRun,
|
|
10
|
+
runsDir,
|
|
11
|
+
transitionRun
|
|
12
|
+
} = require('./run-state.js');
|
|
13
|
+
|
|
14
|
+
function goalError(message, code, details = []) {
|
|
15
|
+
const error = new Error(message);
|
|
16
|
+
error.code = code;
|
|
17
|
+
error.details = details;
|
|
18
|
+
return error;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function actorId(actor) {
|
|
22
|
+
const value = String(actor || '').trim();
|
|
23
|
+
if (!/^[A-Za-z0-9@._-]{1,64}$/.test(value)) {
|
|
24
|
+
throw goalError('Goal actor must be a short account identifier', 'INVALID_GOAL_ACTOR');
|
|
25
|
+
}
|
|
26
|
+
return value;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function goalPaths(rootDir, runId, version) {
|
|
30
|
+
const directory = path.join(runsDir(rootDir), runId);
|
|
31
|
+
return {
|
|
32
|
+
draft: path.join(directory, 'goal-draft.json'),
|
|
33
|
+
canonical: path.join(directory, 'goal-contract.json'),
|
|
34
|
+
version: path.join(directory, `goal-contract.v${version}.json`)
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function saveGoalDraft(rootDir, runId, contract) {
|
|
39
|
+
const run = loadRun(rootDir, runId);
|
|
40
|
+
if (run.goal?.frozen) throw goalError('Frozen Goal must be unfrozen before editing', 'GOAL_IS_FROZEN');
|
|
41
|
+
const value = { ...contract, schemaVersion: 1, runId };
|
|
42
|
+
atomicWriteJson(goalPaths(rootDir, runId, run.goal?.version || 1).draft, value);
|
|
43
|
+
return value;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function freezeGoal(rootDir, runId, { actor, now = new Date() } = {}) {
|
|
47
|
+
const run = loadRun(rootDir, runId);
|
|
48
|
+
if (run.state !== RUN_STATES.STARTED || run.goal?.frozen) {
|
|
49
|
+
throw goalError(`Run ${runId} cannot freeze a Goal from ${run.state}`, 'INVALID_GOAL_TRANSITION');
|
|
50
|
+
}
|
|
51
|
+
const version = run.goal?.version || 1;
|
|
52
|
+
const paths = goalPaths(rootDir, runId, version);
|
|
53
|
+
let contract;
|
|
54
|
+
try {
|
|
55
|
+
contract = JSON.parse(fs.readFileSync(paths.draft, 'utf8'));
|
|
56
|
+
} catch (cause) {
|
|
57
|
+
throw goalError(`Goal draft is unavailable: ${cause.message}`, 'GOAL_DRAFT_MISSING');
|
|
58
|
+
}
|
|
59
|
+
const validation = validateGoalContract(contract);
|
|
60
|
+
if (!validation.valid) throw goalError('Goal Contract gate failed', 'GATE_FAILED', validation.errors);
|
|
61
|
+
const human = actorId(actor);
|
|
62
|
+
if (fs.existsSync(paths.version)) {
|
|
63
|
+
throw goalError(`Goal version ${version} already exists`, 'GOAL_VERSION_EXISTS');
|
|
64
|
+
}
|
|
65
|
+
atomicWriteJson(paths.version, contract);
|
|
66
|
+
atomicWriteJson(paths.canonical, contract);
|
|
67
|
+
const hash = hashFile(paths.version);
|
|
68
|
+
const transitionOptions = {
|
|
69
|
+
artifacts: {
|
|
70
|
+
goalContract: {
|
|
71
|
+
path: path.relative(rootDir, paths.version).split(path.sep).join('/'),
|
|
72
|
+
sha256: hash,
|
|
73
|
+
goalVersion: version
|
|
74
|
+
}
|
|
75
|
+
},
|
|
76
|
+
statePatch: {
|
|
77
|
+
goal: { version, frozen: true, hash, actor: human, frozenAt: now.toISOString() }
|
|
78
|
+
},
|
|
79
|
+
historyMetadata: { actor: human, goalVersion: version, goalHash: hash },
|
|
80
|
+
now
|
|
81
|
+
};
|
|
82
|
+
if (run.workflow) {
|
|
83
|
+
const { applyWorkflowGate } = require('./workflow-runtime.js');
|
|
84
|
+
return applyWorkflowGate(rootDir, 'goal', { runId, now, transitionOptions }).run;
|
|
85
|
+
}
|
|
86
|
+
return transitionRun(rootDir, runId, RUN_STATES.GOAL_FROZEN, {
|
|
87
|
+
gate: 'goal',
|
|
88
|
+
...transitionOptions
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function unfreezeGoal(rootDir, runId, { actor, reason, now = new Date() } = {}) {
|
|
93
|
+
const run = loadRun(rootDir, runId);
|
|
94
|
+
if (run.state !== RUN_STATES.GOAL_FROZEN || !run.goal?.frozen) {
|
|
95
|
+
throw goalError(`Run ${runId} has no frozen editable Goal`, 'INVALID_GOAL_TRANSITION');
|
|
96
|
+
}
|
|
97
|
+
const why = String(reason || '').trim();
|
|
98
|
+
if (!why || why.length > 500) {
|
|
99
|
+
throw goalError('Unfreeze reason must be 1-500 characters', 'INVALID_UNFREEZE_REASON');
|
|
100
|
+
}
|
|
101
|
+
const human = actorId(actor);
|
|
102
|
+
const transitionOptions = {
|
|
103
|
+
reason: why,
|
|
104
|
+
statePatch: {
|
|
105
|
+
goal: {
|
|
106
|
+
version: run.goal.version + 1,
|
|
107
|
+
frozen: false,
|
|
108
|
+
previousVersion: run.goal.version,
|
|
109
|
+
unfrozenBy: human,
|
|
110
|
+
unfrozenAt: now.toISOString()
|
|
111
|
+
}
|
|
112
|
+
},
|
|
113
|
+
historyMetadata: {
|
|
114
|
+
actor: human,
|
|
115
|
+
goalVersion: run.goal.version,
|
|
116
|
+
nextGoalVersion: run.goal.version + 1
|
|
117
|
+
},
|
|
118
|
+
now
|
|
119
|
+
};
|
|
120
|
+
if (run.workflow) {
|
|
121
|
+
const { unfreezeWorkflowGoal } = require('./workflow-runtime.js');
|
|
122
|
+
return unfreezeWorkflowGoal(rootDir, { runId, transitionOptions, now }).run;
|
|
123
|
+
}
|
|
124
|
+
return transitionRun(rootDir, runId, RUN_STATES.STARTED, {
|
|
125
|
+
gate: 'goal-unfreeze',
|
|
126
|
+
...transitionOptions
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
module.exports = { saveGoalDraft, freezeGoal, unfreezeGoal };
|
package/lib/recipe-builder.js
CHANGED
|
@@ -5,6 +5,11 @@ const path = require('path');
|
|
|
5
5
|
const crypto = require('crypto');
|
|
6
6
|
const { NODE_TYPES } = require('./node-registry.js');
|
|
7
7
|
const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
|
|
8
|
+
const {
|
|
9
|
+
mergeGraphs,
|
|
10
|
+
migrateLegacyRecipe,
|
|
11
|
+
planGraphMerge
|
|
12
|
+
} = require('./recipe-graph.js');
|
|
8
13
|
const {
|
|
9
14
|
RECIPE_ID,
|
|
10
15
|
canonicalJson,
|
|
@@ -66,6 +71,25 @@ function validateCandidate(recipe) {
|
|
|
66
71
|
return result;
|
|
67
72
|
}
|
|
68
73
|
|
|
74
|
+
function planRecipeImport(existingRecipe, importedRecipe, operation) {
|
|
75
|
+
if (!['replace', 'merge', 'cancel'].includes(operation)) {
|
|
76
|
+
throw builderError('Import operation must be replace, merge, or cancel', 'INVALID_IMPORT_OPERATION');
|
|
77
|
+
}
|
|
78
|
+
validateCandidate(existingRecipe);
|
|
79
|
+
validateCandidate(importedRecipe);
|
|
80
|
+
if (operation !== 'merge') return { operation, nodeIdMap: {}, edgeIdMap: {} };
|
|
81
|
+
return { operation, ...planGraphMerge(existingRecipe, importedRecipe) };
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function applyRecipeImport(existingRecipe, importedRecipe, plan) {
|
|
85
|
+
if (!plan || !['replace', 'merge', 'cancel'].includes(plan.operation)) {
|
|
86
|
+
throw builderError('A valid import preview is required', 'INVALID_IMPORT_PLAN');
|
|
87
|
+
}
|
|
88
|
+
if (plan.operation === 'cancel') return existingRecipe;
|
|
89
|
+
if (plan.operation === 'replace') return migrateLegacyRecipe(importedRecipe);
|
|
90
|
+
return mergeGraphs(existingRecipe, importedRecipe, plan);
|
|
91
|
+
}
|
|
92
|
+
|
|
69
93
|
function cloneRecipe(rootDir, sourceId, targetId, { description } = {}) {
|
|
70
94
|
assertProjectId(rootDir, targetId);
|
|
71
95
|
const source = loadRecipe(rootDir, sourceId).recipe;
|
|
@@ -107,7 +131,7 @@ function readCandidate(rootDir, candidatePath) {
|
|
|
107
131
|
}
|
|
108
132
|
|
|
109
133
|
function installRecipe(rootDir, candidatePath, { replace = false } = {}) {
|
|
110
|
-
const candidate = readCandidate(rootDir, candidatePath);
|
|
134
|
+
const candidate = migrateLegacyRecipe(readCandidate(rootDir, candidatePath));
|
|
111
135
|
assertProjectId(rootDir, candidate.id);
|
|
112
136
|
validateCandidate(candidate);
|
|
113
137
|
ensurePrivateRuntimeIgnores(rootDir);
|
|
@@ -193,8 +217,10 @@ function diffRecipes(rootDir, leftId, rightId) {
|
|
|
193
217
|
}
|
|
194
218
|
|
|
195
219
|
module.exports = {
|
|
220
|
+
applyRecipeImport,
|
|
196
221
|
cloneRecipe,
|
|
197
222
|
installRecipe,
|
|
223
|
+
planRecipeImport,
|
|
198
224
|
recipeCatalog,
|
|
199
225
|
inspectRecipe,
|
|
200
226
|
diffRecipes
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const crypto = require('crypto');
|
|
4
|
+
|
|
5
|
+
const EDGE_ID = /^[a-z][a-z0-9-]{0,63}$/;
|
|
6
|
+
const MAX_EDGES = 256;
|
|
7
|
+
|
|
8
|
+
function clone(value) {
|
|
9
|
+
return JSON.parse(JSON.stringify(value));
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
function stableEdgeId(from, to) {
|
|
13
|
+
const digest = crypto.createHash('sha256').update(`${from}\0${to}`).digest('hex').slice(0, 16);
|
|
14
|
+
return `edge-${digest}`;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
function migrateLegacyRecipe(recipe) {
|
|
18
|
+
const migrated = clone(recipe);
|
|
19
|
+
if (!migrated || typeof migrated !== 'object' || Array.isArray(migrated)) return migrated;
|
|
20
|
+
if (!Array.isArray(migrated.edges)) {
|
|
21
|
+
migrated.edges = [];
|
|
22
|
+
for (const node of Array.isArray(migrated.nodes) ? migrated.nodes : []) {
|
|
23
|
+
for (const dependency of Array.isArray(node?.dependsOn) ? node.dependsOn : []) {
|
|
24
|
+
migrated.edges.push({ id: stableEdgeId(dependency, node.id), from: dependency, to: node.id });
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
for (const node of Array.isArray(migrated.nodes) ? migrated.nodes : []) {
|
|
29
|
+
if (node && typeof node === 'object') delete node.dependsOn;
|
|
30
|
+
}
|
|
31
|
+
return migrated;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function withDependencies(recipe) {
|
|
35
|
+
const projected = migrateLegacyRecipe(recipe);
|
|
36
|
+
const byId = new Map((projected.nodes || []).map((node) => [node.id, node]));
|
|
37
|
+
for (const node of projected.nodes || []) node.dependsOn = [];
|
|
38
|
+
for (const edge of projected.edges || []) {
|
|
39
|
+
if (byId.has(edge?.to)) byId.get(edge.to).dependsOn.push(edge.from);
|
|
40
|
+
}
|
|
41
|
+
return projected;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function uniqueId(preferred, occupied) {
|
|
45
|
+
if (!occupied.has(preferred)) {
|
|
46
|
+
occupied.add(preferred);
|
|
47
|
+
return preferred;
|
|
48
|
+
}
|
|
49
|
+
for (let suffix = 2; ; suffix++) {
|
|
50
|
+
const ending = `-${suffix}`;
|
|
51
|
+
const candidate = `${preferred.slice(0, 64 - ending.length)}${ending}`;
|
|
52
|
+
if (!occupied.has(candidate)) {
|
|
53
|
+
occupied.add(candidate);
|
|
54
|
+
return candidate;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function planGraphMerge(existingRecipe, importedRecipe) {
|
|
60
|
+
const existing = migrateLegacyRecipe(existingRecipe);
|
|
61
|
+
const imported = migrateLegacyRecipe(importedRecipe);
|
|
62
|
+
const nodeIds = new Set((existing.nodes || []).map((node) => node.id));
|
|
63
|
+
const edgeIds = new Set((existing.edges || []).map((edge) => edge.id));
|
|
64
|
+
const nodeIdMap = {};
|
|
65
|
+
const edgeIdMap = {};
|
|
66
|
+
for (const node of imported.nodes || []) nodeIdMap[node.id] = uniqueId(node.id, nodeIds);
|
|
67
|
+
for (const edge of imported.edges || []) edgeIdMap[edge.id] = uniqueId(edge.id, edgeIds);
|
|
68
|
+
return { nodeIdMap, edgeIdMap };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function mergeGraphs(existingRecipe, importedRecipe, plan) {
|
|
72
|
+
const existing = migrateLegacyRecipe(existingRecipe);
|
|
73
|
+
const imported = migrateLegacyRecipe(importedRecipe);
|
|
74
|
+
const nodes = imported.nodes.map((node) => ({ ...node, id: plan.nodeIdMap[node.id] }));
|
|
75
|
+
const edges = imported.edges.map((edge) => ({
|
|
76
|
+
...edge,
|
|
77
|
+
id: plan.edgeIdMap[edge.id],
|
|
78
|
+
from: plan.nodeIdMap[edge.from],
|
|
79
|
+
to: plan.nodeIdMap[edge.to]
|
|
80
|
+
}));
|
|
81
|
+
return { ...existing, nodes: [...existing.nodes, ...nodes], edges: [...existing.edges, ...edges] };
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
module.exports = {
|
|
85
|
+
EDGE_ID,
|
|
86
|
+
MAX_EDGES,
|
|
87
|
+
mergeGraphs,
|
|
88
|
+
migrateLegacyRecipe,
|
|
89
|
+
planGraphMerge,
|
|
90
|
+
stableEdgeId,
|
|
91
|
+
withDependencies
|
|
92
|
+
};
|