catherd-cli 1.5.0 → 2.0.0-beta.20261022113309

package/src/entry/tui/commands.ts

@@ -1,563 +0,0 @@
-// Command ids and default keys follow anomalyco/opencode packages/tui/src/config/keybind.ts
-// (MIT, © 2025 opencode); see THIRD_PARTY_NOTICES.md.
-import { z } from "zod";
-import { CatherdError } from "../../domain/errors.ts";
-
-/**
- * Where a command's keys are live (spec §9.2's context stack global → tab → pane → dialog → input).
- * - `global`: in every mode, dialogs included.
- * - `app`, `tab.*`, `list`: the base mode (no dialog open); their printable keys only while no text input
- *   has focus.
- * - `row.*`: the base mode, and only while no text input has focus (their keys act on the selected row).
- * - `filter`: only while a list's filter input has focus.
- * - `dialog`: only while a dialog is open (the keymap's modal mode).
- */
-export const SCOPES = [
-  "global",
-  "app",
-  "tab.status",
-  "tab.profiles",
-  "tab.runs",
-  "list",
-  "row.status",
-  "row.profiles",
-  "row.runs",
-  "filter",
-  "dialog",
-] as const;
-export type Scope = (typeof SCOPES)[number];
-
-type Group = "App" | "Tabs" | "Profiles" | "Edit" | "Status" | "Runs" | "Lists" | "Dialogs";
-
-export interface CommandDef {
-  id: string;
-  title: string;
-  group: Group;
-  scope: Scope;
-  /** default keys, in the keymap's syntax: `ctrl+s`, `shift+g`, `<leader>n`, `space`, `return` */
-  keys: readonly string[];
-  /** listed in the command palette */
-  palette?: true;
-  /** listed under "Suggested" while the palette's filter is empty */
-  suggested?: true;
-  /** footer order; commands without one are never hinted */
-  hint?: number;
-  /** the footer's label, when the title is too long for it */
-  short?: string;
-  /** the CLI command that does the same, shown in the palette (research C3: the TUI teaches the CLI) */
-  cli?: string;
-}
-
-/** The leader key and its timeout (spec §9.2: `ctrl+x`, 2 s, as in opencode). */
-export const LEADER = "ctrl+x";
-export const LEADER_TIMEOUT_MS = 2_000;
-
-/** Every action in the TUI. The palette, footer, help and keys all come from this one table. */
-export const COMMANDS = [
-  // global: live in every mode
-  { id: "app.interrupt", title: "Cancel, or quit", group: "App", scope: "global", keys: ["ctrl+c"] },
-  // hinted only while a dialog is open (the Footer), where esc cancels it
-  {
-    id: "app.back",
-    title: "Back",
-    group: "App",
-    scope: "global",
-    keys: ["escape"],
-    hint: 80,
-    short: "cancel",
-  },
-
-  // app: any tab, no dialog open
-  {
-    id: "app.palette",
-    title: "Command palette",
-    group: "App",
-    scope: "app",
-    keys: ["ctrl+p", ":"],
-    hint: 90,
-    short: "commands",
-  },
-  {
-    id: "app.help",
-    title: "Keyboard shortcuts",
-    group: "App",
-    scope: "app",
-    keys: ["?"],
-    palette: true,
-    hint: 91,
-    short: "help",
-  },
-  { id: "app.quit", title: "Quit", group: "App", scope: "app", keys: ["q", "<leader>q"], palette: true },
-  {
-    id: "app.stories",
-    title: "Stories…",
-    group: "App",
-    scope: "app",
-    keys: [],
-    palette: true,
-    suggested: true,
-  },
-  {
-    id: "tab.status",
-    title: "Go to Status",
-    group: "Tabs",
-    scope: "app",
-    keys: ["1", "<leader>1"],
-    palette: true,
-  },
-  {
-    id: "tab.profiles",
-    title: "Go to Profiles",
-    group: "Tabs",
-    scope: "app",
-    keys: ["2", "<leader>2"],
-    palette: true,
-  },
-  {
-    id: "tab.runs",
-    title: "Go to Runs",
-    group: "Tabs",
-    scope: "app",
-    keys: ["3", "<leader>3"],
-    palette: true,
-  },
-  { id: "tab.next", title: "Next tab", group: "Tabs", scope: "app", keys: ["]"] },
-  { id: "tab.prev", title: "Previous tab", group: "Tabs", scope: "app", keys: ["["] },
-  {
-    id: "profile.new",
-    title: "New profile…",
-    group: "Profiles",
-    scope: "app",
-    keys: ["<leader>n"],
-    palette: true,
-    suggested: true,
-    cli: "catherd profile new <name>",
-  },
-  {
-    id: "profile.list",
-    title: "Switch profile…",
-    group: "Profiles",
-    scope: "app",
-    keys: ["<leader>l"],
-    palette: true,
-    suggested: true,
-    cli: "catherd profile list",
-  },
-
-  // tab.status
-  {
-    id: "status.recheck",
-    title: "Re-check setup",
-    group: "Status",
-    scope: "tab.status",
-    keys: ["r"],
-    palette: true,
-    suggested: true,
-    hint: 3,
-    short: "re-check",
-    cli: "catherd doctor",
-  },
-  {
-    id: "status.copy",
-    title: "Copy the fix command",
-    group: "Status",
-    scope: "tab.status",
-    keys: ["y"],
-    palette: true,
-    hint: 2,
-    short: "copy fix",
-  },
-
-  // tab.profiles
-  {
-    id: "profile.save",
-    title: "Save profile…",
-    group: "Profiles",
-    scope: "tab.profiles",
-    keys: ["ctrl+s"],
-    palette: true,
-    suggested: true,
-    hint: 3,
-    short: "save",
-    cli: "catherd profile set <path> <value>",
-  },
-  {
-    id: "profile.activate",
-    title: "Make this profile active…",
-    group: "Profiles",
-    scope: "tab.profiles",
-    keys: ["a"],
-    palette: true,
-    hint: 6,
-    short: "activate",
-    cli: "catherd profile use <name> [--repo]",
-  },
-  {
-    id: "profile.copy",
-    title: "Copy this profile…",
-    group: "Profiles",
-    scope: "tab.profiles",
-    keys: [],
-    palette: true,
-    cli: "catherd profile copy <from> <name>",
-  },
-  {
-    id: "profile.revert",
-    title: "Discard unsaved changes…",
-    group: "Profiles",
-    scope: "tab.profiles",
-    keys: [],
-    palette: true,
-  },
-  {
-    id: "catalog.refresh",
-    title: "Sync the public sources and refresh the model catalog",
-    group: "Profiles",
-    scope: "tab.profiles",
-    keys: ["r"],
-    palette: true,
-    cli: "catherd catalog sync",
-  },
-  {
-    id: "edit.undo",
-    title: "Undo",
-    group: "Edit",
-    scope: "tab.profiles",
-    keys: ["<leader>u"],
-    palette: true,
-    hint: 7,
-    short: "undo",
-  },
-  {
-    id: "edit.redo",
-    title: "Redo",
-    group: "Edit",
-    scope: "tab.profiles",
-    keys: ["<leader>r"],
-    palette: true,
-  },
-
-  // tab.runs
-  {
-    id: "runs.refresh",
-    title: "Refresh now",
-    group: "Runs",
-    scope: "tab.runs",
-    keys: ["r"],
-    palette: true,
-    hint: 3,
-    short: "refresh",
-  },
-  {
-    id: "runs.pause",
-    title: "Pause or resume updates",
-    group: "Runs",
-    scope: "tab.runs",
-    keys: ["p"],
-    palette: true,
-    hint: 4,
-    short: "pause",
-  },
-
-  // list: every list and tree
-  { id: "list.up", title: "Move up", group: "Lists", scope: "list", keys: ["up", "k"] },
-  { id: "list.down", title: "Move down", group: "Lists", scope: "list", keys: ["down", "j"] },
-  { id: "list.pageUp", title: "Page up", group: "Lists", scope: "list", keys: ["pageup"] },
-  { id: "list.pageDown", title: "Page down", group: "Lists", scope: "list", keys: ["pagedown"] },
-  { id: "list.first", title: "First row", group: "Lists", scope: "list", keys: ["home", "g"] },
-  { id: "list.last", title: "Last row", group: "Lists", scope: "list", keys: ["end", "shift+g"] },
-  {
-    id: "list.filter",
-    title: "Filter",
-    group: "Lists",
-    scope: "list",
-    keys: ["/"],
-    hint: 8,
-    short: "filter",
-  },
-
-  // row.*: act on the selected row
-  {
-    id: "status.open",
-    title: "Open",
-    group: "Status",
-    scope: "row.status",
-    keys: ["return"],
-    hint: 1,
-    short: "open",
-  },
-  {
-    id: "tree.toggle",
-    title: "Toggle",
-    group: "Profiles",
-    scope: "row.profiles",
-    keys: ["space"],
-    hint: 1,
-    short: "toggle",
-  },
-  {
-    id: "tree.open",
-    title: "Change or expand",
-    group: "Profiles",
-    scope: "row.profiles",
-    keys: ["return"],
-    hint: 2,
-    short: "change",
-  },
-  { id: "tree.expand", title: "Expand", group: "Profiles", scope: "row.profiles", keys: ["right", "l"] },
-  {
-    id: "tree.detail",
-    title: "Show the rung's values, sources and runs",
-    group: "Profiles",
-    scope: "row.profiles",
-    keys: ["i"],
-    palette: true,
-    cli: "catherd catalog list --json",
-  },
-  {
-    id: "tree.treatLike",
-    title: "Treat the rung like another…",
-    group: "Profiles",
-    scope: "row.profiles",
-    keys: ["t"],
-    palette: true,
-    cli: "catherd catalog treat-like --suggest <rung>",
-  },
-  {
-    id: "tree.collapse",
-    title: "Collapse, or go to the parent",
-    group: "Profiles",
-    scope: "row.profiles",
-    keys: ["left", "h"],
-  },
-  {
-    id: "runs.open",
-    title: "Open the session, milestone or role",
-    group: "Runs",
-    scope: "row.runs",
-    keys: ["return"],
-    hint: 1,
-    short: "open",
-  },
-  {
-    id: "runs.cancel",
-    title: "Cancel the selected role (press twice)",
-    group: "Runs",
-    scope: "row.runs",
-    keys: ["ctrl+d"],
-    hint: 2,
-    short: "cancel",
-    cli: "catherd runs cancel <run> <name>",
-  },
-
-  // filter: a list's filter input has focus
-  {
-    id: "filter.accept",
-    title: "Keep the filter",
-    group: "Lists",
-    scope: "filter",
-    keys: ["return"],
-    hint: 1,
-    short: "done",
-  },
-
-  // dialog: a dialog is open
-  // hints with the same short label and order show as one: `↑↓ move`
-  {
-    id: "dialog.up",
-    title: "Previous",
-    group: "Dialogs",
-    scope: "dialog",
-    keys: ["up", "ctrl+p"],
-    hint: 0,
-    short: "move",
-  },
-  {
-    id: "dialog.down",
-    title: "Next",
-    group: "Dialogs",
-    scope: "dialog",
-    keys: ["down", "ctrl+n"],
-    hint: 0,
-    short: "move",
-  },
-  { id: "dialog.pageUp", title: "Page up", group: "Dialogs", scope: "dialog", keys: ["pageup"] },
-  { id: "dialog.pageDown", title: "Page down", group: "Dialogs", scope: "dialog", keys: ["pagedown"] },
-  {
-    id: "dialog.left",
-    title: "Previous button",
-    group: "Dialogs",
-    scope: "dialog",
-    keys: ["left", "shift+tab"],
-    hint: 0,
-    short: "button",
-  },
-  {
-    id: "dialog.right",
-    title: "Next button",
-    group: "Dialogs",
-    scope: "dialog",
-    keys: ["right", "tab"],
-    hint: 0,
-    short: "button",
-  },
-  {
-    id: "dialog.submit",
-    title: "Choose",
-    group: "Dialogs",
-    scope: "dialog",
-    keys: ["return"],
-    hint: 1,
-    short: "choose",
-  },
-  {
-    id: "dialog.delete",
-    title: "Delete (press twice)",
-    group: "Dialogs",
-    scope: "dialog",
-    keys: ["ctrl+d"],
-    hint: 2,
-    short: "delete",
-  },
-] as const satisfies readonly CommandDef[];
-
-export type CommandId = (typeof COMMANDS)[number]["id"];
-export type Keybinds = Record<CommandId, readonly string[]>;
-
-const BY_ID = new Map<string, CommandDef>(COMMANDS.map((c) => [c.id, c]));
-export const commandsIn = (scope: Scope): CommandDef[] => COMMANDS.filter((c) => c.scope === scope);
-
-/** Keys a text input would take as typing: one character, `space`, or a shifted letter. */
-export const isPrintable = (key: string): boolean =>
-  [...key].length === 1 || key === "space" || /^shift\+.$/.test(key);
-
-/** Scopes whose printable keys go quiet while a text input has focus. */
-const GUARDED: readonly Scope[] = ["app", "tab.status", "tab.profiles", "tab.runs", "list"];
-export const isGuarded = (scope: Scope): boolean => GUARDED.includes(scope);
-
-/** Commands only the ctrl+c layering may run; rebinding them could leave no way out. */
-const RESERVED: readonly CommandId[] = ["app.interrupt", "app.back"];
-
-export const DEFAULT_KEYS: Keybinds = Object.fromEntries(
-  COMMANDS.map((c): [string, readonly string[]] => [c.id, c.keys]),
-) as Keybinds;
-
-/** Spec §9.2 `config.json` `keybinds`: `{ <command id>: string | string[] | "none" }`. */
-const KeybindsSchema = z.record(z.string(), z.union([z.string().min(1), z.array(z.string().min(1))]));
-
-/** The stacks of scopes that can be live at once; a key must mean one thing in each. */
-export const CONTEXTS: readonly { tab: "status" | "profiles" | "runs" | null; typing: boolean }[] = [
-  ...(["status", "profiles", "runs"] as const).flatMap((tab) => [
-    { tab, typing: false },
-    { tab, typing: true },
-  ]),
-  { tab: null, typing: true },
-];
-
-/** The keys live in one context, with the command each would run. */
-export function keysIn(ctx: (typeof CONTEXTS)[number], keys: Keybinds): [string, CommandId][] {
-  const scopes: Scope[] =
-    ctx.tab === null
-      ? ["global", "dialog"]
-      : ["global", "app", `tab.${ctx.tab}`, "list", ctx.typing ? "filter" : `row.${ctx.tab}`];
-  const out: [string, CommandId][] = [];
-  for (const c of COMMANDS) {
-    if (!scopes.includes(c.scope)) continue;
-    for (const k of keys[c.id])
-      if (!(ctx.typing && isGuarded(c.scope) && isPrintable(k))) out.push([k, c.id]);
-  }
-  return out;
-}
-
-/** Every key that means two things somewhere: `"<key>: <id>, <id> (<context>)"`. */
-export function duplicateKeys(keys: Keybinds): string[] {
-  const out: string[] = [];
-  for (const ctx of CONTEXTS) {
-    const seen = new Map<string, CommandId>();
-    for (const [k, id] of keysIn(ctx, keys)) {
-      const first = seen.get(k);
-      if (first && first !== id)
-        out.push(`${k}: ${first}, ${id} (${ctx.tab ?? "dialog"}${ctx.typing && ctx.tab ? ", typing" : ""})`);
-      else seen.set(k, id);
-    }
-  }
-  return [...new Set(out)];
-}
-
-/**
- * The keys in force: the defaults with `config.json`'s `keybinds` over them. Unknown ids, reserved
- * commands, the leader as a command's own key, a typed key on a command live while the user types, and
- * overrides that make one key mean two things are refused with `E_CONFIG_KEYBIND`.
- */
-export function resolveKeybinds(raw: unknown): Keybinds {
-  const keys: Keybinds = { ...DEFAULT_KEYS };
-  if (raw === undefined) return keys;
-  const parsed = KeybindsSchema.safeParse(raw);
-  if (!parsed.success)
-    throw new CatherdError("E_CONFIG_KEYBIND", "config.json keybinds must map command ids to keys", {
-      fix: 'e.g. "keybinds": { "profile.save": "ctrl+w", "app.help": "none" }',
-    });
-  for (const [id, value] of Object.entries(parsed.data)) {
-    if (!BY_ID.has(id))
-      throw new CatherdError("E_CONFIG_KEYBIND", `config.json keybinds: no command "${id}"`, {
-        fix: "the command palette (ctrl+p) and catherd's README list the command ids",
-      });
-    if ((RESERVED as readonly string[]).includes(id))
-      throw new CatherdError("E_CONFIG_KEYBIND", `config.json keybinds: "${id}" cannot be rebound`, {
-        fix: `remove "${id}" from keybinds`,
-      });
-    // a comma list is several keys, as in opencode's config
-    const list = (Array.isArray(value) ? value : [value]).flatMap((v) => v.split(",").map((k) => k.trim()));
-    if (list.some((k) => k.split(" ")[0] === LEADER))
-      throw new CatherdError(
-        "E_CONFIG_KEYBIND",
-        `config.json keybinds: ${id} cannot take ${LEADER}, the leader`,
-        {
-          fix: `bind ${id} to another key, or to the leader and a key: "<leader>w"`,
-        },
-      );
-    // dialog and filter commands are live while the user types: a typed key would take letters from the text
-    const scope = (BY_ID.get(id) as CommandDef).scope;
-    const typed = list.find(isPrintable);
-    if ((scope === "dialog" || scope === "filter") && typed)
-      throw new CatherdError(
-        "E_CONFIG_KEYBIND",
-        `config.json keybinds: ${id} works while you type, so it cannot take "${typed}"`,
-        { fix: `bind ${id} to a key with ctrl or alt, or a named key such as "return"` },
-      );
-    keys[id as CommandId] = list.includes("none") ? [] : list.filter(Boolean);
-  }
-  const dup = duplicateKeys(keys);
-  if (dup.length)
-    throw new CatherdError(
-      "E_CONFIG_KEYBIND",
-      `config.json keybinds give one key two meanings: ${dup.join("; ")}`,
-      {
-        fix: 'bind one of them to another key, or to "none"',
-      },
-    );
-  return keys;
-}
-
-const WORDS: Record<string, string> = {
-  return: "enter",
-  escape: "esc",
-  pageup: "pgup",
-  pagedown: "pgdn",
-  up: "↑",
-  down: "↓",
-  left: "←",
-  right: "→",
-};
-const PLAIN_WORDS: Record<string, string> = { up: "up", down: "down", left: "left", right: "right" };
-
-/** How a key reads in the footer, palette and help: `ctrl+x n`, `enter`, `G`, `↑`. */
-export function formatKey(key: string, plain = false): string {
-  if (key.startsWith("<leader>")) return `${LEADER} ${formatKey(key.slice("<leader>".length), plain)}`;
-  if (/^shift\+[a-z]$/.test(key)) return key.slice(-1).toUpperCase();
-  return (plain ? PLAIN_WORDS[key] : undefined) ?? WORDS[key] ?? key;
-}
-
-/** All of a command's keys, `/`-joined, or "" when it has none. */
-export const formatKeys = (keys: readonly string[], plain = false): string =>
-  keys.map((k) => formatKey(k, plain)).join("/");