@cueloop/client 0.1.0-alpha.64 → 0.1.0-alpha.66

package/src/share.ts

@@ -12,8 +12,14 @@ import {
   SHARE_UPLOAD_USER,
   packSessionBlob,
 } from "@cueloop/daemon/share-blob";
-import type { Annotation, ReviewSession } from "@cueloop/schema";
+import {
+  removalEntries,
+  viewFollowing,
+  type Annotation,
+  type ReviewSession,
+} from "@cueloop/schema";
 import { SessionRecordSchema } from "@cueloop/daemon/validate";
+import type { SharedMerge } from "@cueloop/daemon/client";
 import * as v from "valibot";
 import { copyToClipboard } from "./clipboard";
 
@@ -41,7 +47,8 @@ export async function publishShare(
 ): Promise<ShareResult> {
   const { stdout, stderr, code } = await runShareSsh(
     "cueloop-share",
-    packSessionBlob(session),
+    // the share follows one branch: collaborators see its path wherever the owner stands
+    packSessionBlob(viewFollowing(session)),
     target,
   );
 
@@ -73,6 +80,25 @@ export function collaboratorAnnotations(session: ReviewSession): Annotation[] {
   return session.annotations.filter((annotation) => annotation.author);
 }
 
+/**
+ * What a pulled share hands the local merge: collaborators' notes, the
+ * participant registry, and the removals the share recorded, by entry id.
+ */
+export function mergeFromShare(remote: ReviewSession): SharedMerge {
+  const merge: SharedMerge = { annotations: collaboratorAnnotations(remote) };
+
+  if (remote.participants) merge.participants = remote.participants;
+  if (remote.history) {
+    merge.removals = removalEntries(remote.history).map((entry) => ({
+      id: entry.id,
+      annotationId: entry.annotationId,
+      createdAt: entry.createdAt,
+    }));
+  }
+
+  return merge;
+}
+
 /**
  * Mirror the planner's own annotations up into the share, so collaborators see
  * them on their next refresh. Owner-gated at the gateway; the notes stay
@@ -92,26 +118,98 @@ export async function pushShare(
   if (code !== 0) throw new Error(`gateway push failed: ${stderr.trim() || `ssh exited ${code}`}`);
 }
 
+export interface ShareWatchHandlers {
+  /** The whole session record, each time the share changes. */
+  onSession: (session: ReviewSession) => void;
+  /** The stream ended, for any reason; the caller decides whether to reconnect. */
+  onClose: (reason: string) => void;
+}
+
+const WatchFrameSchema = v.variant("type", [
+  v.object({ type: v.literal("ready") }),
+  v.object({ type: v.literal("ping") }),
+  v.object({ type: v.literal("session"), session: SessionRecordSchema }),
+]);
+
+/**
+ * Follow a share live: one long-lived `cueloop-watch` ssh stream that carries
+ * a JSON line per change. Owner-gated at the gateway. Returns a stop handle.
+ */
+export function watchShare(
+  shareId: string,
+  handlers: ShareWatchHandlers,
+  target: ShareTarget = {},
+): () => void {
+  const proc = Bun.spawn(shareSshCommand("cueloop-watch", target), {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  proc.stdin.write(shareId);
+  proc.stdin.end();
+  void readLines(proc.stdout, (line) => {
+    const frame = v.safeParse(WatchFrameSchema, JSON.parse(line));
+
+    if (frame.success && frame.output.type === "session") handlers.onSession(frame.output.session);
+  }).catch(() => {});
+  void Promise.all([proc.exited, new Response(proc.stderr).text()]).then(([code, stderr]) =>
+    handlers.onClose(stderr.trim() || `ssh exited ${code}`),
+  );
+
+  return () => proc.kill();
+}
+
+/** Feed each complete line of a byte stream to `onLine`; a torn line is dropped. */
+async function readLines(
+  stream: ReadableStream<Uint8Array>,
+  onLine: (line: string) => void,
+): Promise<void> {
+  const decoder = new TextDecoder();
+  let pending = "";
+
+  for await (const chunk of stream) {
+    pending += decoder.decode(chunk, { stream: true });
+    const lines = pending.split("\n");
+
+    pending = lines.pop() ?? "";
+    for (const line of lines) {
+      if (line.trim() === "") continue;
+      try {
+        onLine(line);
+      } catch {
+        // one bad line never ends the stream
+      }
+    }
+  }
+}
+
+function shareSshCommand(command: string, target: ShareTarget): string[] {
+  const host = target.host ?? DEFAULT_SHARE_HOST;
+  const port = target.port ?? DEFAULT_SHARE_PORT;
+
+  return [
+    "ssh",
+    "-p",
+    String(port),
+    "-o",
+    "StrictHostKeyChecking=accept-new",
+    `${SHARE_UPLOAD_USER}@${host}`,
+    command,
+  ];
+}
+
 /** Run one `share@host:port` ssh command with `stdin`; hand back its streams and exit code. */
 async function runShareSsh(
   command: string,
   stdin: Buffer,
   target: ShareTarget,
 ): Promise<{ stdout: string; stderr: string; code: number }> {
-  const host = target.host ?? DEFAULT_SHARE_HOST;
-  const port = target.port ?? DEFAULT_SHARE_PORT;
-  const proc = Bun.spawn(
-    [
-      "ssh",
-      "-p",
-      String(port),
-      "-o",
-      "StrictHostKeyChecking=accept-new",
-      `${SHARE_UPLOAD_USER}@${host}`,
-      command,
-    ],
-    { stdin, stdout: "pipe", stderr: "pipe" },
-  );
+  const proc = Bun.spawn(shareSshCommand(command, target), {
+    stdin,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
   const [stdout, stderr, code] = await Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),

package/src/test-support.test.ts

@@ -2,8 +2,22 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { createElement, type ReactElement } from "react";
+import type { KeyEvent, MouseEvent } from "@opentui/core";
+import type { TestRendererSetup } from "@opentui/core/testing";
+import { useKeyboard } from "@opentui/react";
+import { testRender } from "@opentui/react/test-utils";
 import { loadConfig } from "./config";
-import { isolateUserConfig } from "./test-support";
+import {
+  clickText,
+  dragText,
+  frameRow,
+  isolateUserConfig,
+  locateText,
+  pressKey,
+  waitForText,
+  type FrameLocation,
+} from "./test-support";
 
 describe("isolateUserConfig", () => {
   test("loadConfig sees defaults while isolated and the env is restored after", () => {
@@ -58,3 +72,181 @@ describe("isolateUserConfig", () => {
     }
   });
 });
+
+interface RecordedKey {
+  name: string;
+  ctrl: boolean;
+  shift: boolean;
+  meta: boolean;
+}
+
+interface RecordedMouseEvent {
+  type: "down" | "up";
+  x: number;
+  y: number;
+}
+
+interface FixtureLog {
+  keys: RecordedKey[];
+  mouseEvents: RecordedMouseEvent[];
+  pressZoneClicks: number[];
+}
+
+/**
+ * A minimal interaction surface: one keyboard recorder, a root box recording
+ * down/up coordinates, and stacked text rows at known positions.
+ */
+function InteractionFixture(properties: { log: FixtureLog }): ReactElement {
+  const { log } = properties;
+
+  useKeyboard((key: KeyEvent) => {
+    log.keys.push({ name: key.name, ctrl: key.ctrl, shift: key.shift, meta: key.meta });
+  });
+
+  return createElement(
+    "box",
+    {
+      width: "100%",
+      height: "100%",
+      flexDirection: "column",
+      onMouseDown: (event: MouseEvent) => {
+        log.mouseEvents.push({ type: "down", x: event.x, y: event.y });
+      },
+      onMouseUp: (event: MouseEvent) => {
+        log.mouseEvents.push({ type: "up", x: event.x, y: event.y });
+      },
+    },
+    createElement("text", { content: "header line" }),
+    createElement("text", { content: "   shifted needle" }),
+    createElement("text", { content: "  drag from here" }),
+    createElement("text", { content: "     drop to here" }),
+    createElement("text", {
+      content: "press zone",
+      onMouseDown: (event: MouseEvent) => {
+        log.pressZoneClicks.push(event.x);
+      },
+    }),
+  );
+}
+
+async function renderFixture(): Promise<{ setup: TestRendererSetup; log: FixtureLog }> {
+  const log: FixtureLog = { keys: [], mouseEvents: [], pressZoneClicks: [] };
+  const setup = await testRender(createElement(InteractionFixture, { log }), {
+    width: 40,
+    height: 8,
+  });
+
+  await waitForText(setup, "press zone");
+
+  return { setup, log };
+}
+
+describe("pressKey", () => {
+  test("a ctrl+letter chord reaches the keyboard handler with ctrl set", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await pressKey(setup, "o", { ctrl: true });
+
+    // Assert
+    expect(log.keys).toEqual([{ name: "o", ctrl: true, shift: false, meta: false }]);
+  });
+
+  test("a named key with a modifier arrives as the modified key", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await pressKey(setup, "ARROW_RIGHT", { shift: true });
+
+    // Assert
+    expect(log.keys).toEqual([{ name: "right", ctrl: false, shift: true, meta: false }]);
+  });
+});
+
+describe("locateText", () => {
+  test("returns the 0-based row and start column of the first occurrence", async () => {
+    // Arrange
+    const { setup } = await renderFixture();
+
+    // Act
+    const located = locateText(setup, "shifted needle");
+
+    // Assert
+    expect(located).toEqual({ row: 1, column: 3 });
+  });
+
+  test("a miss throws with the needle and the full frame in the message", async () => {
+    // Arrange
+    const { setup } = await renderFixture();
+
+    // Act
+    const locateMissing = (): FrameLocation => locateText(setup, "absent needle");
+
+    // Assert
+    expect(locateMissing).toThrow('"absent needle"');
+    expect(locateMissing).toThrow("header line");
+  });
+});
+
+describe("frameRow", () => {
+  test("returns rows that reflect the vertical layout", async () => {
+    // Arrange
+    const { setup } = await renderFixture();
+
+    // Act / Assert
+    expect(frameRow(setup, "header line")).toBe(0);
+    expect(frameRow(setup, "drop to here")).toBe(3);
+    expect(frameRow(setup, "press zone")).toBe(4);
+  });
+});
+
+describe("clickText", () => {
+  test("lands the click on the element rendering the needle", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await clickText(setup, "press zone");
+
+    // Assert
+    expect(log.pressZoneClicks).toEqual([0]);
+  });
+
+  test("charOffset shifts the click within the needle", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await clickText(setup, "press zone", 6);
+
+    // Assert
+    expect(log.pressZoneClicks).toEqual([6]);
+  });
+});
+
+describe("dragText", () => {
+  test("delivers the down at the from-text and the up at the to-text", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await dragText(setup, "drag from here", "drop to here");
+
+    // Assert
+    expect(log.mouseEvents).toContainEqual({ type: "down", x: 2, y: 2 });
+    expect(log.mouseEvents).toContainEqual({ type: "up", x: 5, y: 3 });
+  });
+
+  test("an end offset lands the up that many characters past the to-text", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await dragText(setup, "drag from here", "drop to here", 4);
+
+    // Assert
+    expect(log.mouseEvents).toContainEqual({ type: "up", x: 9, y: 3 });
+  });
+});

