@cueloop/client 0.1.0-alpha.7 → 0.1.0-alpha.70

package/src/share.ts

@@ -0,0 +1,215 @@
+/**
+ * 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 { removalEntries, viewFollowing, type Annotation, type Thread } from "@cueloop/schema";
+import { ThreadRecordSchema } from "@cueloop/daemon/validate";
+import type { SharedMerge } from "@cueloop/daemon/client";
+import * as v from "valibot";
+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;
+}
+
+/** The `p_…` share id inside a `ssh p_…@host` line, or undefined. */
+export function shareIdFromLine(line: string): string | undefined {
+  return line.match(/^ssh (\S+)@/)?.[1];
+}
+
+/** Upload the session to the gateway and copy the resulting ssh line. */
+export async function publishShare(
+  session: Thread,
+  target: ShareTarget = {},
+): Promise<ShareResult> {
+  const { stdout, stderr, code } = await runShareSsh(
+    "cueloop-share",
+    // the share follows one branch: collaborators see its path wherever the owner stands
+    packSessionBlob(viewFollowing(session)),
+    target,
+  );
+
+  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)"}`);
+  const copied = await copyToClipboard(line);
+
+  return { line, copied };
+}
+
+/**
+ * Pull a share's current session back from the gateway. The gateway lets only
+ * the fingerprint that uploaded it through, so collaborator notes reach the
+ * planner without exposing the master key.
+ */
+export async function pullShare(shareId: string, target: ShareTarget = {}): Promise<Thread> {
+  const { stdout, stderr, code } = await runShareSsh("cueloop-pull", Buffer.from(shareId), target);
+
+  if (code !== 0) throw new Error(`gateway pull failed: ${stderr.trim() || `ssh exited ${code}`}`);
+
+  return v.parse(ThreadRecordSchema, JSON.parse(stdout));
+}
+
+/** A share's collaborator notes: the ones a viewer authored (author stamped). */
+export function collaboratorAnnotations(session: Thread): 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: Thread): 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
+ * unauthored (the planner's), unioned by id.
+ */
+export async function pushShare(
+  shareId: string,
+  annotations: Array<Omit<Annotation, "createdAt">>,
+  target: ShareTarget = {},
+): Promise<void> {
+  const { stderr, code } = await runShareSsh(
+    "cueloop-push",
+    Buffer.from(JSON.stringify({ shareId, annotations })),
+    target,
+  );
+
+  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: Thread) => 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: ThreadRecordSchema }),
+]);
+
+/**
+ * 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 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(),
+    proc.exited,
+  ]);
+
+  return { stdout, stderr, code };
+}

package/src/skills.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadSkills } from "./skills";
+import { mergeSlashItems, type SlashItem } from "./slash-palette";
+
+function skillDir(): string {
+  const root = mkdtempSync(join(tmpdir(), "cueloop-skills-"));
+
+  mkdirSync(join(root, "typescript-magician"));
+  writeFileSync(
+    join(root, "typescript-magician", "SKILL.md"),
+    "---\nname: typescript-magician\ndescription: Design complex generic types.\n---\n\nbody\n",
+  );
+  mkdirSync(join(root, "no-frontmatter"));
+  writeFileSync(join(root, "no-frontmatter", "SKILL.md"), "just prose, no frontmatter\n");
+
+  return root;
+}
+
+describe("loadSkills", () => {
+  test("reads name and description from each SKILL.md frontmatter", () => {
+    const root = skillDir();
+
+    try {
+      const skills = loadSkills(root);
+      const magician = skills.find((skill) => skill.name === "typescript-magician");
+
+      expect(magician?.description).toBe("Design complex generic types.");
+      // a directory whose SKILL.md has no frontmatter is skipped, not crashed on
+      expect(skills.some((skill) => skill.name === "no-frontmatter")).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("a missing skills directory yields no skills", () => {
+    expect(loadSkills(join(tmpdir(), "cueloop-does-not-exist-xyz"))).toEqual([]);
+  });
+
+  test("CRLF delimiters parse, and a quoted name is unquoted", () => {
+    const root = mkdtempSync(join(tmpdir(), "cueloop-skills-crlf-"));
+
+    try {
+      mkdirSync(join(root, "review"));
+      writeFileSync(
+        join(root, "review", "SKILL.md"),
+        '---\r\nname: "review"\r\ndescription: Review the change.\r\n---\r\n',
+      );
+      const skills = loadSkills(root);
+
+      // no stray quotes and no CRLF-broken frontmatter
+      expect(skills.map((skill) => skill.name)).toEqual(["review"]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("mergeSlashItems", () => {
+  test("a quick action wins a name collision with a skill", () => {
+    const actions: SlashItem[] = [{ name: "lgtm", description: "action", body: "LGTM" }];
+    const skills: SlashItem[] = [
+      { name: "lgtm", description: "skill", body: "" },
+      { name: "vitest-patterns", description: "skill", body: "" },
+    ];
+    const merged = mergeSlashItems(actions, skills);
+
+    expect(merged.filter((item) => item.name === "lgtm")).toHaveLength(1);
+    expect(merged.find((item) => item.name === "lgtm")?.description).toBe("action");
+    expect(merged.some((item) => item.name === "vitest-patterns")).toBe(true);
+  });
+});

package/src/skills.ts

@@ -0,0 +1,68 @@
+import { createContext } from "react";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import * as v from "valibot";
+import type { SlashItem } from "./slash-palette";
+
+/** The default user-level skill store, harness-agnostic; a config path overrides it. */
+export function defaultSkillsDir(): string {
+  return join(homedir(), ".agents", "skills");
+}
+
+const SkillNameSchema = v.pipe(v.string(), v.trim(), v.minLength(1));
+
+/** One `key: value` line from the frontmatter, unquoted; undefined when the key is absent. */
+function frontmatterValue(frontmatter: string, key: string): string | undefined {
+  const match = new RegExp(`^${key}:\\s*(.+)$`, "m").exec(frontmatter);
+
+  return match
+    ? match[1]!
+        .trim()
+        .replace(/^["']|["']$/g, "")
+        .trim()
+    : undefined;
+}
+
+/** User skills as palette items: each `<dir>/SKILL.md` whose frontmatter carries a name and description. */
+export function loadSkills(dir: string): SlashItem[] {
+  let entries;
+
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const items: SlashItem[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    let text;
+
+    try {
+      text = readFileSync(join(dir, entry.name, "SKILL.md"), "utf8");
+    } catch {
+      continue;
+    }
+    const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text.replace(/\r\n/g, "\n"));
+
+    if (!frontmatter) continue;
+    const name = v.safeParse(
+      SkillNameSchema,
+      frontmatterValue(frontmatter[1]!, "name") ?? entry.name,
+    );
+
+    if (!name.success) continue;
+
+    items.push({
+      name: name.output,
+      description: frontmatterValue(frontmatter[1]!, "description") ?? "",
+      body: "",
+    });
+  }
+
+  return items;
+}
+
+/** Skills reach the composer palette through context, so no surface needs a new prop to list them. */
+export const SlashSkillsContext = createContext<SlashItem[]>([]);

package/src/slash-palette.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { inlineSlashToken, scoreMatch, slashFilter, type SlashItem } from "./slash-palette";
+
+function item(name: string): SlashItem {
+  return { name, description: name, body: name };
+}
+
+const ITEMS: SlashItem[] = [
+  item("zoom-out-research-in-depth"),
+  item("restate-simplified"),
+  item("out-of-scope"),
+  item("lgtm"),
+];
+
+describe("scoreMatch", () => {
+  test("an exact name scores highest, then a prefix, then a subsequence", () => {
+    const exact = scoreMatch("lgtm", "lgtm")!;
+    const prefix = scoreMatch("lgtm-please", "lgtm")!;
+    const subsequence = scoreMatch("looking-good-to-me", "lgtm")!;
+
+    expect(exact).toBeGreaterThan(prefix);
+    expect(prefix).toBeGreaterThan(subsequence);
+  });
+
+  test("a query whose characters are not all present, in order, does not match", () => {
+    expect(scoreMatch("restate", "zzz")).toBeNull();
+    expect(scoreMatch("abc", "acb")).toBeNull();
+  });
+
+  test("an empty query matches everything", () => {
+    expect(scoreMatch("anything", "")).toBe(0);
+  });
+});
+
+describe("slashFilter", () => {
+  test("ranks a prefix match above a mere subsequence match", () => {
+    const ranked = slashFilter(ITEMS, "out");
+
+    expect(ranked[0]!.name).toBe("out-of-scope");
+    expect(ranked.map((entry) => entry.name)).toContain("zoom-out-research-in-depth");
+  });
+
+  test("drops items that do not match and returns all on an empty query", () => {
+    expect(slashFilter(ITEMS, "zzzz")).toEqual([]);
+    expect(slashFilter(ITEMS, "")).toHaveLength(ITEMS.length);
+  });
+});
+
+describe("inlineSlashToken", () => {
+  test("finds a trailing /word only when text precedes it", () => {
+    expect(inlineSlashToken("use /vitest-patt")).toBe("/vitest-patt");
+    expect(inlineSlashToken("/vitest-patt")).toBeNull();
+  });
+});

package/src/slash-palette.ts

@@ -0,0 +1,104 @@
+/**
+ * The "/" quick-action palette behind a composer: the skill list a leading
+ * slash opens, its prefix > substring > subsequence filter, and the inline
+ * "/word" completion offered mid-sentence. Pure; the surfaces render it.
+ */
+
+import { quickActionBody, type QuickAction } from "./config";
+
+export interface SlashItem {
+  name: string;
+  description: string;
+  body: string;
+}
+
+export function slashItemsFrom(quickActions: QuickAction[]): SlashItem[] {
+  return quickActions.map((action) => ({
+    name: action.prompt
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, ""),
+    description: action.metadata ?? action.prompt,
+    body: quickActionBody(action),
+  }));
+}
+
+const WORD_BOUNDARY = /[\s\-_./:]/;
+
+/** Order-preserving subsequence score, or null when a query character is missing; higher is better. */
+export function scoreMatch(name: string, query: string): number | null {
+  if (query.length === 0) return 0;
+  const lowerName = name.toLowerCase();
+  const lowerQuery = query.toLowerCase();
+
+  if (lowerName === lowerQuery) return 1000;
+  if (lowerName.startsWith(lowerQuery)) return 500 - name.length;
+  let score = 0;
+  let cursor = 0;
+  let run = 0;
+
+  for (const character of lowerQuery) {
+    const found = lowerName.indexOf(character, cursor);
+
+    if (found === -1) return null;
+    run = found === cursor ? run + 1 : 0;
+    score += found === cursor ? 5 + run : 1;
+    if (found === 0 || WORD_BOUNDARY.test(lowerName[found - 1]!)) score += 10;
+    score -= found - cursor;
+    cursor = found + 1;
+  }
+
+  return score;
+}
+
+export function slashFilter(items: SlashItem[], query: string): SlashItem[] {
+  if (query.length === 0) return items;
+  const scored: Array<{ item: SlashItem; score: number }> = [];
+
+  for (const item of items) {
+    const score = scoreMatch(item.name, query);
+
+    if (score !== null) scored.push({ item, score });
+  }
+
+  return scored.toSorted((left, right) => right.score - left.score).map((entry) => entry.item);
+}
+
+/**
+ * A skill invoked mid-sentence: the trailing "/word" token when text already
+ * precedes it (a draft that starts with "/" is the palette, not an inline
+ * completion). Newline-safe, since the token may sit at the start of a new line.
+ */
+export function inlineSlashToken(text: string): string | null {
+  if (text.startsWith("/")) return null;
+  const match = /(?:^|\s)(\/[a-zA-Z0-9-]*)$/.exec(text);
+
+  return match ? match[1]! : null;
+}
+
+export interface InlineSlash {
+  token: string;
+  suggestion: SlashItem;
+}
+
+/** The inline completion state: the trailing "/word" and its closest item, or null. */
+export function resolveInlineSuggestion(
+  slashActive: boolean,
+  text: string,
+  items: SlashItem[],
+): InlineSlash | null {
+  if (slashActive) return null;
+  const token = inlineSlashToken(text);
+
+  if (token === null) return null;
+  const suggestion = slashFilter(items, token.slice(1))[0];
+
+  return suggestion ? { token, suggestion } : null;
+}
+
+/** Quick actions and user skills in one palette; a quick action wins a name collision (it expands). */
+export function mergeSlashItems(actions: SlashItem[], skills: SlashItem[]): SlashItem[] {
+  const taken = new Set(actions.map((action) => action.name));
+
+  return [...actions, ...skills.filter((skill) => !taken.has(skill.name))];
+}

