@cueloop/schema 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/participants.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { registerParticipant } from "./participants";
+import { SCHEMA_VERSION, type Thread } from "./types";
+
+function emptySession(): Thread {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_1",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "# Plan\n", meta: {} },
+    revisions: [],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+describe("registerParticipant", () => {
+  test("adds a new author with a display name", () => {
+    // Act
+    const next = registerParticipant(emptySession(), "SHA256:ana", "Ana");
+
+    // Assert
+    expect(next.participants).toEqual([{ id: "SHA256:ana", provider: "ssh", name: "Ana" }]);
+  });
+
+  test("records presence without a name (renders anonymous)", () => {
+    // Act
+    const next = registerParticipant(emptySession(), "SHA256:ana");
+
+    // Assert
+    expect(next.participants).toEqual([{ id: "SHA256:ana", provider: "ssh" }]);
+  });
+
+  test("a nameless revisit never erases a name a past visit set", () => {
+    // Arrange
+    const named = registerParticipant(emptySession(), "SHA256:ana", "Ana");
+
+    // Act
+    const next = registerParticipant(named, "SHA256:ana");
+
+    // Assert
+    expect(next).toBe(named);
+    expect(next.participants).toEqual([{ id: "SHA256:ana", provider: "ssh", name: "Ana" }]);
+  });
+
+  test("a later name updates the existing identity in place", () => {
+    // Arrange
+    const present = registerParticipant(emptySession(), "SHA256:ana");
+
+    // Act
+    const next = registerParticipant(present, "SHA256:ana", "Ana");
+
+    // Assert
+    expect(next.participants).toEqual([{ id: "SHA256:ana", provider: "ssh", name: "Ana" }]);
+  });
+});

package/src/participants.ts

@@ -0,0 +1,34 @@
+/**
+ * The participant registry: every annotation carries an `author` id, and the
+ * rail resolves that id to a display name through `session.participants`. This
+ * registers an author in that registry so a name search on "participant" or
+ * "author name" lands here.
+ */
+
+import type { Identity, Thread } from "./types";
+
+/**
+ * Return the session with `author` present in the participant registry, setting
+ * the display name when one is given. A nameless call only records presence (the
+ * rail renders anonymous) and never erases a name a past visit set. Immutable:
+ * the input session is not mutated.
+ */
+export function registerParticipant(session: Thread, author: string, name?: string): Thread {
+  const participants = session.participants ?? [];
+  const existing = participants.find((participant) => participant.id === author);
+  const trimmed = name?.trim();
+
+  if (existing && !trimmed) return session;
+  const next: Identity = {
+    id: author,
+    provider: "ssh",
+    ...(trimmed ? { name: trimmed } : existing?.name ? { name: existing.name } : {}),
+  };
+
+  return {
+    ...session,
+    participants: existing
+      ? participants.map((participant) => (participant.id === author ? next : participant))
+      : [...participants, next],
+  };
+}

package/src/path-view.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, test } from "bun:test";
+import {
+  appendEntry,
+  createBranch,
+  historyFromLinear,
+  navigateTo,
+  switchBranch,
+  type SessionHistory,
+} from "./history";
+import { applyPathView, viewFollowing, viewOfPath } from "./path-view";
+import type { Annotation, Thread } from "./types";
+
+const AT = "2026-09-01T10:00:00.000Z";
+
+function annotation(id: string): Annotation {
+  return {
+    id,
+    kind: "comment",
+    anchor: { quote: "q", prefix: "", suffix: "" },
+    body: id,
+    createdAt: AT,
+  };
+}
+
+/** rev1 (agent) -> comment a1 -> reviewer edit -> comment a2, all on main. */
+function threaded(): SessionHistory {
+  let history = historyFromLinear({
+    id: "ses_1",
+    revisions: [{ revision: 1, content: "Plan v1", submittedAt: AT }],
+    annotations: [],
+    verdict: null,
+    createdAt: AT,
+  });
+
+  history = appendEntry(history, { type: "comment", annotationId: "a1", createdAt: AT }).history;
+  history = appendEntry(history, {
+    type: "revision",
+    by: "reviewer",
+    content: "Plan v1 edited",
+    createdAt: AT,
+  }).history;
+  history = appendEntry(history, { type: "comment", annotationId: "a2", createdAt: AT }).history;
+
+  return history;
+}
+
+describe("viewOfPath", () => {
+  test("the artifact is the agent's last revision and the reviewer's head is the working copy", () => {
+    // Act
+    const view = viewOfPath(threaded(), [annotation("a1"), annotation("a2")]);
+
+    // Assert
+    expect(view.content).toBe("Plan v1");
+    expect(view.workingCopy).toBe("Plan v1 edited");
+    expect(view.annotations.map((entry) => entry.id)).toEqual(["a1", "a2"]);
+    expect(view.shelvedAnnotations).toEqual([]);
+  });
+
+  test("navigating back shelves the comments the path no longer reaches, and forward again unshelves them", () => {
+    // Arrange: a branch that stays at the full path, main moved back to the first comment
+    let history = createBranch(threaded(), "full");
+    const known = [annotation("a1"), annotation("a2")];
+
+    history = switchBranch(history, "main");
+    history = navigateTo(history, history.entries[1]!.id);
+
+    // Act
+    const back = viewOfPath(history, known);
+    const forward = viewOfPath(
+      switchBranch(history, "full"),
+      back.annotations.concat(back.shelvedAnnotations),
+    );
+
+    // Assert
+    expect(back.workingCopy).toBeUndefined();
+    expect(back.annotations.map((entry) => entry.id)).toEqual(["a1"]);
+    expect(back.shelvedAnnotations.map((entry) => entry.id)).toEqual(["a2"]);
+    expect(forward.annotations.map((entry) => entry.id)).toEqual(["a1", "a2"]);
+    expect(forward.shelvedAnnotations).toEqual([]);
+  });
+
+  test("a removed comment stays shelved, not deleted", () => {
+    // Arrange
+    let history = threaded();
+
+    history = appendEntry(history, {
+      type: "comment-removed",
+      annotationId: "a1",
+      createdAt: AT,
+    }).history;
+
+    // Act
+    const view = viewOfPath(history, [annotation("a1"), annotation("a2")]);
+
+    // Assert
+    expect(view.annotations.map((entry) => entry.id)).toEqual(["a2"]);
+    expect(view.shelvedAnnotations.map((entry) => entry.id)).toEqual(["a1"]);
+  });
+});
+
+describe("applyPathView", () => {
+  test("writes the view into the record and removes the fields the view leaves empty", () => {
+    // Arrange
+    const session: Thread = {
+      schemaVersion: "1",
+      id: "ses_1",
+      workspace: { repoRoot: "/repo", branch: "main" },
+      artifact: { type: "plan", content: "old", meta: {} },
+      revisions: [],
+      annotations: [annotation("a2")],
+      shelvedAnnotations: [annotation("a1")],
+      workingCopy: "edited",
+      verdict: null,
+      status: "pending",
+      createdAt: AT,
+    };
+
+    // Act
+    applyPathView(session, {
+      content: "Plan v1",
+      workingCopy: undefined,
+      annotations: [annotation("a1"), annotation("a2")],
+      shelvedAnnotations: [],
+    });
+
+    // Assert
+    expect(session.artifact.content).toBe("Plan v1");
+    expect(session.annotations.map((entry) => entry.id)).toEqual(["a1", "a2"]);
+    expect("workingCopy" in session).toBe(false);
+    expect("shelvedAnnotations" in session).toBe(false);
+  });
+});
+
+describe("viewFollowing", () => {
+  test("a share carries one branch's path: its entries, tip, labels, and open comments, nothing shelved", () => {
+    // Arrange: main has a1 and an edit; a branch off a1 has its own comment; the owner stands on the branch
+    let history = threaded();
+
+    history = navigateTo(history, history.entries[1]!.id);
+    history = createBranch(history, "alt");
+    history = appendEntry(history, { type: "comment", annotationId: "b1", createdAt: AT }).history;
+    const session: Thread = {
+      schemaVersion: "1",
+      id: "ses_1",
+      workspace: { repoRoot: "/repo", branch: "main" },
+      artifact: { type: "plan", content: "Plan v1", meta: {} },
+      revisions: [],
+      annotations: [annotation("a1"), annotation("b1")],
+      shelvedAnnotations: [annotation("a2")],
+      workingCopy: "Plan v1 edited",
+      history,
+      verdict: null,
+      status: "pending",
+      createdAt: AT,
+    };
+
+    // Act
+    const shared = viewFollowing(session);
+
+    // Assert: main's path only, back at the first comment, no working copy, no shelf, the branch named
+    expect(shared.shareBranch).toBe("main");
+    expect(shared.history!.tips).toEqual({ main: history.entries[1]!.id });
+    expect(shared.history!.entries.map((entry) => entry.type)).toEqual(["revision", "comment"]);
+    expect(shared.annotations.map((entry) => entry.id)).toEqual(["a1"]);
+    expect("shelvedAnnotations" in shared).toBe(false);
+    expect("workingCopy" in shared).toBe(false);
+    // the owner's record is untouched
+    expect(session.annotations.map((entry) => entry.id)).toEqual(["a1", "b1"]);
+  });
+
+  test("a followed branch that no longer exists falls back to main", () => {
+    // Arrange: a plain main-only history, asked to follow a branch that is not there
+    const history = historyFromLinear({
+      id: "ses_1",
+      revisions: [{ revision: 1, content: "Plan v1", submittedAt: AT }],
+      annotations: [],
+      verdict: null,
+      createdAt: AT,
+    });
+    const session: Thread = {
+      schemaVersion: "1",
+      id: "ses_1",
+      workspace: { repoRoot: "/repo", branch: "main" },
+      artifact: { type: "plan", content: "Plan v1", meta: {} },
+      revisions: [],
+      annotations: [],
+      shareBranch: "gone",
+      history,
+      verdict: null,
+      status: "pending",
+      createdAt: AT,
+    };
+
+    // Act
+    const shared = viewFollowing(session);
+
+    // Assert: it does not throw, and falls back to main
+    expect(shared.shareBranch).toBe("main");
+    expect(shared.history!.branch).toBe("main");
+  });
+});

