@oracle-agent/oracle 0.4.2 → 0.5.0

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 };

package/src/cli/mcp-targets/chatgpt.mjs

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fakeHome, report } from "./shared.mjs";
+
+export const CHATGPT_CANNOT_SIGN =
+  "ChatGPT is hosted and can NEVER sign or reach your keys. This connector is read/prepare only; anything it prepares is unsigned until you sign it locally.";
+
+function openApiDoc() {
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "Oracle Public (read/prepare)",
+      version: "1.0.0",
+      description: "Secret-free public surface for hosted clients. " + CHATGPT_CANNOT_SIGN,
+    },
+    servers: [{ url: "https://REPLACE-WITH-YOUR-TUNNEL" }],
+    paths: {
+      "/public/health": { get: { operationId: "publicHealth", summary: "Health check", responses: { "200": { description: "ok" } } } },
+      "/public/config": { get: { operationId: "publicConfig", summary: "Public config", responses: { "200": { description: "ok" } } } },
+      "/public/connect/request": { post: { operationId: "connectRequest", summary: "Build a connect request (unsigned)", responses: { "200": { description: "unsigned request artifact" } } } },
+      "/public/connect/assemble": { post: { operationId: "connectAssemble", summary: "Assemble an unsigned grant artifact", responses: { "200": { description: "unsigned grant artifact" } } } },
+      "/public/grants/active": { post: { operationId: "grantsActive", summary: "List active grants (read)", responses: { "200": { description: "ok" } } } },
+      "/public/grants/get": { post: { operationId: "grantsGet", summary: "Get a grant by id (read)", responses: { "200": { description: "ok" } } } },
+    },
+  };
+}
+
+export async function installChatgpt({ printOnly = false } = {}) {
+  const doc = openApiDoc();
+  const target = path.join(fakeHome(), ".config", "oracle", "connectors", "chatgpt-openapi.json");
+  const text = JSON.stringify(doc, null, 2) + "\n";
+  if (!printOnly) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, text);
+  }
+  const instructions = [
+    CHATGPT_CANNOT_SIGN, "",
+    "Next steps:",
+    "  1. oracle public serve",
+    "  2. Expose 127.0.0.1:8799 through YOUR HTTPS tunnel (cloudflared, tailscale funnel, etc.).",
+    "     Oracle will not create tunnels for you.",
+    "  3. Paste the OpenAPI spec into a GPT Action, or add the tunnel URL as a developer-mode MCP connector.",
+    printOnly ? "" : `  Spec written to: ${target}`,
+  ].filter(Boolean).join("\n");
+  return {
+    ok: true,
+    ...report(printOnly ? "printed" : "written", {
+      path: target, print: doc, instructions, cannotSign: CHATGPT_CANNOT_SIGN,
+    }),
+  };
+}

package/src/cli/mcp-targets/claude-code.mjs

@@ -0,0 +1,39 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fakeHome, buildServerSpecs, mergeMcpServers, report } from "./shared.mjs";
+
+function claudeJsonPath() { return path.join(fakeHome(), ".claude.json"); }
+function projectMcpPath(cwd) { return path.join(cwd || process.cwd(), ".mcp.json"); }
+
+function tryClaudeCli(name, spec) {
+  const probe = spawnSync("claude", ["--version"], { encoding: "utf8", timeout: 10000 });
+  if (probe.error || probe.status !== 0) return null;
+  const r = spawnSync("claude", ["mcp", "add-json", name, JSON.stringify(spec), "--scope", "user"], {
+    encoding: "utf8", timeout: 30000,
+  });
+  if (r.status !== 0) return { ok: false, stderr: r.stderr || r.stdout || "failed" };
+  return { ok: true };
+}
+
+export async function installClaudeCode({
+  oracleRoot, operator, withControl = false, project = false, printOnly = false, cwd = process.cwd(),
+}) {
+  const built = buildServerSpecs({ oracleRoot, operator, withControl });
+  if (!built.ok) return { ok: false, code: 3, reason: built.reason };
+  if (printOnly) return { ok: true, print: { mcpServers: built.specs } };
+  if (project) {
+    const target = projectMcpPath(cwd);
+    const result = mergeMcpServers(target, built.specs);
+    return { ok: true, ...report(result.status, { path: target, backup: result.backup }) };
+  }
+  let usedCli = false;
+  for (const [name, spec] of Object.entries(built.specs)) {
+    const cli = tryClaudeCli(name, spec);
+    if (cli && cli.ok) { usedCli = true; continue; }
+    break;
+  }
+  if (usedCli) return { ok: true, ...report("written", { method: "claude-cli" }) };
+  const target = claudeJsonPath();
+  const result = mergeMcpServers(target, built.specs);
+  return { ok: true, ...report(result.status, { path: target, backup: result.backup }) };
+}

