tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/src/tui/chrome/cheatsheet.ts

@@ -0,0 +1,260 @@
+/**
+ * The tmux-ide cheat-sheet — an iPadOS-style "all the keys" command sheet.
+ *
+ * Pressing `⌥k` (or clicking the `[ ? keys ]` trigger in the chrome row) on any
+ * adopted session floats a `display-popup` running `tmux-ide cheatsheet`, which
+ * prints this grouped, styled sheet and then blocks until ANY key closes it.
+ *
+ * The sheet is STATIC content, so it renders as a plain ANSI CLI print — no
+ * OpenTUI/bun boot — which keeps the popup instant. To stop the sheet drifting
+ * from reality, its dynamic groups are SOURCED from live inputs: the configured
+ * key binds + theme tokens (`keys`/`theme`, defaulting to the app-config
+ * defaults) and the team app's `DEFAULT_KEYMAP`/`ACTION_ORDER`. Only the
+ * inherently-static tmux essentials group is hardcoded.
+ *
+ * `buildCheatsheet` and the bind/unbind command builders are PURE (tested); the
+ * CLI `cheatsheet` command wires the io (print + wait-for-key).
+ */
+import { DEFAULT_KEYS, DEFAULT_THEME, type AppKeys, type AppTheme } from "../../lib/app-config.ts";
+import { ACTION_ORDER, DEFAULT_KEYMAP } from "../team/keymap.ts";
+import { GRAMMAR_HELP } from "../../widgets/lib/grammar.ts";
+import { PANEL_POPUPS, panelKey } from "./panels.ts";
+
+/**
+ * The root-table key that floats this sheet: `M-k` (Alt+k). Like the switcher's
+ * popup key it lives in the ROOT table so it fires without the prefix from any adopted
+ * session, and Alt-letter keys are low-collision in terminal apps. Chosen to sit
+ * next to `M-p` (switcher) so the two chrome popups share an ergonomic home.
+ */
+export const CHEATSHEET_KEY = "M-k";
+
+// --- ANSI styling — the CLI's bold/cyan/dim pattern (see bin/cli.ts). ---
+const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;
+const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;
+const cyan = (s: string) => `\x1b[36m${s}\x1b[39m`;
+const head = (s: string) => `\x1b[1;36m${s}\x1b[0m`;
+const color = (code: number, s: string) => `\x1b[38;5;${code}m${s}\x1b[39m`;
+
+/**
+ * The 256-color index of a `colourN` theme token for the ANSI legend, or null
+ * for a non-`colourN` token (e.g. a hex color) — the caller then renders it dim
+ * rather than mis-mapping the code.
+ */
+function tokenCode(token: string): number | null {
+  const m = /^colou?r(\d+)$/.exec(token);
+  if (!m) return null;
+  const n = Number(m[1]);
+  return Number.isInteger(n) && n >= 0 && n <= 255 ? n : null;
+}
+
+/** Render a glyph in a theme status token's color for the legend (dim fallback). */
+function legendMark(token: string, glyph: string): string {
+  const code = tokenCode(token);
+  return code === null ? dim(glyph) : color(code, glyph);
+}
+
+/**
+ * Render a tmux key name for humans: `M-` → `⌥`, `C-` → `^`, `S-` → `⇧`. Keeps
+ * the sheet's key hints sourced from the real `M-…` constants instead of a
+ * separately-maintained pretty string.
+ */
+function renderKey(tmuxKey: string): string {
+  return tmuxKey.replace(/M-/g, "⌥").replace(/C-/g, "^").replace(/S-/g, "⇧");
+}
+
+/**
+ * Clip a styled line to `width` VISIBLE columns, passing ANSI escapes through
+ * untouched (they cost no width) and closing any open style with a reset so a
+ * mid-style cut can't bleed into the next line. Guarantees the sheet respects a
+ * narrow popup without mangling color codes.
+ */
+function clip(line: string, width: number): string {
+  let out = "";
+  let visible = 0;
+  let i = 0;
+  while (i < line.length) {
+    if (line[i] === "\x1b") {
+      // eslint-disable-next-line no-control-regex -- matching the ANSI SGR escape
+      const m = /^\x1b\[[0-9;]*m/.exec(line.slice(i));
+      if (m) {
+        out += m[0];
+        i += m[0].length;
+        continue;
+      }
+    }
+    if (visible >= width) break;
+    out += line[i];
+    visible++;
+    i++;
+  }
+  return `${out}\x1b[0m`;
+}
+
+/** Visible-width of a styled string (ANSI escapes stripped). */
+function visibleWidth(s: string): number {
+  // eslint-disable-next-line no-control-regex -- stripping ANSI SGR escapes
+  return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+/**
+ * Build the full ANSI cheat sheet, one screenful for a ~100x28 popup.
+ *
+ * Groups (each under a bold-cyan heading):
+ *   1. dock       — the ⌥p / ⌥k popups, the clickable bar, and the glyph legend.
+ *   2. picker     — the keys live INSIDE the ⌥p switcher popup.
+ *   3. team app   — DERIVED from ACTION_ORDER/DEFAULT_KEYMAP (two columns if the
+ *                   width allows), so it never drifts from the real keymap.
+ *   4. tmux       — the prefix essentials (inherently static → hardcoded).
+ *   5. cli        — the handful of scriptable commands worth remembering.
+ *
+ * Every line is clipped to `width` so nothing overflows a narrow popup.
+ */
+export function buildCheatsheet(opts: { width: number; keys?: AppKeys; theme?: AppTheme }): string {
+  const width = Math.max(20, opts.width);
+  const keys = opts.keys ?? DEFAULT_KEYS;
+  const theme = opts.theme ?? DEFAULT_THEME;
+  const lines: string[] = [];
+  const pad = (s: string) => `  ${s}`; // two-space indent under each heading
+
+  // Title.
+  lines.push(`${head(" tmux-ide")}  ${dim("cheat sheet — press any key to close")}`);
+  lines.push("");
+
+  // 1. dock — sourced key hints from the configured keys.
+  lines.push(head("dock"));
+  lines.push(
+    pad(
+      `${bold(renderKey(keys.home))} home cockpit   ${bold(renderKey(keys.popup))} switcher popup   ${bold(renderKey(keys.cheatsheet))} this sheet   ${bold(renderKey(keys.menu))} actions menu   ${bold(renderKey(keys.sidebar))} sidebar`,
+    ),
+  );
+  lines.push(
+    pad(
+      dim(
+        `bar: click a project tab = switch there · [ ⌂ home ${renderKey(keys.home)} ] = home · [ ⧉ switch ${renderKey(keys.popup)} ] = switcher · right-click anywhere = menu`,
+      ),
+    ),
+  );
+  const active = theme.glyphs.active;
+  const legend =
+    `${legendMark(theme.status.blocked, active)} blocked  ${legendMark(theme.status.working, active)} working  ` +
+    `${legendMark(theme.status.done, active)} done  ${legendMark(theme.status.idle, active)} idle  ` +
+    `${dim("·")} unknown  ${dim(theme.glyphs.inactive)} stopped`;
+  lines.push(pad(legend));
+  lines.push("");
+
+  // 1a. prefix twins — the RELIABLE bindings (the tmux prefix survives every
+  // keyboard protocol; Alt keys don't always). Letters pinned against
+  // prefixKeyBinds by a statusline test so they can't drift.
+  lines.push(head("prefix keys (always work)"));
+  lines.push(
+    pad(
+      `${bold("prefix h")} home  ${bold("prefix j")} switcher  ${bold("prefix k")} keys  ${bold("prefix u")} menu  ${bold("prefix b")} sidebar  ${bold("prefix e")} files  ${bold("prefix g")} changes  ${bold("prefix v")} config`,
+    ),
+  );
+  lines.push(
+    pad(dim(`prefix = your tmux prefix (usually C-b) — use these when Alt keys don't reach tmux`)),
+  );
+  lines.push("");
+
+  // 1b. panels — every widget floats as a popup, one key away, esc to close.
+  lines.push(head("panels"));
+  const panelHints = PANEL_POPUPS.map(
+    (p) => `${bold(renderKey(panelKey(p, keys.panels)))} ${p.label}`,
+  ).join("   ");
+  lines.push(pad(`${panelHints}   ${dim("esc/q closes any panel")}`));
+  lines.push("");
+
+  // 1c. grammar — the ONE interaction grammar every panel + the sidebar share,
+  // sourced from GRAMMAR_HELP so it can never drift from the widgets.
+  lines.push(head("in panels & sidebar"));
+  const gKeyW = Math.max(...GRAMMAR_HELP.map((r) => r.keys.length));
+  for (const row of GRAMMAR_HELP) {
+    lines.push(pad(`${bold(row.keys.padEnd(gKeyW))}  ${dim(row.label)}`));
+  }
+  lines.push("");
+
+  // 2. picker — keys inside the switcher popup.
+  lines.push(head(`picker  ${dim(`(inside the ${renderKey(keys.popup)} popup)`)}`));
+  lines.push(
+    pad(`${bold("↵")} switch   ${bold("l")} launch   ${bold("/")} find   ${bold("esc")} close`),
+  );
+  lines.push("");
+
+  // 3. team app — derived from the real keymap, two columns when it fits.
+  lines.push(head("team app"));
+  const cells = ACTION_ORDER.map((action) => {
+    const binding = DEFAULT_KEYMAP[action];
+    return { keys: binding.keys.join("/"), desc: binding.description };
+  });
+  const keyW = Math.max(...cells.map((c) => c.keys.length));
+  const descW = Math.max(...cells.map((c) => c.desc.length));
+  const cellW = keyW + 2 + descW; // "keys" + gap + "desc" visible width
+  const renderCell = (c: { keys: string; desc: string }): string => {
+    const text = `${bold(c.keys.padEnd(keyW))}  ${dim(c.desc)}`;
+    return text + " ".repeat(Math.max(0, cellW - visibleWidth(text)));
+  };
+  const twoCols = width >= cellW * 2 + 4;
+  if (twoCols) {
+    const half = Math.ceil(cells.length / 2);
+    for (let i = 0; i < half; i++) {
+      const left = cells[i];
+      const right = cells[i + half];
+      const rendered = left ? renderCell(left) : "";
+      lines.push(pad(right ? `${rendered}  ${renderCell(right)}` : rendered));
+    }
+  } else {
+    for (const c of cells) lines.push(pad(renderCell(c)));
+  }
+  lines.push("");
+
+  // 4. tmux essentials — static.
+  lines.push(head("tmux essentials"));
+  lines.push(
+    pad(
+      `${bold("prefix d")} detach   ${bold("prefix z")} zoom pane   ${bold("prefix [")} copy mode`,
+    ),
+  );
+  lines.push(
+    pad(
+      `${bold("prefix c")} new window   ${bold("prefix n/p")} next/prev   ${bold('prefix % / "')} splits`,
+    ),
+  );
+  lines.push("");
+
+  // 5. cli — scriptable commands.
+  lines.push(head("cli"));
+  lines.push(pad(cyan("tmux-ide team --json")));
+  lines.push(pad(cyan("tmux-ide wait agent-status <s> --status done")));
+  lines.push(pad(cyan("tmux-ide adopt/unadopt <session>")));
+  lines.push(pad(cyan("tmux-ide worktree create <branch>") + dim("   (⎇ in the menu)")));
+
+  return lines.map((line) => clip(line, width)).join("\n");
+}
+
+/**
+ * PURE — the `display-popup` command STRING that floats the cheat sheet (shared
+ * by the M-k bind, the bar's `[ ? keys ]` left-click router, and the actions
+ * menu's "Cheat sheet" item, so all three open an identical popup). Mirror of the
+ * sizing in {@link cheatsheetBindCommand}.
+ */
+export function cheatsheetPopupCommand(cheatsheetCmd = "tmux-ide cheatsheet"): string {
+  return `display-popup -E -w 90% -h 80% "${cheatsheetCmd}"`;
+}
+
+/**
+ * PURE — the tmux argv that binds {@link CHEATSHEET_KEY}: `M-k` opens a
+ * `display-popup` running the cheat sheet (which waits for any key, then exits,
+ * closing the popup). Server-wide root-table bind, mirroring the switcher's
+ * popup key — see the note on `unadoptSession`.
+ */
+export function cheatsheetBindCommand(
+  cheatsheetCmd = "tmux-ide cheatsheet",
+  key = CHEATSHEET_KEY,
+): string[] {
+  return ["bind-key", "-n", key, "display-popup", "-E", "-w", "90%", "-h", "80%", cheatsheetCmd];
+}
+
+/** PURE — the tmux argv that removes the cheat-sheet key binding. */
+export function cheatsheetUnbindCommand(key = CHEATSHEET_KEY): string[] {
+  return ["unbind-key", "-n", key];
+}

package/packages/daemon/src/tui/chrome/chip.ts

@@ -0,0 +1,30 @@
+/**
+ * Per-pane agent chips — the border label rendered INSIDE an adopted session.
+ *
+ * Where the status bar ({@link ./statusline.ts}) shows the fleet rollup (one
+ * glyph per session), a chip shows per-PANE truth: what agent is running in
+ * THIS pane and its live state — `claude · working`, `codex · blocked`. The
+ * updater writes each adopted pane's chip into a `@tmux_ide_chip` pane option
+ * and `adoptSession` points `pane-border-format` at it (falling back to the
+ * pane title when empty). `paneChip` is pure (tested); the io lives in the
+ * updater.
+ */
+import { DEFAULT_THEME, type AppTheme } from "../../lib/app-config.ts";
+import type { AgentStatus } from "../detect/classify.ts";
+import { statusStyle } from "./statusline.ts";
+
+/**
+ * PURE — build a pane's chip string with tmux `#[...]` markup, or `""` for a
+ * non-agent pane (`agent === null`, e.g. a raw shell). An empty chip clears the
+ * pane option so the border format falls back to the pane title. The chip is
+ * `<agent> · <status>` styled via the shared {@link statusStyle} so it reads the
+ * same as its session's rollup glyph — one palette across the bar and the chips.
+ */
+export function paneChip(
+  agent: string | null,
+  status: AgentStatus,
+  theme: AppTheme = DEFAULT_THEME,
+): string {
+  if (!agent) return "";
+  return `${statusStyle(status, theme)}${agent} · ${status}#[default]`;
+}

package/packages/daemon/src/tui/chrome/events.ts

@@ -0,0 +1,119 @@
+/**
+ * Agent-state TRANSITION event log — the fleet's history layer.
+ *
+ * The chrome {@link ./updater.ts updater} sees every session's status EACH
+ * tick, but a status bar is a snapshot: it can't tell you that
+ * `prototyper-platform` went `working → done` at 12:31. This module turns the
+ * per-tick fleet into a stream of transition events and appends them to a
+ * JSONL log that `tmux-ide events` tails.
+ *
+ * Split as usual: {@link diffFleet} + {@link formatEventLine} +
+ * {@link shouldRotate} are PURE (unit-tested without a filesystem), while
+ * {@link appendEvents} is the thin io wrapper that stamps `ts`, rotates the
+ * file, and appends.
+ */
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AgentStatus } from "../detect/classify.ts";
+
+/** A single session-level status transition. `from` is null the first time a session is seen. */
+export interface AgentEvent {
+  ts: string;
+  session: string;
+  from: AgentStatus | null;
+  to: AgentStatus;
+}
+
+/** A transition before it's been stamped with a timestamp (what {@link diffFleet} emits). */
+export type AgentEventInit = Omit<AgentEvent, "ts">;
+
+/** Rotate the log once it grows past this many bytes (crude one-generation rotation). */
+export const EVENTS_MAX_BYTES = 1024 * 1024;
+
+/**
+ * PURE — diff the previous fleet state against the current one.
+ *
+ * For each session in `next` we emit a transition when its status changed, and
+ * a first-sight event (`from: null`) the first time we see it. A session that
+ * DISAPPEARS from `next` emits NOTHING — we don't synthesize an `idle`/gone
+ * event, we just drop it from the returned `state` (keeps the log honest: an
+ * absent session simply stops producing events until it returns).
+ *
+ * Returns both the new events and the fresh state map to thread into the next
+ * tick. The caller stamps `ts` on the events (see {@link appendEvents}).
+ */
+export function diffFleet(
+  prev: Map<string, AgentStatus>,
+  next: Array<{ name: string; status: AgentStatus }>,
+): { events: AgentEventInit[]; state: Map<string, AgentStatus> } {
+  const state = new Map<string, AgentStatus>();
+  const events: AgentEventInit[] = [];
+  for (const { name, status } of next) {
+    const before = prev.has(name) ? prev.get(name)! : null;
+    state.set(name, status);
+    if (before === null) {
+      events.push({ session: name, from: null, to: status });
+    } else if (before !== status) {
+      events.push({ session: name, from: before, to: status });
+    }
+  }
+  return { events, state };
+}
+
+/** PURE — whether a log of `sizeBytes` is due for rotation. */
+export function shouldRotate(sizeBytes: number): boolean {
+  return sizeBytes > EVENTS_MAX_BYTES;
+}
+
+/** Extract `HH:MM:SS` from an ISO-8601 timestamp (UTC); falls back to the raw string. */
+function isoTime(ts: string): string {
+  const m = /T(\d{2}:\d{2}:\d{2})/.exec(ts);
+  return m ? m[1]! : ts;
+}
+
+/**
+ * PURE — render one event for the human-readable `tmux-ide events` view, e.g.
+ * `12:31:07 prototyper-platform working → done`. First-sight events (from=null)
+ * render the origin as `·`. `paint` colors a status token (defaults to
+ * identity so tests get plain text); the CLI passes an ANSI painter.
+ */
+export function formatEventLine(
+  ev: AgentEvent,
+  paint: (status: AgentStatus | null, text: string) => string = (_s, t) => t,
+): string {
+  const from = ev.from === null ? "·" : paint(ev.from, ev.from);
+  return `${isoTime(ev.ts)} ${ev.session} ${from} → ${paint(ev.to, ev.to)}`;
+}
+
+/** Absolute path to the fleet event log. */
+export function eventsPath(): string {
+  return join(homedir(), ".tmux-ide", "events.jsonl");
+}
+
+/**
+ * io — stamp each event with `now()` and append it to the log as JSONL.
+ *
+ * Before appending, rotates the log to `events.jsonl.1` (overwriting any prior
+ * generation) when it's grown past {@link EVENTS_MAX_BYTES}. Best-effort: a
+ * filesystem failure must never break the updater loop, so every step is
+ * guarded. No-op when there are no events.
+ */
+export function appendEvents(
+  events: AgentEventInit[],
+  now: () => string = () => new Date().toISOString(),
+): void {
+  if (events.length === 0) return;
+  const path = eventsPath();
+  try {
+    mkdirSync(join(homedir(), ".tmux-ide"), { recursive: true });
+    if (existsSync(path) && shouldRotate(statSync(path).size)) {
+      renameSync(path, `${path}.1`);
+    }
+    const ts = now();
+    const lines = events.map((e) => `${JSON.stringify({ ts, ...e })}\n`).join("");
+    appendFileSync(path, lines);
+  } catch {
+    // Stale/failed log write just means a gap in history — never fatal.
+  }
+}

package/packages/daemon/src/tui/chrome/kitty-keys.ts

@@ -0,0 +1,55 @@
+/**
+ * Kitty-keyboard-protocol fallback binds for the root-table Alt keys.
+ *
+ * Claude Code enables the Kitty keyboard protocol with event-type reporting.
+ * Under it, the FOCUSED pane's terminal encodes e.g. Alt-m not as the legacy
+ * `ESC m` but as the CSI-u form `ESC[109;3:1u` (109 = 'm', 3 = the Alt modifier,
+ * `:1` = a key-PRESS event-type subparameter). tmux 3.6 does NOT normalize that
+ * `:1`-carrying full form back to `M-m`, so a root-table `bind-key -n M-m` never
+ * fires while a Claude Code pane is focused — every dock shortcut (⌥m/⌥p/⌥k/⌥b/
+ * ⌥e/⌥g/⌥,/⌥h) goes dead. Plain `ESC m` and the basic CSI-u `ESC[109;3u` both
+ * DO reach tmux as `M-m`; only the `:1` full form misses (proven live by
+ * injecting each encoding into a nested client).
+ *
+ * The fix is a tmux USER-KEY fallback per Alt bind: teach tmux the exact kitty
+ * escape as `user-keys[N]`, then bind `UserN` to the SAME action argv as the
+ * `M-…` key. tmux matches the raw escape against the user-key and fires the
+ * bind, so the shortcut works whether the focused pane speaks legacy or full
+ * kitty. Registering the fallback is harmless for panes that never send the
+ * `:1` form (nothing else emits `UserN`).
+ *
+ * Pure — tested as a table; the io (registering the binds) lives in
+ * {@link ./statusline.ts}.
+ */
+
+/**
+ * PURE — the full-kitty key-PRESS encoding for a single-char Alt key (`M-<c>`),
+ * or `null` for anything else (multi-char key names, non-Alt keys — they don't
+ * get a fallback). The sequence is `ESC[<code>;3:1u` where `<code>` is the code
+ * point of the (lowercased) character, `3` is the Alt modifier, and `:1` is the
+ * key-press event-type subparameter. Examples: `M-m` → `ESC[109;3:1u`, `M-h` →
+ * `ESC[104;3:1u`, `M-,` → `ESC[44;3:1u`.
+ */
+export function kittyEscapeFor(key: string): string | null {
+  const m = /^M-(.)$/.exec(key);
+  const ch = m?.[1];
+  if (ch === undefined) return null;
+  const code = ch.toLowerCase().codePointAt(0);
+  if (code === undefined) return null;
+  return `\x1b[${code};3:1u`;
+}
+
+/**
+ * PURE — the tmux `user-keys` array index for the Nth Alt fallback. We claim the
+ * range `[100, …)` (offset 100) so we never clobber a user's own
+ * `user-keys[0..]` entries — anyone hand-setting `user-keys` should keep their
+ * indices below 100.
+ */
+export function kittyUserKeyIndex(slot: number): number {
+  return 100 + slot;
+}
+
+/** PURE — the tmux key name a `user-keys[idx]` entry surfaces as (`UserN`). */
+export function kittyUserKeyName(slot: number): string {
+  return `User${kittyUserKeyIndex(slot)}`;
+}