@cueloop/daemon 0.1.0-alpha.6 → 0.1.0-alpha.61

package/src/share-blob.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { gzipSync } from "node:zlib";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Artifact, WorkspaceKey } from "@cueloop/schema";
+import { DaemonCore } from "./api";
+import { MAX_BLOB_BYTES, packSessionBlob, unpackSessionBlob } from "./share-blob";
+
+const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
+const PLAN: Artifact = { type: "plan", content: "# Plan\n\nDo the thing.\n", meta: {} };
+
+let home: string;
+let core: DaemonCore;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-blob-"));
+  core = new DaemonCore(home);
+});
+afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+describe("share blob roundtrip", () => {
+  test("pack then unpack restores the session with its annotations", () => {
+    // Arrange
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const annotated = core.sessionAnnotate(session.id, {
+      id: "a_1",
+      kind: "comment",
+      anchor: { quote: "the thing", prefix: "", suffix: "" },
+      body: "why this?",
+    });
+
+    // Act
+    const restored = unpackSessionBlob(packSessionBlob(annotated));
+
+    // Assert
+    expect(restored).toEqual(annotated);
+  });
+});
+
+describe("unpack rejects bad input", () => {
+  test("caps the decompressed size, so a compression bomb throws", () => {
+    // Arrange: tiny gzip, huge inflation - the decompression-bomb shape
+    const bomb = gzipSync(Buffer.alloc(MAX_BLOB_BYTES + 1, 0x61));
+
+    // Act / Assert
+    expect(() => unpackSessionBlob(bomb)).toThrow(/exceeds|maxOutputLength/i);
+  });
+
+  test("throws on bytes that are not gzip", () => {
+    // Act / Assert
+    expect(() => unpackSessionBlob(Buffer.from("not gzip at all"))).toThrow(/gzip/i);
+  });
+
+  test("throws on a shape that is not a session", () => {
+    // Arrange
+    const notASession = gzipSync(Buffer.from(JSON.stringify({ hello: "world" })));
+
+    // Act / Assert
+    expect(() => unpackSessionBlob(notASession)).toThrow(/not a valid session/i);
+  });
+});

package/src/share-blob.ts