package/src/test-support.ts

@@ -67,6 +67,70 @@ export async function typeText(setup: TestRendererSetup, text: string): Promise<
   await settle(setup);
 }
 
+/** Drive one key press with modifiers: KeyCodes names ("ARROW_RIGHT") or single letters (ctrl+o). */
+export async function pressKey(
+  setup: TestRendererSetup,
+  key: string,
+  modifiers?: { shift?: boolean; ctrl?: boolean; meta?: boolean },
+): Promise<void> {
+  setup.mockInput.pressKey(key, modifiers);
+  await settle(setup);
+}
+
+/** A 0-based cell position within a captured char frame. */
+export interface FrameLocation {
+  row: number;
+  column: number;
+}
+
+/** Locate the first visual line containing the needle: 0-based row and start column. */
+export function locateText(setup: TestRendererSetup, needle: string): FrameLocation {
+  const frame = setup.captureCharFrame();
+
+  for (const [row, line] of frame.split("\n").entries()) {
+    const column = line.indexOf(needle);
+
+    if (column !== -1) return { row, column };
+  }
+
+  throw new Error(`locateText ${JSON.stringify(needle)} not found.\nframe:\n${frame}`);
+}
+
+/** The 0-based visual row of the needle - for relative vertical-layout assertions. */
+export function frameRow(setup: TestRendererSetup, needle: string): number {
+  return locateText(setup, needle).row;
+}
+
+/** Click the first on-screen occurrence of the needle, offset in characters from its start. */
+export async function clickText(
+  setup: TestRendererSetup,
+  needle: string,
+  charOffset = 0,
+): Promise<void> {
+  const { row, column } = locateText(setup, needle);
+
+  await setup.mockMouse.click(column + charOffset, row);
+  await settle(setup);
+}
+
+/**
+ * Drag from the first occurrence of one needle to the first occurrence of
+ * another, `toCharOffset` characters past the second needle's start - so a
+ * character-precise selection can end inside or right after a word.
+ */
+export async function dragText(
+  setup: TestRendererSetup,
+  fromNeedle: string,
+  toNeedle: string,
+  toCharOffset = 0,
+): Promise<void> {
+  const from = locateText(setup, fromNeedle);
+  const to = locateText(setup, toNeedle);
+
+  await setup.mockMouse.drag(from.column, from.row, to.column + toCharOffset, to.row);
+  await settle(setup);
+}
+
 // Below the 60s per-test budget so a genuinely stuck wait throws its frame
 // error (useful) before bun's bare "timed out" fires. Generous because a
 // contended CI runner starves the render loop and daemon round-trips.