package/src/cli/mcp-targets/claude-desktop.mjs

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fakeHome, buildServerSpecs, mergeMcpServers, report } from "./shared.mjs";
+
+function desktopConfigPath() {
+  if (process.platform === "darwin") {
+    return path.join(fakeHome(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  return path.join(fakeHome(), ".config", "Claude", "claude_desktop_config.json");
+}
+
+export async function installClaudeDesktop({ oracleRoot, operator, withControl = false, printOnly = false }) {
+  const built = buildServerSpecs({ oracleRoot, operator, withControl });
+  if (!built.ok) return { ok: false, code: 3, reason: built.reason };
+  const target = desktopConfigPath();
+  const payload = { mcpServers: built.specs };
+  if (printOnly) return { ok: true, print: payload };
+  const parent = path.dirname(target);
+  if (!fs.existsSync(parent)) {
+    return { ok: true, status: "printed (Claude Desktop not detected)", path: target, print: payload };
+  }
+  const result = mergeMcpServers(target, built.specs);
+  return { ok: true, ...report(result.status, { path: target, backup: result.backup }) };
+}

package/src/cli/mcp-targets/codex.mjs

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fakeHome, buildServerSpecs, backupFile, report } from "./shared.mjs";
+
+const BEGIN = "# oracle-mcp-install begin";
+const END = "# oracle-mcp-install end";
+
+function codexPath() { return path.join(fakeHome(), ".codex", "config.toml"); }
+
+function renderBlock(specs) {
+  const lines = [BEGIN];
+  for (const [name, spec] of Object.entries(specs)) {
+    lines.push(`[mcp_servers.${name}]`);
+    lines.push(`command = ${JSON.stringify(spec.command)}`);
+    lines.push(`args = [${spec.args.map((a) => JSON.stringify(a)).join(", ")}]`);
+    lines.push("");
+  }
+  lines.push(END);
+  return lines.join("\n") + "\n";
+}
+
+function stripExistingBlock(text) {
+  return text.replace(new RegExp(`${BEGIN}[\\s\\S]*?${END}\\n?`, "g"), "");
+}
+
+export async function installCodex({ oracleRoot, operator, withControl = false, printOnly = false }) {
+  const built = buildServerSpecs({ oracleRoot, operator, withControl });
+  if (!built.ok) return { ok: false, code: 3, reason: built.reason };
+  const block = renderBlock(built.specs);
+  const target = codexPath();
+  if (printOnly) return { ok: true, printText: block, path: target };
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const prev = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  if (prev.includes(block.trim())) return { ok: true, ...report("present", { path: target, backup: null }) };
+  const stripped = stripExistingBlock(prev);
+  const next = (stripped.trimEnd() + "\n\n" + block).replace(/^\n+/, "");
+  if (prev.trim() === next.trim()) return { ok: true, ...report("present", { path: target, backup: null }) };
+  const backup = prev ? backupFile(target) : null;
+  fs.writeFileSync(target, next.endsWith("\n") ? next : next + "\n");
+  return { ok: true, ...report("written", { path: target, backup }) };
+}

package/src/cli/mcp-targets/shared.mjs

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { PACKAGE_ROOT } from "../paths.mjs";
+
+export function fakeHome() {
+  return process.env.ORACLE_FAKE_HOME || os.homedir();
+}
+
+export function buildServerSpecs({ oracleRoot = PACKAGE_ROOT, operator = null, withControl = false } = {}) {
+  const specs = {
+    "oracle-data": {
+      command: "node",
+      args: [path.join(oracleRoot, "bin", "oracle-data-mcp.mjs")],
+    },
+  };
+  if (withControl) {
+    if (!operator || !operator.ok) return { ok: false, reason: "operator-missing" };
+    const control = operator.bins?.["oracle-control-mcp"] || operator.controlMcp || null;
+    if (!control) return { ok: false, reason: "control-bin-missing" };
+    specs["oracle-control"] = { command: "node", args: [control] };
+  }
+  return { ok: true, specs };
+}
+
+export function backupFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const bak = `${filePath}.bak-oracle-${Math.floor(Date.now() / 1000)}`;
+  fs.copyFileSync(filePath, bak);
+  return bak;
+}
+
+export function readJson(filePath, fallback = {}) {
+  if (!fs.existsSync(filePath)) return structuredClone(fallback);
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+export function writeJson(filePath, obj) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(obj, null, 2) + "\n");
+}
+
+export function mergeMcpServers(filePath, specs) {
+  const existing = readJson(filePath, {});
+  if (!existing.mcpServers || typeof existing.mcpServers !== "object") existing.mcpServers = {};
+  let changed = false;
+  for (const [name, spec] of Object.entries(specs)) {
+    const prev = existing.mcpServers[name];
+    if (prev && JSON.stringify(prev) === JSON.stringify(spec)) continue;
+    existing.mcpServers[name] = spec;
+    changed = true;
+  }
+  if (!changed) return { status: "present", backup: null };
+  const backup = backupFile(filePath);
+  writeJson(filePath, existing);
+  return { status: "written", backup };
+}
+
+export function report(status, detail = {}) {
+  return { status, ...detail };
+}