owenloop 0.2.1 → 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.d.ts 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,11 +31,57 @@
30
31
  *
31
32
  * Global: --db <path> (env OWENLOOP_DB), --defs <dir> (env OWENLOOP_DEFS).
32
33
  */
34
+ /** An OS keychain backend, keyed by hub origin (the `account`). */
35
+ export interface Keychain {
36
+ get(account: string): string | null;
37
+ set(account: string, value: string): void;
38
+ delete(account: string): void;
39
+ }
33
40
  export interface CliIO {
34
41
  cwd: string;
35
42
  env: Record<string, string | undefined>;
36
43
  out: (line: string) => void;
37
44
  err: (line: string) => void;
45
+ /** Injectable for hermetic tests — the network-touching verbs (`add`, hub commands) use this. */
46
+ fetch?: typeof globalThis.fetch;
47
+ /** Open a URL in the user's browser (login). Default: fire-and-forget `open`/`xdg-open`/`start`. */
48
+ openUrl?: (url: string) => void;
49
+ /**
50
+ * OS keychain backend for credential storage. The backend is chosen ONCE per
51
+ * process (see `credentialBackend`), then used for read/write/delete
52
+ * consistently: a `security`-backed keychain on macOS, else the 0600 file
53
+ * store. `undefined` here — non-mac, or `OWENLOOP_NO_KEYCHAIN=1` — selects
54
+ * the file backend. A keychain write failure is a hard error, never a silent
55
+ * file fallback (REL-6).
56
+ */
57
+ keychain?: Keychain;
58
+ /** Read a secret from stdin (`login --with-token`). Default: drain `process.stdin`. */
59
+ readStdin?: () => Promise<string>;
38
60
  }
61
+ export declare const USAGE = "owenloop \u2014 a dataflow workflow engine\n\nUsage: owenloop <command> [args] [--db <path>] [--defs <dir>]\n\nCommands:\n defs list available workflow definitions\n add <owner>/<repo>[@ref] fetch, validate, and install a repo's workflow defs (public repos)\n add --recover finish or undo a crash-interrupted install (offline; no network)\n login [--hub <url>] [--with-token] authenticate the CLI against a hub, verified via whoami (loopback OAuth, or --with-token from stdin)\n logout [--hub <url>] delete the stored credential for a hub\n connect [--hub <url>] bind this project to a hub and verify the stored credential (whoami)\n push [<defName>...] [--force] [--dry-run] publish local workflow defs to the bound hub (server-diffed, idempotent)\n lint [<def-name>] check def(s) for wiring problems\n check <def> [--format text|json] [--max-depth N] [--max-states N] [--max-collection N] [--assume-provided]\n bounded reachability check (deadlocks, stuck, dead steps, declared invariants)\n create <def> [--title t] [--provide name=json ...] [--param k=v ...]\n provide <wf> <name> [--value json] supply an owed (seedOwed) input\n adopt <wf> re-pin an instance to the current def (\u00A728); settles new debts\n 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)\n reap <wf> [--now] run the reaper; --now forces every claim stale (TTL 0)\n runs <wf> [--open] list this instance's runs (+ claim state for open ones)\n order <wf> <run> print the order packet issued at claim time (persisted in the claim txn)\n status <wf> derive debts / eligible / blocked\n status --all every instance's status in one call (fleet read)\n wait <wf> --until eligible|done [--timeout <dur>] block until engine state matches\n show <wf> dump raw artifacts\n trace <wf> [--format text] causal timeline + artifact biographies\n graph <def-or-wf> [--format dot|mermaid|json] wiring graph (+ live overlay if wf id)\n list list workflow instances\n green <wf> <run> <path> [--value json] [--terminal]\n emit <wf> <run> --items '[{...}]' accrete collection elements\n seal <wf> <run> [--value json] signal a collection is complete\n reject <wf> <path> --by <author> --text <msg>\n retract <wf> <path> --by <author> --text <msg>\n skip <wf> <path> --by <author> --text <msg>\n retry <wf> <path> [--by <author>] [--text <guidance>] clear a \u00A76 stall\n heartbeat <wf> <run> [--now <ms>] touch liveness timestamp on an open run\n close <wf> <run> [--outcome ok|no_work|failed|skipped] [--summary s]\n delete <wf> [--recursive] refuse if children exist unless --recursive (cascades)\n\nEnvironment: OWENLOOP_DB, OWENLOOP_DEFS";
62
+ /**
63
+ * Single source of truth for the `--options` each command accepts, consulted by
64
+ * `preflight` before any side effect. Unknown-OPTION rejection AND
65
+ * unknown-COMMAND detection both derive from this table: a developer who adds a
66
+ * new `dispatch`/`ASYNC_COMMANDS` case without a matching entry here gets
67
+ * `unknown command` on the very first invocation, so the command cannot run
68
+ * until its flags are declared. That is the forcing function that stops the
69
+ * silently-dropped-flag hole (a misspelled `push --dryrn` doing a real push)
70
+ * from reappearing — keep this table in lockstep with the dispatch verbs and
71
+ * the USAGE string. All names are long-form: this CLI has no short options
72
+ * (`-h` reaches dispatch as a positional). Values are audited against every
73
+ * `last/all/flag/needOpt/numOpt` call site.
74
+ */
75
+ export declare const COMMAND_OPTIONS: ReadonlyMap<string, ReadonlySet<string>>;
76
+ /**
77
+ * Async entry point that adds network I/O for `add` and the hub commands on top
78
+ * of the otherwise fully-synchronous engine/CLI (see the doc comment on
79
+ * `sleepMs` above and README "sync end to end"). `main`/`dispatch` stay sync and
80
+ * unchanged — this wraps them, routing only the network-touching verbs through
81
+ * the async path, so every existing command and test keeps working exactly as
82
+ * before.
83
+ */
84
+ export declare const ASYNC_COMMANDS: Set<string>;
85
+ export declare function mainAsync(argv: string[], io?: CliIO): Promise<number>;
39
86
  /** Run the CLI. Returns a process exit code. */
40
87
  export declare function main(argv: string[], io?: CliIO): number;