@awebai/oats 0.69.12 → 0.69.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- package/lib/tmux-config.mjs +0 -35
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
/** lib/command-flags.mjs — the flags each state-changing kernel command defines (oats-project/oats#1791),
|
|
2
|
+
* and the one check of a command's argv against them, which the CLI's dispatch runs before the command
|
|
3
|
+
* runs and before a `--server` command is sent to its host: a flag the command does not define, a value
|
|
4
|
+
* on one of its switches, or an argument after its last one is refused with E_BAD_ARGS, never ignored, so
|
|
5
|
+
* a mistyped protective flag (`--keep-dirs` for `--keep-dir`) never does the unprotected thing. A command
|
|
6
|
+
* missing here is not checked. Kernel-private, not exported from `./core`. Dependency-free. */
|
|
7
|
+
|
|
8
|
+
export const RETIRE_DELETE_BRANCH_REFUSED = "oats retire no longer deletes branches: --delete-branch is not accepted. Retire without it; the branch is left in the repository. Inspect it there and delete it with Git if it is no longer wanted.";
|
|
9
|
+
export const RETIRE_USAGE = "usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--dir <d>] [--server <id>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]";
|
|
10
|
+
export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
|
|
11
|
+
export const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
|
|
12
|
+
export const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
|
|
13
|
+
export const TEAMS_USAGE = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
|
|
14
|
+
export const SOUL_LAUNCH_USAGE = "oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <deployment>] [--json] | oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <deployment>] [--json]";
|
|
15
|
+
export const HOST_RUN_USAGE = "usage: oats host run [--stop-grace <seconds>] [--plan] [--json]";
|
|
16
|
+
export const WORKTREE_USAGE = "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json] | oats worktree remove --purpose <p> [--json]";
|
|
17
|
+
|
|
18
|
+
const WORKTREE_REFUSED = Object.freeze({
|
|
19
|
+
"--server": "oats worktree runs in an instance home on this machine; --server is not accepted",
|
|
20
|
+
"--dir": `oats worktree has no --dir: it acts on the instance home it runs in; ${WORKTREE_USAGE}`,
|
|
21
|
+
"--home": `oats worktree has no --home: it acts on the instance home it runs in; ${WORKTREE_USAGE}`,
|
|
22
|
+
});
|
|
23
|
+
const launchConfigWrite = (sub) => {
|
|
24
|
+
const refused = `launch-config ${sub} writes the deployment's oats-local.yaml: address it with --dir, not --home or --soul`;
|
|
25
|
+
return { "--home": refused, "--soul": refused };
|
|
26
|
+
};
|
|
27
|
+
const SESSION_VALUES = Object.freeze(["--home", "--instance", "--launch-config", "--harness", "--runtime", "--model", "--server"]);
|
|
28
|
+
const SESSION_SWITCHES = Object.freeze(["--reselect-launch", "--yolo", "--no-yolo", "--json"]);
|
|
29
|
+
const SCHEDULE_VALUES = Object.freeze(["--dir", "--server"]);
|
|
30
|
+
const schedule = (verb, switches = []) => ({ command: `schedule ${verb}`, operands: ["id"], values: SCHEDULE_VALUES, switches: [...switches, "--json"],
|
|
31
|
+
usage: `usage: oats schedule ${verb} <id>${switches.map((s) => ` [${s}]`).join("")} [--dir <workspace> | --server <id>] [--json]` });
|
|
32
|
+
const trigger = (verb) => ({ command: `trigger ${verb}`, operands: ["id"], values: ["--dir"], switches: ["--json"], usage: `usage: oats trigger ${verb} <id> [--dir <deployment>] [--json]` });
|
|
33
|
+
const INSTANCE_RECORD_VALUES = Object.freeze(["--home", "--dir", "--server"]);
|
|
34
|
+
const onOff = (verb) => ({ command: `instance ${verb}`, operands: ["instance", "state"], values: INSTANCE_RECORD_VALUES, switches: ["--json"],
|
|
35
|
+
usage: `usage: oats instance ${verb} <instance> on|off [--home <abs>] [--dir <d> | --server <id>] [--json]` });
|
|
36
|
+
const WAITING_VALUES = Object.freeze(["--producer", "--reason", "--message", "--home", "--dir"]);
|
|
37
|
+
const waiting = (verb) => ({ command: `instance waiting ${verb}`, operands: [], values: WAITING_VALUES, switches: ["--json"],
|
|
38
|
+
usage: `usage: oats instance waiting ${verb} --producer <id>${verb === "set" ? " --reason permission|question|attention" : ""} [--message=<text>] [--home <abs>] [--dir <d>] [--json]` });
|
|
39
|
+
const ATTENTION_USAGE = "usage: oats instance attention [--message=<text>] [--clear] [--json]";
|
|
40
|
+
const attentionHasNo = (flag) => `oats instance attention has no ${flag}: it records the agent's own claim on the instance it runs in ($OATS_INSTANCE_HOME); ${ATTENTION_USAGE}`;
|
|
41
|
+
const TRIGGER_RUN_SOURCE = Object.freeze(["--run-source", "--json"]);
|
|
42
|
+
const SESSION_ADDRESS = Object.freeze(["--home", "--instance", "--server"]);
|
|
43
|
+
/** Every `oats session` form refuses the captured path's selector in these words (bin's sessionCmd says them
|
|
44
|
+
* for the forms not declared here). */
|
|
45
|
+
export const NATIVE_RECORD_REFUSED = "--native-record outcome inspection is gone (the captured/portable path was removed in 0.26)";
|
|
46
|
+
const NATIVE_RECORD_GONE = Object.freeze({ "--native-record": NATIVE_RECORD_REFUSED });
|
|
47
|
+
/** A resume is this machine's (#1559, D1): a server resumes its own instances. */
|
|
48
|
+
export const RESUME_LOCAL_ONLY = "session resume and session start --resume act on this machine's instances only; a server runs oats session resume itself";
|
|
49
|
+
const UPDATE_TAKES_NO_PACKAGE = "oats update takes no package: pin package versions in oats-workspace.yaml (`oats package add <id> <version>`), then `oats sync`; bare `oats update [--check] [--yes]` updates the kernel";
|
|
50
|
+
const SPAWN_REMOVED_SOUL = (flag) => `${flag} created a local soul under local-agents/, which the workspace model removed — author souls/<name>/soul.yaml + AGENTS.md in a member repository, then \`oats sync\``;
|
|
51
|
+
/** `oats teams` and `oats soul launch` answer a flag they do not take with E_USAGE in their own words
|
|
52
|
+
* (docs/desktop-cli-api.md "oats teams", "oats soul launch"). */
|
|
53
|
+
const teamsUnknown = (form) => (flag) => ({ code: "E_USAGE", message: `${form} does not take ${flag} (an option this kernel does not know may need a newer kernel; nothing was changed) — ${TEAMS_USAGE}`, details: { flag } });
|
|
54
|
+
/** An `oats teams` form takes these, beyond `--dir` and `--json`; anything else is refused, never ignored:
|
|
55
|
+
* a kernel that ignored `--if-absent` would set unconditionally. */
|
|
56
|
+
const teams = (verb, values, switches) => ({ command: `teams ${verb}`, operands: ["label"], values: ["--dir", ...values], switches: [...switches, "--json"], unknown: teamsUnknown(`oats teams ${verb}`),
|
|
57
|
+
usage: `usage: oats teams ${verb} <label>${[...values.map((v) => ` [${v} <${v.slice(2)}>]`), ...switches.map((s) => ` [${s}]`)].join("")} [--dir <deployment>] [--json]` });
|
|
58
|
+
/** An `oats soul launch` form takes these; anything else is refused, never ignored: `--home` and `--soul`
|
|
59
|
+
* among them, since the soul is the argument and the file the deployment's. */
|
|
60
|
+
const soulLaunch = (verb, values) => ({ command: `soul launch ${verb}`, operands: [verb === "set" ? "soul" : "soul or key"], values: ["--dir", ...values], switches: ["--plan", "--json"],
|
|
61
|
+
unknown: (flag) => ({ code: "E_USAGE", message: `oats soul launch ${verb} does not take ${flag} (nothing was changed) — usage: ${SOUL_LAUNCH_USAGE}`, details: { flag } }),
|
|
62
|
+
// Every name it was given, in its own words: `remove dev writer` would remove dev alone.
|
|
63
|
+
extra: (args) => ({ code: "E_BAD_ARGS", message: `oats soul launch ${verb} takes one ${verb === "set" ? "soul" : "soul or key"}, and got ${args.length}: ${args.map((n) => JSON.stringify(n)).join(", ")} (nothing was changed) — usage: ${SOUL_LAUNCH_USAGE}` }),
|
|
64
|
+
usage: verb === "set" ? "usage: oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <deployment>] [--json]" : "usage: oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <deployment>] [--json]" });
|
|
65
|
+
|
|
66
|
+
/** Each command's argv, frozen to its arrays: `command` its words; `operands` the names of the arguments
|
|
67
|
+
* it takes after them, in order (one more is refused); `required` how many of them it needs (all, unless
|
|
68
|
+
* it says: a missing one is the command's own refusal, and E_USAGE here when `--server` is given);
|
|
69
|
+
* `values` the flags that take a value, `arity` those that take more than one word (`{ flag: words }`);
|
|
70
|
+
* `switches` the flags that take none; `refused` the flags it refuses with their own message; `usage`
|
|
71
|
+
* the line every shared refusal ends with. A row answers in its own words with `unknown(flag)` for a flag
|
|
72
|
+
* it does not define and `extra(args)` for an argument after its last (`args`: every argument it was
|
|
73
|
+
* given), each → { code, message, details? }. `--json` is a switch of every one. A value flag given no
|
|
74
|
+
* value is that flag's own refusal, by the command. */
|
|
75
|
+
export const COMMAND_FLAGS = Object.freeze([
|
|
76
|
+
{ command: "retire", operands: ["instance"], values: ["--plan-revision", "--idempotency-key", "--home", "--dir", "--server"], switches: ["--plan", "--self", "--discard-worktree", "--keep-dir", "--force", "--json"],
|
|
77
|
+
refused: { "--delete-branch": RETIRE_DELETE_BRANCH_REFUSED }, usage: RETIRE_USAGE },
|
|
78
|
+
// `--instance` is refused by a local spawn (with its replacement) but still travels to an older host
|
|
79
|
+
// through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an apply bound
|
|
80
|
+
// by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. `--herdr-socket`
|
|
81
|
+
// and `--backend herdr` are read to be refused (E_HERDR_REMOVED), here and on the route.
|
|
82
|
+
{ command: "spawn", operands: ["soul"],
|
|
83
|
+
values: ["--agents-root", "--backend", "--base", "--branch", "--dir", "--expect-decision", "--harness", "--herdr-socket", "--idempotency-key", "--instance", "--launch-config", "--max-age", "--model", "--name", "--parent", "--provider", "--purpose", "--relation", "--relative-root", "--relative-to", "--repo", "--runtime", "--server", "--task", "--task-file", "--trigger-event", "--wake-cron", "--wake-every", "--wake-file", "--wake-json", "--wake-message", "--wake-message-file", "--wake-tz", "--work", "--work-dir"],
|
|
84
|
+
arity: { "--provider": 2 },
|
|
85
|
+
switches: ["--allow-child-spawns", "--background", "--json", "--no-background", "--no-child-spawns", "--no-launch", "--no-yolo", "--preview", "--same-work", "--suggest-name", "--yolo"],
|
|
86
|
+
// Local souls (local-agents/) are gone with the workspace model: a soul is a member
|
|
87
|
+
// repository's souls/<name>, so spawn never writes one.
|
|
88
|
+
refused: { "--instructions-file": SPAWN_REMOVED_SOUL("--instructions-file"), "--def-file": SPAWN_REMOVED_SOUL("--def-file"),
|
|
89
|
+
"--ephemeral": "--ephemeral was removed by the runtime-boundary ruling — declare the agent in a capability manifest (agents:) for automatic ephemeral semantics" },
|
|
90
|
+
unknown: (flag) => ({ code: "E_BAD_ARGS", message: `oats spawn: unknown flag ${flag}` }),
|
|
91
|
+
extra: ([soul, a]) => ({ code: "E_BAD_ARGS", message: /^[A-Za-z0-9_.-]+=/.test(a)
|
|
92
|
+
? `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: a capability setting is given as --provider <capability> key=value (here: --provider <capability> ${a})`
|
|
93
|
+
: `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: spawn takes one soul` }),
|
|
94
|
+
usage: SPAWN_USAGE },
|
|
95
|
+
// An unknown flag or an argument of sync is refused before anything is read or written (#731).
|
|
96
|
+
{ command: "sync", operands: [], values: ["--dir"], switches: ["--plan", "--json"], refused: { "--approve": `--approve: ${APPROVAL_REMOVED}` }, usage: SYNC_USAGE },
|
|
97
|
+
{ command: "instance stop", operands: ["instance"], values: ["--plan-revision", "--idempotency-key", "--grace-ms", "--home", "--dir", "--server"], switches: ["--plan", "--apply", "--no-recursive", "--json"],
|
|
98
|
+
usage: "usage: oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d> | --server <id>] [--json]" },
|
|
99
|
+
{ command: "instance upgrade", operands: ["instance"], values: ["--plan-revision", "--idempotency-key", "--home", "--dir"], switches: ["--undo", "--plan", "--json"],
|
|
100
|
+
refused: { "--server": "instance upgrade supports local homes only; run it on the deployment host" },
|
|
101
|
+
usage: "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]" },
|
|
102
|
+
{ command: "instance color", operands: ["instance", "color"], required: 1, values: INSTANCE_RECORD_VALUES, switches: ["--clear", "--json"],
|
|
103
|
+
usage: "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d> | --server <id>] [--json]" },
|
|
104
|
+
onOff("background"),
|
|
105
|
+
onOff("same-work"),
|
|
106
|
+
waiting("set"),
|
|
107
|
+
waiting("clear"),
|
|
108
|
+
{ command: "instance attention", operands: [], values: ["--message"], switches: ["--clear", "--json"],
|
|
109
|
+
refused: Object.fromEntries(["--home", "--dir", "--producer", "--reason"].map((f) => [f, attentionHasNo(f)])), usage: ATTENTION_USAGE },
|
|
110
|
+
{ command: "instance suggest-name", operands: [], values: ["--soul", "--task", "--task-file", "--harness", "--model", "--launch-config", "--dir"], switches: ["--json"],
|
|
111
|
+
refused: { "--server": "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)" },
|
|
112
|
+
usage: "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]" },
|
|
113
|
+
{ command: "worktree add", operands: [], values: ["--purpose", "--branch", "--base", "--repo"], switches: ["--preview", "--json"], refused: WORKTREE_REFUSED,
|
|
114
|
+
usage: "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json]" },
|
|
115
|
+
{ command: "worktree remove", operands: [], values: ["--purpose"], switches: ["--json"], refused: WORKTREE_REFUSED,
|
|
116
|
+
usage: "usage: oats worktree remove --purpose <p> [--json]" },
|
|
117
|
+
{ command: "session start", operands: [], refused: NATIVE_RECORD_GONE, values: SESSION_VALUES, switches: [...SESSION_SWITCHES, "--resume"],
|
|
118
|
+
usage: "usage: oats session start (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--launch-config <name>|none | --reselect-launch] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--resume] [--json]" },
|
|
119
|
+
{ command: "session restart", operands: [], values: [...SESSION_VALUES, "--stop-grace"], switches: SESSION_SWITCHES,
|
|
120
|
+
refused: { ...NATIVE_RECORD_GONE, "--resume": "--resume exists on session start only: it brings back a session that was lost" },
|
|
121
|
+
usage: "usage: oats session restart (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--launch-config <name>|none | --reselect-launch] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--stop-grace <seconds>] [--json]" },
|
|
122
|
+
{ command: "session resume", operands: [], values: ["--deployment"],
|
|
123
|
+
refused: { ...NATIVE_RECORD_GONE, "--server": RESUME_LOCAL_ONLY }, switches: ["--plan", "--json"], usage: "usage: oats session resume [--deployment <dir>] [--plan] [--json]" },
|
|
124
|
+
{ command: "session input", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--text-file"], switches: ["--json"], usage: "usage: oats session input --home <abs> [--text-file <path>] [--json]" },
|
|
125
|
+
{ command: "session receive", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--name"], switches: ["--json"], usage: "usage: oats session receive --home <abs> --name <file name> [--json]" },
|
|
126
|
+
{ command: "session upload", operands: [], refused: NATIVE_RECORD_GONE, values: ["--file", ...SESSION_ADDRESS], switches: ["--json"],
|
|
127
|
+
usage: "usage: oats session upload --file <path> (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--json]" },
|
|
128
|
+
{ command: "session attach", operands: [], refused: NATIVE_RECORD_GONE, values: ["--detach-key", ...SESSION_ADDRESS], switches: ["--no-status-line", "--print", "--json"],
|
|
129
|
+
usage: "usage: oats session attach (--home <abs> | --server <id> (--instance <name> | --home <abs>) [--print]) [--detach-key <key>] [--no-status-line]" },
|
|
130
|
+
{ command: "schedule add", operands: ["id"], required: 0, values: ["--file", "--spec-json", "--description", "--workspace", "--runs-on", "--owner", ...SCHEDULE_VALUES], switches: ["--json"],
|
|
131
|
+
usage: "usage: oats schedule add [<id>] (--file <spec.json> | --spec-json <json>) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] [--dir <workspace> | --server <id>] [--json]" },
|
|
132
|
+
{ command: "schedule update", operands: ["id"], values: ["--file", "--spec-json", "--description", ...SCHEDULE_VALUES], switches: ["--json"],
|
|
133
|
+
usage: "usage: oats schedule update <id> (--file <spec.json> | --spec-json <json> [--description=<text>] | --description=<text>) [--dir <workspace> | --server <id>] [--json]" },
|
|
134
|
+
schedule("remove", ["--force"]),
|
|
135
|
+
schedule("run", ["--force"]),
|
|
136
|
+
schedule("enable"),
|
|
137
|
+
schedule("disable"),
|
|
138
|
+
schedule("reconcile", ["--clear"]),
|
|
139
|
+
{ command: "schedule tick", operands: [], values: SCHEDULE_VALUES, switches: ["--dry-run", "--host", "--json"], usage: "usage: oats schedule tick [--dry-run] [--host] [--dir <workspace> | --server <id>] [--json]" },
|
|
140
|
+
{ command: "schedule host install", operands: [], values: ["--max-concurrent", "--triggers-max-concurrent", "--os", ...SCHEDULE_VALUES], switches: ["--register-only", "--print", "--json"],
|
|
141
|
+
usage: "usage: oats schedule host install [--register-only] [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>] | --print [--os darwin|linux] [--dir <workspace> | --server <id>] [--json]" },
|
|
142
|
+
{ command: "schedule host uninstall", operands: [], values: SCHEDULE_VALUES, switches: ["--json"], usage: "usage: oats schedule host uninstall [--dir <workspace> | --server <id>] [--json]" },
|
|
143
|
+
{ command: "host run", operands: [], values: ["--stop-grace"], switches: ["--plan", "--json"], usage: HOST_RUN_USAGE },
|
|
144
|
+
{ command: "trigger add", operands: [], values: ["--file", "--from", "--set", "--id", "--description", "--workspace", "--runs-on", "--owner", "--dir"], switches: ["--json"],
|
|
145
|
+
usage: "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] [--dir <deployment>] [--json]" },
|
|
146
|
+
{ command: "trigger poll", operands: ["id"], values: ["--dir", "--max-age"], switches: TRIGGER_RUN_SOURCE, usage: "usage: oats trigger poll <id> --run-source [--max-age <s>] [--dir <deployment>] [--json]" },
|
|
147
|
+
{ command: "trigger test", operands: ["id"], values: ["--dir"], switches: TRIGGER_RUN_SOURCE, usage: "usage: oats trigger test <id> [--run-source] [--dir <deployment>] [--json]" },
|
|
148
|
+
trigger("remove"),
|
|
149
|
+
trigger("enable"),
|
|
150
|
+
trigger("disable"),
|
|
151
|
+
{ command: "teams", operands: [], values: ["--dir", "--max-age"], switches: ["--json"], unknown: teamsUnknown("oats teams"),
|
|
152
|
+
// A word where a form belongs: the forms' usage, as before.
|
|
153
|
+
extra: () => ({ code: "E_USAGE", message: TEAMS_USAGE }), usage: "usage: oats teams [--max-age <s>] [--dir <deployment>] [--json]" },
|
|
154
|
+
teams("add", ["--team", "--description"], ["--no-default"]),
|
|
155
|
+
teams("remove", [], []),
|
|
156
|
+
teams("default", ["--expect"], ["--if-absent"]),
|
|
157
|
+
soulLaunch("set", ["--launch-config", "--harness", "--model"]),
|
|
158
|
+
soulLaunch("remove", []),
|
|
159
|
+
{ command: "server check", operands: ["id"], values: [], switches: ["--json"], usage: "usage: oats server check <id> [--json]" },
|
|
160
|
+
{ command: "server remove", operands: ["id"], values: [], switches: ["--json"], usage: "usage: oats server remove <id> [--json]" },
|
|
161
|
+
{ command: "server forget", operands: ["id"], values: ["--instance"], switches: ["--json"], usage: "usage: oats server forget <id> --instance <name> [--json]" },
|
|
162
|
+
{ command: "package add", operands: ["id", "version"], values: ["--dir"], switches: ["--json"], usage: "usage: oats package add <id> <version|git:<repo>@<ref>> [--dir <d>] [--json]" },
|
|
163
|
+
{ command: "package remove", operands: ["id"], values: ["--dir"], switches: ["--json"], usage: "usage: oats package remove <id> [--dir <d>] [--json]" },
|
|
164
|
+
{ command: "launch-config set", operands: ["name"], values: ["--file", "--dir", "--server"], switches: ["--keep-env", "--json"], refused: launchConfigWrite("set"),
|
|
165
|
+
usage: "usage: oats launch-config set <name> --file <json> [--keep-env] [--dir <scope> | --server <id>] [--json]" },
|
|
166
|
+
{ command: "launch-config remove", operands: ["name"], values: ["--dir", "--server"], switches: ["--json"], refused: launchConfigWrite("remove"),
|
|
167
|
+
usage: "usage: oats launch-config remove <name> [--dir <scope> | --server <id>] [--json]" },
|
|
168
|
+
{ command: "automations refresh", operands: [], values: ["--dir"], switches: ["--json"], usage: "usage: oats automations refresh [--dir <deployment>] [--json]" },
|
|
169
|
+
// `oats update <package>` left with the installed tier (packages are pinned in the workspace file:
|
|
170
|
+
// `oats package add`); only the kernel self-update remains, and a package word is answered with that.
|
|
171
|
+
{ command: "update", operands: [], values: ["--dir"], switches: ["--check", "--yes", "--json"], refused: { "--to": UPDATE_TAKES_NO_PACKAGE },
|
|
172
|
+
extra: ([a]) => ({ code: "E_BAD_ARGS", message: UPDATE_TAKES_NO_PACKAGE, details: { argument: a } }), usage: "usage: oats update [--check] [--yes] [--dir <deployment>]" },
|
|
173
|
+
].map((c) => Object.freeze({ ...c, operands: Object.freeze([...c.operands]), required: c.required ?? c.operands.length, values: Object.freeze([...c.values]), switches: Object.freeze([...c.switches]),
|
|
174
|
+
arity: Object.freeze({ ...c.arity }), ...(c.refused ? { refused: Object.freeze({ ...c.refused }) } : {}) })));
|
|
175
|
+
|
|
176
|
+
/** The declaration of the command `argv` (the CLI's argv, after `oats`) runs: the one whose words its
|
|
177
|
+
* first words are, the longest of them; undefined for a command not declared here. */
|
|
178
|
+
export function commandFlags(argv) {
|
|
179
|
+
let found;
|
|
180
|
+
for (const c of COMMAND_FLAGS) {
|
|
181
|
+
const words = c.command.split(" ");
|
|
182
|
+
if (words.every((w, i) => argv[i] === w) && (!found || words.length > found.command.split(" ").length)) found = c;
|
|
183
|
+
}
|
|
184
|
+
return found;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** Why `argv` (the CLI's argv, after `oats`, as typed: `--flag=value` unexpanded) is not a command its
|
|
188
|
+
* declaration allows, as { code, message, details? }, or undefined (allowed, or not declared). The first
|
|
189
|
+
* problem from the left, E_BAD_ARGS unless the row answers in its own words: a refused flag (its own
|
|
190
|
+
* message), a flag the command does not define (`oats <command>: unknown flag <flag>`, or the row's
|
|
191
|
+
* `unknown`), a switch given a value with `=`, or an argument after its last (or the row's `extra`, given
|
|
192
|
+
* every argument); each shared one ends with the command's usage. A value flag with no value (none, or a word that starts with `--`) ends the
|
|
193
|
+
* check there with undefined: the command refuses it in its own words. Then, for a command given `--server`,
|
|
194
|
+
* a missing argument it requires: E_USAGE with the usage line, so that it is never sent (on this machine
|
|
195
|
+
* each command answers a missing argument itself). A value flag takes the next word (its `arity` words)
|
|
196
|
+
* as its value unless it starts with `--`, as the CLI's flag reader does (lib/argv.mjs flagValue); a value
|
|
197
|
+
* after `=` is its first. `--` is a flag like any other. */
|
|
198
|
+
export function commandArgvProblem(argv) {
|
|
199
|
+
const c = commandFlags(argv);
|
|
200
|
+
if (!c) return undefined;
|
|
201
|
+
const given = [];
|
|
202
|
+
let extra = null, routed = false;
|
|
203
|
+
for (let i = c.command.split(" ").length; i < argv.length; i++) {
|
|
204
|
+
const a = argv[i];
|
|
205
|
+
if (!a.startsWith("-")) {
|
|
206
|
+
if (given.length === c.operands.length && extra === null) extra = a;
|
|
207
|
+
given.push(a);
|
|
208
|
+
continue;
|
|
209
|
+
}
|
|
210
|
+
const eq = a.startsWith("--") ? a.indexOf("=") : -1;
|
|
211
|
+
const flag = eq > 2 ? a.slice(0, eq) : a;
|
|
212
|
+
// After an argument too many, the rest is read only for the arguments it holds.
|
|
213
|
+
if (extra === null) {
|
|
214
|
+
if (c.refused && Object.hasOwn(c.refused, flag)) return { code: "E_BAD_ARGS", message: c.refused[flag], details: { flag } };
|
|
215
|
+
if (c.switches.includes(flag)) {
|
|
216
|
+
if (flag !== a) return { code: "E_BAD_ARGS", message: `oats ${c.command}: ${flag} takes no value (got ${a})\n${c.usage}`, details: { flag } };
|
|
217
|
+
continue;
|
|
218
|
+
}
|
|
219
|
+
if (!c.values.includes(flag)) return c.unknown ? c.unknown(flag) : { code: "E_BAD_ARGS", message: `oats ${c.command}: unknown flag ${flag}\n${c.usage}`, details: { flag } };
|
|
220
|
+
if (flag === "--server") routed = true;
|
|
221
|
+
} else if (!c.values.includes(flag)) continue;
|
|
222
|
+
for (let words = (c.arity[flag] ?? 1) - (flag === a ? 0 : 1); words > 0; words--) {
|
|
223
|
+
// A value missing is a problem at this flag, the command's own: the check ends here, and the
|
|
224
|
+
// command answers it ("--dir needs a value"), never a flag further on.
|
|
225
|
+
// Its limit: a command that reads such a flag as absent on some path (instance stop --plan and
|
|
226
|
+
// --grace-ms) lets a later unknown flag pass on that path unrefused.
|
|
227
|
+
if (argv[i + 1] === undefined || argv[i + 1].startsWith("--")) { if (extra === null) return undefined; break; }
|
|
228
|
+
i++;
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
if (extra !== null) return c.extra ? c.extra(given) : { code: "E_BAD_ARGS", message: extraArgument(c, extra, given), details: { argument: extra } };
|
|
232
|
+
if (routed && given.length < c.required) return { code: "E_USAGE", message: c.usage };
|
|
233
|
+
return undefined;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
function extraArgument(c, a, given) {
|
|
237
|
+
if (!c.operands.length) return `oats ${c.command}: unexpected argument ${JSON.stringify(a)}: ${c.command} takes no argument\n${c.usage}`;
|
|
238
|
+
const last = c.operands.length - 1;
|
|
239
|
+
return `oats ${c.command}: unexpected argument ${JSON.stringify(a)} after the ${c.operands[last]} ${JSON.stringify(given[last])}: ${c.command} takes ${c.operands.map((n) => `one ${n}`).join(" and ")}\n${c.usage}`;
|
|
240
|
+
}
|