package/src/path-view.ts

@@ -0,0 +1,85 @@
+/**
+ * The linear view of a session's active path. Every client reads the artifact
+ * text, the working copy, and the comments straight off the record, so the
+ * record keeps them materialized; this module recomputes them from the path
+ * whenever a tip moves. Comments the path does not reach are shelved, never
+ * dropped, so a later move can show them again.
+ */
+
+import { derivePath, followBranch, MAIN_BRANCH, pathOf, type SessionHistory } from "./history";
+import type { Annotation, Thread } from "./types";
+
+export interface PathView {
+  /** The last agent revision on the path: what the artifact shows. */
+  content: string;
+  /** The reviewer's edits over it, when the path's head is a reviewer revision. */
+  workingCopy: string | undefined;
+  /** The comments open on the path, in path order. */
+  annotations: Annotation[];
+  /** Every other comment the session knows. */
+  shelvedAnnotations: Annotation[];
+}
+
+/**
+ * Fold the active path over every comment the session holds, on or off the
+ * path. Comments on the path whose objects are gone stay gone.
+ */
+export function viewOfPath(history: SessionHistory, known: Annotation[]): PathView {
+  const derived = derivePath(history);
+  const agentHead = pathOf(history)
+    .filter((entry) => entry.type === "revision" && entry.by === "agent")
+    .at(-1);
+  const content = agentHead?.type === "revision" ? agentHead.content : derived.head.content;
+  const byId = new Map(known.map((annotation) => [annotation.id, annotation]));
+  const annotations: Annotation[] = [];
+
+  for (const id of derived.annotationIds) {
+    const annotation = byId.get(id);
+
+    if (annotation) {
+      annotations.push(annotation);
+      byId.delete(id);
+    }
+  }
+
+  return {
+    content,
+    workingCopy: derived.head.content === content ? undefined : derived.head.content,
+    annotations,
+    shelvedAnnotations: [...byId.values()],
+  };
+}
+
+/** Write a path view back into a record, in place; absent fields are removed. */
+export function applyPathView(session: Thread, view: PathView): void {
+  session.artifact = { ...session.artifact, content: view.content };
+  session.annotations = view.annotations;
+  if (view.workingCopy === undefined) delete session.workingCopy;
+  else session.workingCopy = view.workingCopy;
+  if (view.shelvedAnnotations.length === 0) delete session.shelvedAnnotations;
+  else session.shelvedAnnotations = view.shelvedAnnotations;
+}
+
+/**
+ * The record as a share carries it: the followed branch's path and what it
+ * shows, with no other branch, no shelved comment, and no working copy of the
+ * owner's. A followed branch that no longer exists falls back to main. A record
+ * without a history travels as it is.
+ */
+export function viewFollowing(session: Thread, branch?: string): Thread {
+  const asked = branch ?? session.shareBranch ?? MAIN_BRANCH;
+  // a branch that no longer exists falls back to main, matching the daemon
+  const followed =
+    session.history && session.history.tips[asked] === undefined ? MAIN_BRANCH : asked;
+  const shared: Thread = { ...session, shareBranch: followed };
+
+  if (!session.history) return shared;
+  const history = followBranch(session.history, followed);
+  const known = [...session.annotations, ...(session.shelvedAnnotations ?? [])];
+
+  shared.history = history;
+  applyPathView(shared, viewOfPath(history, known));
+  delete shared.shelvedAnnotations;
+
+  return shared;
+}

