@cueloop/client 0.1.0-alpha.21 → 0.1.0-alpha.23

package/src/keymap.test.ts

@@ -1,8 +1,4 @@
-/**
- * The keyboard grammar as data: every mode x key produces a known intent
- * list, the read-only rule is one gate, and plan and diff reviews share one
- * path for annotation navigation, deletion, and submit.
- */
+/** The keyboard grammar as data: every mode x key maps to a known intent list, gated once by the read-only rule. */
 
 import { describe, expect, test } from "bun:test";
 import { DEFAULT_KEYS } from "./config";
@@ -30,6 +26,7 @@ function key(name: string, shift = false, meta = false): { name: string; shift:
 }
 
 describe("compose overlay", () => {
+  // Arrange
   const keyState = state({ overlay: "compose" });
   const table: [string, Intent[]][] = [
     ["escape", [{ type: "closeOverlay" }]],
@@ -57,6 +54,7 @@ describe("compose overlay", () => {
 });
 
 describe("submit overlay", () => {
+  // Arrange
   const keyState = state({ overlay: "submit" });
   const table: [string, Intent[]][] = [
     ["escape", [{ type: "closeOverlay" }]],
@@ -75,6 +73,7 @@ describe("submit overlay", () => {
 });
 
 describe("completion overlay", () => {
+  // Arrange
   const prompt = state({ overlay: "completion-prompt" });
   const counting = state({ overlay: "completion-counting" });
   const table: [KeyState, string, Intent[]][] = [
@@ -97,6 +96,7 @@ describe("completion overlay", () => {
 });
 
 describe("inbox mode", () => {
+  // Arrange
   const keyState = state({ view: "inbox" });
   const table: [string, Intent[]][] = [
     ["j", [{ type: "inboxMove", to: "down" }]],
@@ -116,7 +116,10 @@ describe("inbox mode", () => {
   }
 
   test("an empty inbox swallows every non-quit key", () => {
+    // Arrange
     const empty = state({ view: "inbox", hasInboxItems: false });
+
+    // Assert
     for (const name of ["j", "k", "down", "up", "return", "enter"]) {
       expect(reduceKey(empty, key(name))).toEqual([]);
     }
@@ -124,7 +127,63 @@ describe("inbox mode", () => {
   });
 });
 
+describe("collaborator (share) capabilities", () => {
+  test("can annotate: comment opens the composer", () => {
+    // Arrange
+    const collab = state({ canEditPlan: false, canSubmitVerdict: false });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("c"), "comment")).toEqual([{ type: "openCompose", kind: "comment", from: "cursor" }]);
+  });
+
+  test("can edit their own card: edit with a focused annotation rewrites it", () => {
+    // Arrange
+    const collab = state({ canEditPlan: false, hasFocusedAnnotation: true });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("e"), "edit")).toEqual([{ type: "editCard" }]);
+  });
+
+  test("cannot edit the plan: cut/edit with no card is silent (no nag, no button)", () => {
+    // Arrange
+    const collab = state({ canEditPlan: false, hasFocusedAnnotation: false });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("e"), "edit")).toEqual([]);
+    expect(reduceKey(collab, key("c"), "cut")).toEqual([]);
+  });
+
+  test("cannot submit a verdict: there is no agent on a share", () => {
+    // Arrange
+    const collab = state({ canSubmitVerdict: false });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("x"), "submit")).toEqual([{ type: "status", message: "shared view - your notes save as you go; q to leave" }]);
+  });
+
+  test("cannot re-share: only the owner shares", () => {
+    // Arrange
+    const collab = state({ canShare: false });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("S", true), "share")).toEqual([{ type: "status", message: "only the plan owner can share" }]);
+  });
+});
+
+describe("share", () => {
+  test("the owner's share key publishes", () => {
+    // Act / Assert
+    expect(reduceKey(state(), key("S", true), "share")).toEqual([{ type: "share" }]);
+  });
+
+  test("an observer cannot share", () => {
+    // Act / Assert
+    expect(reduceKey(state({ readOnly: true }), key("S", true), "share")).toEqual([{ type: "status", message: "observer - read-only" }]);
+  });
+});
+
 describe("plan normal mode", () => {
+  // Arrange
   const keyState = state();
   const table: [string, boolean, Intent[]][] = [
     ["j", false, [{ type: "move", to: "down" }]],
@@ -154,7 +213,10 @@ describe("plan normal mode", () => {
   }
 
   test("resolved sessions guard the mutating verbs", () => {
+    // Arrange
     const resolvedState = state({ resolved: true });
+
+    // Assert
     for (const name of ["c", "s", "x", "e"]) {
       expect(reduceKey(resolvedState, key(name))).toEqual([{ type: "status", message: "review submitted - read-only" }]);
     }
@@ -163,27 +225,37 @@ describe("plan normal mode", () => {
   });
 
   test("cut text cannot host a comment or a span", () => {
+    // Arrange
     const cut = state({ cursorAnnotatable: false });
+
+    // Assert
     expect(reduceKey(cut, key("c"))).toEqual([{ type: "status", message: "text is cut - restore it first" }]);
     expect(reduceKey(cut, key("s"))).toEqual([{ type: "status", message: "text is cut - restore it first" }]);
     expect(reduceKey(cut, key("v"))).toEqual([]);
   });
 
   test("annotation navigation without annotations reports, delete without focus is silent", () => {
+    // Arrange
     const none = state({ annotationCount: 0, hasFocusedAnnotation: false });
+
+    // Assert
     expect(reduceKey(none, key("n"))).toEqual([{ type: "status", message: "no annotations" }]);
     expect(reduceKey(none, key("p"))).toEqual([{ type: "status", message: "no annotations" }]);
     expect(reduceKey(none, key("backspace"))).toEqual([]);
   });
 
   test("without a selected card x cuts the block and e opens the editor", () => {
+    // Arrange
     const unfocused = state({ hasFocusedAnnotation: false });
+
+    // Assert
     expect(reduceKey(unfocused, key("x"))).toEqual([{ type: "cut" }]);
     expect(reduceKey(unfocused, key("e"))).toEqual([{ type: "edit" }]);
   });
 });
 
 describe("span mode", () => {
+  // Arrange
   const keyState = state({ spanMode: true });
   const table: [string, Intent[]][] = [
     ["l", [{ type: "spanKey", name: "l" }]],
@@ -206,6 +278,7 @@ describe("span mode", () => {
 });
 
 describe("diff mode", () => {
+  // Arrange
   const keyState = state({ view: "diff" });
   const table: [string, Intent[]][] = [
     ["j", [{ type: "move", to: "down" }]],
@@ -229,6 +302,7 @@ describe("diff mode", () => {
   }
 
   test("comment guards: resolved first, then non-code rows", () => {
+    // Assert
     expect(reduceKey(state({ view: "diff", resolved: true }), key("c"))).toEqual([
       { type: "status", message: "review submitted - read-only" },
     ]);
@@ -240,6 +314,7 @@ describe("diff mode", () => {
 
 describe("guided walk", () => {
   test("w enters the walk in diff view; resolved and read-only sessions answer", () => {
+    // Assert
     expect(reduceKey(state({ view: "diff" }), key("w"))).toEqual([{ type: "walkStart" }]);
     expect(reduceKey(state({ view: "diff", resolved: true }), key("w"))).toEqual([
       { type: "status", message: "review submitted - read-only" },
@@ -250,6 +325,7 @@ describe("guided walk", () => {
     expect(reduceKey(state(), key("w"))).toEqual([{ type: "status", message: "the guided walk is a diff-review mode" }]);
   });
 
+  // Arrange
   const walking = state({ view: "diff", overlay: "walk" });
   const table: [string, Intent[]][] = [
     ["]", [{ type: "walkForward" }]],
@@ -268,7 +344,10 @@ describe("guided walk", () => {
   }
 
   test("the end card's return leaves the walk and opens the submit confirm", () => {
+    // Arrange
     const atEnd = state({ view: "diff", overlay: "walk", walkAtEnd: true });
+
+    // Assert
     expect(reduceKey(atEnd, key("return"))).toEqual([{ type: "walkLeave" }, { type: "openSubmit" }]);
     expect(reduceKey(atEnd, key("enter"))).toEqual([{ type: "walkLeave" }, { type: "openSubmit" }]);
   });
@@ -289,17 +368,24 @@ describe("review panel controls", () => {
   }
 
   test("observers may still collapse and resize the panel (it is view state, not a mutation)", () => {
+    // Arrange
     const observer = state({ readOnly: true });
+
+    // Assert
     expect(reduceKey(observer, key("b"))).toEqual([{ type: "cycleReviewPanel" }]);
     expect(reduceKey(observer, key("]"))).toEqual([{ type: "resizeReviewPanel", direction: 1 }]);
   });
 
   test("span mode still owns b as a span verb, not a panel cycle", () => {
+    // Assert
     expect(reduceKey(state({ spanMode: true }), key("b"))).toEqual([{ type: "spanKey", name: "b" }]);
   });
 
   test("the walk overlay keeps the brackets for stepping", () => {
+    // Arrange
     const walking = state({ view: "diff", overlay: "walk" });
+
+    // Assert
     expect(reduceKey(walking, key("]"))).toEqual([{ type: "walkForward" }]);
     expect(reduceKey(walking, key("["))).toEqual([{ type: "walkBack" }]);
   });
@@ -332,15 +418,21 @@ describe("read-only filter", () => {
   });
 
   test("navigation and annotation focus still work for observers", () => {
+    // Arrange
     const keyState = state({ readOnly: true });
+
+    // Assert
     expect(reduceKey(keyState, key("j"))).toEqual([{ type: "move", to: "down" }]);
     expect(reduceKey(keyState, key("n"))).toEqual([{ type: "nextAnnotation" }]);
     expect(reduceKey(keyState, key("q"))).toEqual([{ type: "exit" }]);
   });
 
   test("span-mode c/s are gated by key name even under a rebound keymap", () => {
+    // Arrange
     const rebound = { ...DEFAULT_KEYS, comment: ["m"], suggest: ["t"] };
     const keyState = state({ spanMode: true, readOnly: true, keys: rebound });
+
+    // Assert
     expect(reduceKey(keyState, key("c"))).toEqual([{ type: "status", message: "observer - read-only" }]);
     expect(reduceKey(keyState, key("s"))).toEqual([{ type: "status", message: "observer - read-only" }]);
   });

package/src/keymap.ts

@@ -18,6 +18,7 @@ export type Intent =
   | { type: "spanKey"; name: string }
   | { type: "openCompose"; kind: "comment" | "suggestion"; from: "cursor" | "span" }
   | { type: "openSubmit" }
+  | { type: "share" }
   | { type: "cut" }
   | { type: "edit" }
   | { type: "editCard" }
@@ -50,6 +51,15 @@ export interface KeyState {
   /** Loaded keymap (config.ts): action -> key combos. */
   keys: Record<string, string[]>;
   readOnly: boolean;
+  /**
+   * Owner-only verbs a share collaborator lacks (undefined = owner, allowed).
+   * A collaborator annotates but cannot edit the plan (cut / $EDITOR runs on
+   * the gateway) or submit an agent verdict (there is no agent on a share).
+   */
+  canEditPlan?: boolean;
+  canSubmitVerdict?: boolean;
+  /** Owner-only: publish the plan as a share. A collaborator never re-shares. */
+  canShare?: boolean;
   /** Layer that owns keys before the grammar runs. */
   overlay: "none" | "walk" | "compose" | "submit" | "completion-prompt" | "completion-counting";
   view: "inbox" | "plan" | "diff";
@@ -66,7 +76,7 @@ export interface KeyState {
 }
 
 /** Verbs that write session state; an observer never reaches their handlers. */
-const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit", "walk"]);
+const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit", "walk", "share"]);
 
 const SPAN_KEYS = ["l", "h", "w", "b", "$", "0"];
 
@@ -127,6 +137,12 @@ export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: strin
   const mutating = MUTATING_ACTIONS.has(action ?? "") || (state.spanMode && (name === "c" || name === "s"));
   if (state.readOnly && mutating) return status("observer - read-only");
 
+  // share is a session-level verb: it works from any view, owner only
+  if (action === "share") {
+    if (state.canShare === false) return status("only the plan owner can share");
+    return [{ type: "share" }];
+  }
+
   if (state.view === "inbox") return inboxGrammar(state, name);
   // span mode owns its single-letter keys (b slides the span back) before the
   // review-panel controls claim them
@@ -201,6 +217,9 @@ function planGrammar(state: KeyState, action: string | undefined, name: string):
     // the document selects, the rail edits: with a card selected, Cut deletes
     // the annotation and edit rewrites the card body in place
     if (state.hasFocusedAnnotation) return [action === "cut" ? { type: "removeAnnotation" } : { type: "editCard" }];
+    // editing the plan itself is the owner's verb; a share viewer only annotates,
+    // and has no edit affordance, so the key is silent rather than a nag
+    if (state.canEditPlan === false) return [];
     return [{ type: action }];
   }
   return annotationCluster(state, action) ?? [];
@@ -224,6 +243,10 @@ function annotationCluster(state: KeyState, action: string | undefined): Intent[
     if (state.resolved || !state.hasFocusedAnnotation) return [];
     return [{ type: "removeAnnotation" }];
   }
-  if (action === "submit") return state.resolved ? [] : [{ type: "openSubmit" }];
+  if (action === "submit") {
+    // a collaborator's notes union back as they go; there is no verdict to submit
+    if (state.canSubmitVerdict === false) return status("shared view - your notes save as you go; q to leave");
+    return state.resolved ? [] : [{ type: "openSubmit" }];
+  }
   return null;
 }

package/src/serve.test.ts

@@ -70,6 +70,7 @@ function sshCapture(port: number, until: (frame: string) => boolean, timeoutMs =
 
 describe("cueloop serve", () => {
   test("listens on localhost, persists a host key under CUELOOP_HOME/ssh", () => {
+    // Assert
     expect(handle.host).toBe("127.0.0.1");
     expect(handle.port).toBeGreaterThan(0);
     expect(handle.fingerprints.length).toBe(1);
@@ -78,7 +79,10 @@ describe("cueloop serve", () => {
   });
 
   test("an anonymous ssh client gets the observer TUI for the session", async () => {
+    // Act
     const bytes = await sshCapture(handle.port, (frame) => frame.includes("Rollout Plan") && frame.includes("observer"));
+
+    // Assert
     expect(bytes).toContain("cueloop");
     expect(bytes).toContain("Rollout Plan");
     // observer chrome, not the controller's mutating hint bar
@@ -86,10 +90,13 @@ describe("cueloop serve", () => {
   });
 
   test("two observers can watch at once", async () => {
+    // Act
     const [a, b] = await Promise.all([
       sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
       sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
     ]);
+
+    // Assert
     expect(a).toContain("Rollout Plan");
     expect(b).toContain("Rollout Plan");
   });

package/src/session-controller.ts

@@ -8,7 +8,7 @@
  */
 
 import { SystemClock, type Clock, type TimerHandle } from "@opentui/core";
-import { DaemonClient } from "@cueloop/daemon/client";
+import { DaemonClient, type SessionClient } from "@cueloop/daemon/client";
 import {
   cutBlock,
   detectHerdr,
@@ -23,6 +23,7 @@ import {
   type VerdictKind,
 } from "@cueloop/schema";
 import { loadBundledExporters, type BundledExporter } from "./integrations";
+import { publishShare } from "./share";
 import { buildDisplay, nextWorkBlock, type DisplayBlock } from "./view-plan";
 import { diffRowAnchor, diffRows, type DiffRow } from "./view-diff";
 import { firstUnviewedIndex, walkFiles, type WalkFile } from "./walk";
@@ -72,6 +73,12 @@ export interface ReviewControllerOptions {
   onExit?: (code: number) => void;
   /** Timer source for the auto-close countdown; tests inject a ManualClock. */
   clock?: Clock;
+  /**
+   * How the controller gets its session client. Defaults to dialing the local
+   * daemon; the sharing gateway injects a blob-backed client so the same <App>
+   * renders a decrypted share instead.
+   */
+  openClient?: () => Promise<SessionClient>;
 }
 
 export interface ReviewController {
@@ -115,6 +122,8 @@ export interface ReviewController {
   walkLeave(): void;
   /** Resolve the review, run the export, start the completion hand-back. */
   submit(verdict: VerdictKind, summary: string): void;
+  /** Publish the current session as a share; the ssh line lands on the clipboard. */
+  share(): void;
   /** Close the review and, inside herdr, bounce focus back to the agent. */
   finishReview(): void;
   dismissCompletion(): void;
@@ -134,7 +143,7 @@ export function createReviewController(options: ReviewControllerOptions): Review
 
 class Controller implements ReviewController {
   readonly readOnly: boolean;
-  private client: DaemonClient | null = null;
+  private client: SessionClient | null = null;
   private closed = false;
   private snapshot: ControllerSnapshot = {
     session: null,
@@ -179,7 +188,8 @@ class Controller implements ReviewController {
   connect(): void {
     void (async () => {
       try {
-        const client = await DaemonClient.connect({ home: this.options.home, autostart: true });
+        const openClient = this.options.openClient ?? (() => DaemonClient.connect({ home: this.options.home, autostart: true }));
+        const client = await openClient();
         if (this.closed) return void client.close();
         this.client = client;
         client.onEvent((event) => {
@@ -470,6 +480,15 @@ class Controller implements ReviewController {
       .catch((error: unknown) => this.setStatus(String(error instanceof Error ? error.message : error)));
   }
 
+  share(): void {
+    const session = this.snapshot.session;
+    if (!session) return;
+    this.setStatus("sharing…");
+    publishShare(session)
+      .then(({ line, copied }) => this.setStatus(copied ? `✓ share link copied - ${line}` : line))
+      .catch((error: unknown) => this.setStatus(`share failed: ${error instanceof Error ? error.message : String(error)}`));
+  }
+
   // ── completion hand-back ────────────────────
   private startCounting(remaining: number): void {
     if (remaining <= 0) return this.finishReview();

package/src/share.ts

@@ -0,0 +1,47 @@
+/**
+ * Publish a review session as a share: pack it, stream it to the gateway's
+ * `share` user over SSH, and copy the returned `ssh p_…@host` line to the
+ * clipboard. The planner holds no key, so all this side does is upload; the
+ * gateway seals and stores. Used by both `cueloop share` and the in-TUI
+ * Share button, so the two share exactly the same path.
+ */
+
+import { DEFAULT_SHARE_HOST, DEFAULT_SHARE_PORT, SHARE_UPLOAD_USER, packSessionBlob } from "@cueloop/daemon/share-blob";
+import type { ReviewSession } from "@cueloop/schema";
+import { copyToClipboard } from "./clipboard";
+
+export interface ShareTarget {
+  host?: string;
+  port?: number;
+}
+
+export interface ShareResult {
+  /** The one line to paste: `ssh p_xxxxxxxx@host`. */
+  line: string;
+  /** Whether the line made it onto the system clipboard. */
+  copied: boolean;
+}
+
+/** Upload the session to the gateway and copy the resulting ssh line. */
+export async function publishShare(session: ReviewSession, target: ShareTarget = {}): Promise<ShareResult> {
+  const line = await uploadOverSsh(packSessionBlob(session), target.host ?? DEFAULT_SHARE_HOST, target.port ?? DEFAULT_SHARE_PORT);
+  const copied = await copyToClipboard(line);
+  return { line, copied };
+}
+
+/** Stream the blob to `share@host:port` over the system `ssh` client. */
+async function uploadOverSsh(blob: Buffer, host: string, port: number): Promise<string> {
+  const proc = Bun.spawn(
+    ["ssh", "-p", String(port), "-o", "StrictHostKeyChecking=accept-new", `${SHARE_UPLOAD_USER}@${host}`, "cueloop-share"],
+    { stdin: blob, stdout: "pipe", stderr: "pipe" },
+  );
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (code !== 0) throw new Error(`gateway upload failed: ${stderr.trim() || `ssh exited ${code}`}`);
+  const line = stdout.trim();
+  if (!line.startsWith("ssh ")) throw new Error(`unexpected gateway reply: ${line || "(empty)"}`);
+  return line;
+}

package/src/view-diff.test.ts

@@ -21,7 +21,10 @@ index 111..222 100644
 
 describe("diffRows", () => {
   test("flattens files, hunks, and signed lines with line numbers", () => {
+    // Act
     const rows = diffRows(PATCH);
+
+    // Assert
     expect(rows[0]).toMatchObject({ kind: "file", file: "src/store.ts" });
     expect(rows[1]!.kind).toBe("hunk");
     const del = rows.find((row) => row.kind === "del")!;
@@ -36,7 +39,10 @@ describe("diffRows", () => {
   });
 
   test("context lines carry both line numbers", () => {
+    // Act
     const rows = diffRows(PATCH);
+
+    // Assert
     const ctx = rows.find((row) => row.kind === "ctx")!;
     expect(ctx.oldLine).toBe(1);
     expect(ctx.newLine).toBe(1);
@@ -45,9 +51,14 @@ describe("diffRows", () => {
 
 describe("diffRowAnchor", () => {
   test("quote is the line, neighbors are the context selectors", () => {
+    // Arrange
     const rows = diffRows(PATCH);
     const rowIndex = rows.findIndex((row) => row.text.includes("new Map()"));
+
+    // Act
     const anchor = diffRowAnchor(rows, rowIndex);
+
+    // Assert
     expect(anchor.quote).toContain("new Map()");
     expect(anchor.prefix.length).toBeGreaterThan(0);
     expect(anchor.suffix.length).toBeGreaterThan(0);

package/src/view-diff.ts

@@ -29,28 +29,28 @@ export function diffRows(patchText: string): DiffRow[] {
         let newLine = hunk.additionStart;
         for (const segment of hunk.hunkContent) {
           if (segment.type === "context") {
-            for (let i = 0; i < segment.lines; i++) {
+            for (let lineOffset = 0; lineOffset < segment.lines; lineOffset++) {
               rows.push({
                 kind: "ctx",
-                text: file.additionLines[segment.additionLineIndex + i] ?? "",
+                text: file.additionLines[segment.additionLineIndex + lineOffset] ?? "",
                 file: file.name,
                 oldLine: oldLine++,
                 newLine: newLine++,
               });
             }
           } else {
-            for (let i = 0; i < segment.deletions; i++) {
+            for (let lineOffset = 0; lineOffset < segment.deletions; lineOffset++) {
               rows.push({
                 kind: "del",
-                text: file.deletionLines[segment.deletionLineIndex + i] ?? "",
+                text: file.deletionLines[segment.deletionLineIndex + lineOffset] ?? "",
                 file: file.name,
                 oldLine: oldLine++,
               });
             }
-            for (let i = 0; i < segment.additions; i++) {
+            for (let lineOffset = 0; lineOffset < segment.additions; lineOffset++) {
               rows.push({
                 kind: "add",
-                text: file.additionLines[segment.additionLineIndex + i] ?? "",
+                text: file.additionLines[segment.additionLineIndex + lineOffset] ?? "",
                 file: file.name,
                 newLine: newLine++,
               });