@cueloop/daemon 0.1.0-alpha.5 → 0.1.0-alpha.50

package/src/client.ts

@@ -1,38 +1,85 @@
 /**
  * Daemon client: the one library every consumer shares - CLI verbs, the TUI,
- * adapters, and tests. Also owns the lazy-launch story (#14): connect() with
+ * adapters, and tests. Also owns the lazy-launch story: connect() with
  * autostart spawns a detached daemon when the socket is dead, then attaches.
  */
 
 import { existsSync, rmSync } from "node:fs";
-import type { Annotation, Artifact, ReviewSession, VerdictKind, WorkspaceKey } from "@cueloop/schema";
-import { LineBuffer, type EventFrame, type Response } from "./protocol";
+import type {
+  Annotation,
+  Artifact,
+  Identity,
+  ReviewSession,
+  VerdictKind,
+  WorkspaceKey,
+} from "@cueloop/schema";
+import { BackpressureWriter, LineBuffer, type EventFrame, type Response } from "./protocol";
+import type { DaemonRole } from "./capabilities";
+import type { HerdrTabHandle } from "./herdr-tab-store";
 import { cueloopHome, socketPath } from "./paths";
 
+export type { EventFrame } from "./protocol";
+
 export interface ConnectOptions {
   home?: string;
   /** Spawn the daemon when the socket is not alive. */
   autostart?: boolean;
+  /** Capability role for this connection; a review-side agent connects capped. Defaults to owner. */
+  role?: DaemonRole;
 }
 
-type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void };
+type PendingRequest = { resolve: (value: unknown) => void; reject: (error: Error) => void };
 