package/src/types.test.ts

@@ -1,5 +1,37 @@
 import { describe, expect, test } from "bun:test";
-import { newAnnotationId, verdictAllows } from "./types";
+import {
+  annotationTarget,
+  ARTIFACT_TYPES,
+  isArtifactType,
+  isMarkdownArtifact,
+  newAnnotationId,
+  verdictAllows,
+} from "./types";
+
+describe("annotationTarget", () => {
+  test("an annotation with no target means the reviewed artifact", () => {
+    expect(annotationTarget({ target: undefined })).toEqual({ kind: "artifact" });
+  });
+
+  test("a stamped target is returned as-is", () => {
+    const target = { kind: "file", path: "src/x.ts", rev: "worktree" } as const;
+
+    expect(annotationTarget({ target })).toBe(target);
+  });
+});
+
+describe("ARTIFACT_TYPES", () => {
+  test("names every primitive exactly once", () => {
+    expect([...ARTIFACT_TYPES].sort()).toEqual(["diff", "plan", "prototype", "reply"]);
+    expect(new Set(ARTIFACT_TYPES).size).toBe(ARTIFACT_TYPES.length);
+  });
+
+  test("isArtifactType accepts every member and rejects strangers", () => {
+    for (const type of ARTIFACT_TYPES) expect(isArtifactType(type)).toBe(true);
+    expect(isArtifactType("blueprint")).toBe(false);
+    expect(isArtifactType("")).toBe(false);
+  });
+});
 
 describe("verdictAllows", () => {
   test("only approve maps to allow", () => {
@@ -9,9 +41,21 @@ describe("verdictAllows", () => {
   });
 });
 
+describe("isMarkdownArtifact", () => {
+  test("plan, reply, and prototype are markdown; diff is not", () => {
+    expect(isMarkdownArtifact("plan")).toBe(true);
+    expect(isMarkdownArtifact("reply")).toBe(true);
+    expect(isMarkdownArtifact("prototype")).toBe(true);
+    expect(isMarkdownArtifact("diff")).toBe(false);
+  });
+});
+
 describe("newAnnotationId", () => {
   test("unique by construction within a process, even on one millisecond", () => {
+    // Act
     const ids = new Set(Array.from({ length: 10_000 }, () => newAnnotationId()));
+
+    // Assert
     expect(ids.size).toBe(10_000);
     for (const id of ids) expect(id).toMatch(/^a_[0-9a-z]+_[0-9a-z]+$/);
   });