package/src/theme.ts

@@ -54,8 +54,8 @@ export const DARK: Theme = {
   text: "#e4e6ec",
   textMuted: "#b1b6c4",
   textDim: "#6b7280",
-  accent: "#f5a3a3",
-  accentInk: "#2a1416",
+  accent: "#cba6f7",
+  accentInk: "#17171a",
   green: "#62d96b",
   red: "#f08080",
   blue: "#a9c8f5",
@@ -80,8 +80,8 @@ export const LIGHT: Theme = {
   text: "#1c1d24",
   textMuted: "#4b5162",
   textDim: "#868c9c",
-  accent: "#b5495b",
-  accentInk: "#ffffff",
+  accent: "#5b3ea6",
+  accentInk: "#fbfbfa",
   green: "#2f8a3e",
   red: "#c0392b",
   blue: "#2f6fb0",

package/src/thread-chords.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test } from "bun:test";
+import { resolveThreadChord } from "./thread-chords";
+
+const owner = { composing: false, isOwner: true, resolved: false, treeActive: false };
+
+describe("resolveThreadChord", () => {
+  test("ctrl+enter opens the submit overlay for an owner with an open review", () => {
+    // Assert: the terminal-safe chord and the cmd forms all submit
+    expect(resolveThreadChord({ name: "return", ctrl: true }, owner)).toEqual({
+      type: "openSubmit",
+    });
+    expect(resolveThreadChord({ name: "return", super: true }, owner)).toEqual({
+      type: "openSubmit",
+    });
+    expect(resolveThreadChord({ name: "enter", meta: true }, owner)).toEqual({
+      type: "openSubmit",
+    });
+  });
+
+  test("session chords map to their intents", () => {
+    // Assert
+    expect(resolveThreadChord({ name: "e", ctrl: true }, owner)).toEqual({ type: "edit" });
+    expect(resolveThreadChord({ name: "s", ctrl: true }, owner)).toEqual({ type: "share" });
+    expect(resolveThreadChord({ name: "r", ctrl: true }, owner)).toEqual({
+      type: "cycleReviewPanel",
+    });
+  });
+
+  test("option chords drive the rail and curation with the plan sheet's letters", () => {
+    // Assert
+    expect(resolveThreadChord({ name: "n", meta: true }, owner)).toEqual({
+      type: "nextAnnotation",
+    });
+    expect(resolveThreadChord({ name: "p", meta: true }, owner)).toEqual({
+      type: "prevAnnotation",
+    });
+    expect(resolveThreadChord({ name: "e", meta: true }, owner)).toEqual({ type: "editCard" });
+    expect(resolveThreadChord({ name: "backspace", meta: true }, owner)).toEqual({
+      type: "removeAnnotation",
+    });
+    expect(resolveThreadChord({ name: "r", meta: true }, owner)).toEqual({ type: "openRename" });
+    expect(resolveThreadChord({ name: "x", meta: true }, owner)).toEqual({ type: "cut" });
+    expect(resolveThreadChord({ name: "u", meta: true }, owner)).toEqual({
+      type: "restoreCuration",
+    });
+    expect(resolveThreadChord({ name: "w", meta: true }, owner)).toEqual({
+      type: "resizeReviewPanel",
+      direction: 1,
+    });
+    expect(resolveThreadChord({ name: "x", meta: true }, { ...owner, isOwner: false })).toEqual({
+      type: "status",
+      message: "observer - read-only",
+    });
+  });
+
+  test("an open composer swallows every chord, so typing is never hijacked", () => {
+    // Assert
+    expect(
+      resolveThreadChord({ name: "return", ctrl: true }, { ...owner, composing: true }),
+    ).toBeNull();
+    expect(resolveThreadChord({ name: "s", ctrl: true }, { ...owner, composing: true })).toBeNull();
+  });
+
+  test("plain keys and unbound chords belong to the document grammar", () => {
+    // Assert
+    expect(resolveThreadChord({ name: "return" }, owner)).toBeNull();
+    expect(resolveThreadChord({ name: "s" }, owner)).toBeNull();
+    expect(resolveThreadChord({ name: "x", ctrl: true }, owner)).toBeNull();
+  });
+
+  test("a collaborator is told a primitive is read-only, and a resolved review cannot be resubmitted", () => {
+    // Assert
+    const collaborator = { ...owner, isOwner: false };
+    const readOnly = { type: "status" as const, message: "observer - read-only" };
+
+    expect(resolveThreadChord({ name: "return", ctrl: true }, collaborator)).toEqual(readOnly);
+    expect(resolveThreadChord({ name: "e", ctrl: true }, collaborator)).toEqual(readOnly);
+    expect(resolveThreadChord({ name: "s", ctrl: true }, collaborator)).toEqual(readOnly);
+    expect(resolveThreadChord({ name: "r", ctrl: true }, collaborator)).toEqual({
+      type: "cycleReviewPanel",
+    });
+    expect(
+      resolveThreadChord({ name: "return", ctrl: true }, { ...owner, resolved: true }),
+    ).toBeNull();
+  });
+
+  test("a resolved review refuses every change and says so; renaming an author stays open", () => {
+    // Arrange
+    const resolved = { ...owner, resolved: true };
+    const submitted = { type: "status" as const, message: "review submitted - read-only" };
+
+    // Assert
+    expect(resolveThreadChord({ name: "e", ctrl: true }, resolved)).toEqual(submitted);
+    expect(resolveThreadChord({ name: "e", meta: true }, resolved)).toEqual(submitted);
+    expect(resolveThreadChord({ name: "backspace", meta: true }, resolved)).toEqual(submitted);
+    expect(resolveThreadChord({ name: "x", meta: true }, resolved)).toEqual(submitted);
+    expect(resolveThreadChord({ name: "u", meta: true }, resolved)).toEqual(submitted);
+    expect(resolveThreadChord({ name: "r", meta: true }, resolved)).toEqual({ type: "openRename" });
+    expect(resolveThreadChord({ name: "s", ctrl: true }, resolved)).toEqual({ type: "share" });
+  });
+
+  test("the tree chords: toggle, move on the Tree tab, go, branch, label, fork, hand off", () => {
+    // Arrange
+    const onTree = { ...owner, treeActive: true };
+    const readOnly = { type: "status" as const, message: "observer - read-only" };
+    const submitted = { type: "status" as const, message: "review submitted - read-only" };
+
+    // Assert: next / previous follow the tab that shows
+    expect(resolveThreadChord({ name: "t", meta: true }, owner)).toEqual({ type: "toggleTree" });
+    expect(resolveThreadChord({ name: "n", meta: true }, onTree)).toEqual({
+      type: "treeMove",
+      direction: 1,
+    });
+    expect(resolveThreadChord({ name: "p", meta: true }, onTree)).toEqual({
+      type: "treeMove",
+      direction: -1,
+    });
+    expect(resolveThreadChord({ name: "n", meta: true }, owner)).toEqual({
+      type: "nextAnnotation",
+    });
+    expect(resolveThreadChord({ name: "g", meta: true }, owner)).toEqual({ type: "treeGo" });
+    expect(resolveThreadChord({ name: "b", meta: true }, owner)).toEqual({ type: "treeBranch" });
+    expect(resolveThreadChord({ name: "l", meta: true }, owner)).toEqual({ type: "treeLabel" });
+    expect(resolveThreadChord({ name: "f", meta: true }, owner)).toEqual({ type: "treeFork" });
+    expect(resolveThreadChord({ name: "h", meta: true }, owner)).toEqual({ type: "treeForkShare" });
+    // moving the tree is the owner's; a fork is open after a verdict, a move is not
+    expect(resolveThreadChord({ name: "g", meta: true }, { ...owner, isOwner: false })).toEqual(
+      readOnly,
+    );
+    expect(resolveThreadChord({ name: "f", meta: true }, { ...owner, isOwner: false })).toEqual(
+      readOnly,
+    );
+    expect(resolveThreadChord({ name: "b", meta: true }, { ...owner, resolved: true })).toEqual(
+      submitted,
+    );
+    expect(resolveThreadChord({ name: "f", meta: true }, { ...owner, resolved: true })).toEqual({
+      type: "treeFork",
+    });
+    expect(resolveThreadChord({ name: "t", meta: true }, { ...owner, isOwner: false })).toEqual({
+      type: "toggleTree",
+    });
+  });
+
+  test("an observer cannot edit or delete cards either", () => {
+    // Arrange
+    const observer = { ...owner, isOwner: false };
+    const readOnly = { type: "status" as const, message: "observer - read-only" };
+
+    // Assert
+    expect(resolveThreadChord({ name: "e", meta: true }, observer)).toEqual(readOnly);
+    expect(resolveThreadChord({ name: "backspace", meta: true }, observer)).toEqual(readOnly);
+    expect(resolveThreadChord({ name: "r", meta: true }, observer)).toEqual({ type: "openRename" });
+  });
+});