@oracle-agent/oracle 0.13.0 → 0.14.0

package/src/cli/runtime.mjs

@@ -0,0 +1,351 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { homeDir, oracleConfigDir, ensureDir } from "./paths.mjs";
+
+export const HERMES_VERSION = "0.19.0";
+export const HERMES_PYPI = `hermes-agent==${HERMES_VERSION}`;
+const MIN_PY = [3, 11];
+const MAX_PY_EXCLUSIVE = [3, 14];
+export const UV_PYTHON = "3.13";
+export const UV_VERSION = "0.12.1";
+export const UV_INSTALLERS = Object.freeze({
+  posix: Object.freeze({
+    url: `https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/uv-installer.sh`,
+    sha256: "d3f5412d38c99f9d024901843bf98206f0d2c6dbe64df40d0b740e2751ca62c1",
+  }),
+  windows: Object.freeze({
+    url: `https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/uv-installer.ps1`,
+    sha256: "b9ec035151bfbb11d616dbd69886498d885551489eddf095ea3c0ad59f640eb0",
+  }),
+});
+
+export function verifyUvInstaller(bytes, { windows = process.platform === "win32" } = {}) {
+  const body = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  const spec = windows ? UV_INSTALLERS.windows : UV_INSTALLERS.posix;
+  const digest = createHash("sha256").update(body).digest("hex");
+  const text = body.toString("utf8");
+  return digest === spec.sha256 && text.length >= 1_000 && text.includes(UV_VERSION);
+}
+
+export function runtimeDir() {
+  return path.join(oracleConfigDir(), "runtime");
+}
+
+export function runtimeVenvDir() {
+  return path.join(runtimeDir(), "venv");
+}
+
+function venvBin(name) {
+  const dir = process.platform === "win32" ? "Scripts" : "bin";
+  const exe = process.platform === "win32" ? `${name}.exe` : name;
+  return path.join(runtimeVenvDir(), dir, exe);
+}
+
+export function managedHermesPath() {
+  return venvBin("hermes");
+}
+
+export function managedPythonPath() {
+  const py = venvBin("python3");
+  return fs.existsSync(py) ? py : venvBin("python");
+}
+
+export function managedUvPath() {
+  return path.join(runtimeDir(), "uv", process.platform === "win32" ? "uv.exe" : "uv");
+}
+
+export function whichBin(bin) {
+  const suffixes = process.platform === "win32" && !path.extname(bin)
+    ? ["", ".exe", ".cmd", ".bat"]
+    : [""];
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    for (const suffix of suffixes) {
+      const c = path.join(dir, `${bin}${suffix}`);
+      try {
+        if (fs.existsSync(c)) return c;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+function parsePyVersion(out) {
+  const m = /Python (\d+)\.(\d+)\.(\d+)/.exec(out || "");
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function versionSupported(v) {
+  if (!v) return false;
+  const [maj, min] = v;
+  if (maj < MIN_PY[0] || (maj === MIN_PY[0] && min < MIN_PY[1])) return false;
+  if (maj > MAX_PY_EXCLUSIVE[0] || (maj === MAX_PY_EXCLUSIVE[0] && min >= MAX_PY_EXCLUSIVE[1])) {
+    return false;
+  }
+  return true;
+}
+
+export function findHostPython() {
+  const candidates = [
+    process.env.ORACLE_PYTHON,
+    "python3.13",
+    "python3.12",
+    "python3.11",
+    "python3",
+    "python",
+  ].filter(Boolean);
+  for (const cand of candidates) {
+    const bin = path.isAbsolute(cand) ? (fs.existsSync(cand) ? cand : null) : whichBin(cand);
+    if (!bin) continue;
+    const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 15_000 });
+    const v = parsePyVersion(`${r.stdout || ""}${r.stderr || ""}`);
+    if (versionSupported(v)) return { bin, version: v.join("."), source: "host" };
+  }
+  return null;
+}
+
+function uvBin() {
+  return (
+    process.env.ORACLE_UV_BIN ||
+    whichBin("uv") ||
+    (fs.existsSync(path.join(homeDir(), ".local", "bin", "uv"))
+      ? path.join(homeDir(), ".local", "bin", "uv")
+      : null) ||
+    (fs.existsSync(managedUvPath()) ? managedUvPath() : null)
+  );
+}
+
+function downloadFile(url, dest) {
+  const script = [
+    "const fs=require('node:fs');",
+    "const [url,dest]=process.argv.slice(1);",
+    "fetch(url).then(r=>{if(!r.ok)throw new Error('http '+r.status);return r.arrayBuffer()})",
+    ".then(b=>fs.writeFileSync(dest,Buffer.from(b)))",
+    ".catch(e=>{console.error(e.message);process.exit(1)});",
+  ].join("");
+  return spawnSync(process.execPath, ["-e", script, url, dest], {
+    encoding: "utf8",
+    timeout: 2 * 60_000,
+  });
+}
+
+export function installManagedUv({ quiet = false } = {}) {
+  const existing = uvBin();
+  if (existing) return { ok: true, bin: existing, reused: true };
+
+  ensureDir(runtimeDir());
+  const windows = process.platform === "win32";
+  const installer = path.join(runtimeDir(), windows ? "uv-install.ps1" : "uv-install.sh");
+  const spec = windows ? UV_INSTALLERS.windows : UV_INSTALLERS.posix;
+  const dl = downloadFile(spec.url, installer);
+  if (dl.status !== 0) {
+    return {
+      ok: false,
+      reason: `could not download the uv installer (${dl.status})`,
+      stderr: (dl.stderr || "").slice(-800),
+    };
+  }
+
+  const body = fs.readFileSync(installer);
+  if (!verifyUvInstaller(body, { windows })) {
+    return { ok: false, reason: `uv ${UV_VERSION} installer checksum mismatch` };
+  }
+
+  const installDir = path.dirname(managedUvPath());
+  ensureDir(installDir);
+  const command = windows
+    ? (whichBin("powershell.exe") || whichBin("powershell"))
+    : (whichBin("sh") || "/bin/sh");
+  if (!command) return { ok: false, reason: windows ? "PowerShell not found" : "sh not found" };
+  const args = windows
+    ? ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", installer]
+    : [installer];
+  const inst = spawnSync(command, args, {
+    stdio: quiet ? "pipe" : "inherit",
+    encoding: "utf8",
+    timeout: 5 * 60_000,
+    env: {
+      ...process.env,
+      UV_INSTALL_DIR: installDir,
+      UV_NO_MODIFY_PATH: "1",
+    },
+  });
+  if (inst.status !== 0 || !fs.existsSync(managedUvPath())) {
+    return {
+      ok: false,
+      reason: `uv install failed (${inst.status})`,
+      stderr: (inst.stderr || "").slice(-800),
+    };
+  }
+  return { ok: true, bin: managedUvPath(), reused: false };
+}
+
+export function provisionPythonViaUv({ quiet = false } = {}) {
+  const installed = installManagedUv({ quiet });
+  if (!installed.ok) return installed;
+  const uv = installed.bin;
+
+  const uvEnv = {
+    ...process.env,
+    UV_PYTHON_INSTALL_DIR: path.join(runtimeDir(), "python"),
+    UV_CACHE_DIR: path.join(runtimeDir(), "cache"),
+  };
+  const inst = spawnSync(uv, ["python", "install", "--no-bin", UV_PYTHON], {
+    stdio: quiet ? "pipe" : "inherit",
+    encoding: "utf8",
+    timeout: 15 * 60_000,
+    env: uvEnv,
+  });
+  if (inst.status !== 0) {
+    return {
+      ok: false,
+      reason: `uv python install ${UV_PYTHON} failed (${inst.status})`,
+      stderr: (inst.stderr || "").slice(-800),
+    };
+  }
+
+  const found = spawnSync(uv, ["python", "find", UV_PYTHON], {
+    encoding: "utf8",
+    timeout: 60_000,
+    env: uvEnv,
+  });
+  const bin = (found.stdout || "").trim().split(/\r?\n/)[0];
+  if (found.status !== 0 || !bin || !fs.existsSync(bin)) {
+    return { ok: false, reason: `uv could not locate python ${UV_PYTHON}` };
+  }
+  return { ok: true, bin, version: UV_PYTHON, source: "uv" };
+}
+
+/**
+ * Resolve the hermes runtime this Oracle install should use.
+ * Order: explicit override -> system PATH -> oracle-managed venv.
+ */
+export function resolveHermes() {
+  if (process.env.ORACLE_HERMES_BIN) {
+    return { ok: true, bin: process.env.ORACLE_HERMES_BIN, source: "env" };
+  }
+  const onPath = whichBin("hermes");
+  if (onPath) return { ok: true, bin: onPath, source: "path" };
+  const managed = managedHermesPath();
+  if (fs.existsSync(managed)) return { ok: true, bin: managed, source: "managed" };
+  return { ok: false, bin: null, source: null };
+}
+
+export function runtimeStatus() {
+  const resolved = resolveHermes();
+  const host = findHostPython();
+  return {
+    hermes: resolved,
+    managedVenv: runtimeVenvDir(),
+    managedInstalled: fs.existsSync(managedHermesPath()),
+    hostPython: host,
+    uv: uvBin(),
+  };
+}
+
+function run(cmd, args, { quiet }) {
+  return spawnSync(cmd, args, {
+    stdio: quiet ? "pipe" : "inherit",
+    encoding: "utf8",
+    timeout: 20 * 60_000,
+  });
+}
+
+/**
+ * Create ~/.config/oracle/runtime/venv and install hermes-agent into it.
+ * Never touches system python or global site-packages.
+ */
+export function installManagedHermes({ quiet = false, upgrade = false } = {}) {
+  let host = findHostPython();
+  if (!host) {
+    const viaUv = provisionPythonViaUv({ quiet });
+    if (viaUv.ok) {
+      host = { bin: viaUv.bin, version: viaUv.version, source: "uv" };
+    } else {
+      return {
+        ok: false,
+        reason:
+          `no supported python found (need 3.11-3.13) and uv could not provide one: ${viaUv.reason}. ` +
+          "install uv (https://docs.astral.sh/uv) or python 3.13, then re-run 'oracle bootstrap'",
+      };
+    }
+  }
+
+  ensureDir(runtimeDir());
+  const venv = runtimeVenvDir();
+  const alreadyInstalled = fs.existsSync(managedHermesPath());
+  if (alreadyInstalled && !upgrade) {
+    return { ok: true, bin: managedHermesPath(), reused: true };
+  }
+
+  if (!fs.existsSync(path.join(venv, "pyvenv.cfg"))) {
+    let mk = run(host.bin, ["-m", "venv", venv], { quiet });
+    if (mk.status !== 0 && host.source !== "uv") {
+      fs.rmSync(venv, { recursive: true, force: true });
+      const viaUv = provisionPythonViaUv({ quiet });
+      if (viaUv.ok) {
+        host = { bin: viaUv.bin, version: viaUv.version, source: "uv" };
+        mk = run(host.bin, ["-m", "venv", venv], { quiet });
+      } else {
+        return {
+          ok: false,
+          reason: `python -m venv failed (${mk.status}) and uv fallback failed: ${viaUv.reason}`,
+          stderr: (mk.stderr || "").slice(-800),
+        };
+      }
+    }
+    if (mk.status !== 0) {
+      return {
+        ok: false,
+        reason: `isolated python -m venv failed (${mk.status})`,
+        stderr: (mk.stderr || "").slice(-800),
+      };
+    }
+  }
+
+  const py = managedPythonPath();
+  if (!fs.existsSync(py)) {
+    return { ok: false, reason: `venv python missing at ${py}` };
+  }
+
+  const pipArgs = ["-m", "pip", "install", "--disable-pip-version-check"];
+  if (upgrade) pipArgs.push("--upgrade");
+  pipArgs.push(HERMES_PYPI);
+  const inst = run(py, pipArgs, { quiet });
+  if (inst.status !== 0) {
+    return {
+      ok: false,
+      reason: `pip install ${HERMES_PYPI} failed (${inst.status})`,
+      stderr: (inst.stderr || "").slice(-1200),
+    };
+  }
+
+  const bin = managedHermesPath();
+  if (!fs.existsSync(bin)) {
+    return { ok: false, reason: `hermes entrypoint not found after install (${bin})` };
+  }
+  return { ok: true, bin, reused: false, python: host.version };
+}
+
+export const runtime = {
+  HERMES_PYPI,
+  HERMES_VERSION,
+  UV_PYTHON,
+  runtimeDir,
+  runtimeVenvDir,
+  managedHermesPath,
+  managedPythonPath,
+  managedUvPath,
+  findHostPython,
+  installManagedUv,
+  provisionPythonViaUv,
+  resolveHermes,
+  runtimeStatus,
+  installManagedHermes,
+  whichBin,
+};
+
+export default runtime;

package/src/cli/setup-state.mjs

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  listMessagingPlatforms,
+  findMessagingPlatform,
+  renderSetupMenu,
+} from "./messaging-platforms.mjs";
+import { hermesRoot, ensureDir, oracleConfigDir } from "./paths.mjs";
+
+const SECRETISH = /(TOKEN|SECRET|PASSWORD|KEY|AUTH|PRIVATE|MNEMONIC|SEED)/i;
+
+export function profileEnvPath(profile = "oracle") {
+  return path.join(hermesRoot(), "profiles", profile, ".env");
+}
+
+export function parseDotEnv(text) {
+  const out = {};
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let val = trimmed.slice(eq + 1).trim();
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+export function readProfileEnv(profile = "oracle") {
+  const p = profileEnvPath(profile);
+  if (!fs.existsSync(p)) return {};
+  return parseDotEnv(fs.readFileSync(p, "utf8"));
+}
+
+export function writeProfileEnvKey(profile, key, value) {
+  if (!key || SECRETISH.test(key) === false && /[^A-Z0-9_]/.test(key)) {
+    // keep simple env keys
+  }
+  if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+    const err = new Error(`invalid env key '${key}'`);
+    err.code = "BAD_KEY";
+    throw err;
+  }
+  if (value == null || String(value).trim() === "") {
+    const err = new Error(`empty value for ${key}`);
+    err.code = "EMPTY";
+    throw err;
+  }
+  const p = profileEnvPath(profile);
+  ensureDir(path.dirname(p));
+  let text = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  const lines = text ? text.split(/\r?\n/) : [];
+  const next = [];
+  let replaced = false;
+  const assignment = `${key}=${String(value)}`;
+  for (const line of lines) {
+    if (line.startsWith(`${key}=`)) {
+      next.push(assignment);
+      replaced = true;
+    } else if (line.length || next.length) {
+      next.push(line);
+    }
+  }
+  if (!replaced) {
+    if (next.length && next[next.length - 1] !== "") next.push("");
+    next.push(assignment);
+  }
+  while (next.length && next[next.length - 1] === "") next.pop();
+  next.push("");
+  fs.writeFileSync(p, next.join("\n"), { mode: 0o600 });
+  try {
+    fs.chmodSync(p, 0o600);
+  } catch {
+    // best effort on platforms that ignore mode
+  }
+  return { path: p, key, set: true };
+}
+
+export function platformStatus(profile = "oracle") {
+  const env = readProfileEnv(profile);
+  const statuses = {};
+  for (const p of listMessagingPlatforms()) {
+    if (!p.required.length) {
+      statuses[p.key] = "manual";
+      continue;
+    }
+    const missing = p.required.filter((k) => !String(env[k] || "").trim());
+    statuses[p.key] = missing.length ? "unset" : "ready";
+  }
+  return { profile, statuses, envPath: profileEnvPath(profile) };
+}
+
+export function renderStatus(profile = "oracle") {
+  const { statuses } = platformStatus(profile);
+  return renderSetupMenu({ profile, statuses });
+}
+
+export function setPlatformToken(profile, platformKey, token, extra = {}) {
+  const platform = findMessagingPlatform(platformKey);
+  if (!platform) {
+    const err = new Error(`unknown platform '${platformKey}'`);
+    err.code = "UNKNOWN_PLATFORM";
+    throw err;
+  }
+  if (!platform.required.length) {
+    const err = new Error(
+      `${platform.key} uses hermes interactive setup (oracle setup messaging)`,
+    );
+    err.code = "NEEDS_INTERACTIVE";
+    throw err;
+  }
+  const primary = platform.required[0];
+  writeProfileEnvKey(profile, primary, token);
+  for (const [k, v] of Object.entries(extra || {})) {
+    if (v != null && String(v).trim()) writeProfileEnvKey(profile, k, v);
+  }
+  return {
+    platform: platform.key,
+    set: platform.required,
+    profile,
+    path: profileEnvPath(profile),
+  };
+}
+
+export function setupStatePath() {
+  return path.join(oracleConfigDir(), "setup-state.json");
+}
+
+export function touchSetupState(patch = {}) {
+  ensureDir(oracleConfigDir());
+  const p = setupStatePath();
+  let cur = {};
+  if (fs.existsSync(p)) {
+    try {
+      cur = JSON.parse(fs.readFileSync(p, "utf8"));
+    } catch {
+      cur = {};
+    }
+  }
+  const next = {
+    ...cur,
+    ...patch,
+    updatedAt: new Date().toISOString(),
+    host: os.hostname(),
+  };
+  fs.writeFileSync(p, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+  return next;
+}
+
+export default {
+  profileEnvPath,
+  parseDotEnv,
+  readProfileEnv,
+  writeProfileEnvKey,
+  platformStatus,
+  renderStatus,
+  setPlatformToken,
+  setupStatePath,
+  touchSetupState,
+};

package/src/cli/spawn-child.mjs

@@ -0,0 +1,43 @@
+import { spawn } from "node:child_process";
+
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+export function spawnChild(command, args = [], options = {}, label = command) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, options);
+    let settled = false;
+    let forwardedSignal = null;
+
+    const handlers = new Map(
+      FORWARDED_SIGNALS.map((signal) => [signal, () => {
+        forwardedSignal ||= signal;
+        if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+      }]),
+    );
+    for (const [signal, handler] of handlers) process.on(signal, handler);
+
+    const cleanup = () => {
+      for (const [signal, handler] of handlers) process.off(signal, handler);
+    };
+
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      process.stderr.write(`oracle: could not start ${label}: ${error.message}\n`);
+      resolve(1);
+    });
+
+    child.once("exit", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      const propagated = forwardedSignal || signal;
+      if (propagated) {
+        process.kill(process.pid, propagated);
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+}