@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.100

package/src/keyboard/keymap.ts

@@ -0,0 +1,395 @@
+/**
+ * The keyboard grammar as a pure reducer: view state in, intents out.
+ * App builds a KeyState per key event, calls reduceKey, and dispatches the
+ * intents to controller primitives and view-state setters - no branch bodies live
+ * in the key handler. Diff and plan reviews share one path for annotation
+ * navigation, deletion, and submit; the read-only rule is one gate here.
+ */
+
+import { actionFor } from "../settings/config";
+
+export type Intent =
+  | { type: "exit" }
+  | { type: "status"; message: string }
+  | { type: "move"; to: "down" | "up" | "top" | "bottom" }
+  | { type: "inboxMove"; to: "down" | "up" }
+  | { type: "openSession" }
+  | { type: "requestDeleteSession" }
+  | { type: "openRename" }
+  | { type: "confirmDialog" }
+  | { type: "startSpan" }
+  | { type: "spanKey"; name: string }
+  | { type: "spanCut" }
+  | { type: "openSpanActions" }
+  | { type: "moveSpanAction"; direction: -1 | 1 }
+  | { type: "pickSpanAction"; index?: number }
+  | { type: "closeSpanActions" }
+  | { type: "openCompose"; kind: "comment"; from: "cursor" | "span" }
+  | { type: "openSubmit" }
+  | { type: "share" }
+  | { type: "cut" }
+  | { type: "edit" }
+  | { type: "editCard" }
+  | { type: "rejectHunk" }
+  | { type: "rejectChange" }
+  | { type: "restoreCuration" }
+  | { type: "foldFile" }
+  | { type: "unfoldFile" }
+  | { type: "toggleDiffView" }
+  | { type: "nextAnnotation" }
+  | { type: "prevAnnotation" }
+  | { type: "walkStart" }
+  | { type: "walkForward" }
+  | { type: "walkBack" }
+  | { type: "walkLeave" }
+  | { type: "removeAnnotation" }
+  | { type: "deselect" }
+  | { type: "closeOverlay" }
+  | { type: "saveCompose" }
+  | { type: "submitMessage" }
+  | { type: "cycleMessage"; direction: -1 | 1 }
+  | { type: "finishReview" }
+  | { type: "optInAutoClose" }
+  | { type: "dismissCompletion" }
+  | { type: "toggleTree" }
+  | { type: "treeMove"; direction: -1 | 1 }
+  | { type: "treeGo" }
+  | { type: "treeBranch" }
+  | { type: "treeLabel" }
+  | { type: "treeFork" }
+  | { type: "treeForkShare" };
+
+export interface KeyInput {
+  name: string;
+  shift: boolean;
+  meta?: boolean;
+}
+
+export interface KeyState {
+  keys: Record<string, string[]>;
+  readOnly: boolean;
+  canEditPlan?: boolean;
+  canSubmitMessage?: boolean;
+  canShare?: boolean;
+  overlay:
+    | "none"
+    | "walk"
+    | "compose"
+    | "submit"
+    | "confirm"
+    | "prompt"
+    | "spanActions"
+    | "completion-prompt"
+    | "completion-counting";
+  view: "inbox" | "plan" | "diff";
+  spanMode: boolean;
+  walkAtEnd: boolean;
+  resolved: boolean;
+  hasInboxItems: boolean;
+  annotationCount: number;
+  hasFocusedAnnotation: boolean;
+  cursorAnnotatable: boolean;
+}
+
+/** Primitives that write session state; an observer never reaches their handlers. */
+const MUTATING_ACTIONS = new Set([
+  "comment",
+  "cut",
+  "edit",
+  "delete_annotation",
+  "submit",
+  "walk",
+  "share",
+  "reject_hunk",
+  "restore_curation",
+]);
+
+const SPAN_KEYS = new Set(["l", "h", "w", "b", "$", "0"]);
+
+function status(message: string): Intent[] {
+  return [{ type: "status", message }];
+}
+
+/**
+ * Reduce one key event to intents. `resolvedAction` is the binding-layer
+ * resolution (key-bindings.ts over @opentui/keymap) when the caller has one;
+ * without it the reducer falls back to the plain reverse lookup, so the
+ * grammar stays testable as a pure function.
+ */
+export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: string): Intent[] {
+  const name = key.name;
+  const overlayGrammar = overlayGrammars[state.overlay];
+
+  if (overlayGrammar) return overlayGrammar(state, key);
+  const action = resolvedAction ?? actionFor(state.keys, name, key.shift);
+
+  if (action === "quit") return [{ type: "exit" }];
+  // the ONE read-only rule: any mutating attempt answers instead of acting
+  // (span-mode c, x, and a are hardwired keys, so they gate by name as well)
+  const mutating =
+    MUTATING_ACTIONS.has(action ?? "") ||
+    (state.spanMode && (name === "c" || name === "x" || name === "a"));
+
+  if (state.readOnly && mutating) return status("observer - read-only");
+
+  // share is a session-level primitive: 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)
+  if (state.spanMode) return spanGrammar(state, name);
+  if (state.view === "diff") return diffGrammar(state, action);
+
+  return planGrammar(state, action, name);
+}
+
+type OverlayGrammar = (state: KeyState, key: KeyInput) => Intent[];
+
+const overlayGrammars: Partial<Record<KeyState["overlay"], OverlayGrammar>> = {
+  compose: composeOverlayGrammar,
+  submit: submitOverlayGrammar,
+  confirm: confirmOverlayGrammar,
+  prompt: promptOverlayGrammar,
+  spanActions: spanActionsOverlayGrammar,
+  "completion-prompt": completionOverlayGrammar,
+  "completion-counting": completionOverlayGrammar,
+  walk: walkOverlayGrammar,
+};
+
+function composeOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (name === "return" || name === "enter") {
+    // In the composer, ⌥/Alt+⏎ (meta) and shift+⏎ insert a newline - the
+    // focused textarea owns that; only a bare ⏎ saves. The submit overlay
+    // keeps its plain ⏎ submit.
+    if (key.shift || key.meta) return [];
+
+    return [{ type: "saveCompose" }];
+  }
+
+  return [];
+}
+
+function submitOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (name === "left" || name === "right") {
+    return [{ type: "cycleMessage", direction: name === "left" ? -1 : 1 }];
+  }
+
+  return [];
+}
+
+function confirmOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "return" || name === "enter") return [{ type: "confirmDialog" }];
+  if (name === "escape") return [{ type: "closeOverlay" }];
+
+  return [];
+}
+
+function promptOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "return" || name === "enter") return [{ type: "confirmDialog" }];
+  if (name === "escape") return [{ type: "closeOverlay" }];
+
+  return [];
+}
+
+function spanActionsOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "j" || name === "down") return [{ type: "moveSpanAction", direction: 1 }];
+  if (name === "k" || name === "up") return [{ type: "moveSpanAction", direction: -1 }];
+  if (name === "return" || name === "enter") return [{ type: "pickSpanAction" }];
+  if (name === "escape") return [{ type: "closeSpanActions" }];
+
+  return [];
+}
+
+function completionOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "return" || name === "enter" || name === "q") return [{ type: "finishReview" }];
+  if (name === "a") return [{ type: "optInAutoClose" }];
+  if (name === "escape") return [{ type: "dismissCompletion" }];
+
+  return [];
+}
+
+function walkOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "]") return [{ type: "walkForward" }];
+  if (name === "[") return [{ type: "walkBack" }];
+  if (name === "escape") return [{ type: "walkLeave" }];
+  if ((name === "return" || name === "enter") && state.walkAtEnd) {
+    return [{ type: "walkLeave" }, { type: "openSubmit" }];
+  }
+  if (name === "q") return [{ type: "exit" }];
+
+  return [];
+}
+
+function inboxGrammar(state: KeyState, name: string): Intent[] {
+  if (!state.hasInboxItems) return [];
+  if (name === "j" || name === "down") return [{ type: "inboxMove", to: "down" }];
+  if (name === "k" || name === "up") return [{ type: "inboxMove", to: "up" }];
+  if (name === "return" || name === "enter") return [{ type: "openSession" }];
+  if (name === "d") return [{ type: "requestDeleteSession" }];
+
+  return [];
+}
+
+function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
+  const navigation = navigationIntent(action);
+
+  if (navigation) return navigation;
+  if (action === "walk") {
+    // marking viewed writes the session record, so a resolved review answers
+    if (state.resolved) return status("review submitted - read-only");
+
+    return [{ type: "walkStart" }];
+  }
+  if (action === "comment") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (!state.cursorAnnotatable) return status("move to a code line to comment");
+
+    return [{ type: "openCompose", kind: "comment", from: "cursor" }];
+  }
+  // cut rejects the change under the cursor, reject_hunk the whole hunk; both
+  // write the working copy, so they gate on owner like a plan edit.
+  if (action === "cut" || action === "reject_hunk") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return status("only the diff owner can curate hunks");
+
+    return [{ type: action === "reject_hunk" ? "rejectHunk" : "rejectChange" }];
+  }
+  const viewToggle = viewToggleIntent(action);
+
+  if (viewToggle) return viewToggle;
+  // restore un-does a curated-out rejection from the rail; same owner gate as reject
+  if (action === "restore_curation") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return status("only the diff owner can curate hunks");
+
+    return [{ type: "restoreCuration" }];
+  }
+  const shared = annotationCluster(state, action);
+
+  if (shared) return shared;
+  if (action === "span" || action === "edit") {
+    return status("plan-only primitive - diff review uses c on a line");
+  }
+
+  return [];
+}
+
+function spanGrammar(state: KeyState, name: string): Intent[] {
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (SPAN_KEYS.has(name)) return [{ type: "spanKey", name }];
+  // c comments, x cuts, a opens quick-actions - all mutate, so a resolved
+  // review is read-only, like the plan grammar
+  if (name === "c" || name === "x" || name === "a") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (name === "c") return [{ type: "openCompose", kind: "comment", from: "span" }];
+    if (name === "a") return [{ type: "openSpanActions" }];
+    if (state.canEditPlan === false) return [];
+
+    return [{ type: "spanCut" }];
+  }
+
+  return [];
+}
+
+function planGrammar(state: KeyState, action: string | undefined, name: string): Intent[] {
+  const navigation = navigationIntent(action);
+
+  if (navigation) return navigation;
+  if (action === "walk") return status("the guided walk is a diff-review mode");
+  if (name === "escape") return [{ type: "deselect" }];
+  if (action === "span") return state.cursorAnnotatable ? [{ type: "startSpan" }] : [];
+  if (action === "comment") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (!state.cursorAnnotatable) return status("text is cut - restore it first");
+
+    return [{ type: "openCompose", kind: "comment", from: "cursor" }];
+  }
+  // restore un-does a rail removal (a cut block); a plan edit, so owner-only
+  if (action === "restore_curation") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return [];
+
+    return [{ type: "restoreCuration" }];
+  }
+  if (action === "cut" || action === "edit") {
+    if (state.resolved) return status("review submitted - read-only");
+    // 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 primitive; 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) ?? [];
+}
+
+/** Cursor movement is the same intent everywhere; views clamp their own bounds. */
+function navigationIntent(action: string | undefined): Intent[] | null {
+  if (action === "down" || action === "up" || action === "top" || action === "bottom") {
+    return [{ type: "move", to: action }];
+  }
+
+  return null;
+}
+
+/** Ungated view toggles in the diff: right folds a file to its band, left unfolds it, s flips
+ *  split/stacked (split lays out only when the Changes pane is wide/zoomed). */
+function viewToggleIntent(action: string | undefined): Intent[] | null {
+  if (action === "collapse_file") return [{ type: "foldFile" }];
+  if (action === "expand_file") return [{ type: "unfoldFile" }];
+  if (action === "split_diff") return [{ type: "toggleDiffView" }];
+
+  return null;
+}
+
+/** Annotation navigation, deletion, and submit: one path for plan and diff. */
+function annotationCluster(state: KeyState, action: string | undefined): Intent[] | null {
+  if (action === "next_annotation" || action === "prev_annotation") {
+    if (!state.annotationCount) return status("no annotations");
+
+    return [{ type: action === "next_annotation" ? "nextAnnotation" : "prevAnnotation" }];
+  }
+  if (action === "delete_annotation") {
+    if (state.resolved || !state.hasFocusedAnnotation) return [];
+
+    return [{ type: "removeAnnotation" }];
+  }
+  if (action === "rename") {
+    if (!state.hasFocusedAnnotation) return status("select a collaborator's note to rename them");
+
+    return [{ type: "openRename" }];
+  }
+  if (action === "submit") {
+    // a collaborator's notes union back as they go; there is no message to submit
+    if (state.canSubmitMessage === false)
+      return status("shared view - your notes save as you go; q to leave");
+
+    return state.resolved ? [] : [{ type: "openSubmit" }];
+  }
+
+  return null;
+}

