owenloop 0.2.1 → 0.4.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.
- package/CHANGELOG.md +67 -0
- package/README.md +82 -7
- package/bin/owenloop.mjs +2 -2
- package/dist/add.d.ts +412 -0
- package/dist/add.js +999 -0
- package/dist/cli.d.ts +43 -0
- package/dist/cli.js +1865 -19
- package/dist/defs.d.ts +33 -0
- package/dist/defs.js +112 -19
- package/dist/engine.d.ts +338 -50
- package/dist/engine.js +854 -170
- package/dist/factory.d.ts +19 -0
- package/dist/factory.js +41 -5
- package/dist/hub.d.ts +514 -0
- package/dist/hub.js +783 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.js +2 -1
- package/dist/model.d.ts +36 -0
- package/dist/store.d.ts +14 -2
- package/dist/store.js +269 -21
- package/dist/types.d.ts +92 -0
- package/dist/untar.d.ts +47 -0
- package/dist/untar.js +164 -0
- package/dist/util.d.ts +76 -0
- package/dist/util.js +96 -0
- package/docs/authoring.md +48 -1
- package/docs/cli.md +509 -3
- package/docs/design.md +72 -9
- package/docs/embedding.md +87 -7
- package/package.json +1 -1
package/dist/defs.d.ts
CHANGED
|
@@ -93,6 +93,39 @@ export declare function loadDefFile(file: string): WorkflowDef;
|
|
|
93
93
|
* defs in the same directory (M1-SITE).
|
|
94
94
|
*/
|
|
95
95
|
export declare function loadDefs(dir: string): Map<string, WorkflowDef>;
|
|
96
|
+
/**
|
|
97
|
+
* Phase 1 of def loading: scan `dir` and build every workflow def UN-finalized
|
|
98
|
+
* (includes not yet expanded, no cross-def / cycle validation). Loads each
|
|
99
|
+
* top-level `*.yaml` / `*.yml` file (excluding a top-level `workflow.yaml`) and
|
|
100
|
+
* each immediate subdirectory's `workflow.yaml`. Throws `DefError` on a
|
|
101
|
+
* duplicate name WITHIN this dir. This is a pure extraction of what used to live
|
|
102
|
+
* inline in `loadDefs` — `loadDefs(dir)` is exactly `finalizeDefs(loadDefsUnfinalized(dir))`.
|
|
103
|
+
*
|
|
104
|
+
* Exported so a caller can merge the raw maps of several dirs and run a single
|
|
105
|
+
* `finalizeDefs` over the union (giving correct include-expansion and cross-def
|
|
106
|
+
* `calls:` resolution across the merged boundary). This function stays a pure
|
|
107
|
+
* dir-scanner: it holds NO ledger / `installed.json` knowledge (that composition
|
|
108
|
+
* lives at the CLI layer where cwd and defsDir are both known).
|
|
109
|
+
*/
|
|
110
|
+
export declare function loadDefsUnfinalized(dir: string): Map<string, WorkflowDef>;
|
|
111
|
+
/**
|
|
112
|
+
* Phase 2/3 of def loading, factored out so it is the ONE validator every
|
|
113
|
+
* public construction path shares — the filesystem `loadDefs` above AND the
|
|
114
|
+
* in-memory `createEngine({ defs })` factory path (REL-4). Given a raw def map
|
|
115
|
+
* (each def possibly still carrying `_includes`), it: expands each def's
|
|
116
|
+
* includes; runs the cross-def `calls:` checks (target existence, `callsInputs`
|
|
117
|
+
* key validity, exactly-one child output); runs `validateDef` per expanded def;
|
|
118
|
+
* and finally `detectCallsCycles` over the whole expanded map. Returns the
|
|
119
|
+
* expanded, validated map. Throws `DefError` on the first problem — the same
|
|
120
|
+
* messages, in the same order, the filesystem loader has always produced (this
|
|
121
|
+
* is a pure extraction of what used to live inline in `loadDefs`).
|
|
122
|
+
*
|
|
123
|
+
* A host wiring an `Engine` by hand with its own set can call this to get the
|
|
124
|
+
* same validation the factory and the loader apply. `expandIncludes` is a no-op
|
|
125
|
+
* for a def without `_includes` (the normal in-memory case), so passing a plain
|
|
126
|
+
* def map through is cheap and only adds the cross-def + cycle checks.
|
|
127
|
+
*/
|
|
128
|
+
export declare function finalizeDefs(raw: Map<string, WorkflowDef>): Map<string, WorkflowDef>;
|
|
96
129
|
/** One file that `loadDefsRaw` could not turn into a def (malformed YAML, bad shape, duplicate name). */
|
|
97
130
|
export interface DefLoadFailure {
|
|
98
131
|
file: string;
|
package/dist/defs.js
CHANGED
|
@@ -20,8 +20,8 @@
|
|
|
20
20
|
* Draft a plan for ${WORKFLOW}.
|
|
21
21
|
*/
|
|
22
22
|
import { createHash } from 'node:crypto';
|
|
23
|
-
import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
|
|
24
|
-
import { basename, dirname, join } from 'node:path';
|
|
23
|
+
import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
|
|
24
|
+
import { basename, dirname, isAbsolute, join, sep } from 'node:path';
|
|
25
25
|
import { parse as parseYaml } from 'yaml';
|
|
26
26
|
import { parseConsume, parseProduce } from "./paths.js";
|
|
27
27
|
import { parseDurationMs, parseDurationSecs } from "./util.js";
|
|
@@ -41,7 +41,7 @@ const RAW_STEP_KEYS = [
|
|
|
41
41
|
'name', 'consumes', 'produces', 'generates', 'invalidates', 'cadence',
|
|
42
42
|
'maxRunsPerDay', 'parallel', 'maxAttempts', 'maxSchemaFailures', 'model',
|
|
43
43
|
'workdir', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
|
|
44
|
-
'calls', 'reapTtl', 'x', 'worker', 'command', 'spec',
|
|
44
|
+
'calls', 'reapTtl', 'labels', 'maxLease', 'x', 'worker', 'command', 'spec',
|
|
45
45
|
];
|
|
46
46
|
/** Keys valid on a calls: step entry — a DIFFERENT (smaller) shape than RawStep;
|
|
47
47
|
* the `calls:` key is what routes an entry here instead of RAW_STEP_KEYS. */
|
|
@@ -160,6 +160,60 @@ function assertNoUnknownKeys(obj, allowed, ctx) {
|
|
|
160
160
|
throw new DefError(`${ctx}: unknown key${unknown.length > 1 ? 's' : ''} ${unknown.map((k) => `'${k}'`).join(', ')}`);
|
|
161
161
|
}
|
|
162
162
|
}
|
|
163
|
+
/**
|
|
164
|
+
* Read a step/judge `bodyFile`, enforcing that it resolves to a regular file
|
|
165
|
+
* contained within `baseDir` (the def file's own directory). Closes SEC-1: an
|
|
166
|
+
* unchecked `join()` + `readFileSync()` let a remote definition with enough
|
|
167
|
+
* `../` components read arbitrary local files during `owenloop add`, and that
|
|
168
|
+
* content then flowed into emitted orders.
|
|
169
|
+
*
|
|
170
|
+
* `ctx` is the caller's error prefix (e.g. `step 'planner'` / `judge 'rigor'`);
|
|
171
|
+
* every failure throws `DefError`. A missing target keeps the historical
|
|
172
|
+
* "could not be read (resolved to '...')" message shape so anything matching
|
|
173
|
+
* /could not be read/ stays green.
|
|
174
|
+
*
|
|
175
|
+
* The containment root is `baseDir` itself. For an installed package `baseDir`
|
|
176
|
+
* is always at or below `<defsDir>/<owner>-<repo>/`, so this is strictly
|
|
177
|
+
* stronger than package-root containment and needs no extra plumbing.
|
|
178
|
+
*/
|
|
179
|
+
function readBodyFileContained(baseDir, rel, ctx) {
|
|
180
|
+
if (rel === '' || rel.includes('\0')) {
|
|
181
|
+
throw new DefError(`${ctx}: bodyFile '${rel}' must be a relative path with no '.' or '..' components`);
|
|
182
|
+
}
|
|
183
|
+
// Reject absolute paths: POSIX/Windows leading separators and drive prefixes.
|
|
184
|
+
if (isAbsolute(rel) || /^[\\/]/.test(rel) || /^[A-Za-z]:/.test(rel)) {
|
|
185
|
+
throw new DefError(`${ctx}: bodyFile '${rel}' must be a relative path, not absolute`);
|
|
186
|
+
}
|
|
187
|
+
// Reject any '.' or '..' segment (split on both separators — catches
|
|
188
|
+
// doubled separators and backslash tricks). The proposal asks to reject '.'
|
|
189
|
+
// too, not just '..'.
|
|
190
|
+
const segments = rel.split(/[\\/]+/);
|
|
191
|
+
if (segments.some((s) => s === '.' || s === '..')) {
|
|
192
|
+
throw new DefError(`${ctx}: bodyFile '${rel}' must be a relative path with no '.' or '..' components`);
|
|
193
|
+
}
|
|
194
|
+
const resolvedPath = join(baseDir, rel);
|
|
195
|
+
let realBase;
|
|
196
|
+
let realTarget;
|
|
197
|
+
try {
|
|
198
|
+
// Compare realpath-to-realpath so a symlinked temp dir (macOS /var ->
|
|
199
|
+
// /private/var) doesn't spuriously fail containment, and so a symlink
|
|
200
|
+
// INSIDE the package pointing outside resolves — and is caught — below.
|
|
201
|
+
realBase = realpathSync(baseDir);
|
|
202
|
+
realTarget = realpathSync(resolvedPath);
|
|
203
|
+
}
|
|
204
|
+
catch (e) {
|
|
205
|
+
throw new DefError(`${ctx}: bodyFile '${rel}' could not be read (resolved to '${resolvedPath}'): ${e.message}`);
|
|
206
|
+
}
|
|
207
|
+
// The `+ sep` is load-bearing: without it '/pkg-evil' would pass containment
|
|
208
|
+
// for base '/pkg'. A regular-file target can never equal realBase itself.
|
|
209
|
+
if (!realTarget.startsWith(realBase + sep)) {
|
|
210
|
+
throw new DefError(`${ctx}: bodyFile '${rel}' resolves outside the workflow's directory`);
|
|
211
|
+
}
|
|
212
|
+
if (!statSync(realTarget).isFile()) {
|
|
213
|
+
throw new DefError(`${ctx}: bodyFile '${rel}' does not resolve to a regular file`);
|
|
214
|
+
}
|
|
215
|
+
return readFileSync(realTarget, 'utf8');
|
|
216
|
+
}
|
|
163
217
|
/**
|
|
164
218
|
* Parse a `judges:` list hanging off a produce entry (§24 YAML surface). Each
|
|
165
219
|
* entry's `bodyFile` (if present) is resolved against `baseDir` and read
|
|
@@ -194,13 +248,7 @@ function parseJudges(v, ctx, baseDir) {
|
|
|
194
248
|
if (baseDir === undefined) {
|
|
195
249
|
throw new DefError(`judge '${name}': bodyFile requires a workflow loaded from disk (no base directory to resolve '${bodyFileRel}' against)`);
|
|
196
250
|
}
|
|
197
|
-
|
|
198
|
-
try {
|
|
199
|
-
body = readFileSync(resolvedPath, 'utf8');
|
|
200
|
-
}
|
|
201
|
-
catch (e) {
|
|
202
|
-
throw new DefError(`judge '${name}': bodyFile '${bodyFileRel}' could not be read (resolved to '${resolvedPath}'): ${e.message}`);
|
|
203
|
-
}
|
|
251
|
+
body = readBodyFileContained(baseDir, bodyFileRel, `judge '${name}'`);
|
|
204
252
|
}
|
|
205
253
|
else {
|
|
206
254
|
body = asString(raw.body, `judge '${name}'.body`);
|
|
@@ -807,13 +855,7 @@ function buildStep(rl, i, baseDir) {
|
|
|
807
855
|
if (baseDir === undefined) {
|
|
808
856
|
throw new DefError(`step '${name}': bodyFile requires a workflow loaded from disk (no base directory to resolve '${bodyFileRel}' against)`);
|
|
809
857
|
}
|
|
810
|
-
|
|
811
|
-
try {
|
|
812
|
-
body = readFileSync(resolvedPath, 'utf8');
|
|
813
|
-
}
|
|
814
|
-
catch (e) {
|
|
815
|
-
throw new DefError(`step '${name}': bodyFile '${bodyFileRel}' could not be read (resolved to '${resolvedPath}'): ${e.message}`);
|
|
816
|
-
}
|
|
858
|
+
body = readBodyFileContained(baseDir, bodyFileRel, `step '${name}'`);
|
|
817
859
|
}
|
|
818
860
|
else {
|
|
819
861
|
body = hasBody ? asString(rl.body, `step '${name}'.body`) : '';
|
|
@@ -887,6 +929,17 @@ function buildStep(rl, i, baseDir) {
|
|
|
887
929
|
const reapTtlStr = asString(rl.reapTtl, `step '${name}'.reapTtl`);
|
|
888
930
|
step.reapTtlMs = parseDurationMs(reapTtlStr);
|
|
889
931
|
}
|
|
932
|
+
// A2: opaque routing labels. Empty list normalizes to absent (claimable by
|
|
933
|
+
// any caller), mirroring the groups.length > 0 pattern below.
|
|
934
|
+
if (rl.labels !== undefined) {
|
|
935
|
+
const ls = asStringArray(rl.labels, `step '${name}'.labels`);
|
|
936
|
+
if (ls.length > 0)
|
|
937
|
+
step.labels = ls;
|
|
938
|
+
}
|
|
939
|
+
// A3: per-step max total lease lifetime (duration string, same as reapTtl).
|
|
940
|
+
if (rl.maxLease !== undefined) {
|
|
941
|
+
step.maxLeaseMs = parseDurationMs(asString(rl.maxLease, `step '${name}'.maxLease`));
|
|
942
|
+
}
|
|
890
943
|
// generates: entries may not declare judges: (they are lint-exempt side outputs,
|
|
891
944
|
// not part of the step's primary contract) — hard error mirrors the calls: check above.
|
|
892
945
|
for (const p of generatesPatterns) {
|
|
@@ -1430,7 +1483,28 @@ function buildDefFile(file) {
|
|
|
1430
1483
|
* defs in the same directory (M1-SITE).
|
|
1431
1484
|
*/
|
|
1432
1485
|
export function loadDefs(dir) {
|
|
1433
|
-
// Phase 1
|
|
1486
|
+
// Phase 1 (scan) then Phase 2/3 (finalize). The two phases are split so a
|
|
1487
|
+
// caller that needs to MERGE raw maps from several dirs before validating
|
|
1488
|
+
// (e.g. the CLI's installed-defs fold-in, which must let a base def `calls:`
|
|
1489
|
+
// an installed def across the boundary) can run one finalize over the merged
|
|
1490
|
+
// raw map. For a single dir this is exactly the old inline body.
|
|
1491
|
+
return finalizeDefs(loadDefsUnfinalized(dir));
|
|
1492
|
+
}
|
|
1493
|
+
/**
|
|
1494
|
+
* Phase 1 of def loading: scan `dir` and build every workflow def UN-finalized
|
|
1495
|
+
* (includes not yet expanded, no cross-def / cycle validation). Loads each
|
|
1496
|
+
* top-level `*.yaml` / `*.yml` file (excluding a top-level `workflow.yaml`) and
|
|
1497
|
+
* each immediate subdirectory's `workflow.yaml`. Throws `DefError` on a
|
|
1498
|
+
* duplicate name WITHIN this dir. This is a pure extraction of what used to live
|
|
1499
|
+
* inline in `loadDefs` — `loadDefs(dir)` is exactly `finalizeDefs(loadDefsUnfinalized(dir))`.
|
|
1500
|
+
*
|
|
1501
|
+
* Exported so a caller can merge the raw maps of several dirs and run a single
|
|
1502
|
+
* `finalizeDefs` over the union (giving correct include-expansion and cross-def
|
|
1503
|
+
* `calls:` resolution across the merged boundary). This function stays a pure
|
|
1504
|
+
* dir-scanner: it holds NO ledger / `installed.json` knowledge (that composition
|
|
1505
|
+
* lives at the CLI layer where cwd and defsDir are both known).
|
|
1506
|
+
*/
|
|
1507
|
+
export function loadDefsUnfinalized(dir) {
|
|
1434
1508
|
const raw = new Map();
|
|
1435
1509
|
const addRaw = (def, file) => {
|
|
1436
1510
|
if (raw.has(def.name))
|
|
@@ -1451,7 +1525,26 @@ export function loadDefs(dir) {
|
|
|
1451
1525
|
addRaw(buildDefFile(full), full);
|
|
1452
1526
|
}
|
|
1453
1527
|
}
|
|
1454
|
-
|
|
1528
|
+
return raw;
|
|
1529
|
+
}
|
|
1530
|
+
/**
|
|
1531
|
+
* Phase 2/3 of def loading, factored out so it is the ONE validator every
|
|
1532
|
+
* public construction path shares — the filesystem `loadDefs` above AND the
|
|
1533
|
+
* in-memory `createEngine({ defs })` factory path (REL-4). Given a raw def map
|
|
1534
|
+
* (each def possibly still carrying `_includes`), it: expands each def's
|
|
1535
|
+
* includes; runs the cross-def `calls:` checks (target existence, `callsInputs`
|
|
1536
|
+
* key validity, exactly-one child output); runs `validateDef` per expanded def;
|
|
1537
|
+
* and finally `detectCallsCycles` over the whole expanded map. Returns the
|
|
1538
|
+
* expanded, validated map. Throws `DefError` on the first problem — the same
|
|
1539
|
+
* messages, in the same order, the filesystem loader has always produced (this
|
|
1540
|
+
* is a pure extraction of what used to live inline in `loadDefs`).
|
|
1541
|
+
*
|
|
1542
|
+
* A host wiring an `Engine` by hand with its own set can call this to get the
|
|
1543
|
+
* same validation the factory and the loader apply. `expandIncludes` is a no-op
|
|
1544
|
+
* for a def without `_includes` (the normal in-memory case), so passing a plain
|
|
1545
|
+
* def map through is cheap and only adds the cross-def + cycle checks.
|
|
1546
|
+
*/
|
|
1547
|
+
export function finalizeDefs(raw) {
|
|
1455
1548
|
const out = new Map();
|
|
1456
1549
|
const resolver = (name) => raw.get(name);
|
|
1457
1550
|
for (const [name, def] of raw) {
|