@@ -0,0 +1,55 @@
+/**
+ * The share-blob wire format: how a ReviewSession travels from `cueloop share`
+ * to the gateway. The planner's CLI packs (this is the only thing it can do -
+ * it holds no encryption key); the gateway unpacks, then encrypts for R2.
+ *
+ * Format is gzip(JSON). Unpack is the untrusted boundary - the bytes come off
+ * an SSH channel from anyone who can reach the `share` user - so it caps the
+ * decompressed size (a decompression-bomb guard) and runs the same record
+ * validator the daemon store uses, never trusting the shape.
+ */
+
+import { gzipSync, gunzipSync } from "node:zlib";
+import type { ReviewSession } from "@cueloop/schema";
+import { validateSessionRecord } from "./validate";
+
+/** Decompressed ceiling for one shared session (ADR 0004's payload cap). */
+export const MAX_BLOB_BYTES = 1024 * 1024;
+
+/** The SSH username `cueloop share` connects as to upload; the gateway routes on it. */
+export const SHARE_UPLOAD_USER = "share";
+
+/** Where shares live, in one place: the client uploads here, the gateway prints it. */
+export const DEFAULT_SHARE_HOST = "cueloop.dev";
+export const DEFAULT_SHARE_PORT = 22;
+
+/** Serialise + compress a session for upload. */
+export function packSessionBlob(session: ReviewSession): Buffer {
+  return gzipSync(Buffer.from(JSON.stringify(session), "utf8"));
+}
+
+/** Decompress + validate an uploaded blob, or throw a precise reason. */
+export function unpackSessionBlob(bytes: Uint8Array): ReviewSession {
+  let json: string;
+
+  try {
+    json = gunzipSync(bytes, { maxOutputLength: MAX_BLOB_BYTES }).toString("utf8");
+  } catch (err) {
+    throw new Error(
+      `blob is not valid gzip or exceeds ${MAX_BLOB_BYTES} bytes: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    );
+  }
+  let raw: unknown;
+
+  try {
+    raw = JSON.parse(json);
+  } catch {
+    throw new Error("blob is not valid JSON");
+  }
+  const parsed = validateSessionRecord(raw);
+
+  if (!parsed.ok) throw new Error(`blob is not a valid session: ${parsed.error}`);
+
+  return parsed.value as ReviewSession;
+}

package/src/single-instance.test.ts

@@ -1,5 +1,5 @@
 /**
- * Single-instance guarantee (#14): one daemon per home. Two daemons over one
+ * Single-instance guarantee: one daemon per home. Two daemons over one
  * state directory means divergent in-memory sessions and clients seeing
  * whichever half they connect to.
  */
@@ -23,33 +23,44 @@ beforeEach(() => {
   home = mkdtempSync(join(tmpdir(), "cueloop-lock-"));
 });
 afterEach(() => {
-  for (const s of servers.splice(0)) s.stop();
+  for (const runningServer of servers.splice(0)) runningServer.stop();
   rmSync(home, { recursive: true, force: true });
 });
 
 function server(): DaemonServer {
-  const s = new DaemonServer({ home, idleExitMs: 0 });
-  servers.push(s);
-  return s;
+  const daemonServer = new DaemonServer({ home, idleExitMs: 0 });
+
+  servers.push(daemonServer);
+
+  return daemonServer;
 }
 
 describe("one daemon per home", () => {
   test("the second start is refused instead of stealing the socket", () => {
+    // Arrange
     const first = server();
     const path = first.start();
+
     expect(path).toBe(socketPath(home));
     const second = server();
+
+    // Assert
     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 () => {
+    // Arrange
     const first = server();
+
     first.start();
     const created = first.core.sessionCreate({ workspace: WS, artifact: PLAN });
+
     server().start(); // refused
     const client = await DaemonClient.connect({ home });
+
+    // Assert
     try {
       // no split brain: the session created on the winner is visible
       expect((await client.sessionGet(created.id)).id).toBe(created.id);
@@ -60,40 +71,56 @@ describe("one daemon per home", () => {
   });
 
   test("a stale lock from a crashed daemon is reclaimed", () => {
+    // Arrange
     // 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));
+    const daemonServer = server();
+
+    // Assert
+    expect(daemonServer.start()).toBe(socketPath(home));
   });
 
   test("stopping releases the lock so a restart works", () => {
+    // Arrange
     const first = server();
+
     first.start();
+
+    // Act
     first.stop();
+
+    // Assert
     expect(existsSync(lockPath(home))).toBe(false);
     const second = server();
+
     expect(second.start()).toBe(socketPath(home));
   });
 
   test("concurrent autostarts converge on a single daemon", async () => {
+    // Act
     // 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 }),
     ]);
+
+    // Assert
     try {
-      const pids = await Promise.all(clients.map((c) => c.ping()));
-      const unique = new Set(pids.map((p) => p.pid));
+      const pids = await Promise.all(clients.map((client) => client.ping()));
+      const unique = new Set(pids.map((ping) => ping.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);
+      const session = await clients[0]!.sessionCreate(WS, PLAN);
+
+      expect((await clients[2]!.sessionGet(session.id)).id).toBe(session.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();
     }

package/src/store.ts

@@ -1,5 +1,5 @@
 /**
- * Session persistence (#14): one JSON document per session, every write
+ * Session persistence: 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.
@@ -28,19 +28,23 @@ export class SessionStore {
   /** 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;
   }
 
@@ -49,20 +53,24 @@ export class SessionStore {
   }
 
   list(): ReviewSession[] {
-    return [...this.sessions.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    return [...this.sessions.values()].sort((left, right) =>
+      left.createdAt.localeCompare(right.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);
+    const tempPath = path + ".tmp";
+
+    writeFileSync(tempPath, JSON.stringify(session, null, 2));
+    renameSync(tempPath, 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

@@ -1,7 +1,35 @@
 import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonCore } from "./api";
 import { DaemonError } from "./errors";
-import { isKnownMethod, parseParams, validateSessionRecord } from "./validate";
-import { SCHEMA_VERSION } from "@cueloop/schema";
+import {
+  AnchorSchema,
+  AnnotationSchema,
+  ArtifactMetaSchema,
+  ArtifactSchema,
+  IdentitySchema,
+  RevisionSchema,
+  SessionRecordSchema,
+  VerdictSchema,
+  WorkspaceSchema,
+  isKnownMethod,
+  parseParams,
+  validateSessionRecord,
+} from "./validate";
+import {
+  SCHEMA_VERSION,
+  type Anchor,
+  type Annotation,
+  type Artifact,
+  type ArtifactMeta,
+  type Identity,
+  type ReviewSession,
+  type Revision,
+  type Verdict,
+  type WorkspaceKey,
+} from "@cueloop/schema";
 
 describe("method allowlist", () => {
   test("known and unknown methods", () => {
@@ -12,11 +40,14 @@ describe("method allowlist", () => {
 
 describe("parseParams", () => {
   test("accepts a well-formed create and defaults meta", () => {
-    const p = parseParams("session.create", {
+    // Act
+    const params = parseParams("session.create", {
       workspace: { repoRoot: "/repo", branch: "main" },
       artifact: { type: "plan", content: "# P" },
     });
-    expect(p.artifact.meta).toEqual({});
+
+    // Assert
+    expect(params.artifact.meta).toEqual({});
   });
 
   test("rejects a missing workspace with a pathed message", () => {
@@ -30,6 +61,15 @@ describe("parseParams", () => {
     }
   });
 
+  test("accepts the reply artifact type", () => {
+    const params = parseParams("session.create", {
+      workspace: { repoRoot: "/repo", branch: "main" },
+      artifact: { type: "reply", content: "# R" },
+    });
+
+    expect(params.artifact.type).toBe("reply");
+  });
+
   test("rejects an unknown artifact type", () => {
     expect(() =>
       parseParams("session.create", {
@@ -46,21 +86,40 @@ describe("parseParams", () => {
   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();
+    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/);
+    expect(() => parseParams("session.resolve", { id: "s", verdictKind: "lgtm" })).toThrow(
+      /verdictKind/,
+    );
   });
 
   test("annotation kinds stay open (extension kinds are allowed)", () => {
-    const p = parseParams("session.annotate", {
+    // Act
+    const params = 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("");
+
+    // Assert
+    expect(params.annotation.kind).toBe("praise");
+    expect(params.annotation.anchor.prefix).toBe("");
+  });
+
+  test("setViewed takes a full path list and rejects non-string entries", () => {
+    expect(
+      parseParams("session.setViewed", { id: "s", viewedPaths: ["src/a.ts", "src/b.ts"] })
+        .viewedPaths,
+    ).toEqual(["src/a.ts", "src/b.ts"]);
+    expect(parseParams("session.setViewed", { id: "s", viewedPaths: [] }).viewedPaths).toEqual([]);
+    expect(() => parseParams("session.setViewed", { id: "s", viewedPaths: [1] })).toThrow(
+      /viewedPaths/,
+    );
+    expect(() => parseParams("session.setViewed", { id: "s" })).toThrow(/viewedPaths/);
   });
 
   test("null params are treated as empty", () => {
@@ -86,13 +145,136 @@ describe("validateSessionRecord", () => {
   });
 
   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");
+    // Act
+    const result = validateSessionRecord({ ...record, schemaVersion: "99" });
+
+    // Assert
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("schemaVersion");
   });
 
   test("rejects a structurally broken record", () => {
-    const r = validateSessionRecord({ ...record, revisions: "nope" });
-    expect(r.ok).toBe(false);
+    // Act
+    const result = validateSessionRecord({ ...record, revisions: "nope" });
+
+    // Assert
+    expect(result.ok).toBe(false);
+  });
+});
+
+/**
+ * Wire pins: every schema's entries must cover exactly the keys of the
+ * schema type it mirrors. Runtime complement to the compile-time EntriesOf
+ * check - the samples are fully populated and typed, so a new field in
+ * @cueloop/schema shows up here too.
+ */
+describe("wire pins", () => {
+  const keys = (subject: object) => Object.keys(subject).sort();
+  const entryKeys = (schema: { entries: object }) => Object.keys(schema.entries).sort();
+
+  const fullMeta: Required<ArtifactMeta> = {
+    cwd: "/repo",
+    agent: "claude-code",
+    agentSessionId: "sess-1",
+    planPath: "/repo/plan.md",
+    prototypePath: "/repo/proto.html",
+    pr: "org/repo#1",
+    herdrPane: "%7",
+    title: "Plan",
+  };
+  const fullAnchor: Required<Anchor> = {
+    quote: "q",
+    prefix: "p",
+    suffix: "s",
+    blockIndex: 0,
+    start: 0,
+    end: 1,
+    selector: "div.card",
+  };
+  const fullAnnotation: Required<Annotation> = {
+    id: "a1",
+    kind: "comment",
+    anchor: fullAnchor,
+    body: "b",
+    orphan: false,
+    author: "SHA256:abc",
+    resolution: { revision: 2, source: "agent" },
+    createdAt: "now",
+  };
+  const fullArtifact: Required<Artifact> = {
+    type: "plan",
+    content: "# P",
+    meta: fullMeta,
+    files: [{ path: "src/a.ts", oldContents: "old\n", newContents: "new\n", status: "modified" }],
+  };
+  const fullVerdict: Required<Verdict> = {
+    kind: "approve",
+    summary: "",
+    feedback: "",
+    resolvedAt: "now",
+  };
+  const fullRevision: Required<Revision> = { revision: 1, content: "# P", submittedAt: "now" };
+  const fullWorkspace: Required<WorkspaceKey> = { repoRoot: "/repo", branch: "main" };
+  const fullIdentity: Required<Identity> = {
+    id: "SHA256:abc",
+    provider: "ssh",
+    name: "Al",
+    handle: "abc",
+  };
+  const fullSession: Required<ReviewSession> = {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_1",
+    workspace: fullWorkspace,
+    artifact: fullArtifact,
+    revisions: [fullRevision],
+    annotations: [fullAnnotation],
+    workingCopy: "# P edited",
+    viewedPaths: ["src/a.ts"],
+    verdict: fullVerdict,
+    status: "pending",
+    createdAt: "now",
+    shareId: "p_abc123xy",
+    owner: "SHA256:owner",
+    participants: [fullIdentity],
+  };
+
+  test("schema key sets match the schema types", () => {
+    expect(entryKeys(WorkspaceSchema)).toEqual(keys(fullWorkspace));
+    expect(entryKeys(ArtifactMetaSchema)).toEqual(keys(fullMeta));
+    expect(entryKeys(ArtifactSchema)).toEqual(keys(fullArtifact));
+    expect(entryKeys(AnchorSchema)).toEqual(keys(fullAnchor));
+    // wire annotations arrive without createdAt; the daemon stamps it
+    const { createdAt: _stamped, ...wireAnnotation } = fullAnnotation;
+
+    expect(entryKeys(AnnotationSchema)).toEqual(keys(wireAnnotation));
+    expect(entryKeys(RevisionSchema)).toEqual(keys(fullRevision));
+    expect(entryKeys(VerdictSchema)).toEqual(keys(fullVerdict));
+    expect(entryKeys(IdentitySchema)).toEqual(keys(fullIdentity));
+    expect(entryKeys(SessionRecordSchema)).toEqual(keys(fullSession));
+    // persisted annotations carry the stamped createdAt
+    const stored = SessionRecordSchema.entries.annotations.item;
+
+    expect(entryKeys(stored)).toEqual(keys(fullAnnotation));
+  });
+
+  test("a fully-populated meta survives validation and DaemonCore unchanged", () => {
+    const home = mkdtempSync(join(tmpdir(), "cueloop-val-"));
+
+    try {
+      // Arrange
+      const params = parseParams("session.create", {
+        workspace: fullWorkspace,
+        artifact: { type: "plan", content: "# P", meta: fullMeta },
+      });
+      const core = new DaemonCore(home);
+
+      // Act
+      const created = core.sessionCreate(params);
+
+      // Assert
+      expect(core.sessionGet(created.id).artifact.meta).toEqual(fullMeta);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
   });
 });