@cueloop/daemon 0.1.0-alpha.0

package/src/server.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonServer } from "./server";
+import { DaemonClient, DaemonClientError } from "./client";
+import type { Artifact, WorkspaceKey } from "@cueloop/schema";
+
+const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
+const PLAN: Artifact = { type: "plan", content: "# P\n\nBody text.\n", meta: {} };
+
+let home: string;
+let server: DaemonServer;
+let client: DaemonClient;
+
+beforeEach(async () => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-srv-"));
+  server = new DaemonServer({ home, idleExitMs: 0 });
+  server.start();
+  client = await DaemonClient.connect({ home });
+});
+afterEach(() => {
+  client.close();
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("socket round-trip", () => {
+  test("ping and full session flow over the wire", async () => {
+    expect((await client.ping()).pid).toBe(process.pid);
+    const s = await client.sessionCreate(WS, PLAN);
+    expect(s.status).toBe("pending");
+    await client.sessionAnnotate(s.id, {
+      id: "a1",
+      kind: "comment",
+      anchor: { quote: "Body text", prefix: "", suffix: "." },
+      body: "More detail please.",
+    });
+    const wait = client.sessionWait(s.id, 5_000);
+    await client.sessionResolve(s.id, "request_changes", "Expand it.");
+    const resolved = (await wait)!;
+    expect(resolved.verdict!.kind).toBe("request_changes");
+    expect(resolved.verdict!.feedback).toContain("More detail please.");
+  });
+
+  test("errors carry codes across the wire", async () => {
+    expect(client.sessionGet("nope")).rejects.toBeInstanceOf(DaemonClientError);
+    try {
+      await client.sessionGet("nope");
+    } catch (e) {
+      expect((e as DaemonClientError).code).toBe("not_found");
+    }
+  });
+
+  test("events push to subscribed connections only", async () => {
+    const observer = await DaemonClient.connect({ home });
+    const seen: string[] = [];
+    observer.onEvent((e) => seen.push(e.event));
+    await observer.subscribe();
+    const s = await client.sessionCreate(WS, PLAN);
+    await client.sessionResolve(s.id, "approve", "");
+    // events are pushed async over the socket; give the loop a beat
+    await Bun.sleep(50);
+    expect(seen).toContain("session.created");
+    expect(seen).toContain("session.resolved");
+    observer.close();
+  });
+
+  test("malformed requests get structured errors and never wedge the daemon", async () => {
+    // missing required params
+    try {
+      await client.request("session.create", { artifact: { type: "plan", content: "x" } });
+      throw new Error("should have thrown");
+    } catch (e) {
+      expect((e as DaemonClientError).code).toBe("invalid_params");
+    }
+    // wrong types
+    try {
+      await client.request("session.wait", { id: 42 });
+      throw new Error("should have thrown");
+    } catch (e) {
+      expect((e as DaemonClientError).code).toBe("invalid_params");
+    }
+    // unknown method
+    try {
+      await client.request("session.nuke", {});
+      throw new Error("should have thrown");
+    } catch (e) {
+      expect((e as DaemonClientError).code).toBe("unknown_method");
+    }
+    // the daemon is still fully alive afterwards
+    const s = await client.sessionCreate(WS, PLAN);
+    expect((await client.sessionGet(s.id)).id).toBe(s.id);
+  });
+
+  test("two clients see the same state (thin-renderer model)", async () => {
+    const second = await DaemonClient.connect({ home });
+    const s = await client.sessionCreate(WS, PLAN);
+    const fromSecond = await second.sessionGet(s.id);
+    expect(fromSecond.artifact.content).toBe(PLAN.content);
+    second.close();
+  });
+});

package/src/server.ts

@@ -0,0 +1,250 @@
+/**
+ * The socket server: binds DaemonCore's methods to the unix socket, owns the
+ * pidfile, stale-socket cleanup, and the idle-exit timer (#14). File
+ * permissions are the local auth: the socket and state dir are 0700/0600.
+ */
+
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { DaemonCore, type DaemonEvent } from "./api";
+import { DaemonError } from "./errors";
+import { isKnownMethod, parseParams } from "./validate";
+import { LineBuffer, type Request } from "./protocol";
+import { cueloopHome, lockPath, pidPath, socketPath } from "./paths";
+
+interface Conn {
+  write(data: string): void;
+  subscribed: boolean;
+}
+
+export interface DaemonOptions {
+  home?: string;
+  /** Idle-exit delay; 0 disables (tests, foreground runs). */
+  idleExitMs?: number;
+  onIdleExit?: () => void;
+}
+
+/**
+ * Homes locked by a DaemonServer in THIS process. The on-disk lock's pid check
+ * cannot distinguish two instances inside one process (tests do exactly that),
+ * so in-process ownership is tracked separately.
+ */
+const HELD_HOMES = new Set<string>();
+
+export class DaemonServer {
+  readonly core: DaemonCore;
+  readonly home: string;
+  private conns = new Set<Conn>();
+  private server: ReturnType<typeof Bun.listen> | null = null;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private lockFd: number | null = null;
+  private readonly idleExitMs: number;
+  private readonly onIdleExit: () => void;
+
+  constructor(opts: DaemonOptions = {}) {
+    this.home = opts.home ?? cueloopHome();
+    this.idleExitMs = opts.idleExitMs ?? 15 * 60 * 1000;
+    this.onIdleExit = opts.onIdleExit ?? (() => process.exit(0));
+    mkdirSync(this.home, { recursive: true, mode: 0o700 });
+    this.core = new DaemonCore(this.home);
+    this.core.onEvent((e) => this.broadcast(e));
+  }
+
+  /**
+   * Exclusive single-instance lock over a cueloop home. Without it, two
+   * concurrent autostarts both bind: the second unlinks the first's socket and
+   * binds a fresh inode, leaving two daemons with divergent in-memory state
+   * over the same session files - clients then see whichever half won the race.
+   * Returns false when a live daemon already owns this home.
+   */
+  private acquireLock(): boolean {
+    if (HELD_HOMES.has(this.home)) return false; // another instance here owns it
+    const path = lockPath(this.home);
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        // "wx" fails when the file exists - the atomic part of the handshake
+        const fd = openSync(path, "wx");
+        writeFileSync(fd, String(process.pid));
+        this.lockFd = fd;
+        HELD_HOMES.add(this.home);
+        return true;
+      } catch {
+        let ownerPid = 0;
+        try {
+          ownerPid = Number(readFileSync(path, "utf8").trim());
+        } catch {
+          // the owner vanished between open and read; retry
+          continue;
+        }
+        if (ownerPid && ownerPid !== process.pid) {
+          try {
+            process.kill(ownerPid, 0); // throws when the pid is gone
+            return false; // a live daemon owns this home
+          } catch {
+            // stale lock from a crashed daemon
+          }
+        }
+        // ownerPid === our pid but HELD_HOMES says we do not own it: a stale
+        // file from an earlier instance in this process - reclaim it.
+        try {
+          rmSync(path, { force: true });
+        } catch {
+          return false;
+        }
+      }
+    }
+    return false;
+  }
+
+  private releaseLock(): void {
+    HELD_HOMES.delete(this.home);
+    if (this.lockFd !== null) {
+      try {
+        closeSync(this.lockFd);
+      } catch {
+        // already closed
+      }
+      this.lockFd = null;
+    }
+    rmSync(lockPath(this.home), { force: true });
+  }
+
+  /**
+   * Bind the socket and serve. Returns null when another live daemon already
+   * owns this home - the caller should attach to it instead of competing.
+   */
+  start(): string | null {
+    if (!this.acquireLock()) return null;
+    const path = socketPath(this.home);
+    // safe now: holding the lock means no live daemon owns this home, so any
+    // socket file left behind is stale
+    if (existsSync(path)) rmSync(path, { force: true });
+    const self = this;
+    this.server = Bun.listen<{ buffer: LineBuffer; conn: Conn }>({
+      unix: path,
+      socket: {
+        open(socket) {
+          const conn: Conn = { write: (d) => socket.write(d), subscribed: false };
+          socket.data = { buffer: new LineBuffer(), conn };
+          self.conns.add(conn);
+          self.scheduleIdleCheck();
+        },
+        data(socket, data) {
+          socket.data.buffer.push(data.toString(), (line) => {
+            void self.handleLine(socket.data.conn, line);
+          });
+        },
+        close(socket) {
+          self.conns.delete(socket.data.conn);
+          self.scheduleIdleCheck();
+        },
+        error() {},
+      },
+    });
+    chmodSync(path, 0o600);
+    writeFileSync(pidPath(this.home), String(process.pid));
+    this.scheduleIdleCheck();
+    return path;
+  }
+
+  stop(): void {
+    this.server?.stop(true);
+    this.server = null;
+    rmSync(socketPath(this.home), { force: true });
+    rmSync(pidPath(this.home), { force: true });
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.releaseLock();
+  }
+
+  private broadcast(e: DaemonEvent): void {
+    const frame = JSON.stringify(e) + "\n";
+    for (const c of this.conns) if (c.subscribed) c.write(frame);
+    this.scheduleIdleCheck();
+  }
+
+  /** Idle = no pending session and no attached client. */
+  private scheduleIdleCheck(): void {
+    if (this.idleExitMs <= 0) return;
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => {
+      if (this.conns.size === 0 && !this.core.hasPendingSessions()) {
+        this.stop();
+        this.onIdleExit();
+      } else {
+        this.scheduleIdleCheck();
+      }
+    }, this.idleExitMs);
+  }
+
+  private async handleLine(conn: Conn, line: string): Promise<void> {
+    let req: Request;
+    try {
+      req = JSON.parse(line) as Request;
+    } catch {
+      conn.write(JSON.stringify({ id: -1, error: { code: "bad_json", message: "unparseable request" } }) + "\n");
+      return;
+    }
+    try {
+      const result = await this.dispatch(conn, req);
+      conn.write(JSON.stringify({ id: req.id, result }) + "\n");
+    } catch (err) {
+      const code = err instanceof DaemonError ? err.code : "internal";
+      const message = err instanceof Error ? err.message : String(err);
+      conn.write(JSON.stringify({ id: req.id, error: { code, message } }) + "\n");
+    }
+  }
+
+  private async dispatch(conn: Conn, req: Request): Promise<unknown> {
+    // The wire is untrusted JSON: validate before DaemonCore sees anything.
+    if (typeof req.method !== "string" || !isKnownMethod(req.method)) {
+      throw new DaemonError("unknown_method", `unknown method ${String(req.method)}`);
+    }
+    const core = this.core;
+    switch (req.method) {
+      case "daemon.ping":
+        return { pid: process.pid };
+      case "daemon.shutdown":
+        setTimeout(() => {
+          this.stop();
+          this.onIdleExit();
+        }, 10);
+        return {};
+      case "events.subscribe":
+        conn.subscribed = true;
+        return {};
+      case "session.create": {
+        const p = parseParams("session.create", req.params);
+        return core.sessionCreate({ workspace: p.workspace, artifact: p.artifact });
+      }
+      case "session.get":
+        return core.sessionGet(parseParams("session.get", req.params).id);
+      case "session.list":
+        return core.sessionList(parseParams("session.list", req.params).filter);
+      case "session.wait": {
+        const p = parseParams("session.wait", req.params);
+        return core.sessionWait(p.id, p.timeoutMs);
+      }
+      case "session.annotate": {
+        const p = parseParams("session.annotate", req.params);
+        return core.sessionAnnotate(p.id, p.annotation);
+      }
+      case "session.removeAnnotation": {
+        const p = parseParams("session.removeAnnotation", req.params);
+        return core.sessionRemoveAnnotation(p.id, p.annotationId);
+      }
+      case "session.setWorkingCopy": {
+        const p = parseParams("session.setWorkingCopy", req.params);
+        return core.sessionSetWorkingCopy(p.id, p.workingCopy);
+      }
+      case "session.resolve": {
+        const p = parseParams("session.resolve", req.params);
+        return core.sessionResolve(p.id, p.verdictKind, p.summary);
+      }
+      case "session.submitRevision": {
+        const p = parseParams("session.submitRevision", req.params);
+        return core.sessionSubmitRevision(p.id, p.content);
+      }
+      default:
+        throw new DaemonError("unknown_method", `unknown method ${req.method}`);
+    }
+  }
+}

