owenloop 0.4.0 → 0.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.
- package/CHANGELOG.md +45 -0
- package/README.md +98 -25
- package/bin/owenloop.mjs +2 -2
- package/dist/packages/work/src/agent/brief.d.ts +172 -0
- package/dist/packages/work/src/agent/brief.js +193 -0
- package/dist/packages/work/src/agent/loop.d.ts +135 -0
- package/dist/packages/work/src/agent/loop.js +542 -0
- package/dist/packages/work/src/agent/workdir.d.ts +210 -0
- package/dist/packages/work/src/agent/workdir.js +319 -0
- package/dist/packages/work/src/bundle/cache.d.ts +90 -0
- package/dist/packages/work/src/bundle/cache.js +324 -0
- package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
- package/dist/packages/work/src/bundle/fetch.js +325 -0
- package/dist/packages/work/src/bundle/types.d.ts +160 -0
- package/dist/packages/work/src/bundle/types.js +1 -0
- package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
- package/dist/packages/work/src/credentials/owenloop.js +28 -0
- package/dist/packages/work/src/credentials/reader.d.ts +36 -0
- package/dist/packages/work/src/credentials/reader.js +32 -0
- package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
- package/dist/packages/work/src/credentials/resolve.js +56 -0
- package/dist/packages/work/src/exec/loop.d.ts +29 -0
- package/dist/packages/work/src/exec/loop.js +215 -0
- package/dist/packages/work/src/exec/receipt.d.ts +38 -0
- package/dist/packages/work/src/exec/receipt.js +21 -0
- package/dist/packages/work/src/exec/runner.d.ts +65 -0
- package/dist/packages/work/src/exec/runner.js +185 -0
- package/dist/packages/work/src/harness/child-env.d.ts +100 -0
- package/dist/packages/work/src/harness/child-env.js +127 -0
- package/dist/packages/work/src/harness/claude.d.ts +128 -0
- package/dist/packages/work/src/harness/claude.js +635 -0
- package/dist/packages/work/src/harness/codex.d.ts +110 -0
- package/dist/packages/work/src/harness/codex.js +896 -0
- package/dist/packages/work/src/harness/contract.d.ts +283 -0
- package/dist/packages/work/src/harness/contract.js +32 -0
- package/dist/packages/work/src/harness/fake.d.ts +59 -0
- package/dist/packages/work/src/harness/fake.js +90 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
- package/dist/packages/work/src/harness/permissions.d.ts +62 -0
- package/dist/packages/work/src/harness/permissions.js +93 -0
- package/dist/packages/work/src/harness/registry.d.ts +47 -0
- package/dist/packages/work/src/harness/registry.js +45 -0
- package/dist/packages/work/src/harness/session-store.d.ts +163 -0
- package/dist/packages/work/src/harness/session-store.js +319 -0
- package/dist/packages/work/src/harness/types.d.ts +29 -0
- package/dist/packages/work/src/harness/types.js +14 -0
- package/dist/packages/work/src/harnesses.d.ts +38 -0
- package/dist/packages/work/src/harnesses.js +38 -0
- package/dist/packages/work/src/hold/loop.d.ts +36 -0
- package/dist/packages/work/src/hold/loop.js +23 -0
- package/dist/packages/work/src/hold/mcp.d.ts +55 -0
- package/dist/packages/work/src/hold/mcp.js +149 -0
- package/dist/packages/work/src/hub/client.d.ts +22 -0
- package/dist/packages/work/src/hub/client.js +78 -0
- package/dist/packages/work/src/hub/types.d.ts +290 -0
- package/dist/packages/work/src/hub/types.js +28 -0
- package/dist/packages/work/src/lease/loop.d.ts +94 -0
- package/dist/packages/work/src/lease/loop.js +277 -0
- package/dist/packages/work/src/main.d.ts +1 -0
- package/dist/packages/work/src/main.js +48 -0
- package/dist/packages/work/src/mcp/server.d.ts +125 -0
- package/dist/packages/work/src/mcp/server.js +320 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
- package/dist/packages/work/src/roles/agent-run.js +447 -0
- package/dist/packages/work/src/roles/exec.d.ts +40 -0
- package/dist/packages/work/src/roles/exec.js +203 -0
- package/dist/packages/work/src/roles/hold.d.ts +68 -0
- package/dist/packages/work/src/roles/hold.js +324 -0
- package/dist/packages/work/src/roles/join.d.ts +18 -0
- package/dist/packages/work/src/roles/join.js +204 -0
- package/dist/packages/work/src/roles/lint.d.ts +59 -0
- package/dist/packages/work/src/roles/lint.js +200 -0
- package/dist/packages/work/src/roles/prepare.d.ts +1 -0
- package/dist/packages/work/src/roles/prepare.js +249 -0
- package/dist/packages/work/src/roles/release.d.ts +48 -0
- package/dist/packages/work/src/roles/release.js +137 -0
- package/dist/packages/work/src/roles/sessions.d.ts +61 -0
- package/dist/packages/work/src/roles/sessions.js +180 -0
- package/dist/packages/work/src/roles/settings.d.ts +6 -0
- package/dist/packages/work/src/roles/settings.js +66 -0
- package/dist/packages/work/src/roles/shift.d.ts +12 -0
- package/dist/packages/work/src/roles/shift.js +228 -0
- package/dist/packages/work/src/roles/signals.d.ts +55 -0
- package/dist/packages/work/src/roles/signals.js +62 -0
- package/dist/packages/work/src/settings/provision.d.ts +21 -0
- package/dist/packages/work/src/settings/provision.js +47 -0
- package/dist/packages/work/src/settings/settings.d.ts +120 -0
- package/dist/packages/work/src/settings/settings.js +116 -0
- package/dist/packages/work/src/shift/client.d.ts +24 -0
- package/dist/packages/work/src/shift/client.js +124 -0
- package/dist/packages/work/src/shift/loop.d.ts +120 -0
- package/dist/packages/work/src/shift/loop.js +468 -0
- package/dist/packages/work/src/shift/protocol.d.ts +91 -0
- package/dist/packages/work/src/shift/protocol.js +24 -0
- package/dist/packages/work/src/shift/routing.d.ts +35 -0
- package/dist/packages/work/src/shift/routing.js +50 -0
- package/dist/packages/work/src/shift/runtime.d.ts +43 -0
- package/dist/packages/work/src/shift/runtime.js +274 -0
- package/dist/packages/work/src/shift/server.d.ts +23 -0
- package/dist/packages/work/src/shift/server.js +716 -0
- package/dist/packages/work/src/shift/spawn.d.ts +86 -0
- package/dist/packages/work/src/shift/spawn.js +100 -0
- package/dist/packages/work/src/shift/state.d.ts +77 -0
- package/dist/packages/work/src/shift/state.js +162 -0
- package/dist/packages/work/src/usage.d.ts +6 -0
- package/dist/packages/work/src/usage.js +175 -0
- package/dist/{add.d.ts → src/add.d.ts} +12 -40
- package/dist/{add.js → src/add.js} +11 -176
- package/dist/src/cli.d.ts +147 -0
- package/dist/{cli.js → src/cli.js} +1643 -353
- package/dist/src/credentials.d.ts +280 -0
- package/dist/src/credentials.js +697 -0
- package/dist/{defs.js → src/defs.js} +59 -36
- package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
- package/dist/{engine.js → src/engine.js} +29 -20
- package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
- package/dist/{hub.js → src/hub.js} +531 -1
- package/dist/{index.d.ts → src/index.d.ts} +3 -1
- package/dist/{index.js → src/index.js} +2 -1
- package/dist/src/lock.d.ts +80 -0
- package/dist/src/lock.js +217 -0
- package/dist/src/mcp/serve.d.ts +85 -0
- package/dist/src/mcp/serve.js +702 -0
- package/dist/src/mcp/server.d.ts +132 -0
- package/dist/src/mcp/server.js +327 -0
- package/dist/{model.d.ts → src/model.d.ts} +59 -4
- package/dist/{model.js → src/model.js} +149 -22
- package/dist/{types.d.ts → src/types.d.ts} +66 -24
- package/dist/{util.d.ts → src/util.d.ts} +25 -0
- package/dist/{util.js → src/util.js} +26 -0
- package/dist/src/work-settings.d.ts +57 -0
- package/dist/src/work-settings.js +84 -0
- package/docs/authoring.md +102 -53
- package/docs/cli.md +883 -29
- package/docs/design.md +119 -45
- package/docs/embedding.md +39 -14
- package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
- package/examples/workflows/compile-dev-playbook.yaml +338 -0
- package/examples/workflows/judges/gate-sharpness.md +39 -0
- package/examples/workflows/judges/security.md +34 -0
- package/package.json +17 -8
- package/dist/cli.d.ts +0 -83
- /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
- /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
- /package/dist/{factory.js → src/factory.js} +0 -0
- /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
- /package/dist/{paths.js → src/paths.js} +0 -0
- /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
- /package/dist/{schema.js → src/schema.js} +0 -0
- /package/dist/{store.d.ts → src/store.d.ts} +0 -0
- /package/dist/{store.js → src/store.js} +0 -0
- /package/dist/{types.js → src/types.js} +0 -0
- /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
- /package/dist/{untar.js → src/untar.js} +0 -0
|
@@ -391,8 +391,14 @@ function idleEligible(step, arts, time) {
|
|
|
391
391
|
* output to discharge. This is the scheduling gate (§11.4): necessary, not
|
|
392
392
|
* sufficient; the commit fingerprint (§12.2) is the correctness boundary.
|
|
393
393
|
* Assumes `pendingOwed` has already been materialized into `arts`.
|
|
394
|
+
*
|
|
395
|
+
* `opts.ignoreFreeze` (used by `modelCheck`'s stall-vs-true-deadlock
|
|
396
|
+
* recompute): when true, treat every `frozen()` guard as false — i.e.
|
|
397
|
+
* "what would be eligible if every maxAttempts/maxSchemaFailures/held brake
|
|
398
|
+
* were lifted (a human `retry` = unlimited attempts)". It ONLY lifts the
|
|
399
|
+
* freeze; group-exclusivity, input-green gates, and `isDebt` are untouched.
|
|
394
400
|
*/
|
|
395
|
-
export function eligibleFirings(def, arts, time) {
|
|
401
|
+
export function eligibleFirings(def, arts, time, opts) {
|
|
396
402
|
const firings = [];
|
|
397
403
|
for (const step of def.steps) {
|
|
398
404
|
// M2: calls: steps are machine-handled (the engine spawns the child); never emit a worker firing.
|
|
@@ -436,7 +442,7 @@ export function eligibleFirings(def, arts, time) {
|
|
|
436
442
|
if (plainSatisfied) {
|
|
437
443
|
const outs = plainOutputs(step).filter((p) => {
|
|
438
444
|
const a = arts.get(p);
|
|
439
|
-
return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
|
|
445
|
+
return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
|
|
440
446
|
});
|
|
441
447
|
if (outs.length) {
|
|
442
448
|
firings.push({ step: step.name, key: '', inputs: plainPaths, outputs: outs });
|
|
@@ -463,7 +469,9 @@ export function eligibleFirings(def, arts, time) {
|
|
|
463
469
|
// never be a group member today — this check is defensive, not reachable,
|
|
464
470
|
// and exists so a future relaxation of the singleton-only restriction can't
|
|
465
471
|
// silently reopen the eligibility/commit-check gap this file fixes.
|
|
466
|
-
if (!isDebt(outArt) ||
|
|
472
|
+
if (!isDebt(outArt) ||
|
|
473
|
+
(!opts?.ignoreFreeze && frozen(outArt, step)) ||
|
|
474
|
+
groupBlockingWinner(def, arts, outPath) !== undefined)
|
|
467
475
|
continue;
|
|
468
476
|
firings.push({
|
|
469
477
|
step: step.name,
|
|
@@ -494,7 +502,7 @@ export function eligibleFirings(def, arts, time) {
|
|
|
494
502
|
.map((p) => p.stem)
|
|
495
503
|
.filter((p) => {
|
|
496
504
|
const a = arts.get(p);
|
|
497
|
-
return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
|
|
505
|
+
return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
|
|
498
506
|
});
|
|
499
507
|
if (outs.length) {
|
|
500
508
|
firings.push({
|
|
@@ -519,7 +527,7 @@ export function eligibleFirings(def, arts, time) {
|
|
|
519
527
|
// Workflow IS all-green. Check if the evaluator still has a debt to discharge.
|
|
520
528
|
const outs = plainOutputs(step).filter((p) => {
|
|
521
529
|
const a = arts.get(p);
|
|
522
|
-
return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
|
|
530
|
+
return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
|
|
523
531
|
});
|
|
524
532
|
if (outs.length > 0) {
|
|
525
533
|
firings.push({
|
|
@@ -536,7 +544,7 @@ export function eligibleFirings(def, arts, time) {
|
|
|
536
544
|
if (idleEligible(step, arts, time)) {
|
|
537
545
|
const outs = plainOutputs(step).filter((p) => {
|
|
538
546
|
const a = arts.get(p);
|
|
539
|
-
return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
|
|
547
|
+
return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
|
|
540
548
|
});
|
|
541
549
|
if (outs.length > 0) {
|
|
542
550
|
firings.push({
|
|
@@ -561,6 +569,77 @@ function plainOutputs(step) {
|
|
|
561
569
|
out.push(sealPath(p.stem));
|
|
562
570
|
return out;
|
|
563
571
|
}
|
|
572
|
+
/**
|
|
573
|
+
* Forward stem-reachability fixpoint from the seeded workflow inputs: a step's
|
|
574
|
+
* produced stems become reachable once every one of its consumed stems is
|
|
575
|
+
* reachable. Intentionally duplicates defs.ts's `reachabilityErrors` fixpoint
|
|
576
|
+
* rather than importing it — defs.ts does not import model.ts and model.ts
|
|
577
|
+
* does not import defs.ts; canEverFire's discharge-set logic (below) depends
|
|
578
|
+
* on model.ts's own mode helpers, so importing across the boundary either way
|
|
579
|
+
* would create a cycle. This local copy keeps the import graph acyclic.
|
|
580
|
+
*/
|
|
581
|
+
function reachableStems(def) {
|
|
582
|
+
const reachable = new Set(def.inputs.map((i) => i.name));
|
|
583
|
+
let changed = true;
|
|
584
|
+
while (changed) {
|
|
585
|
+
changed = false;
|
|
586
|
+
for (const step of def.steps) {
|
|
587
|
+
if (!step.consumes.every((c) => reachable.has(c.stem)))
|
|
588
|
+
continue;
|
|
589
|
+
for (const p of step.produces) {
|
|
590
|
+
if (!reachable.has(p.stem)) {
|
|
591
|
+
reachable.add(p.stem);
|
|
592
|
+
changed = true;
|
|
593
|
+
}
|
|
594
|
+
}
|
|
595
|
+
}
|
|
596
|
+
}
|
|
597
|
+
return reachable;
|
|
598
|
+
}
|
|
599
|
+
/**
|
|
600
|
+
* Pure static predicate: can `step` EVER fire, under ANY search bounds?
|
|
601
|
+
*
|
|
602
|
+
* A SOUND detector of deadness: returns false ONLY when we are CERTAIN no
|
|
603
|
+
* firing can ever be pushed for this step, mirroring the discharge-set logic
|
|
604
|
+
* `eligibleFirings` (above) actually uses. When uncertain, returns true (the
|
|
605
|
+
* safe, non-failing default) — a false "structurally dead" would wrongly make
|
|
606
|
+
* `check` exit nonzero, so soundness is biased toward under-reporting.
|
|
607
|
+
*
|
|
608
|
+
* - Reachability: if any consumed stem is not reachable from the workflow
|
|
609
|
+
* inputs (see `reachableStems`), the step can never fire. Belt-and-suspenders
|
|
610
|
+
* — `validateDef`'s `reachabilityErrors` already turns this into a hard error
|
|
611
|
+
* before `modelCheck` ever runs, so this arm is defensive, not the live path.
|
|
612
|
+
* - Judge step (`step.judges`): fires against the judged stem, not a produces
|
|
613
|
+
* set; can-fire iff the judged stem is reachable (already implied by the
|
|
614
|
+
* reachability arm above, since a judge step consumes the judged stem — kept
|
|
615
|
+
* explicit for clarity and to stay correct if judge-step synthesis changes).
|
|
616
|
+
* - reduce: the discharge set is `singletonProduces(step)` only (see the
|
|
617
|
+
* reduce branch of `eligibleFirings`) — zero singleton produces means no
|
|
618
|
+
* firing is ever pushed, regardless of bounds.
|
|
619
|
+
* - map: needs both a map-consume and a map-produce to bind an element.
|
|
620
|
+
* - plain (inputsGreen / allGreen / idle): the discharge set is `plainOutputs`
|
|
621
|
+
* (singleton produces + collection seals) — empty means no firing ever.
|
|
622
|
+
*
|
|
623
|
+
* `reachable` may be precomputed once by the caller and passed in (modelCheck
|
|
624
|
+
* calls this per dead step and must not recompute the fixpoint each time).
|
|
625
|
+
*/
|
|
626
|
+
export function canEverFire(step, def, reachable) {
|
|
627
|
+
const reach = reachable ?? reachableStems(def);
|
|
628
|
+
if (!step.consumes.every((c) => reach.has(c.stem)))
|
|
629
|
+
return false;
|
|
630
|
+
if (step.judges)
|
|
631
|
+
return reach.has(step.judges);
|
|
632
|
+
switch (stepMode(step)) {
|
|
633
|
+
case 'reduce':
|
|
634
|
+
return singletonProduces(step).length > 0;
|
|
635
|
+
case 'map':
|
|
636
|
+
return !!mapProduce(step) && !!mapConsume(step);
|
|
637
|
+
case 'plain':
|
|
638
|
+
return plainOutputs(step).length > 0;
|
|
639
|
+
default:
|
|
640
|
+
return true; // not certain of deadness — default to can-fire (soundness bias)
|
|
641
|
+
}
|
|
642
|
+
}
|
|
564
643
|
// ---- level-triggered maintenance (§11.8, §12.3) -----------------------------
|
|
565
644
|
/**
|
|
566
645
|
* The standing guard: re-derive the invariant "an artifact is green only while
|
|
@@ -1525,6 +1604,9 @@ function seedArts(def, assumeProvided = false) {
|
|
|
1525
1604
|
// seedOwed=false → seed green (version 1); seedOwed=true → seed owed (version 0)
|
|
1526
1605
|
// The checker has no runtime `provide` values, so seedOwed inputs start owed —
|
|
1527
1606
|
// unless assumeProvided, which models "the operator ran `provide` at create".
|
|
1607
|
+
// This function's own default stays false; the `owenloop check` CLI command
|
|
1608
|
+
// now passes assumeProvided: true by default (its `--strict-inputs` flag
|
|
1609
|
+
// passes false to restore this owed-start behavior) — see CheckOptions.
|
|
1528
1610
|
const seedGreen = !input.seedOwed || assumeProvided;
|
|
1529
1611
|
arts.set(input.name, {
|
|
1530
1612
|
workflow: '',
|
|
@@ -1546,7 +1628,7 @@ function eligibleOutcomes(def, arts, firing) {
|
|
|
1546
1628
|
return ['green'];
|
|
1547
1629
|
// §24: a judge firing's own verdict is against the judged stem, not against a
|
|
1548
1630
|
// produce of its own (judge steps declare `produces: []`). Model the two verbs
|
|
1549
|
-
// the judge
|
|
1631
|
+
// the judge Step Agent can issue (green/reject, Q2) as their own outcomes, entirely
|
|
1550
1632
|
// separate from the producer-outcome branches below.
|
|
1551
1633
|
if (step.judges) {
|
|
1552
1634
|
// §26: if this is the last pending judge and approving would flip the
|
|
@@ -1857,10 +1939,29 @@ function canonicalKey(def, arts) {
|
|
|
1857
1939
|
* Bounded reachability / liveness checker over a workflow definition.
|
|
1858
1940
|
*
|
|
1859
1941
|
* Explores the full (or depth/state-bounded) state space via BFS to find:
|
|
1860
|
-
* -
|
|
1861
|
-
*
|
|
1942
|
+
* - a non-done, zero-eligible-firings state is split into exactly ONE of two
|
|
1943
|
+
* mutually exclusive buckets by recomputing eligibility with every freeze
|
|
1944
|
+
* lifted (unlimited attempts — see `eligibleFirings`'s `ignoreFreeze`):
|
|
1945
|
+
* - stall states: the recompute yields >= 1 firing — the state's only
|
|
1946
|
+
* blocker is a frozen/stalled debt (maxAttempts / maxSchemaFailures /
|
|
1947
|
+
* held). A by-design human-escalation brake. EXPECTED, never a defect.
|
|
1948
|
+
* - true deadlocks: the recompute STILL yields zero firings — a genuine
|
|
1949
|
+
* structural dead-end with no path to completion even at unlimited
|
|
1950
|
+
* attempts. A real defect.
|
|
1951
|
+
* - stuck states: reachable states that have a stalled debt but STILL have
|
|
1952
|
+
* >= 1 eligible firing elsewhere (a brake tripped on one branch while the
|
|
1953
|
+
* line moves on another). Informational only; a no-moves state is never
|
|
1954
|
+
* listed here — it lands in `stallStates` or `deadlocks` instead, so no
|
|
1955
|
+
* state is ever double-listed.
|
|
1862
1956
|
* - completability: whether any reachable state is done (with an example path)
|
|
1863
|
-
* - dead steps: steps whose name never appears as a firing in any explored
|
|
1957
|
+
* - dead steps: steps whose name never appears as a firing in any explored
|
|
1958
|
+
* transition. Split into two categories by the static `canEverFire` check
|
|
1959
|
+
* (independent of search bounds):
|
|
1960
|
+
* - structurally-dead: `canEverFire` is false — the step can NEVER fire
|
|
1961
|
+
* regardless of `--max-depth`/`--max-states`. A genuine wiring defect.
|
|
1962
|
+
* - unreached-within-bounds: `canEverFire` is true — the step CAN fire in
|
|
1963
|
+
* principle but the bounded search didn't reach it. A bounds artifact,
|
|
1964
|
+
* not a defect; raising `--max-states`/`--max-depth` may surface it.
|
|
1864
1965
|
*
|
|
1865
1966
|
* Pure — no store, no engine, no IO.
|
|
1866
1967
|
*/
|
|
@@ -1878,10 +1979,12 @@ export function modelCheck(def, opts = {}) {
|
|
|
1878
1979
|
bounded: false,
|
|
1879
1980
|
boundsHit: [],
|
|
1880
1981
|
deadlocks: [],
|
|
1982
|
+
stallStates: [],
|
|
1881
1983
|
stuck: [],
|
|
1882
1984
|
completable: false,
|
|
1883
1985
|
completePath: undefined,
|
|
1884
|
-
|
|
1986
|
+
structurallyDeadSteps: [],
|
|
1987
|
+
unreachedSteps: [],
|
|
1885
1988
|
invariantViolations: [],
|
|
1886
1989
|
stats: { statesExplored: 0, depthReached: 0 },
|
|
1887
1990
|
};
|
|
@@ -1926,17 +2029,29 @@ export function modelCheck(def, opts = {}) {
|
|
|
1926
2029
|
}
|
|
1927
2030
|
continue; // done states have no successors
|
|
1928
2031
|
}
|
|
1929
|
-
// Check stuck (any debt.stalled)
|
|
1930
|
-
if (status.debts.some((d) => d.stalled)) {
|
|
1931
|
-
report.stuck.push({ path: node.path });
|
|
1932
|
-
// continue exploring (there may be other paths)
|
|
1933
|
-
}
|
|
1934
2032
|
const firings = status.eligible;
|
|
1935
|
-
//
|
|
2033
|
+
// Non-done state with no eligible firings: classify by recomputing eligibility
|
|
2034
|
+
// as if every freeze/stall were lifted (unlimited attempts). If a producer
|
|
2035
|
+
// would re-arm → an EXPECTED stall state (a by-design brake). If not → a
|
|
2036
|
+
// TRUE deadlock (a structural dead-end with no path to completion even at
|
|
2037
|
+
// unlimited attempts).
|
|
1936
2038
|
if (firings.length === 0 && !status.done) {
|
|
1937
|
-
|
|
2039
|
+
const lifted = eligibleFirings(def, node.arts, undefined, { ignoreFreeze: true });
|
|
2040
|
+
if (lifted.length > 0) {
|
|
2041
|
+
report.stallStates.push({ path: node.path });
|
|
2042
|
+
}
|
|
2043
|
+
else {
|
|
2044
|
+
report.deadlocks.push({ path: node.path });
|
|
2045
|
+
}
|
|
1938
2046
|
continue;
|
|
1939
2047
|
}
|
|
2048
|
+
// The state HAS eligible firings (the line can still move). If a brake tripped
|
|
2049
|
+
// on some *other* branch, record it as an informational stuck state. A no-moves
|
|
2050
|
+
// stall state never reaches here (it `continue`d above), so no state is ever
|
|
2051
|
+
// listed in both `stuck` and `stallStates`/`deadlocks`.
|
|
2052
|
+
if (status.debts.some((d) => d.stalled)) {
|
|
2053
|
+
report.stuck.push({ path: node.path });
|
|
2054
|
+
}
|
|
1940
2055
|
// Respect maxDepth
|
|
1941
2056
|
if (node.depth >= maxDepth) {
|
|
1942
2057
|
boundsHit.add('maxDepth');
|
|
@@ -1970,9 +2085,21 @@ export function modelCheck(def, opts = {}) {
|
|
|
1970
2085
|
report.stats.depthReached = depthReached;
|
|
1971
2086
|
report.boundsHit = [...boundsHit];
|
|
1972
2087
|
report.bounded = boundsHit.size > 0;
|
|
1973
|
-
// Dead steps: steps in the def that never appeared as a firing.step
|
|
1974
|
-
|
|
1975
|
-
|
|
1976
|
-
|
|
2088
|
+
// Dead steps: steps in the def that never appeared as a firing.step, split
|
|
2089
|
+
// by the static canEverFire check into structurally-dead (a real wiring
|
|
2090
|
+
// defect — can never fire regardless of bounds) vs unreached-within-bounds
|
|
2091
|
+
// (can fire in principle; the bounded search just didn't reach it).
|
|
2092
|
+
// Compute the reachability fixpoint once, not per dead step.
|
|
2093
|
+
const reachable = reachableStems(def);
|
|
2094
|
+
for (const l of def.steps) {
|
|
2095
|
+
if (firedSteps.has(l.name))
|
|
2096
|
+
continue;
|
|
2097
|
+
if (canEverFire(l, def, reachable)) {
|
|
2098
|
+
report.unreachedSteps.push(l.name);
|
|
2099
|
+
}
|
|
2100
|
+
else {
|
|
2101
|
+
report.structurallyDeadSteps.push(l.name);
|
|
2102
|
+
}
|
|
2103
|
+
}
|
|
1977
2104
|
return report;
|
|
1978
2105
|
}
|
|
@@ -137,11 +137,11 @@ export interface Order {
|
|
|
137
137
|
/** Declares which kind of executor this order is for. Absent = 'agent'
|
|
138
138
|
* (today's behavior). Opaque to the engine; carried through verbatim from
|
|
139
139
|
* the step definition, same pass-through contract as `model`/`x`. */
|
|
140
|
-
|
|
141
|
-
/** The command string for a `
|
|
140
|
+
executor?: string;
|
|
141
|
+
/** The command string for a `executor: command` order. Opaque to the engine
|
|
142
142
|
* — never parsed, never shelled out. */
|
|
143
143
|
command?: string;
|
|
144
|
-
/** Opaque config object for a non-agent/non-command
|
|
144
|
+
/** Opaque config object for a non-agent/non-command executor type (or
|
|
145
145
|
* alongside `command`). Carried through untouched, contents never read. */
|
|
146
146
|
spec?: Record<string, unknown>;
|
|
147
147
|
/** §27.3: the step's opaque `x:` extension map, carried through untouched
|
|
@@ -256,13 +256,13 @@ export interface ProducePattern {
|
|
|
256
256
|
cadence?: string;
|
|
257
257
|
maxRunsPerDay?: number;
|
|
258
258
|
/** Declares which kind of executor this judge's synthesized order is for.
|
|
259
|
-
* Same opaque-passthrough contract as StepDef.
|
|
259
|
+
* Same opaque-passthrough contract as StepDef.executor — default 'agent'
|
|
260
260
|
* when omitted. */
|
|
261
|
-
|
|
262
|
-
/** Required when
|
|
261
|
+
executor?: string;
|
|
262
|
+
/** Required when executor is 'command'; the command string for that executor
|
|
263
263
|
* to run. Opaque to the engine — never parsed, never shelled out. */
|
|
264
264
|
command?: string;
|
|
265
|
-
/** Optional opaque config object for a non-agent/non-command
|
|
265
|
+
/** Optional opaque config object for a non-agent/non-command executor type
|
|
266
266
|
* (or additionally alongside `command`). Shape-checked as a plain map
|
|
267
267
|
* only (mirrors `x:`'s asExtension contract) — contents never read. */
|
|
268
268
|
spec?: Record<string, unknown>;
|
|
@@ -325,11 +325,11 @@ export interface StepDef {
|
|
|
325
325
|
* unchanged). Opaque to the engine beyond the shape rules validateDef
|
|
326
326
|
* enforces; carried through verbatim on the Order, same contract as
|
|
327
327
|
* `model`. */
|
|
328
|
-
|
|
329
|
-
/** Required when
|
|
328
|
+
executor?: string;
|
|
329
|
+
/** Required when executor is 'command'; the command string for that executor
|
|
330
330
|
* to run. Opaque to the engine — never parsed, never shelled out. */
|
|
331
331
|
command?: string;
|
|
332
|
-
/** Optional opaque config object for a non-agent/non-command
|
|
332
|
+
/** Optional opaque config object for a non-agent/non-command executor type
|
|
333
333
|
* (or additionally alongside `command`). Shape-checked as a plain map
|
|
334
334
|
* only (mirrors `x:`'s asExtension contract) — contents never read. */
|
|
335
335
|
spec?: Record<string, unknown>;
|
|
@@ -347,11 +347,11 @@ export interface StepDef {
|
|
|
347
347
|
idleAfterMs?: number;
|
|
348
348
|
/** Per-step reap TTL override in milliseconds. Falls back to the engine's DEFAULT_REAP_TTL_MS. */
|
|
349
349
|
reapTtlMs?: number;
|
|
350
|
-
/** A2: opaque routing
|
|
351
|
-
* caller passing a
|
|
350
|
+
/** A2: opaque routing capabilities for peer-orchestrator claim filtering. A tick
|
|
351
|
+
* caller passing a capability filter only claims steps whose capabilities intersect it;
|
|
352
352
|
* absent (or empty, normalized to absent at parse) = claimable by any caller.
|
|
353
|
-
* Distinct from `
|
|
354
|
-
|
|
353
|
+
* Distinct from `executor`/`executors` (executor-kind), which this never touches. */
|
|
354
|
+
capabilities?: string[];
|
|
355
355
|
/** A3 (REL-8): per-step OPT-IN max total lease lifetime override in
|
|
356
356
|
* milliseconds — the cap on `claimedAt + maxLease` past which renewals can no
|
|
357
357
|
* longer keep a lease fresh. Overrides the engine `maxLeaseMs`; when both are
|
|
@@ -399,10 +399,10 @@ export interface WorkflowDef {
|
|
|
399
399
|
/** §27.3: opaque workflow-level extension map (`x:`). Validated as a plain
|
|
400
400
|
* map at load time, never interpreted by the engine. */
|
|
401
401
|
x?: Record<string, unknown>;
|
|
402
|
-
/** Optional allow-list of
|
|
403
|
-
* on any step/judge whose `
|
|
404
|
-
* Absent = any
|
|
405
|
-
|
|
402
|
+
/** Optional allow-list of executor values; when present, validateDef errors
|
|
403
|
+
* on any step/judge whose `executor` is not in this list (typo guard).
|
|
404
|
+
* Absent = any executor string accepted. */
|
|
405
|
+
executors?: string[];
|
|
406
406
|
}
|
|
407
407
|
export interface InputDef {
|
|
408
408
|
name: string;
|
|
@@ -556,7 +556,12 @@ export interface CheckOptions {
|
|
|
556
556
|
* Seed `seedOwed: true` inputs green, as if `provide` already ran. The checker
|
|
557
557
|
* has no runtime provide values, so without this every seedOwed input starts
|
|
558
558
|
* owed with no transition that can green it — a def whose inputs the operator
|
|
559
|
-
* supplies at create time reports a false depth-0 deadlock. Default
|
|
559
|
+
* supplies at create time reports a false depth-0 deadlock. Default (this
|
|
560
|
+
* field, when calling `modelCheck` directly) is false — that library default
|
|
561
|
+
* is unchanged. The `owenloop check` CLI command, however, now defaults this
|
|
562
|
+
* to true (seedOwed inputs are assumed provided by default, modeling the
|
|
563
|
+
* operator's `provide` at create); its `--strict-inputs` flag opts back out
|
|
564
|
+
* to false, restoring the seedOwed-starts-owed behavior described above.
|
|
560
565
|
*/
|
|
561
566
|
assumeProvided?: boolean;
|
|
562
567
|
}
|
|
@@ -567,18 +572,55 @@ export interface CheckReport {
|
|
|
567
572
|
bounded: boolean;
|
|
568
573
|
/** Which bounds were hit, for honest reporting. */
|
|
569
574
|
boundsHit: ('maxDepth' | 'maxStates')[];
|
|
570
|
-
/**
|
|
575
|
+
/**
|
|
576
|
+
* Reachable non-done states with zero eligible firings that have NO path to
|
|
577
|
+
* completion even at unlimited attempts — i.e. recomputing eligibility with
|
|
578
|
+
* all freezes lifted (a human `retry` = unlimited attempts) STILL yields
|
|
579
|
+
* zero firings. A genuine structural dead-end (TRUE deadlock). A definite
|
|
580
|
+
* defect only when the search was exhaustive (`!bounded`) — the
|
|
581
|
+
* maxCollectionSize cap can otherwise manufacture a spurious no-moves
|
|
582
|
+
* state. Always present ([] when none).
|
|
583
|
+
*/
|
|
571
584
|
deadlocks: CheckFinding[];
|
|
572
|
-
/**
|
|
585
|
+
/**
|
|
586
|
+
* Reachable non-done states with zero eligible firings whose ONLY blocker
|
|
587
|
+
* is a frozen/stalled debt (maxAttempts / maxSchemaFailures / held).
|
|
588
|
+
* Recomputing eligibility with all freezes lifted (a human `retry` =
|
|
589
|
+
* unlimited attempts) yields >= 1 firing, so a producer would re-arm and
|
|
590
|
+
* the line could move. These are the DESIGNED human-escalation brakes —
|
|
591
|
+
* EXPECTED, never a defect; they do not affect the exit code. Always
|
|
592
|
+
* present ([] when none).
|
|
593
|
+
*/
|
|
594
|
+
stallStates: CheckFinding[];
|
|
595
|
+
/**
|
|
596
|
+
* Reachable states that have a stalled debt (maxAttempts/maxSchemaFailures/
|
|
597
|
+
* held) BUT still have >= 1 eligible firing — a brake tripped on one branch
|
|
598
|
+
* while the line can still move on another. Informational; NOT a defect on
|
|
599
|
+
* its own. A no-moves state whose only blocker is a frozen debt is recorded
|
|
600
|
+
* under `stallStates` instead, never here — so no state appears in both
|
|
601
|
+
* `stuck` and `stallStates`/`deadlocks`.
|
|
602
|
+
*/
|
|
573
603
|
stuck: CheckFinding[];
|
|
574
604
|
/** Whether any explored state is done, and (when true) one example path to it. */
|
|
575
605
|
completable: boolean;
|
|
576
606
|
completePath?: CheckStep[];
|
|
577
607
|
/**
|
|
578
|
-
* Step names that never appear as the firing step in any explored transition
|
|
579
|
-
*
|
|
608
|
+
* Step names that never appear as the firing step in any explored transition,
|
|
609
|
+
* AND a static "can this step ever fire?" check (independent of bounds) is
|
|
610
|
+
* CERTAIN no firing can ever be pushed for it (see model.ts `canEverFire`).
|
|
611
|
+
* A genuine wiring defect — always present ([] when none), and (unlike
|
|
612
|
+
* `unreachedSteps`) ALWAYS a definite finding regardless of `bounded`,
|
|
613
|
+
* because the check needs no search bounds to be certain.
|
|
614
|
+
*/
|
|
615
|
+
structurallyDeadSteps: string[];
|
|
616
|
+
/**
|
|
617
|
+
* Step names that never appear as the firing step in any explored transition,
|
|
618
|
+
* but the static `canEverFire` check says they COULD fire in principle — the
|
|
619
|
+
* bounded search just didn't reach them before exhausting `--max-states`/
|
|
620
|
+
* `--max-depth`. Informational only, NOT a defect: a bounds artifact. Raising
|
|
621
|
+
* the search bounds may make the step fire. Always present ([] when none).
|
|
580
622
|
*/
|
|
581
|
-
|
|
623
|
+
unreachedSteps: string[];
|
|
582
624
|
/**
|
|
583
625
|
* Invariants that are violated in some reachable state. Always present ([]
|
|
584
626
|
* when no invariants declared or none violated). Each entry is deduplicated by
|
|
@@ -1,4 +1,29 @@
|
|
|
1
1
|
/** Small dependency-light helpers. */
|
|
2
|
+
/**
|
|
3
|
+
* A user-facing CLI/library error whose `message` is printed as-is (no stack
|
|
4
|
+
* trace) — the "expected, explained" failure class, distinct from a programming
|
|
5
|
+
* bug. Homed here in `util.ts` (which has no project-internal imports) so it can
|
|
6
|
+
* be shared by `cli.ts` (where `RateLimitError extends CliError`) and
|
|
7
|
+
* `credentials.ts` (which must throw it without importing `cli.ts`, avoiding a
|
|
8
|
+
* cycle and keeping the library barrel from ever loading `cli.ts`). Deliberately
|
|
9
|
+
* NOT re-exported from the package barrel (`src/index.ts`): it was module-private
|
|
10
|
+
* before, and the credential-write PR does not widen the public API beyond the
|
|
11
|
+
* functions the proposal names.
|
|
12
|
+
*
|
|
13
|
+
* `exitCode` lets a specific failure map to a distinct process exit status
|
|
14
|
+
* (consumed by both entry-point catches in `cli.ts`). It defaults to `1`, so
|
|
15
|
+
* every existing `new CliError(msg)` — and `RateLimitError extends CliError`,
|
|
16
|
+
* which inherits this constructor — keeps its byte-for-byte exit-1 behavior. The
|
|
17
|
+
* non-default codes today are exit 2 (hub unresolvable) and exit 3 (human
|
|
18
|
+
* credential absent/irrecoverable), used by `agent new`, `binding
|
|
19
|
+
* new|rm|list`, and `crew`'s five subcommands.
|
|
20
|
+
*/
|
|
21
|
+
export declare class CliError extends Error {
|
|
22
|
+
readonly exitCode: number;
|
|
23
|
+
constructor(message: string, opts?: {
|
|
24
|
+
exitCode?: number;
|
|
25
|
+
});
|
|
26
|
+
}
|
|
2
27
|
/**
|
|
3
28
|
* `mkdir -p` for a project-state directory (e.g. `.owenloop`), refusing to
|
|
4
29
|
* create it through a symlinked component (SEC-3, parent-directory half).
|
|
@@ -1,6 +1,32 @@
|
|
|
1
1
|
/** Small dependency-light helpers. */
|
|
2
2
|
import { createHash, randomBytes } from 'node:crypto';
|
|
3
3
|
import { lstatSync, mkdirSync } from 'node:fs';
|
|
4
|
+
/**
|
|
5
|
+
* A user-facing CLI/library error whose `message` is printed as-is (no stack
|
|
6
|
+
* trace) — the "expected, explained" failure class, distinct from a programming
|
|
7
|
+
* bug. Homed here in `util.ts` (which has no project-internal imports) so it can
|
|
8
|
+
* be shared by `cli.ts` (where `RateLimitError extends CliError`) and
|
|
9
|
+
* `credentials.ts` (which must throw it without importing `cli.ts`, avoiding a
|
|
10
|
+
* cycle and keeping the library barrel from ever loading `cli.ts`). Deliberately
|
|
11
|
+
* NOT re-exported from the package barrel (`src/index.ts`): it was module-private
|
|
12
|
+
* before, and the credential-write PR does not widen the public API beyond the
|
|
13
|
+
* functions the proposal names.
|
|
14
|
+
*
|
|
15
|
+
* `exitCode` lets a specific failure map to a distinct process exit status
|
|
16
|
+
* (consumed by both entry-point catches in `cli.ts`). It defaults to `1`, so
|
|
17
|
+
* every existing `new CliError(msg)` — and `RateLimitError extends CliError`,
|
|
18
|
+
* which inherits this constructor — keeps its byte-for-byte exit-1 behavior. The
|
|
19
|
+
* non-default codes today are exit 2 (hub unresolvable) and exit 3 (human
|
|
20
|
+
* credential absent/irrecoverable), used by `agent new`, `binding
|
|
21
|
+
* new|rm|list`, and `crew`'s five subcommands.
|
|
22
|
+
*/
|
|
23
|
+
export class CliError extends Error {
|
|
24
|
+
exitCode;
|
|
25
|
+
constructor(message, opts) {
|
|
26
|
+
super(message);
|
|
27
|
+
this.exitCode = opts?.exitCode ?? 1;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
4
30
|
/**
|
|
5
31
|
* `mkdir -p` for a project-state directory (e.g. `.owenloop`), refusing to
|
|
6
32
|
* create it through a symlinked component (SEC-3, parent-directory half).
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* execution settings file writer — the ONE place the root `owenloop` CLI writes
|
|
3
|
+
* into the execution-side settings file.
|
|
4
|
+
*
|
|
5
|
+
* `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
|
|
6
|
+
* settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
|
|
7
|
+
* NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
|
|
8
|
+
* `owenloop setup` can point `owenloop work` at the hub it just authenticated
|
|
9
|
+
* against.
|
|
10
|
+
*
|
|
11
|
+
* This module writes exactly ONE key — `hubOrigin` — and preserves every other
|
|
12
|
+
* key byte-for-byte (forward-compat with the execution settings' `cacheDir`,
|
|
13
|
+
* `agentsDir`, `stateDir`, `dispatchCap`, `commandRouting`, and any future or
|
|
14
|
+
* unknown key). It never writes a secret: nothing secret is in scope here by
|
|
15
|
+
* construction (the hub ORIGIN is public).
|
|
16
|
+
*
|
|
17
|
+
* Corrupt-file policy: a settings file that exists but does not parse as a JSON
|
|
18
|
+
* OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
|
|
19
|
+
* it cannot safely merge into. That mirrors the work settings validator's
|
|
20
|
+
* wording family ("not an object").
|
|
21
|
+
*
|
|
22
|
+
* Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
|
|
23
|
+
* util.ts — no CLI/engine closure.
|
|
24
|
+
*/
|
|
25
|
+
/**
|
|
26
|
+
* The execution settings file path for this environment. `XDG_CONFIG_HOME` (when
|
|
27
|
+
* set and non-blank) wins over `HOME`, matching owenloop's own resolution and
|
|
28
|
+
* the owenloop credential store's `configDir`. Throws when neither is set.
|
|
29
|
+
*/
|
|
30
|
+
export declare function owenloopSettingsPath(env: Record<string, string | undefined>): string;
|
|
31
|
+
/**
|
|
32
|
+
* Read and parse the execution settings file at `path`.
|
|
33
|
+
*
|
|
34
|
+
* - Missing file → `null` (an absent settings file is not an error; the writer
|
|
35
|
+
* creates one).
|
|
36
|
+
* - Present and parses to a JSON OBJECT → that object (a `Record`).
|
|
37
|
+
* - Present but not valid JSON, or valid JSON that is NOT an object (an array,
|
|
38
|
+
* `null`, a number, a string) → a hard `CliError` naming the path. The writer
|
|
39
|
+
* must never clobber a file it cannot merge into.
|
|
40
|
+
*/
|
|
41
|
+
export declare function readOwenloopSettingsRaw(path: string): Record<string, unknown> | null;
|
|
42
|
+
/** The outcome of a `writeOwenloopHubOrigin` call — the path written and the
|
|
43
|
+
* previous `hubOrigin` value (`undefined` when the key was absent or the file
|
|
44
|
+
* did not exist), so a caller can report an old→new transition. */
|
|
45
|
+
export interface OwenloopWriteResult {
|
|
46
|
+
path: string;
|
|
47
|
+
previous: string | undefined;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Set ONLY the `hubOrigin` key in the execution settings file to `origin`,
|
|
51
|
+
* preserving every other key. Read the existing file (a parse failure is a hard
|
|
52
|
+
* `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
|
|
53
|
+
* directory, and write atomically (temp + rename via `writeFileAtomic`). The
|
|
54
|
+
* file is pretty-printed with a trailing newline. Returns the path and the
|
|
55
|
+
* previous `hubOrigin` (if any).
|
|
56
|
+
*/
|
|
57
|
+
export declare function writeOwenloopHubOrigin(env: Record<string, string | undefined>, origin: string): OwenloopWriteResult;
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* execution settings file writer — the ONE place the root `owenloop` CLI writes
|
|
3
|
+
* into the execution-side settings file.
|
|
4
|
+
*
|
|
5
|
+
* `owenloop work` reads its settings from `$XDG_CONFIG_HOME/owenloop/
|
|
6
|
+
* settings.json` (else `$HOME/.config/owenloop/settings.json`) and, by design,
|
|
7
|
+
* NEVER writes them — the root CLI's `setup` command is the writer, so a fresh
|
|
8
|
+
* `owenloop setup` can point `owenloop work` at the hub it just authenticated
|
|
9
|
+
* against.
|
|
10
|
+
*
|
|
11
|
+
* This module writes exactly ONE key — `hubOrigin` — and preserves every other
|
|
12
|
+
* key byte-for-byte (forward-compat with the execution settings' `cacheDir`,
|
|
13
|
+
* `agentsDir`, `stateDir`, `dispatchCap`, `commandRouting`, and any future or
|
|
14
|
+
* unknown key). It never writes a secret: nothing secret is in scope here by
|
|
15
|
+
* construction (the hub ORIGIN is public).
|
|
16
|
+
*
|
|
17
|
+
* Corrupt-file policy: a settings file that exists but does not parse as a JSON
|
|
18
|
+
* OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
|
|
19
|
+
* it cannot safely merge into. That mirrors the work settings validator's
|
|
20
|
+
* wording family ("not an object").
|
|
21
|
+
*
|
|
22
|
+
* Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
|
|
23
|
+
* util.ts — no CLI/engine closure.
|
|
24
|
+
*/
|
|
25
|
+
import { existsSync, mkdirSync, readFileSync } from 'node:fs';
|
|
26
|
+
import { dirname, join } from 'node:path';
|
|
27
|
+
import { writeFileAtomic } from "./hub.js";
|
|
28
|
+
import { CliError } from "./util.js";
|
|
29
|
+
/**
|
|
30
|
+
* The execution settings file path for this environment. `XDG_CONFIG_HOME` (when
|
|
31
|
+
* set and non-blank) wins over `HOME`, matching owenloop's own resolution and
|
|
32
|
+
* the owenloop credential store's `configDir`. Throws when neither is set.
|
|
33
|
+
*/
|
|
34
|
+
export function owenloopSettingsPath(env) {
|
|
35
|
+
const xdg = env.XDG_CONFIG_HOME;
|
|
36
|
+
if (xdg && xdg.trim() !== '')
|
|
37
|
+
return join(xdg, 'owenloop', 'settings.json');
|
|
38
|
+
const home = env.HOME;
|
|
39
|
+
if (home && home.trim() !== '')
|
|
40
|
+
return join(home, '.config', 'owenloop', 'settings.json');
|
|
41
|
+
throw new CliError('cannot locate a config directory for execution settings: set HOME or XDG_CONFIG_HOME');
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Read and parse the execution settings file at `path`.
|
|
45
|
+
*
|
|
46
|
+
* - Missing file → `null` (an absent settings file is not an error; the writer
|
|
47
|
+
* creates one).
|
|
48
|
+
* - Present and parses to a JSON OBJECT → that object (a `Record`).
|
|
49
|
+
* - Present but not valid JSON, or valid JSON that is NOT an object (an array,
|
|
50
|
+
* `null`, a number, a string) → a hard `CliError` naming the path. The writer
|
|
51
|
+
* must never clobber a file it cannot merge into.
|
|
52
|
+
*/
|
|
53
|
+
export function readOwenloopSettingsRaw(path) {
|
|
54
|
+
if (!existsSync(path))
|
|
55
|
+
return null;
|
|
56
|
+
let parsed;
|
|
57
|
+
try {
|
|
58
|
+
parsed = JSON.parse(readFileSync(path, 'utf8'));
|
|
59
|
+
}
|
|
60
|
+
catch {
|
|
61
|
+
throw new CliError(`execution settings file at ${path} is not valid JSON — fix or remove it before running setup`);
|
|
62
|
+
}
|
|
63
|
+
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
|
|
64
|
+
throw new CliError(`execution settings file at ${path} is not a JSON object — fix or remove it before running setup`);
|
|
65
|
+
}
|
|
66
|
+
return parsed;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Set ONLY the `hubOrigin` key in the execution settings file to `origin`,
|
|
70
|
+
* preserving every other key. Read the existing file (a parse failure is a hard
|
|
71
|
+
* `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
|
|
72
|
+
* directory, and write atomically (temp + rename via `writeFileAtomic`). The
|
|
73
|
+
* file is pretty-printed with a trailing newline. Returns the path and the
|
|
74
|
+
* previous `hubOrigin` (if any).
|
|
75
|
+
*/
|
|
76
|
+
export function writeOwenloopHubOrigin(env, origin) {
|
|
77
|
+
const path = owenloopSettingsPath(env);
|
|
78
|
+
const existing = readOwenloopSettingsRaw(path);
|
|
79
|
+
const previous = existing !== undefined && existing !== null && typeof existing.hubOrigin === 'string' ? existing.hubOrigin : undefined;
|
|
80
|
+
const merged = { ...(existing ?? {}), hubOrigin: origin };
|
|
81
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
82
|
+
writeFileAtomic(path, `${JSON.stringify(merged, null, 2)}\n`);
|
|
83
|
+
return { path, previous };
|
|
84
|
+
}
|