@mrdrmccoy/xerj-opencode-plugin 0.0.0-stage → 0.4.0

package/src/node/supervisor.ts

@@ -0,0 +1,267 @@
+// Node lifecycle: attach when a XERJ node already answers, otherwise spawn one
+// detached so it outlives the OpenCode server and the index survives restarts.
+// Verified on v1.0.0-rc.100: `--port` claims PORT, PORT+1 (native REST) and
+// PORT+2 (gRPC), and startup fails if any is taken.
+
+import { spawn } from "node:child_process";
+import { mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { connect } from "node:net";
+import { join } from "node:path";
+import type { Logger } from "../log.ts";
+import { nodeDataDir, nodeLogPath, nodePidPath } from "../paths.ts";
+
+export type NodeState = "xerj" | "foreign" | "down";
+
+export interface NodeHandle {
+  readonly baseUrl: string;
+  readonly port: number;
+  readonly pid: number | null;
+  readonly spawned: boolean;
+  readonly version: string;
+}
+
+export interface EnsureNodeOptions {
+  readonly binaryPath: string;
+  /** XERJ release the binary reports; the banner only carries the wire version. */
+  readonly binaryVersion: string;
+  readonly root: string;
+  readonly dataDir?: string | null;
+  readonly preferredPort: number;
+  readonly persistedPort: number | null;
+  readonly onPort?: (port: number) => Promise<void>;
+  readonly logger: Logger;
+  readonly explicitUrl?: string | null;
+  readonly startupTimeoutMs?: number;
+}
+
+export class NodeError extends Error {
+  constructor(message: string, override readonly cause?: unknown) {
+    super(message);
+    this.name = "NodeError";
+  }
+}
+
+const PORT_SCAN_START = 9200;
+const PORT_SCAN_END = 9399;
+const PORT_STRIDE = 3;
+const HEALTH_POLL_MS = 250;
+const SPAWN_LOCK_MS = 60_000;
+
+/** Identifies a node by `GET /`, so an Elasticsearch on 9200 is not mistaken for XERJ. */
+export async function probeNode(baseUrl: string, timeoutMs = 800): Promise<NodeState> {
+  try {
+    const response = await fetch(`${baseUrl}/`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) return "foreign";
+
+    const body = await response.json().catch(() => null);
+    if (isRecord(body) && body.cluster_name === "xerj") return "xerj";
+    return "foreign";
+  } catch {
+    return "down";
+  }
+}
+
+export async function ensureNode(options: EnsureNodeOptions): Promise<NodeHandle> {
+  const { logger } = options;
+
+  if (options.explicitUrl) {
+    const url = options.explicitUrl.replace(/\/+$/, "");
+    if ((await probeNode(url)) !== "xerj") {
+      throw new NodeError(`XERJ is not answering at ${url}`);
+    }
+    return {
+      baseUrl: url,
+      port: Number(new URL(url).port || 9200),
+      pid: null,
+      spawned: false,
+      version: options.binaryVersion,
+    };
+  }
+
+  const dataDir = options.dataDir ?? nodeDataDir(options.root);
+  await mkdir(dataDir, { recursive: true, mode: 0o700 });
+
+  const candidate = options.persistedPort ?? options.preferredPort;
+  const attached = await attach(candidate, options.binaryVersion);
+  if (attached) return attached;
+
+  const port = await choosePort(candidate);
+  if (port === null) {
+    throw new NodeError(`no free port for XERJ between ${PORT_SCAN_START} and ${PORT_SCAN_END}`);
+  }
+
+  const lock = join(dataDir, ".spawn-lock");
+  if (!(await acquireLock(lock))) {
+    // Another process is spawning; wait for it rather than starting a second node.
+    const existing = await waitForNode(port, options.startupTimeoutMs ?? 30_000, options.binaryVersion);
+    if (existing) return existing;
+    throw new NodeError("another process is starting the XERJ node and it did not come up");
+  }
+
+  try {
+    const second = await attach(port, options.binaryVersion);
+    if (second) return second;
+
+    const pid = await spawnNode(options.binaryPath, dataDir, port, options.root);
+    await options.onPort?.(port);
+
+    const node = await waitForNode(port, options.startupTimeoutMs ?? 30_000, options.binaryVersion);
+    if (!node) {
+      throw new NodeError(`xerj did not answer on port ${port} within 30s`);
+    }
+
+    await writeFile(nodePidPath(options.root), String(pid), { mode: 0o600 }).catch(() => {});
+    logger.info("started the xerj node", { port, pid });
+    return { ...node, pid, spawned: true };
+  } finally {
+    await rm(lock, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+async function attach(port: number, binaryVersion: string): Promise<NodeHandle | null> {
+  const baseUrl = `http://127.0.0.1:${port}`;
+  if ((await probeNode(baseUrl)) !== "xerj") return null;
+
+  return {
+    baseUrl,
+    port,
+    pid: null,
+    spawned: false,
+    version: binaryVersion,
+  };
+}
+
+async function waitForNode(
+  port: number,
+  timeoutMs: number,
+  binaryVersion: string,
+): Promise<NodeHandle | null> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const found = await attach(port, binaryVersion);
+    if (found) return found;
+    await sleep(HEALTH_POLL_MS);
+  }
+  return null;
+}
+
+/** A base port is usable only when PORT, PORT+1 and PORT+2 are all free. */
+async function choosePort(preferred: number): Promise<number | null> {
+  if (preferred >= PORT_SCAN_START && (await portTripleFree(preferred))) return preferred;
+
+  const start = Math.max(PORT_SCAN_START, Math.ceil(preferred / PORT_STRIDE) * PORT_STRIDE);
+  for (let port = start; port + 2 <= PORT_SCAN_END; port += PORT_STRIDE) {
+    if (await portTripleFree(port)) return port;
+  }
+
+  for (let port = PORT_SCAN_START; port + 2 <= PORT_SCAN_END; port += PORT_STRIDE) {
+    if (await portTripleFree(port)) return port;
+  }
+
+  return null;
+}
+
+async function portTripleFree(base: number): Promise<boolean> {
+  for (let offset = 0; offset < 3; offset++) {
+    if (!(await portFree(base + offset))) return false;
+  }
+  return true;
+}
+
+function portFree(port: number): Promise<boolean> {
+  return new Promise((resolvePromise) => {
+    const socket = connect({ host: "127.0.0.1", port });
+    const finish = (free: boolean): void => {
+      socket.destroy();
+      resolvePromise(free);
+    };
+
+    socket.setTimeout(400);
+    socket.once("connect", () => finish(false));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(true));
+  });
+}
+
+async function spawnNode(
+  binary: string,
+  dataDir: string,
+  port: number,
+  root: string,
+): Promise<number> {
+  await mkdir(dataDir, { recursive: true, mode: 0o700 });
+
+  const log = await open(nodeLogPath(root), "a", 0o600);
+  const child = spawn(
+    binary,
+    [
+      "--insecure",
+      "--port",
+      String(port),
+      "--data-dir",
+      dataDir,
+      "--disable-feedback",
+    ],
+    {
+      detached: true,
+      stdio: ["ignore", log.fd, log.fd],
+      env: { ...process.env, XERJ_DISABLE_FEEDBACK: "true" },
+    },
+  );
+
+  child.unref();
+  await log.close().catch(() => {});
+  if (child.pid === undefined) throw new NodeError("xerj exited before it had a pid");
+  return child.pid;
+}
+
+/** `mkdir` is the atomic primitive; a lock older than a minute is stale. */
+async function acquireLock(path: string): Promise<boolean> {
+  try {
+    await mkdir(path, { recursive: false });
+    return true;
+  } catch {
+    const info = await stat(path).catch(() => null);
+    if (info && Date.now() - info.mtimeMs > SPAWN_LOCK_MS) {
+      await rm(path, { recursive: true, force: true }).catch(() => {});
+      return acquireLock(path);
+    }
+    return false;
+  }
+}
+
+export async function readPersistedPort(root: string): Promise<number | null> {
+  const raw = await readFile(join(nodeDataDir(root), "port"), "utf8").catch(() => null);
+  if (raw === null) return null;
+  const port = Number(raw.trim());
+  return Number.isInteger(port) && port > 0 && port < 65_536 ? port : null;
+}
+
+export async function persistPort(root: string, port: number): Promise<void> {
+  await mkdir(nodeDataDir(root), { recursive: true, mode: 0o700 });
+  await writeFile(join(nodeDataDir(root), "port"), String(port), { mode: 0o600 });
+}
+
+export async function stopNode(root: string): Promise<boolean> {
+  const pid = Number(await readFile(nodePidPath(root), "utf8").catch(() => ""));
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+
+  try {
+    process.kill(pid, "SIGTERM");
+    await rm(nodePidPath(root), { force: true });
+    return true;
+  } catch {
+    await rm(nodePidPath(root), { force: true }).catch(() => {});
+    return false;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/paths.ts

@@ -0,0 +1,202 @@
+// Filesystem layout and stable names. Pure so the tests can pin the naming
+// without touching disk: index prefixes are the only identity XERJ keeps
+// between runs, and one wrong character means a second copy of the corpus.
+
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, resolve, sep } from "node:path";
+
+export interface Environment {
+  readonly XDG_DATA_HOME?: string;
+  readonly LOCALAPPDATA?: string;
+  readonly HOME?: string;
+}
+
+/** Picks the variables that matter out of a wider process environment. */
+export function environmentFrom(env: Readonly<Record<string, string | undefined>>): Environment {
+  return {
+    XDG_DATA_HOME: env.XDG_DATA_HOME,
+    LOCALAPPDATA: env.LOCALAPPDATA,
+    HOME: env.HOME,
+  };
+}
+
+const APP_DIR = "opencode/xerj";
+const PREFIX_ROOT = "xop";
+const MAX_SLUG_LENGTH = 24;
+const HASH_LENGTH = 8;
+
+/** Root for the binary, node data, and spool. Independent of any project. */
+export function dataRoot(env: Environment, platform: NodeJS.Platform = process.platform): string {
+  if (platform === "win32") {
+    const local = env.LOCALAPPDATA ?? join(env.HOME ?? homedir(), "AppData", "Local");
+    return join(local, APP_DIR);
+  }
+
+  if (platform === "darwin") {
+    const base = env.XDG_DATA_HOME ?? join(env.HOME ?? homedir(), "Library", "Application Support");
+    return join(base, APP_DIR);
+  }
+
+  const base = env.XDG_DATA_HOME ?? join(env.HOME ?? homedir(), ".local", "share");
+  return join(base, APP_DIR);
+}
+
+export function binaryPath(
+  root: string,
+  version: string,
+  platform: NodeJS.Platform,
+  target: string,
+): string {
+  // The target is part of the directory so a shared data root can hold more
+  // than one platform's binary without one overwriting the other.
+  return join(root, "bin", `${version}-${target}`, binaryName(platform));
+}
+
+export function binaryName(platform: NodeJS.Platform): string {
+  return platform === "win32" ? "xerj.exe" : "xerj";
+}
+
+export function nodeDataDir(root: string): string {
+  return join(root, "data");
+}
+
+export function nodeLogPath(root: string): string {
+  return join(root, "data", "node.log");
+}
+
+export function nodePidPath(root: string): string {
+  return join(root, "data", "node.pid");
+}
+
+export function releaseCachePath(root: string): string {
+  return join(root, "release-cache.json");
+}
+
+export function spoolDir(root: string, prefix: string): string {
+  return join(root, "spool", prefix);
+}
+
+/** Project-local state: ignore file and caches. Never the engine index. */
+export function projectStateDir(projectRoot: string): string {
+  return join(projectRoot, ".xerj");
+}
+
+
+/** Lowercase alphanumeric slug, joined by single dashes. */
+export function slug(name: string, maxLength = MAX_SLUG_LENGTH): string {
+  const cleaned = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  if (cleaned.length === 0) return "project";
+  return cleaned.slice(0, maxLength).replace(/-+$/g, "");
+}
+
+/** First `length` hex characters of the canonical path's SHA-256. */
+export function pathHash(directory: string, length = HASH_LENGTH): string {
+  const canonical = resolve(directory).split(sep).join("/");
+  return createHash("sha256").update(canonical).digest("hex").slice(0, length);
+}
+
+/**
+ * One prefix per folder. XERJ refuses to index two folders under one prefix,
+ * so the path hash is part of the name, not a nicety.
+ */
+export function indexPrefix(directory: string): string {
+  return `${PREFIX_ROOT}-${slug(basename(resolve(directory)))}-${pathHash(directory)}`;
+}
+
+export function webPrefix(directory: string): string {
+  return `${PREFIX_ROOT}-web-${pathHash(directory)}`;
+}
+
+export function externalPrefix(directory: string): string {
+  return `${PREFIX_ROOT}-ext-${pathHash(directory)}`;
+}
+
+export function brainPrefix(directory: string, brain: string, hashLength = 6): string {
+  return (
+    `${PREFIX_ROOT}-${slug(brain, 16)}-` +
+    `${pathHash(directory, hashLength)}`
+  );
+}
+
+export interface DocumentRoot {
+  readonly label: string;
+  readonly directory: string;
+}
+
+/** Resolves configured folders relative to the project, dropping duplicates. */
+export function documentRoots(
+  projectRoot: string,
+  labels: ReadonlyArray<string>,
+): DocumentRoot[] {
+  const seen = new Set<string>();
+
+  return labels.flatMap((label) => {
+    const trimmed = label.trim();
+    const directory = isAbsolute(trimmed)
+      ? resolve(trimmed)
+      : resolve(join(projectRoot, trimmed));
+    if (seen.has(directory)) return [];
+    seen.add(directory);
+    return [{ label: trimmed, directory }];
+  });
+}
+
+export interface BrainSpec {
+  /** Graph name, also the `--brain` argument. */
+  readonly name: string;
+  /** The configured value, e.g. `.agents` or `docs/notes`. */
+  readonly label: string;
+  readonly directory: string;
+  readonly prefix: string;
+}
+
+/**
+ * One brain per configured folder. The graph name is the folder's basename, so
+ * `index.brain: [".agents"]` produces brain `agents`; duplicate basenames get a
+ * numeric suffix rather than silently sharing an edge index.
+ */
+export function brainSpecs(
+  projectRoot: string,
+  labels: ReadonlyArray<string>,
+): BrainSpec[] {
+  const used = new Map<string, number>();
+  const seenDirs = new Set<string>();
+
+  return labels.flatMap((label) => {
+    const trimmed = label.trim();
+    const directory = isAbsolute(trimmed)
+      ? resolve(trimmed)
+      : resolve(join(projectRoot, trimmed));
+
+    // The same folder configured twice is one brain, not two graphs.
+    if (seenDirs.has(directory)) return [];
+    seenDirs.add(directory);
+
+    // The graph name is global to the node, while projects share one node.
+    // A folder hash keeps two projects' `agents` brains from sharing edges.
+    const folder = slug(basename(directory), 12);
+    const base = `${folder}-${pathHash(directory, 4)}`;
+    const seen = (used.get(base) ?? 0) + 1;
+    used.set(base, seen);
+    const name = seen === 1 ? base : `${base}-${seen}`;
+
+    return [
+      {
+        name,
+        label: trimmed,
+        directory,
+        prefix: brainPrefix(directory, folder),
+      },
+    ];
+  });
+}
+
+/** Memory namespaces are their own index; the project hash keeps them apart. */
+export function memoryNamespace(directory: string): string {
+  return `proj-${slug(basename(resolve(directory)))}-${pathHash(directory)}`;
+}

package/src/platform.ts

@@ -0,0 +1,88 @@
+// Release target selection. Mirrors the official installer: Linux defaults to
+// the static musl build, and a Rosetta shell on Apple Silicon gets the native
+// arm64 binary rather than a translated x86_64 one.
+
+export type ArchiveKind = "tar.gz" | "zip";
+export type Libc = "musl" | "gnu";
+
+export interface PlatformInfo {
+  readonly target: string;
+  readonly archive: ArchiveKind;
+  readonly binary: string;
+}
+
+const ARCH: Record<string, string> = {
+  x64: "x86_64",
+  arm64: "aarch64",
+};
+
+/** Returns null for a platform XERJ does not publish. */
+export function releaseTarget(
+  platform: NodeJS.Platform,
+  arch: string,
+  rosetta = false,
+  libc: Libc = "musl",
+): PlatformInfo | null {
+  let cpu = ARCH[arch];
+  if (!cpu) return null;
+
+  if (platform === "darwin" || platform === "linux") {
+    if (platform === "darwin" && rosetta) cpu = "aarch64";
+    const suffix =
+      platform === "darwin"
+        ? "apple-darwin"
+        : libc === "gnu"
+          ? "unknown-linux-gnu"
+          : "unknown-linux-musl";
+    return { target: `${cpu}-${suffix}`, archive: "tar.gz", binary: "xerj" };
+  }
+
+  if (platform === "win32") {
+    return { target: `${cpu}-pc-windows-msvc`, archive: "zip", binary: "xerj.exe" };
+  }
+
+  return null;
+}
+
+/** Builds PlatformInfo from an explicit target, for pinned or exotic hosts. */
+export function platformInfoForTarget(
+  target: string,
+  platform: NodeJS.Platform,
+): PlatformInfo | null {
+  const trimmed = target.trim();
+  if (!/^(x86_64|aarch64)-[a-z0-9-]+$/.test(trimmed)) return null;
+
+  const windows = trimmed.includes("windows");
+  if (windows && platform !== "win32") return null;
+  if (!windows && platform === "win32") return null;
+
+  return {
+    target: trimmed,
+    archive: windows ? "zip" : "tar.gz",
+    binary: windows ? "xerj.exe" : "xerj",
+  };
+}
+
+/**
+ * Node reports the architecture of the process, which lies in two cases: an
+ * x86_64 Node under Rosetta 2 on Apple Silicon, and an x64 Node on Windows
+ * ARM64. Both should install the native arm64 build.
+ */
+export function effectiveArch(
+  platform: NodeJS.Platform,
+  arch: string,
+  env: Readonly<Record<string, string | undefined>>,
+  rosetta = false,
+): string {
+  if (platform === "darwin" && rosetta) return "arm64";
+  if (platform !== "win32") return arch;
+
+  const reported = (env.PROCESSOR_ARCHITECTURE ?? env.PROCESSOR_ARCHITEW6432 ?? "").toUpperCase();
+  if (reported === "ARM64" && arch === "x64") return "arm64";
+  return arch;
+}
+
+/** Rosetta detection is a runtime fact; keep the pure selection separate. */
+export function isRosetta(sysctlOutput: string): boolean {
+  return sysctlOutput.trim() === "1";
+}