owenloop 0.2.0 → 0.3.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/dist/cli.js CHANGED
@@ -8,6 +8,7 @@
8
8
  * argv to engine calls.
9
9
  *
10
10
  * owenloop defs list available workflow definitions
11
+ * owenloop add <owner>/<repo>[@ref] fetch, validate, and install a repo's workflow defs (public repos)
11
12
  * owenloop create <def> [--provide n=json] [--title t] start an instance
12
13
  * owenloop provide <wf> <name> [--value json] supply an owed input
13
14
  * owenloop tick <wf> [--now ms] pull eligible orders
@@ -30,21 +31,119 @@
30
31
  *
31
32
  * Global: --db <path> (env OWENLOOP_DB), --defs <dir> (env OWENLOOP_DEFS).
32
33
  */
33
- import { existsSync, mkdirSync } from 'node:fs';
34
- import { dirname, join } from 'node:path';
34
+ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
35
+ import { basename, dirname, join, resolve } from 'node:path';
36
+ import { spawn } from 'node:child_process';
37
+ import { execFileSync } from 'node:child_process';
38
+ import { createServer } from 'node:http';
39
+ import { parse as parseYaml } from 'yaml';
35
40
  import { Engine } from "./engine.js";
36
41
  import { buildGraph, buildTrace, graphToDot, graphToMermaid, modelCheck } from "./model.js";
37
42
  import { openStore } from "./store.js";
38
- import { DefError, lintDef, loadDefs, loadDefsRaw, validateDef } from "./defs.js";
39
- import { detId, nowMs, parseDurationMs } from "./util.js";
43
+ import { buildDef, DefError, finalizeDefs, lintDef, loadDefs, loadDefsRaw, loadDefsUnfinalized, validateDef, } from "./defs.js";
44
+ import { dbPathRefusingSymlink, detId, mkdirRefusingSymlink, nowMs, parseDurationMs, randId } from "./util.js";
45
+ import { DEFAULT_TAR_LIMITS, extractTarGz } from "./untar.js";
46
+ import { acquireInstallLock, ADD_JOURNAL_FILENAME, archivePathViolation, commitInstall, finalizeInstallCommit, githubShaUrl, githubTarballUrl, installFolder, parkOldNameDir, parseRepoSpec, readLockfile, recoverInterruptedInstall, releaseInstallLock, removeAddJournal, rollbackInstallCommit, RollbackFailedError, stageFiles, STAGING_DIRNAME, writeAddJournal, writeLockfile, } from "./add.js";
47
+ import { asCreateWorkflowOk, asWhoami, computeServerDiff, createWorkflowError, credentialFilePath, hashDefForHub, hubBindingPath, normalizeOrigin, parseWorkflowList, pkcePair, randomState, readCredentialFile, readHubBinding, resolveEndpoint, writeCredentialFile, writeHubBinding, } from "./hub.js";
40
48
  function defaultIO() {
41
49
  return {
42
50
  cwd: process.cwd(),
43
51
  env: process.env,
44
52
  out: (s) => process.stdout.write(`${s}\n`),
45
53
  err: (s) => process.stderr.write(`${s}\n`),
54
+ fetch: globalThis.fetch,
55
+ openUrl: defaultOpenUrl,
56
+ readStdin: defaultReadStdin,
46
57
  };
47
58
  }
59
+ /** Fire-and-forget browser open — never blocks the login flow on the child. */
60
+ function defaultOpenUrl(url) {
61
+ const platform = process.platform;
62
+ const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
63
+ try {
64
+ spawn(cmd, [url], { stdio: 'ignore', detached: true }).unref();
65
+ }
66
+ catch {
67
+ // Non-fatal: the URL is also printed to stderr for the user to open manually.
68
+ }
69
+ }
70
+ async function defaultReadStdin() {
71
+ const chunks = [];
72
+ for await (const chunk of process.stdin)
73
+ chunks.push(chunk);
74
+ return Buffer.concat(chunks).toString('utf8');
75
+ }
76
+ /**
77
+ * The default macOS keychain backend (generic passwords under service
78
+ * `owenloop-hub`). The secret is fed through the `security -i` command stream on
79
+ * stdin, never as a `-w` argv value, so it never appears in `ps`/shell history.
80
+ * Returns `undefined` off macOS or when `OWENLOOP_NO_KEYCHAIN=1`, so callers
81
+ * fall back to the 0600 credential file.
82
+ */
83
+ const KEYCHAIN_SERVICE = 'owenloop-hub';
84
+ function defaultKeychain(env) {
85
+ if (env.OWENLOOP_NO_KEYCHAIN === '1')
86
+ return undefined;
87
+ if (process.platform !== 'darwin')
88
+ return undefined;
89
+ return {
90
+ get(account) {
91
+ try {
92
+ const out = execFileSync('security', ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', account, '-w'], {
93
+ encoding: 'utf8',
94
+ stdio: ['ignore', 'pipe', 'ignore'],
95
+ });
96
+ return out.replace(/\n$/, '');
97
+ }
98
+ catch {
99
+ return null; // not found (errSecItemNotFound) — treated as "no credential"
100
+ }
101
+ },
102
+ set(account, value) {
103
+ // `security -i` reads newline-terminated commands from stdin; the secret
104
+ // rides in that stdin stream (single-quoted), never on this process's argv.
105
+ const sq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
106
+ const cmd = `add-generic-password -U -s ${sq(KEYCHAIN_SERVICE)} -a ${sq(account)} -w ${sq(value)}\n`;
107
+ execFileSync('security', ['-i'], { input: cmd, stdio: ['pipe', 'ignore', 'ignore'] });
108
+ },
109
+ delete(account) {
110
+ try {
111
+ execFileSync('security', ['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', account], {
112
+ stdio: 'ignore',
113
+ });
114
+ }
115
+ catch {
116
+ // Not found — already absent; a no-op delete is success.
117
+ }
118
+ },
119
+ };
120
+ }
121
+ /**
122
+ * Flags that are always boolean and must never consume the following token as
123
+ * a value — `owenloop push --force foo` must force-push only `foo`, not treat
124
+ * `foo` as `--force`'s value and swallow it from the positionals. Audited
125
+ * against every `flag(args, ...)` call site in this file. `now` is dual-mode:
126
+ * a bare boolean for `reap`, but `tick` reads it as `--now=<ms>` (the `=` form
127
+ * bypasses this set entirely, handled by the `eq >= 0` branch below); the
128
+ * space-separated `--now 123` form intentionally no longer binds `123` as
129
+ * `now`'s value — docs/cli.md documents only `--now=<ms>`.
130
+ */
131
+ const BOOLEAN_FLAGS = new Set([
132
+ 'assume-provided',
133
+ 'shallow',
134
+ 'now',
135
+ 'all',
136
+ 'open',
137
+ 'terminal',
138
+ 'recursive',
139
+ 'with-token',
140
+ 'dry-run',
141
+ 'force',
142
+ // `add --recover` takes NO value: `add --recover acme/widgets` must keep
143
+ // `acme/widgets` as a positional so the recover branch can refuse it, rather
144
+ // than binding it as `--recover`'s value and silently dropping it.
145
+ 'recover',
146
+ ]);
48
147
  function parseArgs(argv) {
49
148
  const positionals = [];
50
149
  const options = new Map();
@@ -58,6 +157,9 @@ function parseArgs(argv) {
58
157
  val = key.slice(eq + 1);
59
158
  key = key.slice(0, eq);
60
159
  }
160
+ else if (BOOLEAN_FLAGS.has(key)) {
161
+ val = 'true'; // never consume the next token for a known-boolean flag
162
+ }
61
163
  else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
62
164
  val = argv[++i];
63
165
  }
@@ -85,6 +187,17 @@ const flag = (args, key) => {
85
187
  };
86
188
  class CliError extends Error {
87
189
  }
