@skastr0/prism-sdk 0.3.0

package/dist/mcp/uds-registry.js

@@ -0,0 +1,270 @@
+import { mkdir, writeFile, readFile, unlink, readdir, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+/**
+ * Error type for registry operation violations.
+ * Used to distinguish registry errors from other file system errors.
+ */
+export class UDSRegistryError extends Error {
+    context;
+    kind = "uds-registry-error";
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = "UDSRegistryError";
+    }
+}
+/**
+ * Storage layout
+ * --------------
+ * Each plugin owns its own registry file:
+ *
+ *   ~/.prism/runtime/mcp/<plugin>/<hash>.registry.json
+ *
+ * where `<hash>` is a short content-addressed digest of the plugin name.
+ * There is deliberately no single shared registry.json spanning every
+ * plugin: registering plugin A never touches any file plugin B reads or
+ * writes, so concurrent registrations across different plugins cannot race
+ * on the same path and cannot drop each other's entries. Within one
+ * plugin's file, writes are still atomic (write-temp + rename), so the
+ * per-plugin file itself is never observed half-written.
+ */
+/** `~/.prism/runtime/mcp` — the root of all registry state. */
+function registryRootDir() {
+    return join(homedir(), ".prism", "runtime", "mcp");
+}
+/**
+ * Filesystem-safe representation of a plugin name for use as a directory
+ * segment. Plugin names may contain characters (e.g. `/` in a scoped name
+ * like `@scope/plugin`) that would otherwise create unintended nested
+ * directories; the original, unsanitized name is preserved inside the
+ * stored record itself (see `StoredRecord`) so readers never need to
+ * reverse this transform.
+ */
+function sanitizePluginSegment(plugin) {
+    const sanitized = plugin.replace(/[^a-zA-Z0-9._-]/g, "_");
+    return sanitized.length > 0 ? sanitized : "_";
+}
+function pluginDir(plugin) {
+    return join(registryRootDir(), sanitizePluginSegment(plugin));
+}
+/**
+ * Deterministic, content-addressed file name for a plugin's registration
+ * record: every reader and writer for a given plugin name resolves to
+ * exactly this one path, so there is never ambiguity about which file is
+ * "the" current record for that plugin.
+ */
+function pluginRegistryFilePath(plugin) {
+    const hash = createHash("sha256").update(plugin).digest("hex").slice(0, 16);
+    return join(pluginDir(plugin), `${hash}.registry.json`);
+}
+function isValidStoredRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return (typeof record.plugin === "string" &&
+        typeof record.pid === "number" &&
+        typeof record.sock === "string" &&
+        typeof record.bundleHash === "string" &&
+        typeof record.startedAt === "number" &&
+        typeof record.lastUsed === "number");
+}
+async function ensurePluginDir(plugin) {
+    try {
+        await mkdir(pluginDir(plugin), { recursive: true });
+    }
+    catch {
+        // Directory may already exist; proceed.
+    }
+}
+/**
+ * Atomically write a single plugin's registration record via write-temp +
+ * rename. Because each plugin owns a distinct file, this never reads or
+ * merges another plugin's (or another write's) data — there is no
+ * read-modify-write of shared state to race on.
+ *
+ * Throws UDSRegistryError on I/O failure (unrecoverable).
+ */
+async function writePluginEntry(plugin, entry) {
+    try {
+        await ensurePluginDir(plugin);
+    }
+    catch (error) {
+        throw new UDSRegistryError(`Failed to ensure registry directory for plugin ${plugin}: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+    const finalPath = pluginRegistryFilePath(plugin);
+    const randomSuffix = Math.random().toString(36).substring(2, 10);
+    const tempPath = `${finalPath}.tmp.${process.pid}.${Date.now()}.${randomSuffix}`;
+    const stored = { ...entry, plugin };
+    try {
+        await writeFile(tempPath, JSON.stringify(stored, null, 2), "utf8");
+        await rename(tempPath, finalPath);
+    }
+    catch (error) {
+        try {
+            await unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup failures
+        }
+        throw new UDSRegistryError(`Failed to write registry entry for plugin ${plugin}: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+}
+/**
+ * Read a single plugin's registration record. Returns undefined if the file
+ * does not exist, is corrupted, or is missing required fields — never
+ * throws.
+ */
+async function readPluginEntry(plugin) {
+    try {
+        const json = await readFile(pluginRegistryFilePath(plugin), "utf8");
+        const parsed = JSON.parse(json);
+        if (!isValidStoredRecord(parsed))
+            return undefined;
+        const { plugin: _plugin, ...entry } = parsed;
+        return entry;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Register a new daemon instance or update an existing one.
+ *
+ * Atomically writes the entry to this plugin's own registry file. Never
+ * reads or rewrites any other plugin's file.
+ *
+ * Throws UDSRegistryError on I/O failure (unrecoverable).
+ */
+export async function registerDaemon(plugin, entry) {
+    await writePluginEntry(plugin, entry);
+}
+/**
+ * Unregister a daemon instance by plugin name.
+ *
+ * Removes this plugin's registry file. Does nothing (no error) if the
+ * entry does not exist.
+ *
+ * Throws UDSRegistryError on I/O failure (unrecoverable), file-not-found excepted.
+ */
+export async function unregisterDaemon(plugin) {
+    try {
+        await unlink(pluginRegistryFilePath(plugin));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw new UDSRegistryError(`Failed to unregister plugin ${plugin}: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+}
+/**
+ * Get a single daemon entry by plugin name.
+ *
+ * Returns `{ kind: "ok", value: entry }` on success.
+ * Returns `{ kind: "absent" }` if the plugin is not registered or
+ * the registry is corrupted.
+ *
+ * Never throws.
+ */
+export async function getDaemon(plugin) {
+    const entry = await readPluginEntry(plugin);
+    return entry ? { kind: "ok", value: entry } : { kind: "absent" };
+}
+/**
+ * Get all registered daemon entries across every plugin.
+ *
+ * Returns `{ kind: "ok", value: data }` on success (may be empty).
+ * Returns `{ kind: "absent" }` if the registry root directory does not
+ * exist yet (nothing has ever registered).
+ *
+ * Never throws; unreadable or corrupted per-plugin files are skipped
+ * individually rather than failing the whole scan.
+ */
+export async function getAllDaemons() {
+    const root = registryRootDir();
+    let pluginDirs;
+    try {
+        pluginDirs = await readdir(root);
+    }
+    catch {
+        return { kind: "absent" };
+    }
+    const data = {};
+    for (const dirName of pluginDirs) {
+        let files;
+        try {
+            files = await readdir(join(root, dirName));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.endsWith(".registry.json"))
+                continue;
+            try {
+                const json = await readFile(join(root, dirName, file), "utf8");
+                const parsed = JSON.parse(json);
+                if (!isValidStoredRecord(parsed))
+                    continue;
+                const { plugin, ...entry } = parsed;
+                data[plugin] = entry;
+            }
+            catch {
+                // Skip unreadable/corrupted per-plugin files; they do not affect
+                // any other plugin's data.
+            }
+        }
+    }
+    return { kind: "ok", value: data };
+}
+/**
+ * Update the lastUsed timestamp for a daemon entry.
+ *
+ * Returns `{ kind: "ok" }` on success.
+ * Returns `{ kind: "absent" }` if the plugin is not registered.
+ *
+ * Throws UDSRegistryError on I/O failure (unrecoverable).
+ */
+export async function touchDaemon(plugin) {
+    const entry = await readPluginEntry(plugin);
+    if (!entry) {
+        return { kind: "absent" };
+    }
+    await writePluginEntry(plugin, { ...entry, lastUsed: Date.now() });
+    return { kind: "ok", value: undefined };
+}
+/**
+ * Ownership-gated teardown for a daemon's registration and socket file.
+ *
+ * Re-reads the current registry record for `plugin` and only acts — unlink
+ * `socketPath` and remove the registry entry — when that record's pid
+ * matches `pid`, i.e. when the caller is still the process the registry
+ * currently considers live for that plugin.
+ *
+ * This exists to protect a fast-respawning successor: if a predecessor is
+ * slow to drain and only calls this after a successor has already bound
+ * the same socket path and re-registered under the same plugin key, the
+ * registry record now names the successor's pid — a missing record or one
+ * naming a different pid means "not mine to clean up", so the successor's
+ * live socket file and registration are left completely untouched.
+ */
+export async function cleanupDaemonIfOwner(plugin, pid, socketPath) {
+    const result = await getDaemon(plugin);
+    if (result.kind === "absent") {
+        return "absent";
+    }
+    if (result.value.pid !== pid) {
+        return "not-owner";
+    }
+    if (socketPath) {
+        try {
+            await unlink(socketPath);
+        }
+        catch {
+            // Socket may already be gone; non-fatal.
+        }
+    }
+    await unregisterDaemon(plugin);
+    return "cleaned";
+}

package/dist/mcp/uds-singleton.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Error type for singleton/stale-socket violations.
+ */
+export declare class UDSSingletonError extends Error {
+    readonly context?: unknown | undefined;
+    readonly kind: "uds-singleton-error";
+    constructor(message: string, context?: unknown | undefined);
+}
+/**
+ * Result of probing for an existing live daemon on a socket path.
+ *
+ * - "live": Another daemon is running on this socket; this process should exit.
+ * - "stale": Socket file exists but the daemon is not responding; safe to unlink and bind.
+ * - "available": Socket path is free; bind immediately.
+ */
+export type ProbeResult = "live" | "stale" | "available";
+/**
+ * Attempt to connect to an existing Unix domain socket to detect a live daemon.
+ *
+ * Returns "live" if a connection succeeds (live daemon).
+ * Returns "stale" if connection is refused/times out (socket file exists but no daemon).
+ * Returns "available" if the socket file does not exist.
+ *
+ * @param socketPath Absolute path to the UDS socket
+ * @param timeoutMs How long to wait before considering a connection attempt stale
+ */
+export declare function probeSocketLiveness(socketPath: string, timeoutMs?: number): Promise<ProbeResult>;
+/**
+ * Acquire a lock via exclusive file creation (fs `wx` open), with
+ * dead-holder reclamation and retry.
+ *
+ * Only one concurrent caller can ever hold the lock: the underlying
+ * `open(lockPath, "wx")` is an atomic O_CREAT|O_EXCL create that fails with
+ * EEXIST for every caller after the first, unlike a rename-based scheme
+ * (which silently replaces the destination and lets every racer "succeed").
+ *
+ * On EEXIST, the recorded holder's pid is liveness-checked via
+ * `process.kill(pid, 0)`: a dead holder's lock file is reclaimed (unlinked)
+ * and creation is retried once immediately; a live holder means the lock is
+ * genuinely held elsewhere, so this attempt waits out the retry interval
+ * and tries again until timeoutMs elapses.
+ *
+ * @param lockPath Path to the lock file
+ * @param timeoutMs How long to wait
+ * @param pid Process ID to write into the lock file
+ */
+export declare function acquireLock(lockPath: string, timeoutMs: number, pid: number): Promise<boolean>;
+/**
+ * Atomically probe and recover from a stale socket using a lock file for race safety.
+ *
+ * On the first call (or after lock acquisition), probes for a live daemon:
+ * - If live: returns "live" immediately (this process should exit)
+ * - If stale: unlinks the socket file and returns "stale-recovered"
+ * - If available: returns "available" immediately
+ *
+ * The lock file (at `<socketPath>.lock`) ensures only one process enters the
+ * probe-unlink-bind critical section at a time. Two simultaneous spawners will
+ * race to acquire the lock; the winner probes/unlinks/binds, the loser re-probes
+ * and discovers "live" (sees the winner's bound socket) and exits.
+ *
+ * @param socketPath Absolute path to the UDS socket
+ * @param lockTimeoutMs How long to wait acquiring the lock file
+ * @returns "live" (other daemon won the race), "stale-recovered" (unlinked stale socket), or "available" (free to bind)
+ * @throws UDSSingletonError if lock acquisition fails or other I/O errors
+ */
+export declare function probeAndRecoverWithLock(socketPath: string, lockTimeoutMs?: number): Promise<"live" | "stale-recovered" | "available">;
+/**
+ * Ensure the daemon can bind to the given socket path, handling stale sockets.
+ *
+ * This is the high-level entry point for singleton + stale-socket recovery.
+ * Call this before binding to a UDS socket in your server:
+ *
+ * ```
+ * const result = await ensureSocketBindability(socketPath);
+ * if (result === "live") {
+ *   // Another daemon already owns this socket; exit gracefully
+ *   process.exit(0);
+ * }
+ * // result is "stale-recovered" or "available"; proceed with binding
+ * ```
+ *
+ * @param socketPath Absolute path to the UDS socket
+ * @returns "live" if another daemon owns the socket (exit immediately),
+ *          or "stale-recovered"/"available" (safe to bind)
+ * @throws UDSSingletonError on unrecoverable errors (lock acquisition, etc.)
+ */
+export declare function ensureSocketBindability(socketPath: string): Promise<"live" | "stale-recovered" | "available">;
+/**
+ * Outcome of `bindUnixSocketSingleton`.
+ *
+ * - "bound": this call's `bind` callback ran and its result is attached.
+ * - "already-served": a live daemon already owns the socket; the caller
+ *   should exit cleanly (e.g. `process.exit(0)`) without ever binding.
+ */
+export type UdsBindOutcome<T> = {
+    readonly kind: "bound";
+    readonly server: T;
+} | {
+    readonly kind: "already-served";
+};
+/**
+ * Probe, recover from a stale socket, and invoke `bind()` — all inside the
+ * single critical section held by the `<socketPath>.lock` file.
+ *
+ * This closes the race the two-step "check bindability, then bind()
+ * separately" pattern leaves open: between releasing the probe/unlink lock
+ * and actually calling `bind()`, another process could probe the same
+ * now-empty path, also decide it is free, and race this one to `bind()`.
+ * Here `bind()` itself runs while the lock is still held, so at most one
+ * process per lock ever reaches it while the path is in the
+ * stale/available state.
+ *
+ * `bind()` is also wrapped in try/catch: if it still throws EADDRINUSE
+ * (e.g. a process outside this locking scheme bound the path, or a timing
+ * gap before the lock was acquired), the live owner is re-probed — if it
+ * responds, this process reports "already-served" instead of crashing
+ * uncaught; if it does not respond, the socket is stale, and `bind()` is
+ * retried exactly once after unlinking it.
+ *
+ * @param socketPath Absolute path to the UDS socket
+ * @param bind Callback that performs the actual bind (e.g. `() => Bun.serve(...)`)
+ * @param lockTimeoutMs How long to wait acquiring the lock file
+ */
+export declare function bindUnixSocketSingleton<T>(socketPath: string, bind: () => T | Promise<T>, lockTimeoutMs?: number): Promise<UdsBindOutcome<T>>;