@cueloop/schema 0.1.0-alpha.9 → 0.1.0-alpha.90

package/src/path-view.test.ts

@@ -0,0 +1,206 @@
+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: [],
+    message: null,
+    createdAt: AT,
+  });
+
+  history = appendEntry(history, { type: "comment", annotationId: "a1", createdAt: AT }).history;
+  history = appendEntry(history, {
+    type: "revision",
+    by: "reviewer",
+    content: "Plan v1 edited",
+    textCuts: [{ start: 5, end: 8, quote: "v1 " }],
+    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.textCuts).toEqual([{ start: 5, end: 8, quote: "v1 " }]);
+    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.textCuts).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.textCuts).toEqual([{ start: 5, end: 8, quote: "v1 " }]);
+    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",
+      message: null,
+      status: "pending",
+      createdAt: AT,
+    };
+
+    // Act
+    applyPathView(session, {
+      content: "Plan v1",
+      workingCopy: undefined,
+      textCuts: 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,
+      message: 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: [],
+      message: 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,
+      message: 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,90 @@
+/**
+ * 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, TextCut } 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;
+  /** Exact character Cuts attached to the reviewer revision at the path head. */
+  textCuts: TextCut[] | 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,
+    textCuts: derived.head.by === "reviewer" ? derived.head.textCuts : undefined,
+    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.textCuts?.length) session.textCuts = view.textCuts;
+  else delete session.textCuts;
+  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/share-access.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { isShareViewerAllowed } from "./share-access";
+
+describe("isShareViewerAllowed", () => {
+  test("an unauthenticated viewer is refused", () => {
+    expect(isShareViewerAllowed({ githubLogins: ["octocat"] }, undefined)).toBe(false);
+  });
+
+  test("a member is admitted, case-insensitively", () => {
+    expect(isShareViewerAllowed({ githubLogins: ["OctoCat"] }, "octocat")).toBe(true);
+  });
+
+  test("a non-member is refused", () => {
+    expect(isShareViewerAllowed({ githubLogins: ["octocat"] }, "hubot")).toBe(false);
+  });
+
+  test("an empty allowlist admits no one", () => {
+    expect(isShareViewerAllowed({ githubLogins: [] }, "octocat")).toBe(false);
+  });
+});

package/src/share-access.ts

@@ -0,0 +1,13 @@
+/** Whether a github login may view a private share; membership is case-insensitive and an unauthenticated viewer is never allowed. */
+
+import type { ShareAccess } from "./types";
+
+export function isShareViewerAllowed(
+  access: ShareAccess,
+  githubLogin: string | undefined,
+): boolean {
+  if (githubLogin === undefined) return false;
+  const login = githubLogin.toLowerCase();
+
+  return access.githubLogins.some((allowed) => allowed.toLowerCase() === login);
+}

package/src/share-links.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { SCHEMA_VERSION, type Thread } from "./types";
+import { threadShareLinks, withShareLinks } from "./share-links";
+
+function thread(overrides: Partial<Thread> = {}): Thread {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_1",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "# Plan\n", meta: {} },
+    revisions: [{ revision: 1, content: "# Plan\n", submittedAt: "2026-01-01T00:00:00.000Z" }],
+    annotations: [],
+    message: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+describe("share-link migration", () => {
+  test("a never-shared thread has no links", () => {
+    expect(threadShareLinks(thread())).toBeUndefined();
+    expect(withShareLinks(thread()).shares).toBeUndefined();
+  });
+
+  test("a legacy private share migrates into a one-element list", () => {
+    const legacy = thread({
+      shareId: "p_abc123xy",
+      access: { githubLogins: ["octocat"] },
+      owner: "SHA256:owner",
+      shareBranch: "feature",
+    });
+
+    expect(withShareLinks(legacy).shares).toEqual([
+      {
+        id: "p_abc123xy",
+        requireAuth: true,
+        allowlist: ["octocat"],
+        owner: "SHA256:owner",
+        shareBranch: "feature",
+      },
+    ]);
+  });
+
+  test("a legacy public share migrates as requireAuth false with an empty allowlist", () => {
+    const legacy = thread({ shareId: "p_public00", owner: "SHA256:owner" });
+    const [link] = withShareLinks(legacy).shares!;
+
+    expect(link).toMatchObject({ id: "p_public00", requireAuth: false, allowlist: [] });
+  });
+
+  test("a thread that already has shares is returned untouched", () => {
+    const modern = thread({
+      shares: [{ id: "p_modern00", name: "team", requireAuth: false, allowlist: [] }],
+      // stale legacy fields must not override the explicit shares
+      shareId: "p_legacy00",
+    });
+
+    expect(withShareLinks(modern).shares).toEqual([
+      { id: "p_modern00", name: "team", requireAuth: false, allowlist: [] },
+    ]);
+  });
+});

package/src/share-links.ts

@@ -0,0 +1,29 @@
+import type { ShareLink, Thread } from "./types";
+
+/**
+ * A thread's share links, migrating a legacy single share (scalar shareId +
+ * access + owner + shareBranch) into a one-element list. Undefined when the
+ * thread was never shared. Records already carrying `shares` are returned as-is.
+ */
+export function threadShareLinks(session: Thread): ShareLink[] | undefined {
+  if (session.shares !== undefined) return session.shares;
+  if (session.shareId === undefined) return undefined;
+
+  return [
+    {
+      id: session.shareId,
+      requireAuth: session.access !== undefined,
+      allowlist: session.access?.githubLogins ?? [],
+      owner: session.owner,
+      shareBranch: session.shareBranch,
+    },
+  ];
+}
+
+/** The thread with `shares` populated from the legacy fields when absent; a never-shared thread is unchanged. */
+export function withShareLinks(session: Thread): Thread {
+  if (session.shares !== undefined) return session;
+  const shares = threadShareLinks(session);
+
+  return shares ? { ...session, shares } : session;
+}

package/src/thread-surface.test.ts

@@ -0,0 +1,6 @@
+import { expect, test } from "bun:test";
+import { manualThreadOpenCommand } from "./thread-surface";
+
+test("manual Thread command uses the shared harness wording", () => {
+  expect(manualThreadOpenCommand("ses_123")).toBe("Open cueloop threads: cueloop ses_123");
+});

package/src/thread-surface.ts

@@ -0,0 +1,6 @@
+export type ThreadSurfaceOpenStatus = "opened" | "focused" | "disabled" | "unavailable" | "failed";
+
+/** Give a harness the same manual command when any terminal integration cannot open. */
+export function manualThreadOpenCommand(threadId: string): string {
+  return `Open cueloop threads: cueloop ${threadId}`;
+}

package/src/types.test.ts

@@ -1,17 +1,70 @@
 import { describe, expect, test } from "bun:test";
-import { newAnnotationId, verdictAllows } from "./types";
+import {
+  annotationTarget,
+  ARTIFACT_TYPES,
+  WORKFLOW_KINDS,
+  isArtifactType,
+  isMarkdownArtifact,
+  newAnnotationId,
+  messageAllows,
+} from "./types";
 
-describe("verdictAllows", () => {
+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("WORKFLOW_KINDS", () => {
+  test("review and refine are workflows, not artifact types", () => {
+    expect(WORKFLOW_KINDS).toEqual(["plan", "reply", "prototype", "diff", "review", "refine"]);
+    expect(isArtifactType("review")).toBe(false);
+    expect(isArtifactType("refine")).toBe(false);
+  });
+});
+
+describe("messageAllows", () => {
   test("only approve maps to allow", () => {
-    expect(verdictAllows("approve")).toBe(true);
-    expect(verdictAllows("comment")).toBe(false);
-    expect(verdictAllows("request_changes")).toBe(false);
+    expect(messageAllows("approved")).toBe(true);
+    expect(messageAllows("comment")).toBe(false);
+    expect(messageAllows("changes_requested")).toBe(false);
+  });
+});
+
+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]+$/);
   });