moshcode 0.24.0

package/src/cli-schema.mjs

@@ -0,0 +1,533 @@
+// The command table, and everything help needs to describe it.
+//
+// One table, three consumers: the dispatcher in bin/moshcode.mjs, shell
+// completion (src/completion.mjs), and help (src/help.mjs). Help used to be an
+// 87-line template literal that re-typed all of this by hand, which is why
+// `dns` and `version` were dispatchable, completable, and absent from `moshcode
+// help` at the same time (PRD 0006).
+//
+// `description` stays the one-line summary completion already renders. The rest
+// — synopsis, flags, examples — exists so per-command help can be rendered
+// rather than written. A flag that is parsed but not listed here is a flag
+// nobody can discover, so test/help.test.mjs greps the parsers and fails when
+// the two disagree.
+
+/**
+ * Groups for the one-screen overview.
+ *
+ * The top-level help is a menu, not an index: 30-odd verbs in one flat list is
+ * the wall this replaces. Order is the order they appear.
+ */
+export const COMMAND_GROUPS = [
+  { key: "engines", title: "engines" },
+  { key: "tools", title: "tools" },
+  { key: "extend", title: "extend" },
+  { key: "script", title: "script" },
+  { key: "account", title: "account" },
+  { key: "hosting", title: "hosting" },
+  { key: "system", title: "system" },
+];
+
+export const CORE_CLI_COMMANDS = [
+  {
+    name: "agents",
+    group: "engines",
+    description: "list engines or launch one autonomously",
+    synopsis: [
+      ["moshcode agents", "list engines and their install status"],
+      ["moshcode agents --json", "list engine status as machine-readable JSON"],
+      ["moshcode agents <engine> [args…]", "open the engine's agent view, or start it autonomously"],
+    ],
+    flags: [
+      ["--json", "print engine status as JSON", ""],
+    ],
+    examples: [
+      ["moshcode agents", "which engines are here"],
+      ["moshcode agents --json", "pipe engine status into a script"],
+      ["moshcode agents claude", "claude's agent list"],
+    ],
+    seeAlso: ["start", "engines", "install"],
+    note: "autonomous modes bypass approval prompts — use them in a container or a workspace you trust.",
+  },
+  {
+    name: "start",
+    group: "engines",
+    description: "launch an engine with its native defaults",
+    synopsis: [["moshcode start <engine> [args…]", "no bypass flags, no agent view"]],
+    examples: [["moshcode start opencode", ""]],
+    seeAlso: ["agents", "engines"],
+  },
+  {
+    name: "install",
+    group: "engines",
+    description: "install an engine or workflow tool",
+    synopsis: [["moshcode install <engine|tool>", ""]],
+    examples: [
+      ["moshcode install claude", "an engine"],
+      ["moshcode install gh", "a workflow tool"],
+    ],
+    seeAlso: ["uninstall", "upgrade", "engines", "tools"],
+  },
+  {
+    name: "uninstall",
+    group: "engines",
+    description: "take an engine or workflow tool off this machine",
+    synopsis: [["moshcode uninstall <engine|tool> [--yes] [--dry-run]", ""]],
+    flags: [
+      ["-y, --yes", "actually delete a binary this did not install", ""],
+      ["--dry-run", "print the plan and stop", ""],
+    ],
+    examples: [
+      ["moshcode uninstall codex --dry-run", "what would happen"],
+      ["moshcode uninstall codex --yes", "do it"],
+    ],
+    seeAlso: ["install"],
+    note: "removing a plain binary needs --yes; a package-manager uninstall does not.",
+  },
+  { name: "remove", aliasOf: "uninstall", description: "alias for uninstall" },
+  {
+    name: "upgrade",
+    group: "engines",
+    description: "update moshcode, engines, or tools",
+    synopsis: [
+      ["moshcode upgrade [target…]", "default: everything installed"],
+      ["moshcode upgrade --check", "report what is stale and exit"],
+    ],
+    flags: [
+      ["--check", "report available updates without installing", ""],
+      ["--if-newer", "install only when the remote is newer", ""],
+      ["--timer <interval>", "install a scheduled self-update", ""],
+    ],
+    verbs: "UPGRADE_TARGETS",
+    examples: [
+      ["moshcode upgrade", "moshcode + engines + tools"],
+      ["moshcode upgrade engines", "just the engines"],
+    ],
+    seeAlso: ["install", "version"],
+  },
+  { name: "update", aliasOf: "upgrade", description: "alias for upgrade" },
+  {
+    name: "mcp",
+    group: "extend",
+    description: "register and inspect MCP servers",
+    synopsis: [["moshcode mcp <verb> [args…]", ""]],
+    verbs: "MCP_VERBS",
+    examples: [
+      ["moshcode mcp list --json", "support and install status"],
+      ["moshcode mcp install https://mcp.example.com", "a remote server"],
+    ],
+    seeAlso: ["skill", "engines"],
+  },
+  {
+    name: "skill",
+    group: "extend",
+    description: "install and inspect agent skills",
+    synopsis: [["moshcode skill <verb> [args…]", ""]],
+    verbs: "SKILL_VERBS",
+    examples: [["moshcode skill list", ""]],
+    seeAlso: ["mcp"],
+  },
+  { name: "skills", aliasOf: "skill", description: "alias for skill" },
+  {
+    name: "prd",
+    group: "script",
+    description: "publish or list product requirement documents",
+    synopsis: [
+      ["moshcode prd", "list the PRDs in this repo"],
+      ["moshcode prd list [--json]", "the same, explicitly"],
+      ["moshcode prd <idea…>", "publish prd/NNNN-slug.md (Draft) and hand it to an engine"],
+    ],
+    flags: [["--json", "machine-readable listing", ""]],
+    examples: [
+      ["moshcode prd", "the index"],
+      ['moshcode prd "a --help that works"', "publish + author"],
+    ],
+    seeAlso: ["run", "commands"],
+    note: "publishing writes a file and commits it. `moshcode prd --help` does neither.",
+  },
+  {
+    name: "login",
+    group: "account",
+    description: "authenticate with app.moshcode.sh",
+    synopsis: [["moshcode login [--device] [--browser]", ""]],
+    flags: [
+      ["-d, --device", "device-code flow", "default when stdin is not a TTY"],
+      ["-b, --browser", "force the browser flow", ""],
+    ],
+    examples: [["moshcode login --device", "on a headless box"]],
+    seeAlso: ["whoami", "logout", "console"],
+  },
+  {
+    name: "whoami",
+    group: "account",
+    description: "show the logged-in account",
+    synopsis: [["moshcode whoami", ""]],
+    seeAlso: ["login", "logout"],
+  },
+  {
+    name: "logout",
+    group: "account",
+    description: "clear the logged-in account",
+    synopsis: [["moshcode logout", ""]],
+    seeAlso: ["login"],
+  },
+  {
+    name: "console",
+    group: "account",
+    description: "serve or connect to the browser terminal",
+    synopsis: [["moshcode console [--port N] [--bind addr] [--ttyd host:port] [--url u]", ""]],
+    flags: [
+      ["--port <n>", "port to serve on", ""],
+      ["--bind <addr>", "interface to bind", ""],
+      ["--ttyd <host:port>", "front an existing ttyd", ""],
+      ["--url <url>", "connect to a console already running", ""],
+    ],
+    examples: [["moshcode console --port 7681", ""]],
+    seeAlso: ["login"],
+  },
+  {
+    name: "dns",
+    group: "hosting",
+    description: "resolve Moshpit names on this machine",
+    synopsis: [["moshcode dns <verb> [args…]", ""]],
+    verbs: "DNS_VERBS",
+    flags: [
+      ["--port <n>", "port for the bridge", "5354"],
+      ["--registry <url>", "registry to resolve against", "https://pit.moshcode.sh"],
+      ["--no-trust", "with enable: route names but skip the local CA", ""],
+    ],
+    examples: [
+      ["sudo moshcode dns enable", "route Moshpit endings here"],
+      ["moshcode dns resolve blue.eggs", "what a machine actually gets"],
+    ],
+    seeAlso: ["doh", "site"],
+  },
+  {
+    name: "doh",
+    group: "hosting",
+    description: "run the DNS-over-HTTPS resolver",
+    synopsis: [
+      ["moshcode doh [--port N]", "serve DoH"],
+      ["moshcode doh --nginx <name> [--tls]", "print an nginx site and exit"],
+    ],
+    flags: [
+      ["--port <n>", "port to listen on", ""],
+      ["--nginx <name>", "emit an nginx server block instead of serving", ""],
+      ["--tls", "include TLS directives in the emitted block", ""],
+      ["--no-guards", "disable rate limiting and bans", "guards on"],
+    ],
+    examples: [["moshcode doh --nginx dns.example", ""]],
+    seeAlso: ["dns"],
+    note: "has no TLS of its own and trusts X-Forwarded-For — never expose it directly.",
+  },
+  {
+    name: "site",
+    group: "hosting",
+    description: "install web-server config for a Moshpit name",
+    synopsis: [["moshcode site <name> [args…]", ""]],
+    examples: [["moshcode site blue.eggs", ""]],
+    seeAlso: ["template", "dns"],
+  },
+  { name: "serve", aliasOf: "site", description: "alias for site" },
+  {
+    name: "template",
+    group: "hosting",
+    description: "scaffold a stack for a Moshpit-hosted service",
+    synopsis: [
+      ["moshcode template list [--json]", "what there is"],
+      ["moshcode template install <name>", "write it here"],
+    ],
+    flags: [
+      ["--into <dir>", "write somewhere other than the current directory", ""],
+      ["--force", "overwrite files that are already there", ""],
+      ["--dry-run", "show changes without writing anything", ""],
+      ["--json", "machine-readable template list", ""],
+    ],
+    examples: [["moshcode template install bun-caddy-sqlite", ""]],
+    seeAlso: ["site"],
+  },
+  { name: "templates", aliasOf: "template", description: "alias for template" },
+  {
+    name: "pwd",
+    group: "system",
+    description: "show the current directory and git context",
+    synopsis: [["moshcode pwd [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]],
+    seeAlso: ["commands"],
+  },
+  { name: "where", aliasOf: "pwd", description: "alias for pwd" },
+  {
+    name: "engines",
+    group: "engines",
+    description: "list engines and installation status",
+    synopsis: [["moshcode engines [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]],
+    seeAlso: ["agents", "install"],
+  },
+  {
+    name: "tools",
+    group: "tools",
+    description: "list workflow tools and installation status",
+    synopsis: [["moshcode tools [--json]", ""]],
+    flags: [["--json", "machine-readable, and suppresses the trailing note", ""]],
+    seeAlso: ["install"],
+  },
+  {
+    name: "trade",
+    group: "tools",
+    description: "look up markets and trade through Alpaca",
+    synopsis: [["moshcode trade <verb> [args…]", "paper trading is Alpaca's default"]],
+    verbs: "TRADE_VERBS",
+    examples: [
+      ["moshcode trade ticker AAPL", "asset lookup"],
+      ["moshcode trade analysis AAPL", "quote/trade/bar snapshot"],
+      ["moshcode trade buy AAPL 1", "preview a market order"],
+      ["moshcode trade buy AAPL 1 --submit", "place it"],
+    ],
+    seeAlso: ["tools", "install"],
+    note: "buy/sell inject --dry-run unless --submit is present. Alpaca defaults to paper trading; live trading requires its separate --live opt-in.",
+  },
+  {
+    name: "commands",
+    group: "script",
+    description: "list built-in moshscript commands",
+    synopsis: [["moshcode commands [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]],
+    seeAlso: ["run", "prd"],
+  },
+  {
+    name: "completion",
+    group: "extend",
+    description: "print a shell completion script",
+    synopsis: [["moshcode completion <bash|zsh|fish|powershell>", ""]],
+    examples: [["moshcode completion zsh > ~/.moshcode-completion.zsh", ""]],
+    seeAlso: ["help"],
+  },
+  {
+    name: "run",
+    group: "script",
+    description: "run a moshscript",
+    synopsis: [
+      ["moshcode run [flags] [file] [args…]", "no file → the bundled example"],
+      ["moshcode run -", "read the script from stdin"],
+    ],
+    flags: [
+      ["-n, --max <n>", "loop ceiling", "3"],
+      ["--dry-run", "parse and report without side effects", ""],
+      ["--", "everything after this reaches the script as argv", ""],
+    ],
+    examples: [
+      ["moshcode run deploy.mosh", ""],
+      ["moshcode run deploy.mosh -- --verbose", "--verbose goes to the script"],
+    ],
+    seeAlso: ["commands", "prd"],
+    note: "--help before the file is the runner's; after it, it belongs to the script.",
+  },
+  {
+    name: "help",
+    group: "system",
+    description: "show command help",
+    synopsis: [
+      ["moshcode help", "the one-screen overview"],
+      ["moshcode help <command> [verb]", "drill into one"],
+      ["moshcode help --all", "every command, in full"],
+      ["moshcode help --json", "the machine-readable model"],
+    ],
+    flags: [
+      ["--all", "render every command instead of the overview", ""],
+      ["--json", "emit the help model as JSON", ""],
+      ["--markdown", "emit the command table for README.md", ""],
+    ],
+    examples: [
+      ["moshcode help mcp install", "a sub-verb"],
+      ["moshcode help --json | jq '.commands[].name'", "for an agent"],
+    ],
+    seeAlso: ["commands", "completion"],
+  },
+  { name: "--help", aliasOf: "help", description: "show command help" },
+  { name: "-h", aliasOf: "help", description: "show command help" },
+  {
+    name: "version",
+    group: "system",
+    description: "show the installed version",
+    synopsis: [["moshcode version", ""]],
+    seeAlso: ["upgrade"],
+  },
+  { name: "--version", aliasOf: "version", description: "show the installed version" },
+  { name: "-v", aliasOf: "version", description: "show the installed version" },
+];
+
+export const CORE_CLI_COMMAND_NAMES = CORE_CLI_COMMANDS.map(({ name }) => name);
+
+export const MCP_VERBS = [
+  {
+    name: "install",
+    description: "register an MCP server across engines",
+    acceptsServerSpec: true,
+    synopsis: [
+      ["moshcode mcp install <url>", "remote server (http/sse)"],
+      ["moshcode mcp install --name <n> -- <cmd…>", "local stdio server"],
+      ["moshcode mcp install <catalog-name>", "e.g. porkbun, sentry"],
+    ],
+    flags: [
+      ["--name <n>", "override the derived server name", ""],
+      ["-t, --transport <t>", "http | sse | stdio", "inferred from the target"],
+      ["-e, --env K=V", "repeatable", ""],
+      ["-H, --header 'K: V'", "repeatable", ""],
+      ["--", "everything after this is the server's argv", ""],
+    ],
+  },
+  {
+    name: "add",
+    description: "register a named MCP server",
+    acceptsServerSpec: true,
+    synopsis: [["moshcode mcp add --name <n> <target>", ""]],
+  },
+  { name: "catalog", description: "show known MCP servers", synopsis: [["moshcode mcp catalog", ""]] },
+  {
+    name: "list",
+    description: "show MCP support and install status",
+    synopsis: [["moshcode mcp list [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]],
+  },
+];
+
+export const SKILL_VERBS = [
+  {
+    name: "install",
+    description: "install a skill across supported engines",
+    acceptsSource: true,
+    synopsis: [["moshcode skill install <source>", ""]],
+  },
+  {
+    name: "list",
+    description: "show skills support and install status",
+    synopsis: [["moshcode skill list [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]],
+  },
+];
+
+export const UPGRADE_TARGETS = [
+  { name: "all", description: "update moshcode and all installed integrations" },
+  { name: "self", description: "update moshcode itself" },
+  { name: "moshcode", description: "alias for self" },
+  { name: "engines", description: "update all installed engines" },
+  { name: "tools", description: "update all installed workflow tools" },
+];
+
+export const TRADE_VERBS = [
+  { name: "ticker", description: "look up an asset by ticker", synopsis: [["moshcode trade ticker <symbol> [flags…]", ""]] },
+  { name: "quote", description: "get the latest quote", synopsis: [["moshcode trade quote <symbol> [flags…]", ""]] },
+  { name: "analysis", description: "get an analysis-ready market snapshot", synopsis: [["moshcode trade analysis <symbol> [flags…]", ""]] },
+  {
+    name: "buy", description: "preview or submit a buy order",
+    synopsis: [
+      ["moshcode trade buy <symbol> <qty> [alpaca flags…] [--submit]", "share quantity"],
+      ["moshcode trade buy <symbol> --notional <usd> [--submit]", "dollar amount"],
+    ],
+    flags: [["--submit", "place the order instead of injecting --dry-run", "preview"]],
+  },
+  {
+    name: "sell", description: "preview or submit a sell order",
+    synopsis: [
+      ["moshcode trade sell <symbol> <qty> [alpaca flags…] [--submit]", "share quantity"],
+      ["moshcode trade sell <symbol> --notional <usd> [--submit]", "dollar amount"],
+    ],
+    flags: [["--submit", "place the order instead of injecting --dry-run", "preview"]],
+  },
+  { name: "watch", description: "manage watchlists", synopsis: [["moshcode trade watch [list|create|get|add|remove|delete] [args…]", ""]] },
+  { name: "positions", description: "list, inspect, or close positions", synopsis: [["moshcode trade positions [verb] [args…]", "default: list"]] },
+  { name: "orders", description: "list, inspect, replace, or cancel orders", synopsis: [["moshcode trade orders [verb] [args…]", "default: list"]] },
+  { name: "account", description: "show account details", synopsis: [["moshcode trade account [args…]", ""]] },
+  { name: "login", description: "authenticate an Alpaca profile", synopsis: [["moshcode trade login [alpaca profile flags…]", "paper by default"]] },
+  { name: "clock", description: "show market status and next open/close", synopsis: [["moshcode trade clock [args…]", ""]] },
+  { name: "raw", description: "invoke the native Alpaca command tree", synopsis: [["moshcode trade raw <alpaca args…>", ""]] },
+];
+
+/**
+ * `dns` sub-verbs.
+ *
+ * New here rather than in completion, which never had them: the bridge grew
+ * these verbs after the completion table was written, so they were dispatchable
+ * and invisible to both help and the shell.
+ */
+export const DNS_VERBS = [
+  { name: "enable", description: "route Moshpit endings to the local bridge (needs sudo)" },
+  { name: "disable", description: "undo enable" },
+  { name: "status", description: "what is running, what is routed, does it work" },
+  { name: "refresh", description: "re-apply routing for endings claimed since" },
+  { name: "start", description: "run the bridge in the foreground" },
+  { name: "install", description: "print the resolver config without applying it" },
+  { name: "service", description: "install or remove the background service" },
+  { name: "tlds", description: "list the endings claimed in the Pit" },
+  { name: "resolve", description: "what a name resolves to, and why" },
+  { name: "trust", description: "trust one name's certificate, after checking it against the registry pin" },
+];
+
+/** Sub-verb tables, by the name a command's `verbs` field refers to. */
+export const VERB_TABLES = {
+  MCP_VERBS,
+  SKILL_VERBS,
+  UPGRADE_TARGETS,
+  DNS_VERBS,
+  TRADE_VERBS,
+};
+
+/**
+ * The pit's own command surface (PRD 0006 R12).
+ *
+ * Separate from CORE_CLI_COMMANDS because it genuinely is: the pit dispatches
+ * `/shell` and `/quit`, which have no CLI equivalent, and does not dispatch
+ * `dns`, `console`, `doh`, `site`, `template`, `completion` or `uninstall`,
+ * which do. `/help` used to imply otherwise by omission — it listed neither the
+ * commands it lacked nor `/logout`, which it has.
+ *
+ * `cli` points at the CORE_CLI_COMMANDS entry that documents the same verb, so
+ * `/help <command>` renders the flags and examples already written there rather
+ * than a second, thinner copy that drifts.
+ */
+export const PIT_COMMANDS = [
+  { name: "new", pitOnly: true,
+    description: "open and switch to another moshcode tab" },
+  { name: "agents", aliases: ["agent", "engines"], args: "[name]", cli: "agents",
+    description: "list engines, or launch one autonomously" },
+  { name: "start", args: "<engine> [args…]", cli: "start",
+    description: "raw launch; inject no engine arguments" },
+  { name: "tools", args: "[name] [args…]", cli: "tools",
+    description: "list workflow tools, or run one" },
+  { name: "trade", args: "<verb> [args…]", cli: "trade",
+    description: "look up markets and preview/place Alpaca orders" },
+  { name: "install", args: "<engine|tool>", cli: "install",
+    description: "install an engine or workflow tool" },
+  { name: "upgrade", aliases: ["update"], args: "[name…]", cli: "upgrade",
+    description: "update moshcode + installed engines/tools" },
+  { name: "mcp", args: "<verb> [args…]", cli: "mcp",
+    description: "register and inspect MCP servers" },
+  { name: "skill", aliases: ["skills"], args: "<verb> [args…]", cli: "skill",
+    description: "install and inspect agent skills" },
+  { name: "prd", args: "[idea…]", cli: "prd",
+    description: "publish a numbered PRD, or list them with no argument" },
+  { name: "run", args: "<file.mosh> [--max N] [--dry-run]", cli: "run",
+    description: "run a moshscript" },
+  { name: "login", args: "[--device] [--browser]", cli: "login",
+    description: "connect this machine to app.moshcode.sh" },
+  { name: "whoami", cli: "whoami", description: "who this machine is logged in as" },
+  // Dispatched since forever and missing from /help until now.
+  { name: "logout", cli: "logout", description: "clear the logged-in account" },
+  { name: "pwd", aliases: ["where"], cli: "pwd",
+    description: "show the current dir + git repo/branch/origin" },
+  { name: "shell", aliases: ["sh"], args: "[cmd]", pitOnly: true,
+    description: "drop into $SHELL (exit → back to the pit); also !cmd" },
+  { name: "help", aliases: ["?", "h"], args: "[command]", pitOnly: true,
+    description: "this, or one command in detail" },
+  { name: "quit", aliases: ["exit", "q"], pitOnly: true,
+    description: "leave the pit  (or Ctrl-D)" },
+];
+
+/**
+ * CLI verbs the pit does not have.
+ *
+ * Named rather than silently absent: "it isn't here" is a different answer from
+ * "you typed it wrong", and only one of them tells you to use the CLI instead.
+ */
+export const NOT_IN_PIT = ["uninstall", "dns", "doh", "site", "template", "console", "completion", "commands", "version"];

package/src/cli.mjs

@@ -0,0 +1,118 @@
+// The CLI-scripting seam: moshscript verbs that are "just" the moshcode CLI.
+//
+// moshscript is scripting the moshcode command line. A verb like `agents("claude")`
+// runs `moshcode agents claude` — the exact same command a human would type — so
+// there is one implementation of every capability (the CLI) and moshscript is a
+// second caller of it, not a reimplementation.
+//
+// cliVerb(name) builds a vocabulary command whose run() shells out to
+//   moshcode <name> <...args>
+//
+// It uses spawnSync with inherited stdio, so the call BLOCKS until the CLI
+// finishes — which is exactly right for "scripting the CLI":
+//   - the simple no-`await` style works: `install("claude"); agents("claude");`
+//     runs one after the other, in order;
+//   - interactive engine/tool sessions own the real terminal and hand control
+//     back to the script when they exit.
+// Under --dry-run it narrates the argv instead of spawning.
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { ENGINES, aiExecArgs, pickAiEngine, resolveEngine } from "./engines.mjs";
+
+// Resolve THIS package's own moshcode entrypoint, so scripting stays
+// self-referential and doesn't depend on `moshcode` being on PATH.
+const MOSHCODE_BIN = fileURLToPath(new URL("../bin/moshcode.mjs", import.meta.url));
+
+/**
+ * Run `moshcode <cmd> ...args`, blocking until it exits.
+ *
+ * Returns { ok, code } — always. A non-zero exit returns { ok: false, code }
+ * so scripts can branch on outcomes (`if (!install("foo").ok) …`) without a
+ * try/catch. Only truly fatal errors (spawn failures like ENOENT) throw.
+ * This is the R8 convention from PRD 0004.
+ */
+export function runMoshcode(cmd, args, ctx) {
+  const argv = [cmd, ...args.map(String)];
+  const printable = `moshcode ${argv.join(" ")}`.trimEnd();
+
+  if (ctx.dryRun) {
+    ctx.out(`  ▶ ${cmd}(${args.join(", ")}) → would run: ${printable}`);
+    // `code` is part of the R8 contract above ("always"), so dry-run has to
+    // carry it too — otherwise `if (install("x").code !== 0)` reads undefined
+    // and takes the failure branch on a run where nothing was even spawned.
+    return { ok: true, code: 0, dryRun: true };
+  }
+
+  ctx.out(`  ▶ ${printable}`);
+  const res = spawnSync(process.execPath, [MOSHCODE_BIN, ...argv], {
+    stdio: "inherit",
+    env: { ...process.env, MOSHCODE_NESTED: "1" },
+  });
+  if (res.error) throw res.error; // truly fatal: spawn itself failed (ENOENT etc.)
+
+  const code = res.status ?? 1;
+  if (code !== 0) {
+    ctx.out(`  ✗ ${cmd}() exited ${res.signal || code}`);
+    return { ok: false, code, signal: res.signal || null };
+  }
+  return { ok: true, code: 0 };
+}
+
+/** A vocabulary command mapping `name(...args)` → `moshcode name ...args`. */
+export function cliVerb(name, summary) {
+  // `usage` is the call signature `moshcode help <verb>` renders (PRD 0006
+  // R14). Every CLI verb has the same one — it forwards its arguments to
+  // `moshcode <name>` — so deriving it here means a verb added below is
+  // documented by the act of adding it.
+  return {
+    name,
+    summary,
+    usage: `${name}(...args)`,
+    detail: `runs \`moshcode ${name} ...args\` and returns { ok, code }`,
+    run: (ctx, ...args) => runMoshcode(name, args, ctx),
+  };
+}
+
+/**
+ * ai(prompt, opts?) — run a coding engine HEADLESSLY on `prompt` and RETURN its
+ * output as a string (unlike agents()/start(), which hand over the terminal and
+ * return nothing). Blocking (spawnSync, stdout captured). opts.engine picks the
+ * engine; otherwise the first installed one. Honors dry-run (returns "").
+ */
+export function runAi(ctx, prompt, opts = {}) {
+  if (ctx.dryRun) {
+    // narrate without requiring an installed engine — so the fallback has to
+    // resolve an alias itself: with nothing installed pickAiEngine() returns
+    // null, and handing the raw alias to aiExecArgs threw instead of narrating.
+    const engine = pickAiEngine(opts.engine) || resolveEngine(opts.engine)?.[0] || opts.engine || "claude";
+    const args = aiExecArgs(engine, prompt); // throws only on an unknown engine name
+    ctx.out(`  🧠 ai(${JSON.stringify(String(prompt).slice(0, 48))}) → would run: ${engine} ${args.join(" ")}`);
+    return "";
+  }
+
+  const engine = pickAiEngine(opts.engine);
+  if (!engine) {
+    throw new Error(`moshscript: ai() needs an installed engine — try install("claude")`);
+  }
+  const e = ENGINES[engine];
+  const args = aiExecArgs(engine, prompt);
+  ctx.out(`  🧠 ai() → ${engine}: ${String(prompt).slice(0, 60)}${String(prompt).length > 60 ? "…" : ""}`);
+
+  const env = { ...process.env };
+  for (const k of e.stripEnv || []) delete env[k];
+  const res = spawnSync(e.bin, args, { encoding: "utf8", env, maxBuffer: 16 * 1024 * 1024 });
+  if (res.error) throw res.error;
+  if (res.status !== 0) {
+    throw new Error(`moshscript: ai() → ${engine} exited with ${res.signal || res.status}${res.stderr ? `: ${res.stderr.trim().slice(0, 200)}` : ""}`);
+  }
+  return (res.stdout || "").trim();
+}
+
+/** The ai() shortcut as a vocabulary command. */
+export const aiVerb = {
+  name: "ai",
+  summary: "run a coding engine on a prompt and return its output (shortcut)",
+  usage: "ai(prompt, { engine })",
+  detail: "blocking; returns the engine's stdout as a string. engine defaults to the first installed one. needs await",
+  run: (ctx, prompt, opts) => runAi(ctx, prompt, opts),
+};