package/src/keyboard/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/keyboard/skills.ts

@@ -0,0 +1,75 @@
+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[]>([]);
+
+/**
+ * The action and skill names every composer paints as "/name" references. Held in
+ * context so each surface - the plan thread, the diff sheet, the prototype - reads
+ * the same palette without threading a prop.
+ */
+export const PaletteNamesContext = createContext<ReadonlySet<string>>(new Set());

package/src/keyboard/slash-palette.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import {
+  activeSlashToken,
+  insertSlashItem,
+  isStandaloneSlashQuery,
+  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("activeSlashToken", () => {
+  const atEnd = (text: string) => activeSlashToken(text, text.length);
+
+  test("finds the caret's /word at the start or after a space, so each new / reopens the palette", () => {
+    expect(atEnd("/vitest-patt")).toBe("/vitest-patt");
+    expect(atEnd("use /vitest-patt")).toBe("/vitest-patt");
+    expect(atEnd("/zoom-out hello world /")).toBe("/");
+    // an underscore is a valid skill-name character, so the token spans it
+    expect(atEnd("run /my_skill")).toBe("/my_skill");
+  });
+
+  test("closes on the space that ends the token, and ignores prose", () => {
+    expect(atEnd("/zoom-out ")).toBeNull();
+    expect(atEnd("just some prose")).toBeNull();
+  });
+
+  test("tracks the caret, not the string end: a slash mid-draft is the active token", () => {
+    // caret sits right after "/imp" in "/imp done", ignoring the trailing text
+    expect(activeSlashToken("/imp done", 4)).toBe("/imp");
+    // caret inside plain prose, even with a later slash token, has no active token
+    expect(activeSlashToken("plain text /later", 5)).toBeNull();
+  });
+});
+
+describe("isStandaloneSlashQuery", () => {
+  test("true only when the whole draft is a bare /query, so prose ending in /name still saves", () => {
+    expect(isStandaloneSlashQuery("/lgtm")).toBe(true);
+    expect(isStandaloneSlashQuery("  /lgtm  ")).toBe(true);
+    expect(isStandaloneSlashQuery("please inspect /tmp")).toBe(false);
+    expect(isStandaloneSlashQuery("just prose")).toBe(false);
+  });
+});
+
+describe("insertSlashItem", () => {
+  test("replaces the active slash token with the reference and lands the caret after it", () => {
+    const result = insertSlashItem("look at /rev", 12, "review");
+
+    expect(result.text).toBe("look at /review ");
+    expect(result.caret).toBe("look at /review ".length);
+  });
+
+  test("keeps text after the caret intact", () => {
+    const result = insertSlashItem("/pl tail", 3, "plan");
+
+    expect(result.text).toBe("/plan  tail");
+    expect(result.caret).toBe("/plan ".length);
+  });
+});