@oracle-agent/oracle 0.4.1 → 0.5.0

package/src/cli/commands/doctor.mjs

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DOCTOR_SIGNING_OPTIONAL } from "../first-run.mjs";
+
+function nodeVersionOk() {
+  const [maj, min] = process.versions.node.split(".").map(Number);
+  return maj > 20 || (maj === 20 && min >= 19);
+}
+
+function loadExecEnv(p) {
+  if (!fs.existsSync(p)) return {};
+  const out = {};
+  for (const line of fs.readFileSync(p, "utf8").split(/\r?\n/)) {
+    const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+
+function which(bin) {
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    const c = path.join(dir, bin);
+    try { if (fs.existsSync(c)) return c; } catch {}
+  }
+  return null;
+}
+
+async function probeDataServer(url) {
+  try {
+    const res = await fetch(url.replace(/\/$/, "") + "/");
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export default {
+  name: "doctor",
+  summary: "check read plane; checks signer too when installed",
+  group: "read",
+  usage: "oracle doctor [--json]",
+  async run(ctx) {
+    const json = ctx.argv.includes("--json");
+    const checks = [];
+    let failed = false;
+    const push = (id, status, detail, fix = null) => {
+      checks.push({ id, status, detail, fix });
+      if (status === "fail") failed = true;
+    };
+
+    push("node", nodeVersionOk() ? "ok" : "fail", `node ${process.versions.node}`,
+      nodeVersionOk() ? null : "install node >= 20.19");
+
+    const execEnvPath = ctx.paths.oracleExecEnvPath();
+    const envFile = loadExecEnv(execEnvPath);
+    const att =
+      process.env.ORACLE_ATTESTATION_SECRET ||
+      process.env.ORACLE_STAMP_HMAC_SECRET ||
+      envFile.ORACLE_ATTESTATION_SECRET ||
+      envFile.ORACLE_STAMP_HMAC_SECRET;
+    push("attestation_secret", att ? "ok" : "warn", att ? "present" : "missing",
+      att ? null : "run oracle init --apply (writes ~/.config/oracle/exec.env)");
+
+    const dataUrl = process.env.ORACLE_DATA_URL || "http://127.0.0.1:8787";
+    const dataUp = await probeDataServer(dataUrl);
+    push("data_server", dataUp ? "ok" : "warn", dataUp ? `reachable ${dataUrl}` : `down ${dataUrl}`,
+      dataUp ? null : "oracle data serve");
+
+    const hermes = which("hermes");
+    push("hermes_cli", hermes ? "ok" : "warn", hermes ? `present ${hermes}` : "not on PATH",
+      hermes ? null : "install Hermes if you want agent lanes");
+
+    const profilesDir = path.join(ctx.paths.hermesRoot(), "profiles");
+    let laneCount = 0;
+    if (fs.existsSync(profilesDir)) {
+      laneCount = fs.readdirSync(profilesDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length;
+    }
+    push("hermes_lanes", laneCount > 0 ? "ok" : "warn",
+      laneCount > 0 ? `${laneCount} profile dir(s)` : "no lane profiles found",
+      laneCount > 0 ? null : "oracle init --apply");
+
+    const operator = ctx.resolveOperator();
+    let operatorBlock = { installed: false };
+    if (operator.ok) {
+      const r = ctx.dispatchOperator("oracle-agentic-doctor", ["--json"], { stdio: "pipe" });
+      let detail = { installed: true, version: operator.version, source: operator.source };
+      if (r && typeof r === "object" && r.stdout) {
+        try {
+          const parsed = JSON.parse(r.stdout);
+          detail = {
+            installed: true,
+            version: operator.version,
+            source: operator.source,
+            signingReady: parsed.signingReady,
+            broadcastReady: parsed.broadcastReady,
+            executionReady: parsed.executionReady,
+            masterKillSwitch: parsed.masterKillSwitch,
+            raw: parsed,
+          };
+        } catch {
+          detail.doctorParseError = true;
+          detail.doctorExit = r.code;
+        }
+      } else if (typeof r === "number") {
+        detail.doctorExit = r;
+      }
+      operatorBlock = detail;
+      const signingReady = detail.signingReady === true;
+      push(
+        "signing",
+        signingReady ? "ok" : "warn",
+        signingReady
+          ? `operator ${operator.version} ready via ${operator.source}`
+          : `operator ${operator.version} installed but signing is not ready`,
+        signingReady ? null : "oracle sign doctor --json",
+      );
+    }
+
+    const report = { ok: !failed, checks, operator: operatorBlock };
+    if (json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    } else {
+      for (const c of checks) {
+        process.stdout.write(`${c.status.toUpperCase().padEnd(4)} ${c.id}: ${c.detail}\n`);
+        if (c.fix) process.stdout.write(`     fix: ${c.fix}\n`);
+      }
+      if (!operator.ok) process.stdout.write(`INFO ${DOCTOR_SIGNING_OPTIONAL}\n`);
+    }
+    return failed ? 1 : 0;
+  },
+};

package/src/cli/commands/help.mjs

@@ -0,0 +1,7 @@
+export default {
+  name: "help",
+  summary: "show command help",
+  group: "meta",
+  usage: "oracle help [noun]",
+  async run() { return 0; },
+};

package/src/cli/commands/init.mjs

@@ -0,0 +1,27 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { renderNextSteps } from "../first-run.mjs";
+
+export default {
+  name: "init",
+  summary: "install agent lanes + read plane (dry-run by default)",
+  group: "read",
+  usage: "oracle init [--apply --force --only <lane> --json --yes]",
+  async run(ctx) {
+    const argv = [...ctx.argv];
+    if (argv.includes("--yes") && !argv.includes("--apply")) argv.push("--apply");
+    const bin = path.join(ctx.root, "bin", "oracle-init.mjs");
+    const r = spawnSync(process.execPath, [bin, ...argv], { encoding: "utf8", env: process.env });
+    if (r.error) {
+      process.stderr.write(`oracle: failed to spawn oracle-init: ${r.error.message}\n`);
+      return 1;
+    }
+    if (r.stdout) process.stdout.write(r.stdout);
+    if (r.stderr) process.stderr.write(r.stderr);
+    const code = typeof r.status === "number" ? r.status : 1;
+    if (code === 0 && argv.includes("--apply") && !argv.includes("--json")) {
+      process.stdout.write(renderNextSteps());
+    }
+    return code;
+  },
+};

package/src/cli/commands/mcp.mjs

@@ -0,0 +1,142 @@
+import { parseArgs } from "node:util";
+import { printOperatorNotInstalled } from "../operator-dispatch.mjs";
+import { installClaudeCode } from "../mcp-targets/claude-code.mjs";
+import { installClaudeDesktop } from "../mcp-targets/claude-desktop.mjs";
+import { installCodex } from "../mcp-targets/codex.mjs";
+import { installChatgpt } from "../mcp-targets/chatgpt.mjs";
+import { buildServerSpecs } from "../mcp-targets/shared.mjs";
+
+function usage() {
+  process.stderr.write(
+    "usage: oracle mcp <install|print> [target] [flags]\n" +
+      "  targets: claude-code | claude-desktop | codex | chatgpt | generic\n" +
+      "  flags:   --with-control --project --print --json\n",
+  );
+}
+
+function emitResult(result, { json = false } = {}) {
+  if (result.print && !result.instructions) {
+    process.stdout.write(JSON.stringify(result.print, null, 2) + "\n");
+  } else if (result.printText) {
+    process.stdout.write(result.printText);
+  }
+  if (result.instructions) {
+    process.stdout.write(result.instructions + "\n");
+    if (result.print && json) process.stdout.write(JSON.stringify(result.print, null, 2) + "\n");
+  }
+  if (!result.print && !result.printText && !result.instructions) {
+    const line = {
+      status: result.status,
+      path: result.path || null,
+      backup: result.backup || null,
+      method: result.method || null,
+    };
+    process.stdout.write(
+      (json ? JSON.stringify(line, null, 2) : `${line.status}${line.path ? " " + line.path : ""}`) + "\n",
+    );
+  }
+}
+
+export default {
+  name: "mcp",
+  summary: "wire Oracle into AI clients",
+  group: "read",
+  usage: "oracle mcp install <target> | oracle mcp print [--target <t>]",
+  async run(ctx) {
+    const verb = ctx.argv[0];
+    if (!verb || verb === "--help" || verb === "-h") {
+      usage();
+      return verb ? 0 : 1;
+    }
+
+    let values, positionals;
+    try {
+      ({ values, positionals } = parseArgs({
+        args: ctx.argv.slice(1),
+        options: {
+          "with-control": { type: "boolean", default: false },
+          project: { type: "boolean", default: false },
+          print: { type: "boolean", default: false },
+          json: { type: "boolean", default: false },
+          target: { type: "string" },
+        },
+        allowPositionals: true,
+        strict: false,
+      }));
+    } catch (err) {
+      process.stderr.write(`oracle mcp: ${err.message}\n`);
+      usage();
+      return 1;
+    }
+
+    const withControl = !!values["with-control"];
+    const project = !!values.project;
+    const json = !!values.json;
+    const operator = ctx.resolveOperator ? ctx.resolveOperator() : { ok: false };
+
+    if (withControl && (!operator || !operator.ok)) {
+      printOperatorNotInstalled(process.stderr);
+      return 3;
+    }
+
+    const opts = { oracleRoot: ctx.root, operator, withControl, project, cwd: process.cwd() };
+
+    if (verb === "print") {
+      const target = values.target || positionals[0] || "claude-code";
+      if (target === "generic" || target === "claude-code") {
+        const built = buildServerSpecs(opts);
+        if (!built.ok) { printOperatorNotInstalled(process.stderr); return 3; }
+        process.stdout.write(JSON.stringify({ mcpServers: built.specs }, null, 2) + "\n");
+        return 0;
+      }
+      if (target === "chatgpt") {
+        const r = await installChatgpt({ printOnly: true });
+        emitResult(r, { json });
+        return 0;
+      }
+      if (target === "codex") {
+        emitResult(await installCodex({ ...opts, printOnly: true }), { json });
+        return 0;
+      }
+      if (target === "claude-desktop") {
+        emitResult(await installClaudeDesktop({ ...opts, printOnly: true }), { json });
+        return 0;
+      }
+      process.stderr.write(`oracle mcp: unknown target '${target}'\n`);
+      return 1;
+    }
+
+    if (verb === "install") {
+      const target = positionals[0] || values.target;
+      if (!target) { usage(); return 1; }
+      const printOnly = !!values.print;
+      let result;
+      if (target === "claude-code") result = await installClaudeCode({ ...opts, printOnly });
+      else if (target === "claude-desktop") result = await installClaudeDesktop({ ...opts, printOnly });
+      else if (target === "codex") result = await installCodex({ ...opts, printOnly });
+      else if (target === "chatgpt") result = await installChatgpt({ printOnly });
+      else if (target === "generic") {
+        const built = buildServerSpecs(opts);
+        if (!built.ok) { printOperatorNotInstalled(process.stderr); return 3; }
+        process.stdout.write(JSON.stringify({ mcpServers: built.specs }, null, 2) + "\n");
+        return 0;
+      } else {
+        process.stderr.write(`oracle mcp: unknown target '${target}'\n`);
+        return 1;
+      }
+      if (!result.ok) {
+        if (result.code === 3) printOperatorNotInstalled(process.stderr);
+        else process.stderr.write(`oracle mcp: ${result.reason || "failed"}\n`);
+        return result.code || 1;
+      }
+      emitResult(result, { json });
+      if (result.status && String(result.status).startsWith("printed") && result.print) {
+        process.stdout.write(JSON.stringify(result.print, null, 2) + "\n");
+      }
+      return 0;
+    }
+
+    usage();
+    return 1;
+  },
+};

package/src/cli/commands/prepare.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "prepare", summary: "build an unsigned swap (alias of route prepare)", group: "read",
+  usage: "oracle prepare <chain> <tokenIn> <tokenOut> <taker> [amt]",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-route.mjs");
+    const r = spawnSync(process.execPath, [bin, "prepare", ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-route: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/public.mjs

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { spawnChild } from "../spawn-child.mjs";
+export default {
+  name: "public", summary: "secret-free public HTTP surface", group: "read",
+  usage: "oracle public serve [--port N]",
+  async run(ctx) {
+    const verb = ctx.argv[0] || "serve";
+    if (verb !== "serve") { process.stderr.write("usage: oracle public serve [--port N]\n"); return 1; }
+    let port = null;
+    try {
+      const { values } = parseArgs({ args: ctx.argv.slice(1), options: { port: { type: "string" } }, allowPositionals: true, strict: false });
+      port = values.port || null;
+    } catch {}
+    const env = { ...process.env };
+    if (port) env.ORACLE_PUBLIC_PORT = String(port);
+    const bin = path.join(ctx.root, "bin", "oracle-public-server.mjs");
+    return spawnChild(process.execPath, [bin], { stdio: "inherit", env }, "oracle-public-server");
+  },
+};

package/src/cli/commands/route.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "route", summary: "swap/bridge prepare helpers", group: "read",
+  usage: "oracle route <swap|bridge|prepare|prepare-bridge> ...",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-route.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-route: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/runner.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "runner",
+  summary: "action runner daemon",
+  group: "sign",
+  usage: "oracle runner [--interval-ms N ...]",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-runner", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/scan.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "scan", summary: "chain scanner", group: "read",
+  usage: "oracle scan <chains|head|token|pools|risk|quote|sell> ...",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-scan.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-scan: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/sign.mjs

@@ -0,0 +1,21 @@
+export default {
+  name: "sign",
+  summary: "provision / check the local signer (opt-in)",
+  group: "sign",
+  usage: "oracle sign <init|doctor> ...",
+  async run(ctx) {
+    const verb = ctx.argv[0];
+    if (verb === "init") {
+      return ctx.dispatchOperator("oracle-agentic-init", ctx.argv.slice(1), { appendHintOnError: true });
+    }
+    if (verb === "doctor") {
+      return ctx.dispatchOperator("oracle-agentic-doctor", ctx.argv.slice(1), { appendHintOnError: true });
+    }
+    process.stderr.write(
+      "usage: oracle sign <init|doctor> ...\n" +
+        "  oracle sign init      provision keys + policy (interactive)\n" +
+        "  oracle sign doctor    check local signer readiness\n",
+    );
+    return 1;
+  },
+};

package/src/cli/commands/signer.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "signer",
+  summary: "loopback signer daemon",
+  group: "sign",
+  usage: "oracle signer [--port N ...]",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-signer", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/upgrade.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "upgrade", summary: "upgrade installed Hermes lanes", group: "read",
+  usage: "oracle upgrade [--apply ...]",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-upgrade.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-upgrade: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/vault.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "vault",
+  summary: "encrypt local key files at rest",
+  group: "sign",
+  usage: "oracle vault <encrypt|rekey|inspect|decrypt> ...",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-vault", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/version.mjs

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveOperator } from "../operator-dispatch.mjs";
+
+export default {
+  name: "version",
+  summary: "print oracle (and operator, if present) version",
+  group: "meta",
+  usage: "oracle version",
+  async run(ctx) {
+    let version = "0.0.0";
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(ctx.root, "package.json"), "utf8"));
+      version = pkg.version || version;
+    } catch {}
+    let line = `oracle ${version}`;
+    const op = (ctx.resolveOperator || resolveOperator)();
+    if (op.ok) line += `  operator ${op.version}`;
+    process.stdout.write(line + "\n");
+    return 0;
+  },
+};

package/src/cli/first-run.mjs

@@ -0,0 +1,20 @@
+export const NEXT_STEPS_AFTER_INIT = [
+  "oracle data serve          # loopback read/prepare plane on 127.0.0.1:8787",
+  "oracle doctor              # verify",
+  "oracle mcp install claude-code",
+  "# optional, explicit second step — signing stays a separate local package:",
+  "npm i -g @oracle-agent/operator",
+  "oracle sign init",
+];
+
+export function renderNextSteps() {
+  return [
+    "",
+    "Next:",
+    ...NEXT_STEPS_AFTER_INIT.map((l) => "  " + l),
+    "",
+  ].join("\n");
+}
+
+export const DOCTOR_SIGNING_OPTIONAL =
+  "signing: not installed (optional) — npm i -g @oracle-agent/operator";

package/src/cli/kernel.mjs

@@ -0,0 +1,198 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { PACKAGE_ROOT, paths } from "./paths.mjs";
+import {
+  dispatchOperator,
+  resolveOperator,
+  printOperatorNotInstalled,
+  SIGN_NOUNS,
+} from "./operator-dispatch.mjs";
+
+const HELP_HEADER = `oracle — prepare-only multichain agent control plane`;
+
+const STATIC_HELP = `READ / RESEARCH (no keys, this package)
+  oracle init                 install agent lanes + read plane (dry-run by default)
+  oracle doctor               check read plane; checks signer too when installed
+  oracle data serve|call|catalog|health
+  oracle data-mcp             start the read-only MCP server
+  oracle scan chains|head|token|pools|risk|quote|sell
+  oracle route swap|bridge|prepare|prepare-bridge
+  oracle prepare              build an unsigned swap (alias of route prepare)
+  oracle public serve         secret-free public HTTP surface
+  oracle mcp install <t>      wire Oracle into claude-code|claude-desktop|codex|chatgpt
+  oracle upgrade              upgrade installed Hermes lanes
+
+SIGNING (dispatches to @oracle-agent/operator on THIS machine; never in this package)
+  oracle sign init|doctor     provision / check the local signer (opt-in)
+  oracle vault ...            encrypt local key files at rest
+  oracle signer / runner      loopback signer daemon / action runner
+  oracle credential ...       OS credential store glue
+
+oracle <noun> --help for details. Keys never leave your machine; this package
+cannot sign — signing commands run the locally installed operator package.
+`;
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"),
+    );
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+export function commandsDir() {
+  return path.join(PACKAGE_ROOT, "src", "cli", "commands");
+}
+
+export async function discoverCommands() {
+  const dir = commandsDir();
+  const out = new Map();
+  if (!fs.existsSync(dir)) return out;
+  const entries = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".mjs"))
+    .sort();
+  for (const file of entries) {
+    const full = path.join(dir, file);
+    try {
+      const mod = await import(pathToFileURL(full).href + `?t=${Date.now()}`);
+      const cmd = mod.default;
+      if (!cmd || typeof cmd !== "object" || typeof cmd.run !== "function") {
+        continue;
+      }
+      const name = cmd.name || file.replace(/\.mjs$/, "");
+      out.set(name, { ...cmd, name, __file: full });
+    } catch (err) {
+      if (process.env.ORACLE_CLI_DEBUG) {
+        console.error(`oracle: failed loading command ${file}: ${err.message}`);
+      }
+    }
+  }
+  return out;
+}
+
+export function renderHelp(version, commands) {
+  const lines = [];
+  lines.push(`${HELP_HEADER} (v${version})`);
+  lines.push("");
+  lines.push(STATIC_HELP.trimEnd());
+
+  const extras = [];
+  for (const cmd of commands.values()) {
+    if (["help", "version"].includes(cmd.name)) continue;
+    const known = new Set([
+      "init","doctor","data","data-mcp","scan","route","prepare","public","mcp","upgrade",
+      "sign","vault","signer","runner","credential",
+    ]);
+    if (!known.has(cmd.name) && cmd.summary) {
+      extras.push(`  oracle ${cmd.name.padEnd(20)} ${cmd.summary}`);
+    }
+  }
+  if (extras.length) {
+    lines.push("");
+    lines.push("ADDITIONAL");
+    lines.push(...extras);
+  }
+  return lines.join("\n") + "\n";
+}
+
+function unknownNounMessage(noun, commands) {
+  const known = [...commands.keys()].sort();
+  const list = known.length ? known.join(", ") : "(none loaded yet)";
+  return `oracle: unknown command '${noun}'. Known: ${list}\nTry: oracle --help\n`;
+}
+
+function buildCtx(argv) {
+  return {
+    argv,
+    root: PACKAGE_ROOT,
+    paths,
+    dispatchOperator,
+    resolveOperator,
+  };
+}
+
+export async function run(argv = []) {
+  const version = readPackageVersion();
+
+  if (argv.includes("--version") || argv.includes("-V")) {
+    return runVersion();
+  }
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    const commands = await discoverCommands();
+    process.stdout.write(renderHelp(version, commands));
+    return 0;
+  }
+
+  const noun = argv[0];
+  const rest = argv.slice(1);
+
+  if (noun === "version") {
+    return runVersion();
+  }
+  if (noun === "help") {
+    const commands = await discoverCommands();
+    if (rest[0]) {
+      const cmd = commands.get(rest[0]);
+      if (cmd) {
+        process.stdout.write((cmd.usage || `oracle ${cmd.name}`) + "\n");
+        if (cmd.summary) process.stdout.write(cmd.summary + "\n");
+        return 0;
+      }
+      process.stderr.write(unknownNounMessage(rest[0], commands));
+      return 1;
+    }
+    process.stdout.write(renderHelp(version, commands));
+    return 0;
+  }
+
+  const commands = await discoverCommands();
+  const cmd = commands.get(noun);
+
+  if (cmd) {
+    if (rest[0] === "--help" || rest[0] === "-h") {
+      process.stdout.write((cmd.usage || `oracle ${cmd.name}`) + "\n");
+      if (cmd.summary) process.stdout.write(cmd.summary + "\n");
+      return 0;
+    }
+    try {
+      const code = await cmd.run(buildCtx(rest));
+      return typeof code === "number" ? code : 0;
+    } catch (err) {
+      process.stderr.write(`oracle ${noun}: ${err?.message || err}\n`);
+      return 1;
+    }
+  }
+
+  if (SIGN_NOUNS.includes(noun)) {
+    const resolved = resolveOperator();
+    if (!resolved.ok) {
+      printOperatorNotInstalled(process.stderr);
+      return 3;
+    }
+    process.stderr.write(
+      `oracle: sign-plane command '${noun}' is not available in this build (operator is installed).\n`,
+    );
+    return 1;
+  }
+
+  process.stderr.write(unknownNounMessage(noun, commands));
+  return 1;
+}
+
+async function runVersion() {
+  const version = readPackageVersion();
+  let line = `oracle ${version}`;
+  const op = resolveOperator();
+  if (op.ok) {
+    line += `  operator ${op.version}`;
+  }
+  process.stdout.write(line + "\n");
+  return 0;
+}
+
+export default { run, discoverCommands, renderHelp };