190
+ /**
191
+ * A 429 from the hub during a push batch (REL-10). Thrown from the batch loop
192
+ * and handled by an explicit `instanceof` branch that halts the rest of the
193
+ * batch and surfaces `Retry-After` — NOT folded into the generic per-def
194
+ * failure path or matched by message regex. Keeping it a distinct class is the
195
+ * fix for the shared-catch gotcha (knowledge node "CLI: split a shared
196
+ * switch-case when one verb's return type changes"): branch on the type, never
197
+ * on the message text.
198
+ */
199
+ class RateLimitError extends CliError {
200
+ }
88
201
  function need(args, idx, label) {
89
202
  const v = args.positionals[idx];
90
203
  if (v === undefined)
@@ -97,6 +210,17 @@ function needOpt(args, key) {
97
210
  throw new CliError(`missing required option: --${key}`);
98
211
  return v;
99
212
  }
213
+ /** Read an optional numeric flag; throw a CliError (never NaN) on a non-finite value. */
214
+ function numOpt(args, key) {
215
+ const raw = last(args, key);
216
+ if (raw === undefined)
217
+ return undefined;
218
+ const n = Number(raw);
219
+ if (!Number.isFinite(n)) {
220
+ throw new CliError(`invalid value for --${key}: expected --${key}=<number> (got "${raw}")`);
221
+ }
222
+ return n;
223
+ }
100
224
  function parseJson(s, fallback = {}) {
101
225
  if (s === undefined)
102
226
  return fallback;
@@ -135,12 +259,109 @@ function parsePairs(entries, jsonValue) {
135
259
  }
136
260
  return out;
137
261
  }
262
+ /**
263
+ * Load the DEFAULT def set, folding in the defs `owenloop add` installed under
264
+ * ledger-recorded subfolders of `defsDir` so `defs`/`create`/`tick`/etc. see
265
+ * them by name with NO `--defs` flag. Called ONLY when the operator did not
266
+ * override the defs dir (see {@link openCtx}) — an explicit `--defs`/`OWENLOOP_DEFS`
267
+ * targets a specific literal dir and keeps today's pure-scan behavior, including
268
+ * `--defs workflows/<owner>-<repo>-<hash>` pointed straight at an install folder.
269
+ *
270
+ * The composition is ledger-DRIVEN and BOUNDED: it only folds in folders named
271
+ * by fail-closed-validated `installed.json` entries (never a raw tree recurse),
272
+ * and it stays in the CLI layer (where both cwd and defsDir are known) so
273
+ * `loadDefs`/`loadDefsUnfinalized` in defs.ts hold no ledger knowledge.
274
+ *
275
+ * Two-phase discipline: it merges the RAW (unfinalized) maps of the base dir and
276
+ * each install folder, then runs ONE `finalizeDefs` over the union. That single
277
+ * finalize is what lets a project-local def `calls:` an installed def across the
278
+ * boundary — finalizing each dir independently would throw "does not exist"
279
+ * before the merge. When the ledger is empty/missing the result is exactly
280
+ * `finalizeDefs(loadDefsUnfinalized(defsDir))` === today's `loadDefs(defsDir)`:
281
+ * zero behavior drift on the no-installs path.
282
+ *
283
+ * Precedence: project-local (base) defs WIN over installed defs; among installed
284
+ * entries, ledger sources are iterated in sorted order and the FIRST-loaded def
285
+ * with a given name wins. Every shadowed def is surfaced as a warning on stderr,
286
+ * never a silent clobber. Note the outer base scan ALREADY loads an install
287
+ * folder's `workflow.yaml` via its immediate-subdir rule, while the fold-in
288
+ * loads that folder's top-level `*.yaml` (excluding `workflow.yaml`) — the two
289
+ * scans are disjoint per file, so no file is ever loaded twice and any name
290
+ * collision is a genuine two-file collision.
291
+ *
292
+ * Fail-OPEN: the fold-in never breaks base loading. A corrupt/invalid ledger, a
293
+ * missing install folder, or an install folder that fails to load each emits a
294
+ * warning on stderr and is skipped; base defs still load. (The add-time
295
+ * fail-closed validation in add.ts is untouched — we consume `readLockfile`,
296
+ * discovery merely refuses to act on a bad ledger rather than crashing.)
297
+ */
298
+ function loadDefsWithInstalled(io, defsDir) {
299
+ const merged = existsSync(defsDir) ? loadDefsUnfinalized(defsDir) : new Map();
300
+ let lf;
301
+ try {
302
+ lf = readLockfile(join(io.cwd, '.owenloop', 'installed.json'));
303
+ }
304
+ catch (e) {
305
+ io.err(`warning: skipping installed workflow defs: ${e.message}`);
306
+ return finalizeDefs(merged);
307
+ }
308
+ for (const source of Object.keys(lf.installed).sort()) {
309
+ const entry = lf.installed[source];
310
+ if (entry === undefined)
311
+ continue; // unreachable — keys come from lf.installed
312
+ const entryDir = join(defsDir, entry.path);
313
+ if (!existsSync(entryDir)) {
314
+ io.err(`warning: installed defs folder missing for ${source}: ${entry.path}`);
315
+ continue;
316
+ }
317
+ let entryRaw;
318
+ try {
319
+ entryRaw = loadDefsUnfinalized(entryDir);
320
+ }
321
+ catch (e) {
322
+ io.err(`warning: failed to load installed defs for ${source} (${entry.path}): ${e.message}`);
323
+ continue;
324
+ }
325
+ for (const [name, def] of entryRaw) {
326
+ const winner = merged.get(name);
327
+ if (winner !== undefined) {
328
+ io.err(`warning: workflow '${name}' from ${def.dir ?? entryDir} is shadowed by ${winner.dir ?? 'project defs'} (project defs take precedence over installed defs)`);
329
+ continue;
330
+ }
331
+ merged.set(name, def);
332
+ }
333
+ }
334
+ return finalizeDefs(merged);
335
+ }
138
336
  function openCtx(io, args) {
139
- const dbPath = last(args, 'db') ?? io.env.OWENLOOP_DB ?? join(io.cwd, '.owenloop', 'state.db');
140
- const defsDir = last(args, 'defs') ?? io.env.OWENLOOP_DEFS ?? join(io.cwd, 'workflows');
141
- mkdirSync(dirname(dbPath), { recursive: true });
337
+ const dbOverride = last(args, 'db') ?? io.env.OWENLOOP_DB;
338
+ const dbPath = dbOverride ?? join(io.cwd, '.owenloop', 'state.db');
339
+ // An explicit `--defs`/`OWENLOOP_DEFS` is the operator targeting a literal dir
340
+ // (keep pure-scan behavior, no ledger fold-in); its ABSENCE means the default
341
+ // dir, where `add` installs and the ledger's folders live — fold installed
342
+ // defs in there. The rule is "was an override given", not path equality: even
343
+ // `OWENLOOP_DEFS=<cwd>/workflows` counts as an override and stays literal.
344
+ const defsOverride = last(args, 'defs') ?? io.env.OWENLOOP_DEFS;
345
+ const defsDir = defsOverride ?? join(io.cwd, 'workflows');
346
+ // Guard the built-in default (`cwd/.owenloop/state.db`) against a symlinked
347
+ // `.owenloop` from a hostile checkout (SEC-3). Directory guard first, then the
348
+ // file-level guard on `state.db` and its SQLite sidecars — a symlinked db file
349
+ // inside a REAL `.owenloop` would otherwise redirect writes SQLite follows. An
350
+ // explicit `--db`/`OWENLOOP_DB` comes from the operator, not the repo —
351
+ // deliberately pointing state through a symlink is intent, so keep today's
352
+ // behavior for overrides.
353
+ if (dbOverride === undefined) {
354
+ mkdirRefusingSymlink(dirname(dbPath));
355
+ dbPathRefusingSymlink(dbPath);
356
+ }
357
+ else
358
+ mkdirSync(dirname(dbPath), { recursive: true });
142
359
  const store = openStore(dbPath);
143
- const defs = existsSync(defsDir) ? loadDefs(defsDir) : new Map();
360
+ const defs = defsOverride !== undefined
361
+ ? existsSync(defsDir)
362
+ ? loadDefs(defsDir)
363
+ : new Map()
364
+ : loadDefsWithInstalled(io, defsDir);
144
365
  const engine = new Engine(store, (name) => {
145
366
  const d = defs.get(name);
146
367
  if (!d)
@@ -163,21 +384,28 @@ function sleepMs(ms) {
163
384
  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
164
385
  }
165
386
  // ---- commands ----------------------------------------------------------------
166
- const USAGE = `owenloop — a dataflow workflow engine
387
+ export const USAGE = `owenloop — a dataflow workflow engine
167
388
 
168
389
  Usage: owenloop <command> [args] [--db <path>] [--defs <dir>]
169
390
 
170
391
  Commands:
171
392
  defs list available workflow definitions
393
+ add <owner>/<repo>[@ref] fetch, validate, and install a repo's workflow defs (public repos)
394
+ add --recover finish or undo a crash-interrupted install (offline; no network)
395
+ login [--hub <url>] [--with-token] authenticate the CLI against a hub, verified via whoami (loopback OAuth, or --with-token from stdin)
396
+ logout [--hub <url>] delete the stored credential for a hub
397
+ connect [--hub <url>] bind this project to a hub and verify the stored credential (whoami)
398
+ push [<defName>...] [--force] [--dry-run] publish local workflow defs to the bound hub (server-diffed, idempotent)
172
399
  lint [<def-name>] check def(s) for wiring problems
173
400
  check <def> [--format text|json] [--max-depth N] [--max-states N] [--max-collection N] [--assume-provided]
174
401
  bounded reachability check (deadlocks, stuck, dead steps, declared invariants)
175
402
  create <def> [--title t] [--provide name=json ...] [--param k=v ...]
176
403
  provide <wf> <name> [--value json] supply an owed (seedOwed) input
177
404
  adopt <wf> re-pin an instance to the current def (§28); settles new debts
178
- tick <wf> [--now <ms>] pull eligible orders
405
+ tick <wf> [--now <ms>] [--shallow] [--label <l>]... pull eligible orders (deep: also from calls: children; --shallow for this instance only; --label filters to matching-label steps)
179
406
  reap <wf> [--now] run the reaper; --now forces every claim stale (TTL 0)
180
407
  runs <wf> [--open] list this instance's runs (+ claim state for open ones)
408
+ order <wf> <run> print the order packet issued at claim time (persisted in the claim txn)
181
409
  status <wf> derive debts / eligible / blocked
182
410
  status --all every instance's status in one call (fleet read)
183
411
  wait <wf> --until eligible|done [--timeout <dur>] block until engine state matches
@@ -203,6 +431,133 @@ function failureNote(failures) {
203
431
  return '';
204
432
  return `\n${failures.length} file(s) failed to load:\n - ${failures.map((f) => `${f.file}: ${f.error}`).join('\n - ')}`;
205
433
  }
434
+ /**
435
+ * Options accepted on EVERY command. docs/cli.md documents `--db`/`--defs` as
436
+ * global ("pass both on every command"), so they are allowlisted everywhere —
437
+ * even on commands that ignore them — to avoid rejecting a documented
438
+ * invocation.
439
+ */
440
+ const GLOBAL_OPTIONS = ['db', 'defs'];
441
+ /** Build a command's option allowlist: the two globals plus its own long-form flags. */
442
+ const cmdOpts = (...extra) => new Set([...GLOBAL_OPTIONS, ...extra]);
443
+ /**
444
+ * Single source of truth for the `--options` each command accepts, consulted by
445
+ * `preflight` before any side effect. Unknown-OPTION rejection AND
446
+ * unknown-COMMAND detection both derive from this table: a developer who adds a
447
+ * new `dispatch`/`ASYNC_COMMANDS` case without a matching entry here gets
448
+ * `unknown command` on the very first invocation, so the command cannot run
449
+ * until its flags are declared. That is the forcing function that stops the
450
+ * silently-dropped-flag hole (a misspelled `push --dryrn` doing a real push)
451
+ * from reappearing — keep this table in lockstep with the dispatch verbs and
452
+ * the USAGE string. All names are long-form: this CLI has no short options
453
+ * (`-h` reaches dispatch as a positional). Values are audited against every
454
+ * `last/all/flag/needOpt/numOpt` call site.
455
+ */
456
+ export const COMMAND_OPTIONS = new Map([
457
+ ['help', cmdOpts()],
458
+ ['defs', cmdOpts()],
459
+ ['add', cmdOpts('recover')],
460
+ ['login', cmdOpts('hub', 'with-token')],
461
+ ['logout', cmdOpts('hub')],
462
+ ['connect', cmdOpts('hub')],
463
+ ['push', cmdOpts('dry-run', 'force', 'hub')],
464
+ ['lint', cmdOpts()],
465
+ ['check', cmdOpts('format', 'max-depth', 'max-states', 'max-collection', 'assume-provided')],
466
+ ['create', cmdOpts('title', 'provide', 'param')],
467
+ ['provide', cmdOpts('value')],
468
+ ['adopt', cmdOpts()],
469
+ ['tick', cmdOpts('now', 'shallow', 'label')],
470
+ ['reap', cmdOpts('now')],
471
+ ['status', cmdOpts('all')],
472
+ ['wait', cmdOpts('until', 'timeout')],
473
+ ['show', cmdOpts()],
474
+ ['trace', cmdOpts('format')],
475
+ ['runs', cmdOpts('open')],
476
+ ['order', cmdOpts()],
477
+ ['list', cmdOpts()],
478
+ ['green', cmdOpts('value', 'terminal')],
479
+ ['emit', cmdOpts('items')],
480
+ ['seal', cmdOpts('value')],
481
+ ['reject', cmdOpts('by', 'text')],
482
+ ['retract', cmdOpts('by', 'text')],
483
+ ['skip', cmdOpts('by', 'text')],
484
+ ['retry', cmdOpts('by', 'text')],
485
+ ['close', cmdOpts('outcome', 'summary')],
486
+ ['heartbeat', cmdOpts('now')],
487
+ ['delete', cmdOpts('recursive')],
488
+ ['graph', cmdOpts('format')],
489
+ ]);
490
+ /** Levenshtein edit distance (small DP, no deps) — used only for "did you mean" hints. */
491
+ function editDistance(a, b) {
492
+ const m = a.length;
493
+ const n = b.length;
494
+ let prev = new Array(n + 1);
495
+ let curr = new Array(n + 1);
496
+ for (let j = 0; j <= n; j++)
497
+ prev[j] = j;
498
+ for (let i = 1; i <= m; i++) {
499
+ curr[0] = i;
500
+ for (let j = 1; j <= n; j++) {
501
+ const cost = a[i - 1] === b[j - 1] ? 0 : 1;
502
+ const del = prev[j] + 1;
503
+ const ins = curr[j - 1] + 1;
504
+ const sub = prev[j - 1] + cost;
505
+ curr[j] = Math.min(del, ins, sub);
506
+ }
507
+ [prev, curr] = [curr, prev];
508
+ }
509
+ return prev[n];
510
+ }
511
+ /**
512
+ * Reject any `--option` the target command does not declare in
513
+ * `COMMAND_OPTIONS`. Names each offender with its `--` prefix, suggests the
514
+ * nearest valid option (edit distance ≤ 2), and lists the command's valid
515
+ * options. Throws `CliError` (exit 1 via the entry-point catch). Runs BEFORE
516
+ * any side effect — see `preflight`.
517
+ */
518
+ function assertKnownOptions(command, args) {
519
+ const allowed = COMMAND_OPTIONS.get(command);
520
+ if (!allowed)
521
+ return; // unknown command is handled separately (in preflight)
522
+ const unknown = [...args.options.keys()].filter((k) => !allowed.has(k));
523
+ if (unknown.length === 0)
524
+ return;
525
+ const lines = unknown.map((k) => {
526
+ const base = `unknown option --${k} for '${command}'`;
527
+ const near = k.length > 0
528
+ ? [...allowed]
529
+ .map((o) => ({ o, d: editDistance(k, o) }))
530
+ .filter((c) => c.d <= 2)
531
+ .sort((a, b) => a.d - b.d)[0]
532
+ : undefined;
533
+ return near ? `${base} (did you mean --${near.o}?)` : base;
534
+ });
535
+ const validSorted = [...allowed].map((o) => `--${o}`).sort();
536
+ throw new CliError(`${lines.join('\n')}\nvalid options for '${command}': ${validSorted.join(', ')}`);
537
+ }
538
+ /**
539
+ * Pre-dispatch guard shared by both entry points (`main` and `mainAsync`) so
540
+ * the sync and async paths cannot drift. In order: the help escape hatch
541
+ * (`help`/`--help`/`-h`, or `--help` given anywhere e.g. `push --help`) prints
542
+ * usage and short-circuits with exit 0; an unrecognized command throws the same
543
+ * `unknown command` error dispatch's `default:` produces (but now before
544
+ * `openCtx`, so it no longer creates `.owenloop/state.db`); then unknown
545
+ * options are rejected. All of this runs ahead of any filesystem, keychain, or
546
+ * network I/O. Returns an exit code to short-circuit on, or `undefined` to
547
+ * proceed to dispatch. `command` is always defined here — callers own the
548
+ * no-command usage branch.
549
+ */
550
+ function preflight(command, args, io) {
551
+ if (command === 'help' || command === '--help' || command === '-h' || args.options.has('help')) {
552
+ io.out(USAGE);
553
+ return 0;
554
+ }
555
+ if (!COMMAND_OPTIONS.has(command)) {
556
+ throw new CliError(`unknown command: ${command}\n\n${USAGE}`);
557
+ }
558
+ assertKnownOptions(command, args);
559
+ return undefined;
560
+ }
206
561
  function dispatch(command, io, args) {
207
562
  // help and lint need no store
208
563
  if (command === 'help' || command === '--help' || command === '-h') {
@@ -260,9 +615,9 @@ function dispatch(command, io, args) {
260
615
  throw new CliError(`workflow '${def.name}' has validation errors:\n - ${defErrors.join('\n - ')}`);
261
616
  }
262
617
  const format = last(args, 'format') ?? 'text';
263
- const maxDepth = last(args, 'max-depth') !== undefined ? Number(last(args, 'max-depth')) : undefined;
264
- const maxStates = last(args, 'max-states') !== undefined ? Number(last(args, 'max-states')) : undefined;
265
- const maxCollection = last(args, 'max-collection') !== undefined ? Number(last(args, 'max-collection')) : undefined;
618
+ const maxDepth = numOpt(args, 'max-depth');
619
+ const maxStates = numOpt(args, 'max-states');
620
+ const maxCollection = numOpt(args, 'max-collection');
266
621
  const report = modelCheck(def, {
267
622
  ...(maxDepth !== undefined ? { maxDepth } : {}),
268
623
  ...(maxStates !== undefined ? { maxStates } : {}),
@@ -381,8 +736,19 @@ function dispatch(command, io, args) {
381
736
  }
382
737
  case 'tick': {
383
738
  const wf = need(args, 1, 'workflow');
384
- const nowRaw = last(args, 'now');
385
- const tickOpts = nowRaw !== undefined ? { now: Number(nowRaw) } : {};
739
+ const now = numOpt(args, 'now');
740
+ // §23.6.8: tick is deep by default (descends into calls: children and
741
+ // returns their orders too); --shallow restores single-instance ticking.
742
+ const tickOpts = {};
743
+ if (now !== undefined)
744
+ tickOpts.now = now;
745
+ if (flag(args, 'shallow'))
746
+ tickOpts.deep = false;
747
+ // A2: repeatable --label narrows the claim to steps whose labels
748
+ // intersect the caller's; absent = claim everything (today's behavior).
749
+ const labels = all(args, 'label');
750
+ if (labels.length > 0)
751
+ tickOpts.labels = labels;
386
752
  print(io, engine.tick(wf, tickOpts));
387
753
  return 0;
388
754
  }
@@ -409,8 +775,9 @@ function dispatch(command, io, args) {
409
775
  // `--all` is the whole-fleet read; a workflow argument is
410
776
  // contradictory (one or all?). Reject it in both orderings rather
411
777
  // than silently ignoring the caller's intent:
412
- // `status wf --all` → the wf lands in positionals[1]
413
- // `status --all wf` → the parser binds wf as `--all`'s value
778
+ // `status wf --all` / `status --all wf` → the wf lands in positionals[1]
779
+ // (`all` is a boolean flag and never consumes the next token)
780
+ // `status --all=wf` → the `=` form binds wf as `--all`'s value
414
781
  const v = last(args, 'all');
415
782
  const stray = args.positionals[1] ?? (v !== 'true' && v !== '' ? v : undefined);
416
783
  if (stray !== undefined) {
@@ -565,6 +932,19 @@ function dispatch(command, io, args) {
565
932
  print(io, rows);
566
933
  return 0;
567
934
  }
935
+ case 'order': {
936
+ const wf = need(args, 1, 'workflow');
937
+ const run = need(args, 2, 'run');
938
+ const r = store.getRun(run);
939
+ if (!r)
940
+ throw new CliError(`run not found: ${run}`);
941
+ if (r.workflow !== wf)
942
+ throw new CliError(`run ${run} belongs to workflow ${r.workflow}, not ${wf}`);
943
+ if (r.order === undefined)
944
+ throw new CliError(`run ${run} has no persisted order (created before order persistence, schema v7)`);
945
+ print(io, r.order);
946
+ return 0;
947
+ }
568
948
  case 'list': {
569
949
  print(io, store.listWorkflows().map((w) => {
570
950
  const s = safeStatus(engine, w.id);
@@ -672,8 +1052,7 @@ function dispatch(command, io, args) {
672
1052
  case 'heartbeat': {
673
1053
  const wf = need(args, 1, 'workflow');
674
1054
  const run = need(args, 2, 'run');
675
- const nowRaw = last(args, 'now');
676
- engine.heartbeat(wf, run, nowRaw !== undefined ? Number(nowRaw) : undefined);
1055
+ engine.heartbeat(wf, run, numOpt(args, 'now'));
677
1056
  print(io, { ok: true, workflow: wf, run });
678
1057
  return 0;
679
1058
  }
@@ -767,6 +1146,1414 @@ function statusEntry(engine, w) {
767
1146
  return { ...base, error: e.message };
768
1147
  }
769
1148
  }
1149
+ /**
1150
+ * `owenloop add <owner>/<repo>[@ref]` — the one network-touching CLI verb
1151
+ * (workflow-distribution Stage 1). Fetches a public GitHub repo's tarball,
1152
+ * validates its `workflows/**` defs with the same lint/check machinery
1153
+ * `owenloop lint`/`owenloop check` use, and — only if everything passes —
1154
+ * installs them under `<defsDir>/<installFolder(owner,repo)>/` and records
1155
+ * provenance in `.owenloop/installed.json`. A partial install is never left
1156
+ * behind: any refusal (parse/lint/validate/check failure) writes nothing, and
1157
+ * even a failure of the lockfile write after the directory swap rolls the
1158
+ * directory state back — the commit point is the durable lockfile write.
1159
+ *
1160
+ * Kept inside cli.ts (rather than add.ts) so it can reuse `Args`/`need`/
1161
+ * `last`/`CliError`/`parseJson`/`print`/`failureNote` without exporting them
1162
+ * from this module — the pure, unit-tested logic (spec parsing, lockfile
1163
+ * I/O, file install) lives in `src/add.ts`; this function is just the async
1164
+ * network + arg glue.
1165
+ */
1166
+ // Request deadlines for the two `add` fetches. A small JSON/text sha lookup
1167
+ // should be quick; the whole-repo tarball may be large on a slow link, so it
1168
+ // gets a much longer budget. Constants only — no env knob (a follow-up can add
1169
+ // one if ever needed).
1170
+ const ADD_SHA_TIMEOUT_MS = 30_000;
1171
+ const ADD_TARBALL_TIMEOUT_MS = 300_000;
1172
+ /**
1173
+ * Read a `Response` body while enforcing a byte `cap`, so a hostile server can
1174
+ * never make us allocate an oversized body. Rejects UP FRONT on a declared
1175
+ * oversize `Content-Length`; otherwise streams the body in chunks, counting the
1176
+ * bytes that actually land in memory, and cancels the stream the moment the
1177
+ * running total crosses the cap — the chunk buffer never holds more than `cap`
1178
+ * plus one chunk. `label` names the request in the error and is origin+path or
1179
+ * `owner/repo@sha` only — never a token. Counting post-decode bytes (what lands
1180
+ * in memory) is deliberate: the cap protects memory, not wire bytes.
1181
+ *
1182
+ * `res.body === null` (empty/no-body response) yields empty bytes, so callers
1183
+ * behave exactly as they did under `arrayBuffer()`. An absent, malformed, or
1184
+ * multi-valued `Content-Length` skips the header check — the counting path is
1185
+ * the real guard (GitHub codeload tarballs are typically chunked, no header). A
1186
+ * `TimeoutError`/`AbortError` from `read()` (the abort signal fired mid-body)
1187
+ * propagates untouched, so each call site's existing timeout mapping still
1188
+ * fires exactly as it did for `arrayBuffer()` rejections. `cancel()` may reject
1189
+ * on an already-errored stream — swallowed; the cap `CliError` is the story.
1190
+ */
1191
+ async function readBodyBounded(res, cap, label) {
1192
+ const declared = Number(res.headers.get('content-length'));
1193
+ if (Number.isFinite(declared) && declared > cap) {
1194
+ await res.body?.cancel().catch(() => { });
1195
+ throw new CliError(`response body for ${label} exceeds the ${cap}-byte cap (declared Content-Length ${declared})`);
1196
+ }
1197
+ if (res.body === null)
1198
+ return new Uint8Array(0);
1199
+ const reader = res.body.getReader();
1200
+ const chunks = [];
1201
+ let total = 0;
1202
+ for (;;) {
1203
+ const { done, value } = await reader.read();
1204
+ if (done)
1205
+ break;
1206
+ if (value === undefined)
1207
+ continue;
1208
+ total += value.byteLength;
1209
+ chunks.push(value);
1210
+ if (total > cap) {
1211
+ await reader.cancel().catch(() => { });
1212
+ throw new CliError(`response body for ${label} exceeds the ${cap}-byte cap`);
1213
+ }
1214
+ }
1215
+ const out = new Uint8Array(total);
1216
+ let offset = 0;
1217
+ for (const chunk of chunks) {
1218
+ out.set(chunk, offset);
1219
+ offset += chunk.byteLength;
1220
+ }
1221
+ return out;
1222
+ }
1223
+ /**
1224
+ * Cap on the `add` tarball download body, enforced DURING the stream by
1225
+ * `readBodyBounded` — defense in depth with `extractTarGz`'s own post-hoc
1226
+ * `maxCompressedBytes` check (kept intact). `OWENLOOP_TARBALL_MAX_BYTES`
1227
+ * overrides it (a test-only knob, validated `Number.isFinite && > 0`,
1228
+ * consistent with the project's other `OWENLOOP_*` knobs) so a mid-stream test
1229
+ * need not buffer the real 256 MiB cap in CI.
1230
+ */
1231
+ function tarballMaxBytes(io) {
1232
+ const override = Number(io.env.OWENLOOP_TARBALL_MAX_BYTES);
1233
+ return Number.isFinite(override) && override > 0 ? override : DEFAULT_TAR_LIMITS.maxCompressedBytes;
1234
+ }
1235
+ /**
1236
+ * `owenloop add <owner>/<repo>[@ref]` — fetch a repo's `workflows/**`, validate
1237
+ * it, and install it under `<defsDir>/<installFolder(owner,repo)>`.
1238
+ *
1239
+ * The network fetch/extract/path-filter runs FIRST, unlocked (a tarball can
1240
+ * take minutes and holding a lock that long would needlessly serialize
1241
+ * unrelated adds). Everything that touches project state then runs under the
1242
+ * per-project `.owenloop/add.lock`: crash-recovery pass → stale-staging cleanup
1243
+ * → lockfile read → ownership check → stage → strict validation → atomic commit
1244
+ * (backups retained) → journal write → lockfile write → journal advance →
1245
+ * finalize (backups discarded) → journal remove. Deciding ownership and reading
1246
+ * the lockfile INSIDE the lock is deliberate (TOCTOU discipline — see the
1247
+ * store-migration knowledge node). The install is staged on the destination
1248
+ * filesystem and swapped in with an atomic rename, but the displaced previous
1249
+ * install and any old-name dir are kept until the lockfile write succeeds — the
1250
+ * directory commit and the ledger write are one recoverable operation. Any
1251
+ * failure before the lockfile is durably written rolls the directory state back
1252
+ * and leaves the previous install and lockfile exactly as they were, with no
1253
+ * staging debris.
1254
+ *
1255
+ * A `.owenloop/add.journal` intent record closes the crash-recovery gap the
1256
+ * in-process rollback arms can't: it is written (phase `applying`) right before
1257
+ * the destructive `commitInstall`, advanced (phase `finalizing`) right after the
1258
+ * durable ledger write, and removed on clean completion. A process killed
1259
+ * mid-install leaves the journal behind; the NEXT add runs
1260
+ * `recoverInterruptedInstall` FIRST inside the lock — before the stale-staging
1261
+ * clear, since the backups a rollback needs live under the staging root — to
1262
+ * roll the interrupted install forward (past the commit point) or back (before
1263
+ * it) to a consistent (defs ⇔ ledger) state. The journal is attacker-
1264
+ * influenceable input, validated fail-closed with the same A1 discipline as the
1265
+ * lockfile; a bad/mismatched/contradictory journal REFUSES with no fs mutation
1266
+ * (and, via `preserveStagingRoot`, without the `finally` clearing the evidence).
1267
+ */
1268
+ async function dispatchAdd(io, args) {
1269
+ // Offline crash-recovery branch. This sits at the VERY TOP — before `need`/
1270
+ // `parseRepoSpec` and before either network fetch — so `--recover` is
1271
+ // structurally incapable of reaching the SHA/tarball fetches. A machine that
1272
+ // crashed mid-install and is now offline can finish or undo the interrupted
1273
+ // install with no network (recovery is purely local filesystem work).
1274
+ if (flag(args, 'recover'))
1275
+ return dispatchAddRecover(io, args);
1276
+ const spec = need(args, 1, 'owner/repo[@ref]');
1277
+ const { owner, repo, ref } = parseRepoSpec(spec);
1278
+ const source = `${owner}/${repo}`;
1279
+ const defsOverride = last(args, 'defs') ?? io.env.OWENLOOP_DEFS;
1280
+ const defsDir = defsOverride ?? join(io.cwd, 'workflows');
1281
+ const lockfilePath = join(io.cwd, '.owenloop', 'installed.json');
1282
+ const installLockPath = join(io.cwd, '.owenloop', 'add.lock');
1283
+ const journalPath = join(io.cwd, '.owenloop', ADD_JOURNAL_FILENAME);
1284
+ const fetchFn = io.fetch ?? globalThis.fetch;
1285
+ // 1. Resolve the ref to a pinned commit sha.
1286
+ let shaRes;
1287
+ try {
1288
+ shaRes = await fetchFn(githubShaUrl(owner, repo, ref), {
1289
+ headers: { Accept: 'application/vnd.github.sha', 'User-Agent': 'owenloop' },
1290
+ signal: AbortSignal.timeout(ADD_SHA_TIMEOUT_MS),
1291
+ });
1292
+ }
1293
+ catch (e) {
1294
+ const err = e;
1295
+ if (err.name === 'TimeoutError' || err.name === 'AbortError') {
1296
+ throw new CliError(`timed out after ${ADD_SHA_TIMEOUT_MS / 1000}s resolving ${source}@${ref}`);
1297
+ }
1298
+ throw e;
1299
+ }
1300
+ if (!shaRes.ok) {
1301
+ const notFoundNote = shaRes.status === 404 ? ' (repo or ref not found)' : '';
1302
+ throw new CliError(`could not resolve ${source}@${ref}: GitHub returned ${shaRes.status}${notFoundNote}`);
1303
+ }
1304
+ const shaBytes = await readBodyBounded(shaRes, hubMaxResponseBytes(io), `sha resolution for ${source}@${ref}`);
1305
+ const shaBody = new TextDecoder().decode(shaBytes).trim();
1306
+ if (!/^[0-9a-f]{40}$/i.test(shaBody)) {
1307
+ throw new CliError(`unexpected response resolving ${source}@${ref}: expected a 40-char commit sha, got "${shaBody}"`);
1308
+ }
1309
+ const sha = shaBody;
1310
+ // 2. Fetch the tarball for that pinned sha. The timeout must cover the body
1311
+ // read too — undici ties the abort signal to the body stream — so the
1312
+ // fetch AND the bounded read live in the same try. readBodyBounded caps the
1313
+ // download DURING the stream (cancelling at the cap), so an oversized
1314
+ // tarball is never fully allocated; extractTarGz still re-checks the size
1315
+ // post-hoc (defense in depth).
1316
+ let bytes;
1317
+ try {
1318
+ const tarRes = await fetchFn(githubTarballUrl(owner, repo, sha), {
1319
+ headers: { 'User-Agent': 'owenloop' },
1320
+ signal: AbortSignal.timeout(ADD_TARBALL_TIMEOUT_MS),
1321
+ });
1322
+ if (!tarRes.ok) {
1323
+ throw new CliError(`could not fetch tarball for ${source}@${sha}: GitHub returned ${tarRes.status}`);
1324
+ }
1325
+ bytes = await readBodyBounded(tarRes, tarballMaxBytes(io), `tarball for ${source}@${sha}`);
1326
+ }
1327
+ catch (e) {
1328
+ const err = e;
1329
+ if (err.name === 'TimeoutError' || err.name === 'AbortError') {
1330
+ throw new CliError(`timed out after ${ADD_TARBALL_TIMEOUT_MS / 1000}s downloading tarball for ${source}@${sha}`);
1331
+ }
1332
+ throw e;
1333
+ }
1334
+ // 3. Extract, strip the single leading '<owner>-<repo>-<sha>/' root-dir
1335
+ // component GitHub tarballs always have, and keep only workflows/**
1336
+ // (re-keyed relative to that dir).
1337
+ let rawFiles;
1338
+ try {
1339
+ rawFiles = extractTarGz(bytes);
1340
+ }
1341
+ catch (e) {
1342
+ throw new CliError(`could not extract tarball for ${source}@${sha}: ${e.message}`);
1343
+ }
1344
+ const files = new Map();
1345
+ const pathViolations = [];
1346
+ for (const [rawPath, data] of rawFiles) {
1347
+ const firstSlash = rawPath.indexOf('/');
1348
+ const rest = firstSlash >= 0 ? rawPath.slice(firstSlash + 1) : '';
1349
+ if (rest.startsWith('workflows/')) {
1350
+ const relPath = rest.slice('workflows/'.length);
1351
+ if (relPath) {
1352
+ // Reject any entry that would escape the staging/install dir BEFORE it
1353
+ // is ever joined and written (SEC-1). Collect every offender so the
1354
+ // refusal names them all.
1355
+ const violation = archivePathViolation(relPath);
1356
+ if (violation) {
1357
+ pathViolations.push(`${rawPath}: ${violation}`);
1358
+ continue;
1359
+ }
1360
+ files.set(relPath, data);
1361
+ }
1362
+ }
1363
+ }
1364
+ if (pathViolations.length > 0) {
1365
+ throw new CliError(`refusing to install ${source}@${sha} — ${pathViolations.length} unsafe archive path(s) found; nothing written:\n - ${pathViolations.join('\n - ')}`);
1366
+ }
1367
+ // Note: git (and so GitHub's tarball export) never tracks a truly empty
1368
+ // directory, so "no workflows/ dir at all" and "workflows/ dir exists but
1369
+ // is untracked-empty" are indistinguishable from the archive's contents —
1370
+ // both land here as files.size === 0. A `workflows/` dir that is tracked
1371
+ // but genuinely has zero yaml defs in it (e.g. holds only a .gitkeep)
1372
+ // takes the success/`installed: 0` path below instead, since it has at
1373
+ // least one file under the prefix.
1374
+ if (files.size === 0) {
1375
+ throw new CliError(`no workflows/ directory found in ${source}@${ref}`);
1376
+ }
1377
+ // 4. Everything that touches project state runs under the per-project install
1378
+ // lock: concurrent `add` runs serialize instead of interleaving. The lock
1379
+ // is acquired only now — AFTER the (potentially slow) network fetch — so a
1380
+ // tarball download never blocks an unrelated add.
1381
+ const folder = installFolder(owner, repo);
1382
+ const stagingRoot = join(defsDir, STAGING_DIRNAME);
1383
+ const stagingId = randId('stg');
1384
+ const stagingDir = join(stagingRoot, stagingId);
1385
+ // SEC-3, add's half: refuse a symlinked project `.owenloop` (the parent of
1386
+ // add.lock and installed.json — always cwd-derived in add, no override
1387
+ // exists) and a symlinked DEFAULT defs dir before any state write. Both must
1388
+ // precede acquireInstallLock: `.owenloop` is written by the lock acquire and
1389
+ // the ledger; defsDir is DELETED-through by the stale-staging rmSync below and
1390
+ // then written by staging/commit. An explicit --defs/OWENLOOP_DEFS is operator
1391
+ // intent, not repo content — deliberately installing through a symlink keeps
1392
+ // today's behavior, matching the --db/OWENLOOP_DB rule.
1393
+ mkdirRefusingSymlink(join(io.cwd, '.owenloop'));
1394
+ if (defsOverride === undefined)
1395
+ mkdirRefusingSymlink(defsDir);
1396
+ const lock = await acquireInstallLock(installLockPath);
1397
+ // Set true only on a rollback double-fault, where the ONLY copy of the
1398
+ // previous content ends up parked under the staging root — then the `finally`
1399
+ // must NOT delete it (the error message tells the user to recover it).
1400
+ let preserveStagingRoot = false;
1401
+ try {
1402
+ // Recover a crash-interrupted prior install FIRST — before the stale-staging
1403
+ // clear, since the backups/parked dirs a rollback needs live UNDER the
1404
+ // staging root, so clearing it first would destroy them. Any refusal (bad or
1405
+ // mismatched or contradictory journal) must preserve the staging root and the
1406
+ // journal as evidence: without this, the `finally` below would rmSync the
1407
+ // staging root and take the backups a later recovery needs with it.
1408
+ try {
1409
+ recoverInterruptedInstall({ defsDir, journalPath, lockfilePath });
1410
+ }
1411
+ catch (e) {
1412
+ preserveStagingRoot = true;
1413
+ throw e;
1414
+ }
1415
+ // The lock holder is the only legitimate writer under the staging root, so
1416
+ // anything already there is debris from a crashed/killed prior run — clear
1417
+ // it. Keeps "no staging debris" true even across a Ctrl-C.
1418
+ rmSync(stagingRoot, { recursive: true, force: true });
1419
+ // Read the lockfile and decide ownership INSIDE the lock (TOCTOU: a pre-lock
1420
+ // read could be stale by the time we act on it). A corrupt lockfile is a
1421
+ // hard error (readLockfile), never a silent reset.
1422
+ const lf = readLockfile(lockfilePath);
1423
+ const dest = join(defsDir, folder);
1424
+ const existing = lf.installed[source];
1425
+ // Use-site exact-match (Layer 2): the entry being installed may only record
1426
+ // the currently computed folder OR the exact legacy `<owner>-<repo>` name
1427
+ // (the only pre-hash scheme this tool ever wrote). `readLockfile` has
1428
+ // already refused any structurally unsafe `path`; this additionally refuses
1429
+ // a structurally-valid-but-WRONG segment (e.g. 'not-the-right-folder')
1430
+ // before any staging/commit mutation, so the later `existing.path !== folder`
1431
+ // migration branch is guaranteed to see only the exact legacy name.
1432
+ const legacyFolder = `${owner}-${repo}`;
1433
+ if (existing && existing.path !== folder && existing.path !== legacyFolder) {
1434
+ throw new CliError(`refusing to install ${source}: lockfile records install path '${existing.path}', ` +
1435
+ `which is neither the expected '${folder}' nor the legacy '${legacyFolder}' — fix ${lockfilePath} manually`);
1436
+ }
1437
+ if (existsSync(dest) && !(existing && existing.path === folder)) {
1438
+ throw new CliError(`refusing to install ${source}: destination '${folder}' already exists and is not owned by ${source} — ` +
1439
+ `remove it manually or fix ${lockfilePath}`);
1440
+ }
1441
+ // Stage the incoming files onto the DESTINATION filesystem (under defsDir),
1442
+ // so the commit is an atomic same-fs rename. Two-level layout keeps the
1443
+ // staged content invisible to loadDefs(defsDir).
1444
+ const written = stageFiles(stagingDir, files);
1445
+ // 5. Validate the STAGED tree — the exact bytes that will be renamed into
1446
+ // place, with no re-write after validation.
1447
+ const failures = [];
1448
+ const staged = loadDefsRaw(stagingDir, failures);
1449
+ const reasons = failures.map((f) => `${f.file}: ${f.error}`);
1450
+ for (const stagedDef of staged.values()) {
1451
+ const lintResult = lintDef(stagedDef);
1452
+ reasons.push(...lintResult.errors.map((e) => `${stagedDef.name}: ${e}`));
1453
+ const validationErrors = validateDef(stagedDef);
1454
+ reasons.push(...validationErrors.map((e) => `${stagedDef.name}: ${e}`));
1455
+ // Mirror the `check` command's exact "definite defect" predicate — but,
1456
+ // deliberately, WITH `assumeProvided: true`. Without it, a def with any
1457
+ // `seedOwed` input (the norm — see e.g. `proposal` in delivery.yaml)
1458
+ // deadlocks in the very first state, because the checker models "no
1459
+ // `provide` has happened yet" by default (see `seedArts` in
1460
+ // src/model.ts). `owenloop check <def>` behaves the same way absent
1461
+ // `--assume-provided`; verified every def under examples/workflows/
1462
+ // fails plain `check` for exactly this reason. Since `add` validates a
1463
+ // def that a real user will `provide` into after install (that's the
1464
+ // whole point of a seedOwed input), refusing every seedOwed def here
1465
+ // would make `add` unable to install almost any real workflow,
1466
+ // including this project's own examples — so this checks "is it
1467
+ // completable once its owed inputs are supplied," the same bar a
1468
+ // careful author would clear with `check --assume-provided` before
1469
+ // publishing.
1470
+ const report = modelCheck(stagedDef, { assumeProvided: true });
1471
+ const hasDefiniteDefect = report.invariantViolations.length > 0 ||
1472
+ (!report.bounded && (report.deadlocks.length > 0 || report.stuck.length > 0));
1473
+ if (hasDefiniteDefect) {
1474
+ reasons.push(`${stagedDef.name}: definite defects found (${report.invariantViolations.length} invariant violation(s), ` +
1475
+ `${report.deadlocks.length} deadlock(s), ${report.stuck.length} stuck state(s))`);
1476
+ }
1477
+ }
1478
+ // Strict backstop: only if the aggregate pass found nothing, run the FULL
1479
+ // loadDefs on the staged tree. `loadDefsRaw` is best-effort — it swallows
1480
+ // include-expansion failures and cross-def `calls:` errors that strict
1481
+ // `loadDefs` (via finalizeDefs) throws on. Every later command loads the
1482
+ // installed dir with strict `loadDefs`, so this guarantees whatever we
1483
+ // commit cannot make a subsequent `loadDefs` of that dir throw.
1484
+ if (reasons.length === 0) {
1485
+ try {
1486
+ loadDefs(stagingDir);
1487
+ }
1488
+ catch (e) {
1489
+ if (e instanceof DefError) {
1490
+ reasons.push(`cross-definition validation failed: ${e.message}`);
1491
+ }
1492
+ else {
1493
+ throw e;
1494
+ }
1495
+ }
1496
+ }
1497
+ if (reasons.length > 0) {
1498
+ throw new CliError(`refusing to install ${source}@${sha} — ${reasons.length} problem(s) found; nothing written:\n - ${reasons.join('\n - ')}`);
1499
+ }
1500
+ // 6. Commit as one recoverable operation: atomically swap the validated
1501
+ // staging dir into place (backups RETAINED, not dropped), park any
1502
+ // old-naming dir this source used to occupy, write the lockfile, and only
1503
+ // then finalize (discard the retained backups). If the lockfile write
1504
+ // fails after the swap, roll the directory state back so the previous
1505
+ // install and lockfile are left exactly as they were.
1506
+ //
1507
+ // Write the crash-recovery journal (phase `applying`) BEFORE the first
1508
+ // destructive step. `hadDest` is captured here, under the lock, right before
1509
+ // commitInstall reads the same fact — so recovery knows whether a backup dir
1510
+ // will exist. A migration off the old `<owner>-<repo>` name records that
1511
+ // path so recovery can restore the parked old-name dir. If the process is
1512
+ // killed anywhere past this point, the next add's recovery pass uses this
1513
+ // record to roll forward or back.
1514
+ const migratingOldName = existing !== undefined && existing.path !== folder;
1515
+ const journalBase = {
1516
+ version: 1,
1517
+ phase: 'applying',
1518
+ source,
1519
+ sha,
1520
+ folder,
1521
+ stagingId,
1522
+ hadDest: existsSync(dest),
1523
+ ...(migratingOldName ? { oldNamePath: existing.path } : {}),
1524
+ defsDir: resolve(defsDir),
1525
+ ref,
1526
+ startedAt: nowMs(),
1527
+ };
1528
+ writeAddJournal(journalPath, journalBase);
1529
+ let handle;
1530
+ try {
1531
+ handle = commitInstall(defsDir, folder, stagingDir);
1532
+ }
1533
+ catch (e) {
1534
+ // commitInstall's own swap-then-rollback double-fault left the only copy
1535
+ // of previous content under the staging root — keep it (see the `finally`).
1536
+ if (e instanceof RollbackFailedError)
1537
+ preserveStagingRoot = true;
1538
+ throw e;
1539
+ }
1540
+ if (existing && existing.path !== folder) {
1541
+ // Migrating off the old `<owner>-<repo>` scheme: park (not delete) the old
1542
+ // dir so a failure below can restore it. Finalized away on success. This
1543
+ // park now sits INSIDE the recoverable region — a park failure must roll
1544
+ // the committed swap back too, exactly like the lockfile-write failure
1545
+ // below (a bare park could otherwise strand the swap and leave the next
1546
+ // `add` refusing on an ownership mismatch).
1547
+ try {
1548
+ parkOldNameDir(handle, defsDir, existing.path);
1549
+ }
1550
+ catch (e) {
1551
+ try {
1552
+ rollbackInstallCommit(handle);
1553
+ }
1554
+ catch (rollbackErr) {
1555
+ // Double fault: parking the old dir failed AND rolling the committed
1556
+ // swap back failed. Nothing of value sits under the staging root here —
1557
+ // the staging dir was consumed by the swap, and this migration branch
1558
+ // never has a backup (`dest` cannot pre-exist; see the ownership refusal
1559
+ // above). The old-name dir was never moved (the park is a single atomic
1560
+ // rename recorded only on success) so it stays intact at its original
1561
+ // path, and the stranded item is the NEW content still at `dest`. LEAVE
1562
+ // the journal (phase `applying`) so the next add's recovery rolls the
1563
+ // swap back (case (c): discards `dest`) before anything clears the
1564
+ // staging root, mirroring the lockfile-write double fault below.
1565
+ preserveStagingRoot = true;
1566
+ throw new CliError(`could not migrate ${source} off old-name directory '${existing.path}' (${e.message}) ` +
1567
+ `and rolling the install back failed too (${rollbackErr.message}); ` +
1568
+ `the old-name directory was never moved and is intact at ${join(defsDir, existing.path)}, ` +
1569
+ `and the newly installed content is stranded at ${dest} — ` +
1570
+ `the next owenloop add will recover automatically (discarding the stranded content and leaving the previous install in place)`);
1571
+ }
1572
+ // Directory state restored in-process — nothing left to recover, so drop
1573
+ // the journal before surfacing the (single-fault) failure.
1574
+ removeAddJournal(journalPath);
1575
+ throw new CliError(`could not migrate ${source} off old-name directory '${existing.path}': ${e.message} — ` +
1576
+ `install rolled back, previous state restored`);
1577
+ }
1578
+ }
1579
+ const entry = { source, ref, sha, installedAt: nowMs(), path: folder, files: written };
1580
+ lf.installed[source] = entry;
1581
+ try {
1582
+ writeLockfile(lockfilePath, lf);
1583
+ }
1584
+ catch (e) {
1585
+ try {
1586
+ rollbackInstallCommit(handle);
1587
+ }
1588
+ catch (rollbackErr) {
1589
+ // Double fault: the ledger write failed AND restoring the directory
1590
+ // failed. The previous content is now parked under the staging root —
1591
+ // preserve it past the `finally` and LEAVE the journal (phase
1592
+ // `applying`, ledger not committed) so the next add's recovery restores
1593
+ // the previous state before anything clears the staging root.
1594
+ preserveStagingRoot = true;
1595
+ throw new CliError(`could not record install of ${source} in ${lockfilePath} (${e.message}) ` +
1596
+ `and rolling the install back failed too (${rollbackErr.message}); ` +
1597
+ `previous content preserved under ${stagingRoot} — recover it before running add again ` +
1598
+ `(the next owenloop add will attempt recovery automatically; leaving it, that dir is cleared as debris)`);
1599
+ }
1600
+ // Directory state restored in-process — drop the journal before surfacing
1601
+ // the (single-fault) failure.
1602
+ removeAddJournal(journalPath);
1603
+ throw new CliError(`could not record install of ${source} in ${lockfilePath}: ${e.message} — ` +
1604
+ `install rolled back, previous state restored`);
1605
+ }
1606
+ // The ledger write is the durable commit point: past here a crash rolls
1607
+ // FORWARD. Record that in the journal (phase `finalizing`) so recovery
1608
+ // finishes the install rather than tearing it down, then finalize and drop
1609
+ // the journal now that there is nothing left to recover.
1610
+ writeAddJournal(journalPath, { ...journalBase, phase: 'finalizing' });
1611
+ finalizeInstallCommit(handle);
1612
+ removeAddJournal(journalPath);
1613
+ // 7. Report.
1614
+ print(io, {
1615
+ ok: true,
1616
+ source,
1617
+ ref,
1618
+ sha,
1619
+ path: folder,
1620
+ installed: written.length,
1621
+ defs: [...staged.values()].map((d) => d.name).sort(),
1622
+ hint: `installed workflows are now discoverable by default — run e.g. \`owenloop create ${[...staged.values()].map((d) => d.name).sort()[0] ?? '<def-name>'}\` with no --defs flag; for an explicit --defs, point it at ${folder}`,
1623
+ });
1624
+ return 0;
1625
+ }
1626
+ finally {
1627
+ // On success the staging dir was renamed away and its retained backups
1628
+ // finalized; on failure this clears whatever staging debris is left. The one
1629
+ // exception is a rollback double-fault (`preserveStagingRoot`), where the
1630
+ // only surviving copy of the previous content is parked here — leave it for
1631
+ // the user to recover (the next add clears it as debris). Then release the lock.
1632
+ if (!preserveStagingRoot)
1633
+ rmSync(stagingRoot, { recursive: true, force: true });
1634
+ releaseInstallLock(lock);
1635
+ }
1636
+ }
1637
+ /**
1638
+ * `owenloop add --recover`: an OFFLINE, network-free entry point to the same
1639
+ * `recoverInterruptedInstall` the normal add path runs inline. `dispatchAdd`
1640
+ * branches here at its very top, before `parseRepoSpec` and before the SHA and
1641
+ * tarball fetches — so this path can never touch the network. The normal add
1642
+ * path already runs recovery inline (belt-and-suspenders); this exists only so a
1643
+ * machine that crashed mid-install and is now offline can finish/undo the
1644
+ * interrupted install without waiting for the network to return.
1645
+ *
1646
+ * The lock scope here is recovery-ONLY: acquire `.owenloop/add.lock`, run
1647
+ * recovery, release. There is no fetch to keep outside the lock (the reason the
1648
+ * normal path acquires the lock only after the download), so the whole
1649
+ * short local operation runs under it. No `--db`/store open — recovery never
1650
+ * reads the store. Refusals (bad/mismatched/contradictory journal) throw and
1651
+ * propagate to `mainAsync`'s catch as `error: ...`, exit 1, mutating nothing —
1652
+ * and unlike the inline path there is no `preserveStagingRoot` dance, because
1653
+ * this path never rmSyncs the staging root itself, so a refusal naturally leaves
1654
+ * the journal, staging root, and dest untouched as evidence.
1655
+ */
1656
+ async function dispatchAddRecover(io, args) {
1657
+ // With --recover the owner/repo positional is optional; a supplied spec is
1658
+ // ambiguous ("recover then install"?), so refuse rather than guess — the
1659
+ // normal add path runs recovery inline anyway, so "recover then install" is
1660
+ // just `owenloop add owner/repo`.
1661
+ if (args.positionals[1] !== undefined) {
1662
+ throw new CliError('--recover takes no repository argument — run recovery alone, then re-run add');
1663
+ }
1664
+ // Resolve paths EXACTLY as dispatchAdd does — same defsDir/lock/journal
1665
+ // derivation — so recovery acts on the same tree a real add would. No fetch
1666
+ // reference, no store open.
1667
+ const defsOverride = last(args, 'defs') ?? io.env.OWENLOOP_DEFS;
1668
+ const defsDir = defsOverride ?? join(io.cwd, 'workflows');
1669
+ const lockfilePath = join(io.cwd, '.owenloop', 'installed.json');
1670
+ const installLockPath = join(io.cwd, '.owenloop', 'add.lock');
1671
+ const journalPath = join(io.cwd, '.owenloop', ADD_JOURNAL_FILENAME);
1672
+ // Mirror the SEC-3 symlink guards from the normal path (same order, same
1673
+ // rationale): `.owenloop` is written by the lock acquire; the default defsDir
1674
+ // is mutated-through by recovery. An explicit --defs/OWENLOOP_DEFS is operator
1675
+ // intent, not repo content, so it is not symlink-guarded (matching dispatchAdd).
1676
+ mkdirRefusingSymlink(join(io.cwd, '.owenloop'));
1677
+ if (defsOverride === undefined)
1678
+ mkdirRefusingSymlink(defsDir);
1679
+ const lock = await acquireInstallLock(installLockPath);
1680
+ let outcome;
1681
+ try {
1682
+ outcome = recoverInterruptedInstall({ defsDir, journalPath, lockfilePath });
1683
+ }
1684
+ finally {
1685
+ releaseInstallLock(lock);
1686
+ }
1687
+ switch (outcome) {
1688
+ case 'no-journal':
1689
+ print(io, { ok: true, recovered: false, message: 'nothing to recover — no interrupted install found' });
1690
+ return 0;
1691
+ case 'rolled-forward':
1692
+ print(io, {
1693
+ ok: true,
1694
+ recovered: true,
1695
+ outcome: 'rolled-forward',
1696
+ message: 'interrupted install completed (rolled forward)',
1697
+ });
1698
+ return 0;
1699
+ case 'rolled-back':
1700
+ print(io, {
1701
+ ok: true,
1702
+ recovered: true,
1703
+ outcome: 'rolled-back',
1704
+ message: 'interrupted install undone — previous state restored (or already consistent)',
1705
+ });
1706
+ return 0;
1707
+ }
1708
+ }
1709
+ // ---- hub onboarding: login / logout / connect / push -------------------------
1710
+ /**
1711
+ * Resolve the target hub origin: `--hub` > `OWENLOOP_HUB` env > the default
1712
+ * production hub. Normalized (scheme required, trailing slash/path stripped) so
1713
+ * it can serve as a stable credential-store key and project binding value.
1714
+ */
1715
+ const DEFAULT_HUB = 'https://api.owenloop.com';
1716
+ function resolveHub(io, args) {
1717
+ const raw = last(args, 'hub') ?? io.env.OWENLOOP_HUB ?? DEFAULT_HUB;
1718
+ try {
1719
+ return normalizeOrigin(raw);
1720
+ }
1721
+ catch (e) {
1722
+ throw new CliError(e.message);
1723
+ }
1724
+ }
1725
+ function resolveKeychain(io) {
1726
+ if (io.env.OWENLOOP_NO_KEYCHAIN === '1')
1727
+ return undefined;
1728
+ return io.keychain ?? defaultKeychain(io.env);
1729
+ }
1730
+ function credentialBackend(io) {
1731
+ const kc = resolveKeychain(io);
1732
+ return kc ? { kind: 'keychain', kc } : { kind: 'file' };
1733
+ }
1734
+ /**
1735
+ * Read the stored credential for `origin` from the chosen backend ONLY. A
1736
+ * keychain-backed read NEVER falls through to the file (that fallback was the
1737
+ * REL-6 shadowing bug), and a corrupt keychain entry reads as absent (`null`)
1738
+ * — login overwrites it, logout clears it — never as a reason to consult the
1739
+ * file.
1740
+ */
1741
+ function readCredential(io, origin) {
1742
+ const backend = credentialBackend(io);
1743
+ if (backend.kind === 'keychain') {
1744
+ const raw = backend.kc.get(origin);
1745
+ if (!raw)
1746
+ return null;
1747
+ try {
1748
+ return JSON.parse(raw);
1749
+ }
1750
+ catch {
1751
+ return null; // corrupt entry — treat as absent; do NOT consult the file
1752
+ }
1753
+ }
1754
+ const file = readCredentialFile(credentialFilePath(io.env));
1755
+ return file.hubs[origin] ?? null;
1756
+ }
1757
+ /**
1758
+ * Store a credential for `origin` in the chosen backend ONLY; returns which
1759
+ * one. A failed keychain write is a hard error (REL-6), never a silent
1760
+ * fall-through to the file — the escape hatch is to choose the file backend up
1761
+ * front with `OWENLOOP_NO_KEYCHAIN=1`.
1762
+ */
1763
+ function storeCredential(io, origin, cred) {
1764
+ const backend = credentialBackend(io);
1765
+ if (backend.kind === 'keychain') {
1766
+ try {
1767
+ backend.kc.set(origin, JSON.stringify(cred));
1768
+ }
1769
+ catch (e) {
1770
+ throw new CliError(`could not write the credential to the OS keychain: ${e.message}. ` +
1771
+ 'Fix the keychain, or set OWENLOOP_NO_KEYCHAIN=1 to use the 0600 file store');
1772
+ }
1773
+ return 'keychain';
1774
+ }
1775
+ const path = credentialFilePath(io.env);
1776
+ const file = readCredentialFile(path);
1777
+ file.hubs[origin] = cred;
1778
+ writeCredentialFile(path, file);
1779
+ return 'file';
1780
+ }
1781
+ /**
1782
+ * Delete any stored credential for `origin` from BOTH backends. Deliberately
1783
+ * not routed through `credentialBackend`: logout is a defensive dual-clear
1784
+ * (the proposal explicitly blesses it), so a live refresh token can never be
1785
+ * stranded in the store that wasn't the currently-chosen one. Returns whether
1786
+ * anything was removed.
1787
+ */
1788
+ function deleteCredential(io, origin) {
1789
+ let removed = false;
1790
+ const kc = resolveKeychain(io);
1791
+ if (kc && kc.get(origin) !== null) {
1792
+ kc.delete(origin);
1793
+ removed = true;
1794
+ }
1795
+ const path = credentialFilePath(io.env);
1796
+ const file = readCredentialFile(path);
1797
+ if (file.hubs[origin] !== undefined) {
1798
+ delete file.hubs[origin];
1799
+ writeCredentialFile(path, file);
1800
+ removed = true;
1801
+ }
1802
+ return removed;
1803
+ }
1804
+ /** The Bearer value for an authenticated request. Never logged. */
1805
+ function authHeader(cred) {
1806
+ return `Bearer ${cred.accessToken}`;
1807
+ }
1808
+ // Request deadline for EVERY hub/auth call — OAuth discovery, DCR, code
1809
+ // exchange, token refresh, whoami, workflow list, and push (REL-7). These are
1810
+ // all small JSON round-trips, so one budget fits them all;
1811
+ // OWENLOOP_HUB_TIMEOUT_MS overrides it (a test knob, consistent with
1812
+ // OWENLOOP_LOGIN_TIMEOUT_MS and the project's other OWENLOOP_* test-only knobs).
1813
+ const HUB_TIMEOUT_MS = 30_000;
1814
+ function hubTimeoutMs(io) {
1815
+ const override = Number(io.env.OWENLOOP_HUB_TIMEOUT_MS);
1816
+ return Number.isFinite(override) && override > 0 ? override : HUB_TIMEOUT_MS;
1817
+ }
1818
+ // Cap on any hub/auth JSON RESPONSE body (OAuth discovery, DCR, code exchange,
1819
+ // token refresh, whoami, the workflow list, create_workflow). Hub responses are
1820
+ // small round-trips — the largest realistic body is a workflows summary list,
1821
+ // far below 8 MiB. This is a RESPONSE cap; the hub's 32MB figure (the 413 path)
1822
+ // is a REQUEST cap and responses never echo YAML. OWENLOOP_HUB_MAX_RESPONSE_BYTES
1823
+ // overrides it (a test-only knob, consistent with OWENLOOP_HUB_TIMEOUT_MS).
1824
+ const HUB_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
1825
+ function hubMaxResponseBytes(io) {
1826
+ const override = Number(io.env.OWENLOOP_HUB_MAX_RESPONSE_BYTES);
1827
+ return Number.isFinite(override) && override > 0 ? override : HUB_MAX_RESPONSE_BYTES;
1828
+ }
1829
+ /**
1830
+ * `fetch` wrapper putting a deadline on every hub/auth call (REL-7). The abort
1831
+ * signal is threaded into `fetch` AND the body is read (via `readBodyBounded`,
1832
+ * which caps the response size — see HUB_MAX_RESPONSE_BYTES) inside the same
1833
+ * try, so the deadline covers a stalled BODY read too — the exact undici
1834
+ * behavior the two `add` fetches document (`AbortSignal.timeout` ties the
1835
+ * signal to the body stream). The returned `Response` re-exposes the read
1836
+ * body, so every call site's `res.json()` / `res.status` /
1837
+ * `res.headers.get(...)` usage is byte-for-byte unchanged. A
1838
+ * `TimeoutError`/`AbortError` becomes a clear `CliError` (naming the request,
1839
+ * which is origin+path only — never a token); anything else is rethrown
1840
+ * untouched.
1841
+ *
1842
+ * `redirect: 'error'` is forced on every call — after the `...init` spread, so
1843
+ * no caller can override it — to close the redirect gap `resolveEndpoint`
1844
+ * (SEC-4) cannot see: same-origin validation covers only the INITIAL URL, but a
1845
+ * validated endpoint answering 307/308 would re-send the POST body (refresh
1846
+ * token, PKCE verifier, auth code, workflow YAML) to a foreign origin — undici
1847
+ * strips the Authorization header on a cross-origin redirect but RESENDS the
1848
+ * body. The hub protocol has no redirects, so any 3xx is a hard, loud failure
1849
+ * mapped to a `CliError` (again naming origin+path only, never a token).
1850
+ */
1851
+ async function hubFetch(io, url, init) {
1852
+ const fetchFn = io.fetch ?? globalThis.fetch;
1853
+ const ms = hubTimeoutMs(io);
1854
+ const method = (init?.method ?? 'GET').toUpperCase();
1855
+ try {
1856
+ const res = await fetchFn(url, { ...init, signal: AbortSignal.timeout(ms), redirect: 'error' });
1857
+ // 204/304 carry no body — reading one would be a spec violation.
1858
+ if (res.status === 204 || res.status === 304) {
1859
+ return new Response(null, { status: res.status, statusText: res.statusText, headers: res.headers });
1860
+ }
1861
+ const body = await readBodyBounded(res, hubMaxResponseBytes(io), `${method} ${url}`);
1862
+ return new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
1863
+ }
1864
+ catch (e) {
1865
+ const err = e;
1866
+ if (err.name === 'TimeoutError' || err.name === 'AbortError') {
1867
+ throw new CliError(`hub did not respond within ${ms / 1000}s (${method} ${url})`);
1868
+ }
1869
+ // `redirect: 'error'` makes undici reject a 3xx with a TypeError whose
1870
+ // cause message is 'unexpected redirect' (verified on Node 22.22.3 and 26).
1871
+ // Substring-match for slack against undici wording drift — if it ever stops
1872
+ // matching, the raw TypeError still surfaces (fail-closed, just less pretty).
1873
+ const cause = String(err.cause?.message ?? '');
1874
+ if (err.name === 'TypeError' && cause.includes('unexpected redirect')) {
1875
+ throw new CliError(`hub responded with a redirect — refusing to follow it (${method} ${url}); redirects are not part of the hub protocol`);
1876
+ }
1877
+ throw e;
1878
+ }
1879
+ }
1880
+ /**
1881
+ * Ensure an `oauth` credential's access token is fresh: if it expires within
1882
+ * 60s, refresh once (grant_type=refresh_token) and persist the new token. No-op
1883
+ * for `agent`/`oauth-pasted` credentials (they don't refresh). Returns the
1884
+ * possibly-updated credential.
1885
+ */
1886
+ async function ensureFreshOAuth(io, origin, cred, persist = true) {
1887
+ if (cred.kind !== 'oauth')
1888
+ return cred;
1889
+ if (cred.expiresAt - nowMs() > 60_000)
1890
+ return cred;
1891
+ return refreshOAuth(io, origin, cred, persist);
1892
+ }
1893
+ /**
1894
+ * `persist` defaults to true — the normal case is refreshing an ALREADY
1895
+ * stored, trusted credential (push/connect), where persisting immediately
1896
+ * matters because refresh tokens can be single-use/rotating: losing the new
1897
+ * one to a later crash would strand the user. `verifyCredential`'s login-time
1898
+ * use passes `persist: false` — a not-yet-stored credential must never be
1899
+ * written to disk/keychain before it is proven to work end to end (a 401 on
1900
+ * the retry after this refresh still fails the overall login), matching the
1901
+ * "never store an unverified token" rule enforced at every login call site.
1902
+ */
1903
+ async function refreshOAuth(io, origin, cred, persist = true) {
1904
+ const tokenEndpoint = await discoverTokenEndpoint(io, origin);
1905
+ const body = new URLSearchParams({
1906
+ grant_type: 'refresh_token',
1907
+ refresh_token: cred.refreshToken,
1908
+ client_id: cred.clientId,
1909
+ });
1910
+ const res = await hubFetch(io, tokenEndpoint, {
1911
+ method: 'POST',
1912
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
1913
+ body: body.toString(),
1914
+ });
1915
+ if (!res.ok) {
1916
+ throw new CliError('credential expired and refresh failed — run `owenloop login`');
1917
+ }
1918
+ const json = (await res.json());
1919
+ if (typeof json.access_token !== 'string') {
1920
+ throw new CliError('credential expired and refresh returned no access token — run `owenloop login`');
1921
+ }
1922
+ const expiresIn = typeof json.expires_in === 'number' ? json.expires_in : 3600;
1923
+ const refreshed = {
1924
+ kind: 'oauth',
1925
+ accessToken: json.access_token,
1926
+ refreshToken: typeof json.refresh_token === 'string' ? json.refresh_token : cred.refreshToken,
1927
+ expiresAt: nowMs() + expiresIn * 1000,
1928
+ clientId: cred.clientId,
1929
+ };
1930
+ if (persist)
1931
+ storeCredential(io, origin, refreshed);
1932
+ return refreshed;
1933
+ }
1934
+ async function discoverMetadata(io, origin) {
1935
+ const res = await hubFetch(io, resolveEndpoint(origin, '/.well-known/oauth-authorization-server'), {
1936
+ headers: { Accept: 'application/json' },
1937
+ });
1938
+ if (!res.ok) {
1939
+ throw new CliError(`could not read OAuth metadata from ${origin} (HTTP ${res.status})`);
1940
+ }
1941
+ return (await res.json());
1942
+ }
1943
+ async function discoverTokenEndpoint(io, origin) {
1944
+ const meta = await discoverMetadata(io, origin);
1945
+ if (!meta.token_endpoint)
1946
+ throw new CliError(`hub ${origin} advertises no token_endpoint`);
1947
+ return resolveEndpoint(origin, meta.token_endpoint);
1948
+ }
1949
+ /**
1950
+ * GET `path` on `origin` with a bearer credential, refreshing an expiring
1951
+ * oauth token first and retrying exactly once after a 401→refresh for oauth.
1952
+ * Returns the raw response plus the credential actually used (possibly
1953
+ * refreshed), so the caller can both persist it and apply its own hard-error
1954
+ * semantics on the final status (a 401 after the retry, a non-2xx, etc. —
1955
+ * left to the caller since the wording differs slightly by context).
1956
+ */
1957
+ async function authedGet(io, origin, cred, path, persist = true) {
1958
+ let current = await ensureFreshOAuth(io, origin, cred, persist);
1959
+ let res = await hubFetch(io, resolveEndpoint(origin, path), {
1960
+ headers: { Authorization: authHeader(current), Accept: 'application/json' },
1961
+ });
1962
+ if (res.status === 401 && current.kind === 'oauth') {
1963
+ current = await refreshOAuth(io, origin, current, persist);
1964
+ res = await hubFetch(io, resolveEndpoint(origin, path), {
1965
+ headers: { Authorization: authHeader(current), Accept: 'application/json' },
1966
+ });
1967
+ }
1968
+ return { res, cred: current };
1969
+ }
1970
+ /**
1971
+ * A 401 on an agent token is a hard "revoked/invalid" error; a 401 on any
1972
+ * other credential kind (after `authedGet`'s one refresh-and-retry) is a hard
1973
+ * "credential rejected" error; any other non-2xx is a generic hub-rejected
1974
+ * error naming the status. Shared by `verifyCredential` and `dispatchPush`'s
1975
+ * server-list fetch so both surfaces the same wording for the same failure.
1976
+ */
1977
+ function assertAuthOk(res, cred, origin) {
1978
+ if (res.status === 401) {
1979
+ if (cred.kind === 'agent') {
1980
+ throw new CliError('token revoked or invalid — re-mint it in the console or run `owenloop login`');
1981
+ }
1982
+ throw new CliError('credential rejected by the hub — run `owenloop login`');
1983
+ }
1984
+ if (!res.ok) {
1985
+ throw new CliError(`hub ${origin} rejected the credential (HTTP ${res.status})`);
1986
+ }
1987
+ }
1988
+ /**
1989
+ * Verify a credential works against the hub's `GET /api/whoami` (any 2xx =
1990
+ * authenticated) and return the identity it names. Whoami carries no RBAC
1991
+ * verb, so this proves *authentication*, not any particular scope (e.g.
1992
+ * `list`) — a token lacking a scope `push` later needs still fails there,
1993
+ * with the hub's own 401/403, which is acceptable and honest. Refreshes an
1994
+ * expiring oauth token first, and retries exactly once after a 401→refresh
1995
+ * for oauth; a 401 on an agent token is a hard "revoked/invalid" error.
1996
+ * Returns the credential actually used (possibly refreshed), so the caller
1997
+ * can persist it, alongside the parsed identity.
1998
+ *
1999
+ * `persist` (default true) controls whether an in-flight refresh writes its
2000
+ * new token to storage immediately (see `refreshOAuth`'s doc comment) —
2001
+ * `dispatchLogin`'s OAuth branch passes `false` because the credential being
2002
+ * verified here hasn't been stored yet at all; a refresh mid-verify must not
2003
+ * sneak a not-yet-proven credential onto disk ahead of the pass/fail verdict.
2004
+ */
2005
+ async function verifyCredential(io, origin, cred, persist = true) {
2006
+ const { res, cred: current } = await authedGet(io, origin, cred, '/api/whoami', persist);
2007
+ assertAuthOk(res, current, origin);
2008
+ const body = await res.json();
2009
+ return { cred: current, identity: asWhoami(body) };
2010
+ }
2011
+ /**
2012
+ * `owenloop login` — authenticate the CLI against a hub. Primary flow is a
2013
+ * loopback OAuth auth-code + PKCE(S256) exchange; `--with-token` reads an
2014
+ * `olp_`/`mcpat_` token from stdin instead (never argv). Either way the
2015
+ * credential is verified before it is stored, and stored in the OS keychain or
2016
+ * a 0600 file — never plaintext in the repo or `.env`.
2017
+ */
2018
+ async function dispatchLogin(io, args) {
2019
+ const origin = resolveHub(io, args);
2020
+ const existed = readCredential(io, origin) !== null;
2021
+ if (flag(args, 'with-token')) {
2022
+ const readStdin = io.readStdin ?? defaultReadStdin;
2023
+ const token = (await readStdin()).trim();
2024
+ if (token === '')
2025
+ throw new CliError('no token on stdin (pipe the token in, e.g. `pbpaste | owenloop login --with-token`)');
2026
+ let cred;
2027
+ if (token.startsWith('olp_'))
2028
+ cred = { kind: 'agent', accessToken: token };
2029
+ else if (token.startsWith('mcpat_'))
2030
+ cred = { kind: 'oauth-pasted', accessToken: token };
2031
+ else
2032
+ throw new CliError('unrecognized token — expected an `olp_` agent token or an `mcpat_` access token');
2033
+ const { identity } = await verifyCredential(io, origin, cred); // never store an unverified token
2034
+ const storage = storeCredential(io, origin, cred);
2035
+ print(io, {
2036
+ ok: true,
2037
+ hub: origin,
2038
+ kind: cred.kind,
2039
+ storage,
2040
+ replaced: existed,
2041
+ org: identity.orgName,
2042
+ orgId: identity.orgId,
2043
+ identity: identity.actor,
2044
+ ...(identity.email ? { email: identity.email } : {}),
2045
+ });
2046
+ return 0;
2047
+ }
2048
+ // Loopback OAuth: bind the port FIRST (the service matches redirect URIs by
2049
+ // exact string — no RFC 8252 variable-port allowance — so the DCR must carry
2050
+ // the concrete 127.0.0.1:<port> callback).
2051
+ const { verifier, challenge } = pkcePair();
2052
+ const state = randomState();
2053
+ const timeoutOverride = Number(io.env.OWENLOOP_LOGIN_TIMEOUT_MS);
2054
+ const timeoutMs = Number.isFinite(timeoutOverride) && timeoutOverride > 0 ? timeoutOverride : undefined;
2055
+ const { server, port, waitForCallback, close } = await startLoopbackServer(state, timeoutMs);
2056
+ try {
2057
+ const redirectUri = `http://127.0.0.1:${port}/callback`;
2058
+ const meta = await discoverMetadata(io, origin);
2059
+ if (!meta.authorization_endpoint || !meta.token_endpoint || !meta.registration_endpoint) {
2060
+ throw new CliError(`hub ${origin} does not advertise the OAuth endpoints login needs`);
2061
+ }
2062
+ const clientId = await registerClient(io, origin, meta.registration_endpoint, redirectUri);
2063
+ const authUrl = new URL(resolveEndpoint(origin, meta.authorization_endpoint));
2064
+ authUrl.searchParams.set('response_type', 'code');
2065
+ authUrl.searchParams.set('client_id', clientId);
2066
+ authUrl.searchParams.set('redirect_uri', redirectUri);
2067
+ authUrl.searchParams.set('code_challenge', challenge);
2068
+ authUrl.searchParams.set('code_challenge_method', 'S256');
2069
+ authUrl.searchParams.set('state', state);
2070
+ io.err(`Opening your browser to sign in. If it does not open, visit:\n ${authUrl.toString()}`);
2071
+ (io.openUrl ?? defaultOpenUrl)(authUrl.toString());
2072
+ const { code } = await waitForCallback;
2073
+ const exchanged = await exchangeCode(io, origin, meta.token_endpoint, {
2074
+ code,
2075
+ clientId,
2076
+ redirectUri,
2077
+ verifier,
2078
+ });
2079
+ const { cred, identity } = await verifyCredential(io, origin, exchanged, false); // never store an unverified token
2080
+ const storage = storeCredential(io, origin, cred);
2081
+ print(io, {
2082
+ ok: true,
2083
+ hub: origin,
2084
+ kind: cred.kind,
2085
+ storage,
2086
+ replaced: existed,
2087
+ org: identity.orgName,
2088
+ orgId: identity.orgId,
2089
+ identity: identity.actor,
2090
+ ...(identity.email ? { email: identity.email } : {}),
2091
+ });
2092
+ return 0;
2093
+ }
2094
+ finally {
2095
+ void server;
2096
+ close();
2097
+ }
2098
+ }
2099
+ const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
2100
+ /**
2101
+ * Bind a single-use loopback catcher on 127.0.0.1:0 that resolves on the OAuth
2102
+ * callback. `timeoutMs` overrides the 5-minute default (test knob, threaded
2103
+ * from `OWENLOOP_LOGIN_TIMEOUT_MS` by `dispatchLogin`, consistent with the
2104
+ * project's other `OWENLOOP_*` test-only env knobs).
2105
+ */
2106
+ async function startLoopbackServer(expectedState, timeoutMs = LOGIN_TIMEOUT_MS) {
2107
+ const loginHtml = (msg) => `<!doctype html><meta charset="utf-8"><title>owenloop</title><body style="font-family:system-ui;padding:2rem"><p>${msg}</p></body>`;
2108
+ let resolveCb;
2109
+ let rejectCb;
2110
+ const waitForCallback = new Promise((res, rej) => {
2111
+ resolveCb = res;
2112
+ rejectCb = rej;
2113
+ });
2114
+ // The timeout timer (below) can fire — and reject waitForCallback — before
2115
+ // dispatchLogin reaches its `await waitForCallback` (it awaits
2116
+ // discoverMetadata/registerClient first), which would otherwise surface as
2117
+ // an unhandled rejection and crash the process. This no-op .catch marks the
2118
+ // rejection handled without consuming it; the later real `await
2119
+ // waitForCallback` in dispatchLogin still sees and throws the same error.
2120
+ waitForCallback.catch(() => { });
2121
+ const server = createServer((req, res) => {
2122
+ const u = new URL(req.url ?? '/', 'http://127.0.0.1');
2123
+ if (u.pathname !== '/callback') {
2124
+ res.writeHead(404);
2125
+ res.end();
2126
+ return;
2127
+ }
2128
+ const error = u.searchParams.get('error');
2129
+ const code = u.searchParams.get('code');
2130
+ const gotState = u.searchParams.get('state');
2131
+ if (error) {
2132
+ res.writeHead(400, { 'Content-Type': 'text/html' });
2133
+ res.end(loginHtml('Login failed. You can close this tab.'));
2134
+ rejectCb(new CliError(`login denied by the hub: ${error}`));
2135
+ return;
2136
+ }
2137
+ if (gotState !== expectedState) {
2138
+ res.writeHead(400, { 'Content-Type': 'text/html' });
2139
+ res.end(loginHtml('State mismatch. You can close this tab.'));
2140
+ rejectCb(new CliError('state mismatch on the OAuth callback — possible CSRF; aborting login'));
2141
+ return;
2142
+ }
2143
+ if (!code) {
2144
+ res.writeHead(400, { 'Content-Type': 'text/html' });
2145
+ res.end(loginHtml('Missing authorization code. You can close this tab.'));
2146
+ rejectCb(new CliError('OAuth callback carried no authorization code'));
2147
+ return;
2148
+ }
2149
+ res.writeHead(200, { 'Content-Type': 'text/html' });
2150
+ res.end(loginHtml('Login complete — return to your terminal.'));
2151
+ resolveCb({ code });
2152
+ });
2153
+ const timer = setTimeout(() => {
2154
+ const human = timeoutMs % 60_000 === 0 ? `${timeoutMs / 60_000} minutes` : `${timeoutMs}ms`;
2155
+ rejectCb(new CliError(`login timed out after ${human} waiting for the browser callback`));
2156
+ }, timeoutMs);
2157
+ timer.unref?.();
2158
+ await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
2159
+ const port = server.address().port;
2160
+ return {
2161
+ server,
2162
+ port,
2163
+ waitForCallback,
2164
+ close: () => {
2165
+ clearTimeout(timer);
2166
+ server.close();
2167
+ },
2168
+ };
2169
+ }
2170
+ /** DCR a public client (no client secret) with the exact loopback redirect URI. */
2171
+ async function registerClient(io, origin, registrationEndpoint, redirectUri) {
2172
+ const res = await hubFetch(io, resolveEndpoint(origin, registrationEndpoint), {
2173
+ method: 'POST',
2174
+ headers: { 'Content-Type': 'application/json' },
2175
+ body: JSON.stringify({
2176
+ client_name: 'owenloop CLI',
2177
+ redirect_uris: [redirectUri],
2178
+ token_endpoint_auth_method: 'none',
2179
+ grant_types: ['authorization_code', 'refresh_token'],
2180
+ response_types: ['code'],
2181
+ }),
2182
+ });
2183
+ if (!res.ok) {
2184
+ throw new CliError(`dynamic client registration failed at ${origin} (HTTP ${res.status})`);
2185
+ }
2186
+ const json = (await res.json());
2187
+ if (typeof json.client_id !== 'string') {
2188
+ throw new CliError('dynamic client registration returned no client_id');
2189
+ }
2190
+ return json.client_id;
2191
+ }
2192
+ /** Exchange an auth code for tokens (form-encoded, with the PKCE verifier). */
2193
+ async function exchangeCode(io, origin, tokenEndpoint, p) {
2194
+ const body = new URLSearchParams({
2195
+ grant_type: 'authorization_code',
2196
+ code: p.code,
2197
+ client_id: p.clientId,
2198
+ redirect_uri: p.redirectUri,
2199
+ code_verifier: p.verifier,
2200
+ });
2201
+ const res = await hubFetch(io, resolveEndpoint(origin, tokenEndpoint), {
2202
+ method: 'POST',
2203
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
2204
+ body: body.toString(),
2205
+ });
2206
+ if (!res.ok) {
2207
+ throw new CliError(`token exchange failed at ${origin} (HTTP ${res.status})`);
2208
+ }
2209
+ const json = (await res.json());
2210
+ if (typeof json.access_token !== 'string' || typeof json.refresh_token !== 'string') {
2211
+ throw new CliError('token exchange returned an incomplete token set');
2212
+ }
2213
+ const expiresIn = typeof json.expires_in === 'number' ? json.expires_in : 3600;
2214
+ return {
2215
+ kind: 'oauth',
2216
+ accessToken: json.access_token,
2217
+ refreshToken: json.refresh_token,
2218
+ expiresAt: nowMs() + expiresIn * 1000,
2219
+ clientId: p.clientId,
2220
+ };
2221
+ }
2222
+ /**
2223
+ * `owenloop logout` — delete the stored credential for a hub from both the
2224
+ * keychain and the file store. Cheap; completes the credential lifecycle.
2225
+ */
2226
+ async function dispatchLogout(io, args) {
2227
+ const origin = resolveHub(io, args);
2228
+ const removed = deleteCredential(io, origin);
2229
+ print(io, { ok: true, hub: origin, removed });
2230
+ return 0;
2231
+ }
2232
+ /**
2233
+ * `owenloop connect` — bind the current project to a hub (writes
2234
+ * `.owenloop/hub.json`) and verify the stored credential works. Requires a
2235
+ * prior `owenloop login` for the resolved origin. `.owenloop/hub.json` is a
2236
+ * pure binding — there's no push state to preserve or reset across a rebind
2237
+ * (see `HubBinding`); `switchedFrom` is still reported when the origin
2238
+ * changes so the caller notices the rebind.
2239
+ */
2240
+ async function dispatchConnect(io, args) {
2241
+ const origin = resolveHub(io, args);
2242
+ const cred = readCredential(io, origin);
2243
+ if (!cred)
2244
+ throw new CliError(`no stored credential for ${origin} — run \`owenloop login\` first`);
2245
+ const { identity } = await verifyCredential(io, origin, cred);
2246
+ const path = hubBindingPath(io.cwd);
2247
+ const existing = readHubBinding(path);
2248
+ const switched = existing !== null && existing.hub !== origin;
2249
+ const binding = { version: 1, hub: origin };
2250
+ writeHubBinding(path, binding);
2251
+ print(io, {
2252
+ ok: true,
2253
+ hub: origin,
2254
+ ...(switched ? { switchedFrom: existing.hub } : {}),
2255
+ org: identity.orgName,
2256
+ orgId: identity.orgId,
2257
+ identity: identity.actor,
2258
+ ...(identity.email ? { email: identity.email } : {}),
2259
+ });
2260
+ return 0;
2261
+ }
2262
+ /**
2263
+ * `owenloop push [<defName>...] [--force] [--dry-run]` — publish local workflow
2264
+ * defs to the bound hub, diffed against the hub's own def `hash`
2265
+ * (`GET /api/workflows` — see `computeServerDiff`), never a client-side
2266
+ * ledger. Mirrors `add`'s all-or-nothing client-side validation gate before
2267
+ * any network write; server-side failures mid-batch record what landed and
2268
+ * exit 1. `POST /api/create_workflow` is itself idempotent, so even a wrong
2269
+ * "changed" verdict (e.g. from engine-version drift between this CLI and the
2270
+ * hub) is harmless — it just costs one extra round-trip that the server
2271
+ * reports back as a no-op.
2272
+ */
2273
+ async function dispatchPush(io, args) {
2274
+ const defsDir = last(args, 'defs') ?? io.env.OWENLOOP_DEFS ?? join(io.cwd, 'workflows');
2275
+ const dryRun = flag(args, 'dry-run');
2276
+ const force = flag(args, 'force');
2277
+ // Require a project binding.
2278
+ const bindingPath = hubBindingPath(io.cwd);
2279
+ const binding = readHubBinding(bindingPath);
2280
+ if (!binding)
2281
+ throw new CliError('this project is not bound to a hub — run `owenloop connect` first');
2282
+ // Defense in depth (SEC-2): a hub.json written by an older CLI could carry a
2283
+ // remote-http origin that predates the transport policy, and dispatchPush uses
2284
+ // it verbatim as the request origin. Validate the persisted binding at USE
2285
+ // time — normalizeOrigin enforces https-except-loopback. This check lives
2286
+ // here, NOT inside readHubBinding: dispatchConnect reads the existing binding
2287
+ // only to report switchedFrom, and a read-time throw would deadlock rebinding
2288
+ // AWAY from a bad origin. Leave readHubBinding shape-validation-only.
2289
+ let origin;
2290
+ try {
2291
+ origin = normalizeOrigin(binding.hub);
2292
+ }
2293
+ catch (e) {
2294
+ throw new CliError(`${e.message} — re-run \`owenloop connect\` to rebind`);
2295
+ }
2296
+ // A --hub that disagrees with the binding is a mistake, not a silent override.
2297
+ const hubArg = last(args, 'hub');
2298
+ if (hubArg !== undefined) {
2299
+ const requested = normalizeOrigin(hubArg);
2300
+ if (requested !== origin) {
2301
+ throw new CliError(`this project is bound to ${origin}, not ${requested} — re-run \`owenloop connect\` to rebind`);
2302
+ }
2303
+ }
2304
+ let cred = readCredential(io, origin);
2305
+ if (!cred)
2306
+ throw new CliError(`no stored credential for ${origin} — run \`owenloop login\``);
2307
+ // Load defs (same machinery as lint/add).
2308
+ if (!existsSync(defsDir))
2309
+ throw new CliError(`defs directory not found: ${defsDir}`);
2310
+ const failures = [];
2311
+ const allDefs = loadDefsRaw(defsDir, failures);
2312
+ // Narrow to positional names, if any (error on an unknown name).
2313
+ const requested = args.positionals.slice(1);
2314
+ let selected;
2315
+ if (requested.length > 0) {
2316
+ selected = [];
2317
+ for (const name of requested) {
2318
+ const def = allDefs.get(name);
2319
+ if (!def) {
2320
+ throw new CliError(`unknown workflow definition '${name}' (looked in ${defsDir})${failureNote(failures)}`);
2321
+ }
2322
+ selected.push(def);
2323
+ }
2324
+ }
2325
+ else {
2326
+ selected = [...allDefs.values()];
2327
+ }
2328
+ if (selected.length === 0) {
2329
+ throw new CliError(`nothing to push — no workflow definitions found in ${defsDir}`);
2330
+ }
2331
+ // Client-side validation gate — all-or-nothing, mirroring dispatchAdd exactly.
2332
+ // Any failure aborts the entire push; nothing is sent.
2333
+ const reasons = failures.map((f) => `${f.file}: ${f.error}`);
2334
+ for (const def of selected) {
2335
+ const lintResult = lintDef(def);
2336
+ reasons.push(...lintResult.errors.map((e) => `${def.name}: ${e}`));
2337
+ reasons.push(...validateDef(def).map((e) => `${def.name}: ${e}`));
2338
+ const report = modelCheck(def, { assumeProvided: true });
2339
+ const hasDefiniteDefect = report.invariantViolations.length > 0 ||
2340
+ (!report.bounded && (report.deadlocks.length > 0 || report.stuck.length > 0));
2341
+ if (hasDefiniteDefect) {
2342
+ reasons.push(`${def.name}: definite defects found (${report.invariantViolations.length} invariant violation(s), ` +
2343
+ `${report.deadlocks.length} deadlock(s), ${report.stuck.length} stuck state(s))`);
2344
+ }
2345
+ }
2346
+ // Assemble the push candidates: verbatim source yaml + the server-canonical
2347
+ // content hash (hashDefForHub). Defs whose file uses include: are not
2348
+ // hub-pushable (the service's create_workflow parses without include
2349
+ // expansion, and a re-serialized expanded def is not round-trippable) —
2350
+ // refuse them with a clear per-def reason. Same for bodyFile: — hashDefForHub
2351
+ // parses with no baseDir (matching the server's own computation), which
2352
+ // throws a DefError naming bodyFile for such a def; catch that specific
2353
+ // failure and refuse the def pre-push rather than letting it read as a
2354
+ // generic error (the server would reject the raw-YAML push anyway).
2355
+ const candidates = [];
2356
+ for (const def of selected) {
2357
+ if (!def.dir) {
2358
+ reasons.push(`${def.name}: has no source file on disk to push`);
2359
+ continue;
2360
+ }
2361
+ const yaml = readFileSync(def.dir, 'utf8');
2362
+ let usesInclude = false;
2363
+ try {
2364
+ const rawDef = buildDef(parseYaml(yaml), basename(def.dir), dirname(def.dir));
2365
+ usesInclude = (rawDef._includes?.length ?? 0) > 0;
2366
+ }
2367
+ catch {
2368
+ // A shape error here would already have surfaced via the validation gate;
2369
+ // treat an unexpected re-parse failure conservatively as pushable-as-is.
2370
+ }
2371
+ if (usesInclude) {
2372
+ reasons.push(`${def.name}: uses include:, not hub-pushable yet`);
2373
+ continue;
2374
+ }
2375
+ let hash;
2376
+ try {
2377
+ hash = hashDefForHub(yaml);
2378
+ }
2379
+ catch (e) {
2380
+ if (e instanceof DefError && /bodyFile/.test(e.message)) {
2381
+ reasons.push(`${def.name}: uses bodyFile:, not hub-pushable`);
2382
+ continue;
2383
+ }
2384
+ throw e;
2385
+ }
2386
+ candidates.push({ name: def.name, hash, yaml });
2387
+ }
2388
+ if (reasons.length > 0) {
2389
+ throw new CliError(`refusing to push — ${reasons.length} problem(s) found; nothing sent:\n - ${reasons.join('\n - ')}`);
2390
+ }
2391
+ // Fetch the server's own list once — the diff source of truth. Always
2392
+ // fetched, even under --force, so the new/changed labels stay accurate.
2393
+ const { res: listRes, cred: listCred } = await authedGet(io, origin, cred, '/api/workflows');
2394
+ assertAuthOk(listRes, listCred, origin);
2395
+ cred = listCred;
2396
+ let serverMap;
2397
+ try {
2398
+ serverMap = parseWorkflowList(await listRes.json());
2399
+ }
2400
+ catch (e) {
2401
+ throw new CliError(e.message);
2402
+ }
2403
+ const { toPush, unchanged } = computeServerDiff(candidates, serverMap, force);
2404
+ // Diff-style human lines go to stderr so stdout stays machine-parseable JSON.
2405
+ for (const c of unchanged)
2406
+ io.err(`= ${c.name} (unchanged)`);
2407
+ if (dryRun) {
2408
+ for (const c of toPush) {
2409
+ io.err(c.status === 'new' ? `+ ${c.name} (new)` : `~ ${c.name} (changed)`);
2410
+ }
2411
+ print(io, {
2412
+ ok: true,
2413
+ dryRun: true,
2414
+ hub: origin,
2415
+ new: toPush.filter((c) => c.status === 'new').map((c) => c.name),
2416
+ changed: toPush.filter((c) => c.status === 'changed').map((c) => c.name),
2417
+ unchanged: unchanged.map((c) => c.name),
2418
+ wouldPush: toPush.map((c) => c.name),
2419
+ });
2420
+ return 0;
2421
+ }
2422
+ // Refresh an expiring oauth token once up front (per-request 401 refresh below covers mid-batch expiry).
2423
+ cred = await ensureFreshOAuth(io, origin, cred);
2424
+ const pushedNames = [];
2425
+ const noopNames = [];
2426
+ const failed = [];
2427
+ const skipped = [];
2428
+ for (let i = 0; i < toPush.length; i++) {
2429
+ const c = toPush[i];
2430
+ const label = c.status === 'new' ? '+' : '~';
2431
+ try {
2432
+ let res = await createWorkflowRequest(io, origin, cred, c.yaml);
2433
+ if (res.status === 401 && cred.kind === 'oauth') {
2434
+ cred = await refreshOAuth(io, origin, cred);
2435
+ res = await createWorkflowRequest(io, origin, cred, c.yaml);
2436
+ }
2437
+ if (res.status === 401) {
2438
+ if (cred.kind === 'agent') {
2439
+ throw new CliError('token revoked or invalid — re-mint it in the console or run `owenloop login`');
2440
+ }
2441
+ throw new CliError('credential rejected by the hub — run `owenloop login`');
2442
+ }
2443
+ if (res.status === 413)
2444
+ throw new CliError('workflow yaml exceeds the hub 32MB request cap');
2445
+ if (res.status === 429) {
2446
+ const retryAfter = res.headers.get('retry-after');
2447
+ throw new RateLimitError(`rate limited by the hub${retryAfter ? ` (retry after ${retryAfter})` : ''}`);
2448
+ }
2449
+ if (!res.ok)
2450
+ throw new CliError(`hub returned HTTP ${res.status}`);
2451
+ const bodyJson = await res.json();
2452
+ const errText = createWorkflowError(bodyJson);
2453
+ if (errText !== null)
2454
+ throw new CliError(`hub rejected the def: ${errText}`);
2455
+ const okBody = asCreateWorkflowOk(bodyJson, c.name);
2456
+ if (okBody.unchanged) {
2457
+ noopNames.push(c.name);
2458
+ io.err(`= ${c.name} (server: unchanged, v${okBody.version})`);
2459
+ }
2460
+ else {
2461
+ pushedNames.push(c.name);
2462
+ io.err(`${label} ${c.name} (→ v${okBody.version})`);
2463
+ }
2464
+ }
2465
+ catch (e) {
2466
+ // A 429 halts the whole batch immediately (REL-10): record this def as
2467
+ // failed, then stop — the not-yet-attempted remainder is reported as
2468
+ // `skipped`, not silently hammered against a rate-limited server.
2469
+ // Handled before the generic path because RateLimitError extends CliError.
2470
+ if (e instanceof RateLimitError) {
2471
+ const msg = e.message;
2472
+ failed.push({ name: c.name, error: msg });
2473
+ io.err(`! ${c.name} (failed: ${msg})`);
2474
+ const remainder = toPush.slice(i + 1).map((r) => r.name);
2475
+ skipped.push(...remainder);
2476
+ if (remainder.length > 0) {
2477
+ io.err(`stopping — rate limited by the hub; ${remainder.length} def(s) not attempted`);
2478
+ }
2479
+ break;
2480
+ }
2481
+ // A hard auth error aborts the whole run (re-throw); a per-def server
2482
+ // failure is recorded and the batch continues (already-pushed defs stand).
2483
+ if (e instanceof CliError && /run `owenloop login`|re-mint it/.test(e.message)) {
2484
+ throw e;
2485
+ }
2486
+ const msg = e.message;
2487
+ failed.push({ name: c.name, error: msg });
2488
+ io.err(`! ${c.name} (failed: ${msg})`);
2489
+ }
2490
+ }
2491
+ print(io, {
2492
+ ok: failed.length === 0,
2493
+ hub: origin,
2494
+ pushed: pushedNames,
2495
+ noop: noopNames,
2496
+ unchanged: unchanged.map((c) => c.name),
2497
+ skipped,
2498
+ failed,
2499
+ });
2500
+ return failed.length === 0 ? 0 : 1;
2501
+ }
2502
+ function createWorkflowRequest(io, origin, cred, yaml) {
2503
+ return hubFetch(io, resolveEndpoint(origin, '/api/create_workflow'), {
2504
+ method: 'POST',
2505
+ headers: {
2506
+ Authorization: authHeader(cred),
2507
+ 'Content-Type': 'application/json',
2508
+ Accept: 'application/json',
2509
+ },
2510
+ body: JSON.stringify({ yaml }),
2511
+ });
2512
+ }
2513
+ /**
2514
+ * Async entry point that adds network I/O for `add` and the hub commands on top
2515
+ * of the otherwise fully-synchronous engine/CLI (see the doc comment on
2516
+ * `sleepMs` above and README "sync end to end"). `main`/`dispatch` stay sync and
2517
+ * unchanged — this wraps them, routing only the network-touching verbs through
2518
+ * the async path, so every existing command and test keeps working exactly as
2519
+ * before.
2520
+ */
2521
+ export const ASYNC_COMMANDS = new Set(['add', 'login', 'logout', 'connect', 'push']);
2522
+ export async function mainAsync(argv, io = defaultIO()) {
2523
+ const args = parseArgs(argv);
2524
+ const command = args.positionals[0];
2525
+ if (command === undefined || !ASYNC_COMMANDS.has(command)) {
2526
+ return main(argv, io);
2527
+ }
2528
+ try {
2529
+ const short = preflight(command, args, io);
2530
+ if (short !== undefined)
2531
+ return short;
2532
+ switch (command) {
2533
+ case 'add':
2534
+ return await dispatchAdd(io, args);
2535
+ case 'login':
2536
+ return await dispatchLogin(io, args);
2537
+ case 'logout':
2538
+ return await dispatchLogout(io, args);
2539
+ case 'connect':
2540
+ return await dispatchConnect(io, args);
2541
+ case 'push':
2542
+ return await dispatchPush(io, args);
2543
+ default:
2544
+ return main(argv, io); // unreachable — ASYNC_COMMANDS guards the switch
2545
+ }
2546
+ }
2547
+ catch (e) {
2548
+ if (e instanceof CliError || e instanceof DefError) {
2549
+ io.err(`error: ${e.message}`);
2550
+ }
2551
+ else {
2552
+ io.err(`error: ${e.message}`);
2553
+ }
2554
+ return 1;
2555
+ }
2556
+ }
770
2557
  /** Run the CLI. Returns a process exit code. */
771
2558
  export function main(argv, io = defaultIO()) {
772
2559
  const args = parseArgs(argv);
@@ -776,6 +2563,9 @@ export function main(argv, io = defaultIO()) {
776
2563
  return 0;
777
2564
  }
778
2565
  try {
2566
+ const short = preflight(command, args, io);
2567
+ if (short !== undefined)
2568
+ return short;
779
2569
  return dispatch(command, io, args);
780
2570
  }
781
2571
  catch (e) {