-export class DaemonClient {
+/**
+ * The session verbs the review controller drives. DaemonClient is the local
+ * implementation (unix socket); the sharing gateway supplies an in-memory,
+ * blob-backed one. Depending on this interface - not DaemonClient - is what
+ * lets the same <App> render a local session or a decrypted share unchanged.
+ */
+export interface SessionClient {
+  onEvent(listener: (event: EventFrame) => void): () => void;
+  subscribe(): Promise<void>;
+  sessionGet(id: string): Promise<ReviewSession>;
+  sessionList(filter?: { status?: "pending" | "resolved" }): Promise<ReviewSession[]>;
+  sessionAnnotate(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<ReviewSession>;
+  sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession>;
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession>;
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession>;
+  sessionSetShareId(id: string, shareId: string): Promise<ReviewSession>;
+  sessionMergeShared(
+    id: string,
+    incoming: { annotations: Annotation[]; participants?: Identity[] },
+  ): Promise<ReviewSession>;
+  sessionDelete(id: string): Promise<void>;
+  /** Record the caller's own identity name (collaborator self-naming on a share). */
+  sessionSetSelfName(id: string, name: string): Promise<ReviewSession>;
+  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession>;
+  close(): void;
+}
+
+export class DaemonClient implements SessionClient {
   private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
-  private pending = new Map<number, Pending>();
+  private writer: BackpressureWriter | null = null;
+  private pending = new Map<number, PendingRequest>();
   private nextId = 1;
-  private eventListeners = new Set<(e: EventFrame) => void>();
+  private eventListeners = new Set<(event: EventFrame) => void>();
   private closed = false;
+  private role: DaemonRole = "owner";
 
-  static async connect(opts: ConnectOptions = {}): Promise<DaemonClient> {
-    const home = opts.home ?? cueloopHome();
+  static async connect(options: ConnectOptions = {}): Promise<DaemonClient> {
+    const home = options.home ?? cueloopHome();
     const path = socketPath(home);
     const client = new DaemonClient();
+    client.role = options.role ?? "owner";
     try {
       await client.dial(path);
       return client;
     } catch (err) {
-      if (!opts.autostart) throw err;
+      if (!options.autostart) throw err;
     }
     // Socket dead or absent: clean a stale file and spawn the daemon detached.
     if (existsSync(path)) rmSync(path, { force: true });
@@ -40,47 +87,53 @@ export class DaemonClient {
     // Generous: a cold or loaded machine pays for a runtime start before the
     // socket exists, and giving up early looks to callers like a broken daemon.
     const deadline = Date.now() + Number(process.env.CUELOOP_START_TIMEOUT_MS ?? 30_000);
-    let lastErr: unknown;
+    let lastError: unknown;
     while (Date.now() < deadline) {
       try {
         await client.dial(path);
         return client;
       } catch (err) {
-        lastErr = err;
+        lastError = err;
         await Bun.sleep(50);
       }
     }
-    throw new Error(`daemon did not come up at ${path}: ${String(lastErr)}`);
+    throw new Error(`daemon did not come up at ${path}: ${String(lastError)}`);
   }
 
   private async dial(path: string): Promise<void> {
     const buffer = new LineBuffer();
-    const self = this;
     this.socket = await Bun.connect({
       unix: path,
       socket: {
-        data(_socket, data) {
-          buffer.push(data.toString(), (line) => self.handleFrame(line));
+        data: (_socket, data) => {
+          buffer.push(data.toString(), (line) => this.routeInboundFrame(line));
+        },
+        drain: () => {
+          this.writer?.drain();
         },
-        close() {
-          self.closed = true;
-          for (const p of self.pending.values()) p.reject(new Error("daemon connection closed"));
-          self.pending.clear();
+        close: () => {
+          this.closed = true;
+          for (const pendingRequest of this.pending.values())
+            pendingRequest.reject(new Error("daemon connection closed"));
+          this.pending.clear();
         },
         error() {},
       },
     });
+    this.writer = new BackpressureWriter(this.socket);
     // Verify liveness: a dead socket file accepts connects on some platforms
     // only to fail later, so a ping is the actual handshake.
     await this.request("daemon.ping", {}, 2_000);
+    // Cap this connection's role for the daemon's capability gate (owner is the default).
+    if (this.role !== "owner") await this.request("daemon.hello", { role: this.role }, 2_000);
   }
 
-  onEvent(listener: (e: EventFrame) => void): () => void {
+  onEvent(listener: (event: EventFrame) => void): () => void {
     this.eventListeners.add(listener);
     return () => this.eventListeners.delete(listener);
   }
 
-  private handleFrame(line: string): void {
+  private routeInboundFrame(line: string): void {
     let frame: Response | EventFrame;
     try {
       frame = JSON.parse(line) as Response | EventFrame;
@@ -88,14 +141,15 @@ export class DaemonClient {
       return;
     }
     if ("event" in frame) {
-      for (const l of this.eventListeners) l(frame);
+      for (const listener of this.eventListeners) listener(frame);
       return;
     }
-    const p = this.pending.get(frame.id);
-    if (!p) return;
+    const pendingRequest = this.pending.get(frame.id);
+    if (!pendingRequest) return;
     this.pending.delete(frame.id);
-    if (frame.error) p.reject(new DaemonClientError(frame.error.code, frame.error.message));
-    else p.resolve(frame.result);
+    if (frame.error)
+      pendingRequest.reject(new DaemonClientError(frame.error.code, frame.error.message));
+    else pendingRequest.resolve(frame.result);
   }
 
   request<T = unknown>(method: string, params: unknown, timeoutMs = 30_000): Promise<T> {
@@ -107,16 +161,16 @@ export class DaemonClient {
         reject(new Error(`request ${method} timed out`));
       }, timeoutMs);
       this.pending.set(id, {
-        resolve: (v) => {
+        resolve: (value) => {
           clearTimeout(timer);
-          resolve(v as T);
+          resolve(value as T);
         },
-        reject: (e) => {
+        reject: (error) => {
           clearTimeout(timer);
-          reject(e);
+          reject(error);
         },
       });
-      this.socket!.write(JSON.stringify({ id, method, params }) + "\n");
+      this.writer!.write(JSON.stringify({ id, method, params }) + "\n");
     });
   }
 
@@ -145,8 +199,12 @@ export class DaemonClient {
   sessionWait(id: string, timeoutMs: number): Promise<ReviewSession | null> {
     return this.request("session.wait", { id, timeoutMs }, timeoutMs + 10_000);
   }
-  sessionAnnotate(id: string, annotation: Omit<Annotation, "createdAt">): Promise<ReviewSession> {
-    return this.request("session.annotate", { id, annotation });
+  sessionAnnotate(
+    id: string,
+    annotation: Omit<Annotation, "createdAt">,
+    authorName?: string,
+  ): Promise<ReviewSession> {
+    return this.request("session.annotate", { id, annotation, authorName });
   }
   sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession> {
     return this.request("session.removeAnnotation", { id, annotationId });
@@ -154,11 +212,45 @@ export class DaemonClient {
   sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession> {
     return this.request("session.setWorkingCopy", { id, workingCopy });
   }
+  sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession> {
+    return this.request("session.setViewed", { id, viewedPaths });
+  }
+  /** Re-capture a diff session's working tree; changed=true when the patch moved and an event fired. */
+  sessionRefreshDiff(id: string): Promise<{ changed: boolean }> {
+    return this.request("session.refreshDiff", { id });
+  }
+  sessionSetShareId(id: string, shareId: string): Promise<ReviewSession> {
+    return this.request("session.setShareId", { id, shareId });
+  }
+  sessionMergeShared(
+    id: string,
+    incoming: { annotations: Annotation[]; participants?: Identity[] },
+  ): Promise<ReviewSession> {
+    return this.request("session.mergeShared", { id, ...incoming });
+  }
+  sessionDelete(id: string): Promise<void> {
+    return this.request("session.delete", { id });
+  }
+  /** Local sessions have no collaborator self-name; the share client owns this. */
+  sessionSetSelfName(id: string, _name: string): Promise<ReviewSession> {
+    return this.sessionGet(id);
+  }
   sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
     return this.request("session.resolve", { id, verdictKind, summary });
   }
-  sessionSubmitRevision(id: string, content: string): Promise<ReviewSession> {
-    return this.request("session.submitRevision", { id, content });
+  sessionSubmitRevision(
+    id: string,
+    content: string,
+    addressedAnnotationIds: string[] = [],
+  ): Promise<ReviewSession> {
+    return this.request("session.submitRevision", { id, content, addressedAnnotationIds });
+  }
+  /** herdr adapter scratch: the tab opened for a review; local-only, off the SessionClient contract. */
+  herdrGetTab(id: string): Promise<HerdrTabHandle | null> {
+    return this.request("herdr.getTab", { id });
+  }
+  async herdrSetTab(id: string, handle: HerdrTabHandle): Promise<void> {
+    await this.request("herdr.setTab", { id, ...handle });
   }
   shutdown(): Promise<void> {
     return this.request("daemon.shutdown", {});

package/src/diff-hot-reload.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Diff hot-reload: session.refreshDiff re-captures a diff session's working
+ * tree, and the fs watcher drives it on a real change. Exercised against a
+ * real temp git repo so the capture path is the production one.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonCore } from "./api";
+import { workingTreeDiff } from "./working-tree";
+import { resolveWorkspace } from "./review";
+import type { Artifact } from "@cueloop/schema";
+
+function git(args: string[], cwd: string): void {
+  const result = Bun.spawnSync(["git", ...args], { cwd, stdout: "ignore", stderr: "ignore" });
+  if (result.exitCode !== 0) throw new Error(`git ${args.join(" ")} failed in ${cwd}`);
+}
+
+let home: string;
+let repo: string;
+let core: DaemonCore;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-hotreload-home-"));
+  repo = mkdtempSync(join(tmpdir(), "cueloop-hotreload-repo-"));
+  git(["init", "-q", "-b", "main"], repo);
+  git(["config", "user.email", "t@t"], repo);
+  git(["config", "user.name", "t"], repo);
+  writeFileSync(join(repo, "a.ts"), "export const a = 1;\n");
+  git(["add", "."], repo);
+  git(["commit", "-qm", "init"], repo);
+  core = new DaemonCore(home);
+});
+
+afterEach(() => {
+  core.dispose();
+  rmSync(home, { recursive: true, force: true });
+  rmSync(repo, { recursive: true, force: true });
+});
+
+/** Open a diff session over the temp repo's current working tree. */
+async function openDiffSession() {
+  const workspace = await resolveWorkspace(repo);
+  const diff = await workingTreeDiff(repo);
+  const artifact: Artifact = { type: "diff", content: diff.patch, files: diff.files, meta: {} };
+  return core.sessionCreate({ workspace, artifact });
+}
+
+describe("session.refreshDiff", () => {
+  test("re-captures the working tree and updates the artifact when the patch changed", async () => {
+    // Given an open diff session whose working tree then gains a new change
+    const session = await openDiffSession();
+    writeFileSync(join(repo, "a.ts"), "export const a = 2;\n");
+
+    // When the diff is refreshed
+    const result = await core.sessionRefreshDiff(session.id);
+
+    // Then the change is reported and the stored artifact carries the fresh patch and files
+    expect(result.changed).toBe(true);
+    const refreshed = core.sessionGet(session.id);
+    expect(refreshed.artifact.content).toContain("+export const a = 2;");
+    const modified = refreshed.artifact.files!.find((file) => file.path === "a.ts")!;
+    expect(modified.newContents).toBe("export const a = 2;\n");
+  });
+
+  test("reports no change and emits nothing when the working tree is unchanged", async () => {
+    // Given an open diff session and a listener for session events
+    const session = await openDiffSession();
+    const events: string[] = [];
+    core.onEvent((event) => events.push(event.event));
+
+    // When the diff is refreshed without any working-tree change
+    const result = await core.sessionRefreshDiff(session.id);
+
+    // Then nothing changed and no session.updated event fired
+    expect(result.changed).toBe(false);
+    expect(events).not.toContain("session.updated");
+  });
+
+  test("a changed refresh emits session.updated so attached clients re-fetch", async () => {
+    // Given an open diff session, a listener, and a fresh working-tree change
+    const session = await openDiffSession();
+    const events: string[] = [];
+    core.onEvent((event) => events.push(event.event));
+    writeFileSync(join(repo, "a.ts"), "export const a = 3;\n");
+
+    // When the diff is refreshed
+    await core.sessionRefreshDiff(session.id);
+
+    // Then a session.updated event fired for this session
+    expect(events).toContain("session.updated");
+  });
+
+  test("is a no-op for a non-diff (plan) session", async () => {
+    // Given a plan session in the same workspace
+    const workspace = await resolveWorkspace(repo);
+    const plan: Artifact = { type: "plan", content: "# Plan\n\nBody.\n", meta: {} };
+    const session = core.sessionCreate({ workspace, artifact: plan });
+
+    // When a refresh is attempted
+    const result = await core.sessionRefreshDiff(session.id);
+
+    // Then it reports no change and leaves the plan content untouched
+    expect(result.changed).toBe(false);
+    expect(core.sessionGet(session.id).artifact.content).toBe("# Plan\n\nBody.\n");
+  });
+
+  test("refusing a resolved diff session never mutates it (no revive of a closed review)", async () => {
+    // Given a diff session that has been resolved
+    const session = await openDiffSession();
+    core.sessionResolve(session.id, "approve", "");
+    const resolvedContent = core.sessionGet(session.id).artifact.content;
+    writeFileSync(join(repo, "a.ts"), "export const a = 99;\n");
+
+    // When a refresh is attempted on the resolved session
+    // Then it is rejected and the frozen artifact is untouched
+    expect(core.sessionRefreshDiff(session.id)).rejects.toThrow(/resolved/);
+    expect(core.sessionGet(session.id).artifact.content).toBe(resolvedContent);
+  });
+
+  test("overlapping refreshes settle to one coherent artifact without error", async () => {
+    // Given a live diff session with a fresh working-tree change
+    const session = await openDiffSession();
+    writeFileSync(join(repo, "a.ts"), "export const a = 7;\n");
+
+    // When two refreshes run concurrently over the same session
+    const [first, second] = await Promise.all([
+      core.sessionRefreshDiff(session.id),
+      core.sessionRefreshDiff(session.id),
+    ]);
+
+    // Then both settle and the stored artifact reflects the current tree exactly
+    // once - the generation guard keeps the older capture from regressing it
+    expect(first.changed || second.changed).toBe(true);
+    expect(core.sessionGet(session.id).artifact.content).toContain("+export const a = 7;");
+  });
+});
+
+describe("the fs watcher drives hot-reload", () => {
+  test("a working-tree change under a live diff session refreshes it in place", async () => {
+    // Given a live diff session whose repo the daemon is watching
+    const session = await openDiffSession();
+
+    // When a tracked file changes on disk
+    writeFileSync(join(repo, "a.ts"), "export const a = 42;\n");
+
+    // Then the watcher debounces and re-captures the diff without any manual call.
+    // Watchers can be slow under CI contention, so poll generously.
+    const deadline = Date.now() + 8_000;
+    let content = core.sessionGet(session.id).artifact.content;
+    while (!content.includes("+export const a = 42;") && Date.now() < deadline) {
+      await Bun.sleep(100);
+      content = core.sessionGet(session.id).artifact.content;
+    }
+    expect(content).toContain("+export const a = 42;");
+  }, 12_000);
+});

package/src/diff-watcher.ts

@@ -0,0 +1,99 @@
+/**
+ * Watches a diff session's repository for working-tree changes and drives the
+ * hot-reload: on any change under a repo root that a live diff session tracks,
+ * the daemon re-captures that session's diff so the open review updates in place.
+ * One recursive fs watcher per repo root - many diff sessions can share a repo -
+ * with a debounce so a burst of file writes triggers a single re-capture.
+ */
+
+import { watch, type FSWatcher } from "node:fs";
+import { sep } from "node:path";
+
+/** Debounce window: a save or a checkout writes many files in a burst; collapse them into one re-capture. */
+const DIFF_REFRESH_DEBOUNCE_MS = 300;
+
+/**
+ * Paths whose churn must never trigger a diff refresh. git rewrites `.git`
+ * metadata (the index, lock files) on every read `cueloop diff` itself runs, so
+ * watching it would loop; `node_modules` churns on installs and is never review
+ * content.
+ */
+function isIgnoredWatchPath(relativePath: string): boolean {
+  const segments = relativePath.split(sep);
+  return segments.includes(".git") || segments.includes("node_modules");
+}
+
+interface RepoWatch {
+  handle: FSWatcher;
+  /** Live diff session ids sharing this repo root; the watch closes when the last one leaves. */
+  sessionIds: Set<string>;
+  debounce: ReturnType<typeof setTimeout> | null;
+}
+
+/**
+ * Owns the fs watchers behind diff hot-reload. `onRepoChange` fires once per
+ * debounced burst with the repo root that changed; the caller re-captures every
+ * live diff session on that root. A watcher error or an unwatchable root is
+ * swallowed - hot-reload is best-effort and must never crash the daemon.
+ */
+export class DiffWatcher {
+  private readonly repoWatches = new Map<string, RepoWatch>();
+
+  constructor(private readonly onRepoChange: (repoRoot: string) => void) {}
+
+  /** Start (or join) watching a repo root for one diff session. Idempotent per (root, session). */
+  trackDiffRepo(repoRoot: string, sessionId: string): void {
+    const existing = this.repoWatches.get(repoRoot);
+    if (existing) {
+      existing.sessionIds.add(sessionId);
+      return;
+    }
+    let handle: FSWatcher;
+    try {
+      handle = watch(repoRoot, { recursive: true }, (_event, filename) => {
+        if (filename !== null && isIgnoredWatchPath(filename.toString())) return;
+        this.scheduleRepoRefresh(repoRoot);
+      });
+    } catch {
+      // repo root gone or not watchable on this platform: skip, no hot-reload here
+      return;
+    }
+    // a watcher error (the root is deleted mid-review) must not take down the
+    // daemon; the inherited EventEmitter `on` is absent from Bun's FSWatcher type
+    (handle as FSWatcher & { on(event: "error", listener: (error: Error) => void): void }).on(
+      "error",
+      () => {},
+    );
+    this.repoWatches.set(repoRoot, { handle, sessionIds: new Set([sessionId]), debounce: null });
+  }
+
+  /** Drop one diff session; close the repo watch once no diff session tracks it. */
+  untrackDiffRepo(repoRoot: string, sessionId: string): void {
+    const repoWatch = this.repoWatches.get(repoRoot);
+    if (!repoWatch) return;
+    repoWatch.sessionIds.delete(sessionId);
+    if (repoWatch.sessionIds.size > 0) return;
+    if (repoWatch.debounce !== null) clearTimeout(repoWatch.debounce);
+    repoWatch.handle.close();
+    this.repoWatches.delete(repoRoot);
+  }
+
+  private scheduleRepoRefresh(repoRoot: string): void {
+    const repoWatch = this.repoWatches.get(repoRoot);
+    if (!repoWatch) return;
+    if (repoWatch.debounce !== null) clearTimeout(repoWatch.debounce);
+    repoWatch.debounce = setTimeout(() => {
+      repoWatch.debounce = null;
+      this.onRepoChange(repoRoot);
+    }, DIFF_REFRESH_DEBOUNCE_MS);
+  }
+
+  /** Close every watcher and cancel pending debounces (daemon shutdown). */
+  close(): void {
+    for (const repoWatch of this.repoWatches.values()) {
+      if (repoWatch.debounce !== null) clearTimeout(repoWatch.debounce);
+      repoWatch.handle.close();
+    }
+    this.repoWatches.clear();
+  }
+}