package/src/split-diff.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import { diffRows } from "./view-diff";
+import { splitDiffRows, splitRowOffsets, type SplitRow } from "./split-diff";
+
+const PATCH = `diff --git a/greet.ts b/greet.ts
+--- a/greet.ts
++++ b/greet.ts
+@@ -1,4 +1,4 @@
+ const name = "world";
+-console.log("hi " + name);
+-console.log("done");
++console.log("hello " + name);
++console.log("finished");
+ export {};
+`;
+
+function pairs(rows: SplitRow[]): SplitRow[] {
+  return rows.filter((row) => row.kind === "pair");
+}
+
+describe("splitDiffRows", () => {
+  test("carries the file and hunk headers through unchanged", () => {
+    // Act
+    const split = splitDiffRows(diffRows(PATCH));
+
+    // Assert
+    expect(split[0]).toMatchObject({ kind: "file", file: "greet.ts", text: "greet.ts" });
+    expect(split[1]?.kind).toBe("hunk");
+  });
+
+  test("a context line sits on both sides with its own line numbers", () => {
+    // Act
+    const first = pairs(splitDiffRows(diffRows(PATCH)))[0]!;
+
+    // Assert
+    expect(first.left).toMatchObject({ kind: "ctx", lineNumber: 1 });
+    expect(first.right).toMatchObject({ kind: "ctx", lineNumber: 1 });
+    expect(first.left?.text).toBe(first.right?.text);
+  });
+
+  test("a balanced change block pairs each deletion against an addition", () => {
+    // Act - the two deletions zip against the two additions, one per row
+    const changed = pairs(splitDiffRows(diffRows(PATCH))).filter(
+      (row) => row.left?.kind === "del" || row.right?.kind === "add",
+    );
+
+    // Assert
+    expect(changed).toHaveLength(2);
+    expect(changed[0]).toMatchObject({
+      left: { kind: "del", lineNumber: 2 },
+      right: { kind: "add", lineNumber: 2 },
+    });
+    expect(changed[1]).toMatchObject({
+      left: { kind: "del", lineNumber: 3 },
+      right: { kind: "add", lineNumber: 3 },
+    });
+  });
+
+  test("an unbalanced block blank-fills the shorter side", () => {
+    // Arrange - one deletion, three additions
+    const patch = `diff --git a/x.ts b/x.ts
+--- a/x.ts
++++ b/x.ts
+@@ -1,2 +1,4 @@
+ keep;
+-old;
++new1;
++new2;
++new3;
+`;
+
+    // Act
+    const changed = pairs(splitDiffRows(diffRows(patch))).filter(
+      (row) => row.left?.kind === "del" || row.right?.kind === "add",
+    );
+
+    // Assert - three rows tall, only the first has a left deletion
+    expect(changed).toHaveLength(3);
+    expect(changed[0]?.left?.kind).toBe("del");
+    expect(changed[1]?.left).toBeUndefined();
+    expect(changed[2]?.left).toBeUndefined();
+    expect(changed.map((row) => row.right?.text.trim())).toEqual(["new1;", "new2;", "new3;"]);
+  });
+
+  test("each side keeps its originating unified row for anchoring", () => {
+    // Act
+    const base = diffRows(PATCH);
+    const changed = pairs(splitDiffRows(base)).find((row) => row.right?.kind === "add")!;
+
+    // Assert - the split line points back at a row from the base list
+    expect(base[changed.right!.rowIndex]).toBe(changed.right!.row);
+  });
+});
+
+describe("splitRowOffsets", () => {
+  test("maps both sides of a pair to the same y and steps a file band by three", () => {
+    // Arrange
+    const base = diffRows(PATCH);
+    const split = splitDiffRows(base);
+
+    // Act
+    const offsets = splitRowOffsets(split);
+
+    // Assert - the file band is three rows and the hunk one, so the first context pair sits at y 4
+    const firstContext = split.find((row) => row.kind === "pair" && row.left?.kind === "ctx")!;
+
+    expect(offsets.get(firstContext.left!.rowIndex)).toBe(4);
+    expect(offsets.get(firstContext.right!.rowIndex)).toBe(4);
+  });
+});