package/src/single-instance.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Single-instance guarantee (#14): one daemon per home. Two daemons over one
+ * state directory means divergent in-memory sessions and clients seeing
+ * whichever half they connect to.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonServer } from "./server";
+import { DaemonClient } from "./client";
+import { lockPath, socketPath } from "./paths";
+import type { Artifact, WorkspaceKey } from "@cueloop/schema";
+
+const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
+const PLAN: Artifact = { type: "plan", content: "# P\n\nBody.\n", meta: {} };
+
+let home: string;
+const servers: DaemonServer[] = [];
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-lock-"));
+});
+afterEach(() => {
+  for (const s of servers.splice(0)) s.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+function server(): DaemonServer {
+  const s = new DaemonServer({ home, idleExitMs: 0 });
+  servers.push(s);
+  return s;
+}
+
+describe("one daemon per home", () => {
+  test("the second start is refused instead of stealing the socket", () => {
+    const first = server();
+    const path = first.start();
+    expect(path).toBe(socketPath(home));
+    const second = server();
+    expect(second.start()).toBeNull();
+    // the winner's socket survives untouched
+    expect(existsSync(path!)).toBe(true);
+  });
+
+  test("clients keep talking to the one live daemon after a refused start", async () => {
+    const first = server();
+    first.start();
+    const created = first.core.sessionCreate({ workspace: WS, artifact: PLAN });
+    server().start(); // refused
+    const client = await DaemonClient.connect({ home });
+    try {
+      // no split brain: the session created on the winner is visible
+      expect((await client.sessionGet(created.id)).id).toBe(created.id);
+      expect((await client.sessionList()).length).toBe(1);
+    } finally {
+      client.close();
+    }
+  });
+
+  test("a stale lock from a crashed daemon is reclaimed", () => {
+    // a pid that cannot be running (init is never a cueloop daemon, and this
+    // simulates the record a crashed process leaves behind)
+    writeFileSync(lockPath(home), "999999");
+    const s = server();
+    expect(s.start()).toBe(socketPath(home));
+  });
+
+  test("stopping releases the lock so a restart works", () => {
+    const first = server();
+    first.start();
+    first.stop();
+    expect(existsSync(lockPath(home))).toBe(false);
+    const second = server();
+    expect(second.start()).toBe(socketPath(home));
+  });
+
+  test("concurrent autostarts converge on a single daemon", async () => {
+    // several clients race to autostart; all must end up on the same daemon
+    const clients = await Promise.all([
+      DaemonClient.connect({ home, autostart: true }),
+      DaemonClient.connect({ home, autostart: true }),
+      DaemonClient.connect({ home, autostart: true }),
+    ]);
+    try {
+      const pids = await Promise.all(clients.map((c) => c.ping()));
+      const unique = new Set(pids.map((p) => p.pid));
+      expect(unique.size).toBe(1);
+      // and state is shared: one client's session is visible to the others
+      const s = await clients[0]!.sessionCreate(WS, PLAN);
+      expect((await clients[2]!.sessionGet(s.id)).id).toBe(s.id);
+    } finally {
+      for (const c of clients) c.close();
+      // the autostarted daemon is not one of `servers` - shut it down
+      const admin = await DaemonClient.connect({ home });
+      await admin.shutdown();
+      admin.close();
+    }
+  }, 60_000);
+});

package/src/store.ts

@@ -0,0 +1,68 @@
+/**
+ * Session persistence (#14): one JSON document per session, every write
+ * through a temp file + atomic rename so a crash mid-write can never leave
+ * a corrupt record. Recovery is a read-only scan; records that fail to
+ * parse are skipped and reported, never deleted.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ReviewSession } from "@cueloop/schema";
+import { validateSessionRecord } from "./validate";
+import { sessionsDir } from "./paths";
+
+export interface RecoveryReport {
+  recovered: string[];
+  skipped: { file: string; error: string }[];
+}
+
+export class SessionStore {
+  private sessions = new Map<string, ReviewSession>();
+  private readonly dir: string;
+
+  constructor(home: string) {
+    this.dir = sessionsDir(home);
+    mkdirSync(this.dir, { recursive: true });
+  }
+
+  /** Read-only scan of the state directory; called once on boot. */
+  recover(): RecoveryReport {
+    const report: RecoveryReport = { recovered: [], skipped: [] };
+    for (const file of readdirSync(this.dir)) {
+      if (!file.endsWith(".json")) continue;
+      try {
+        const raw = readFileSync(join(this.dir, file), "utf8");
+        const parsed = validateSessionRecord(JSON.parse(raw));
+        if (!parsed.ok) throw new Error(`invalid record - ${parsed.error}`);
+        const session = parsed.value as ReviewSession;
+        this.sessions.set(session.id, session);
+        report.recovered.push(session.id);
+      } catch (err) {
+        report.skipped.push({ file, error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+    return report;
+  }
+
+  get(id: string): ReviewSession | undefined {
+    return this.sessions.get(id);
+  }
+
+  list(): ReviewSession[] {
+    return [...this.sessions.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  }
+
+  upsert(session: ReviewSession): void {
+    this.sessions.set(session.id, session);
+    const path = join(this.dir, `${session.id}.json`);
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify(session, null, 2));
+    renameSync(tmp, path);
+  }
+
+  delete(id: string): boolean {
+    if (!this.sessions.delete(id)) return false;
+    rmSync(join(this.dir, `${id}.json`), { force: true });
+    return true;
+  }
+}

package/src/validate.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import { DaemonError } from "./errors";
+import { isKnownMethod, parseParams, validateSessionRecord } from "./validate";
+import { SCHEMA_VERSION } from "@cueloop/schema";
+
+describe("method allowlist", () => {
+  test("known and unknown methods", () => {
+    expect(isKnownMethod("session.create")).toBe(true);
+    expect(isKnownMethod("session.destroyEverything")).toBe(false);
+  });
+});
+
+describe("parseParams", () => {
+  test("accepts a well-formed create and defaults meta", () => {
+    const p = parseParams("session.create", {
+      workspace: { repoRoot: "/repo", branch: "main" },
+      artifact: { type: "plan", content: "# P" },
+    });
+    expect(p.artifact.meta).toEqual({});
+  });
+
+  test("rejects a missing workspace with a pathed message", () => {
+    try {
+      parseParams("session.create", { artifact: { type: "plan", content: "" } });
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(DaemonError);
+      expect((err as DaemonError).code).toBe("invalid_params");
+      expect((err as DaemonError).message).toContain("session.create: workspace");
+    }
+  });
+
+  test("rejects an unknown artifact type", () => {
+    expect(() =>
+      parseParams("session.create", {
+        workspace: { repoRoot: "/r", branch: "b" },
+        artifact: { type: "spreadsheet", content: "" },
+      }),
+    ).toThrow(/artifact.type/);
+  });
+
+  test("rejects an empty session id", () => {
+    expect(() => parseParams("session.get", { id: "" })).toThrow(/invalid|id/i);
+  });
+
+  test("defaults and clamps the wait timeout", () => {
+    expect(parseParams("session.wait", { id: "ses_1" }).timeoutMs).toBe(60_000);
+    expect(() => parseParams("session.wait", { id: "ses_1", timeoutMs: -5 })).toThrow();
+    expect(() => parseParams("session.wait", { id: "ses_1", timeoutMs: 99 * 60 * 60 * 1000 })).toThrow();
+  });
+
+  test("verdict kinds are closed", () => {
+    expect(parseParams("session.resolve", { id: "s", verdictKind: "approve" }).summary).toBe("");
+    expect(() => parseParams("session.resolve", { id: "s", verdictKind: "lgtm" })).toThrow(/verdictKind/);
+  });
+
+  test("annotation kinds stay open (extension kinds are allowed)", () => {
+    const p = parseParams("session.annotate", {
+      id: "s",
+      annotation: { id: "a1", kind: "praise", anchor: { quote: "x" }, body: "nice" },
+    });
+    expect(p.annotation.kind).toBe("praise");
+    expect(p.annotation.anchor.prefix).toBe("");
+  });
+
+  test("null params are treated as empty", () => {
+    expect(parseParams("daemon.ping", null)).toEqual({});
+  });
+});
+
+describe("validateSessionRecord", () => {
+  const record = {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_1",
+    workspace: { repoRoot: "/r", branch: "main" },
+    artifact: { type: "plan", content: "# P", meta: {} },
+    revisions: [{ revision: 1, content: "# P", submittedAt: "now" }],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "now",
+  };
+
+  test("accepts a valid record", () => {
+    expect(validateSessionRecord(record).ok).toBe(true);
+  });
+
+  test("rejects a foreign schema version with a readable reason", () => {
+    const r = validateSessionRecord({ ...record, schemaVersion: "99" });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toContain("schemaVersion");
+  });
+
+  test("rejects a structurally broken record", () => {
+    const r = validateSessionRecord({ ...record, revisions: "nope" });
+    expect(r.ok).toBe(false);
+  });
+});