tmux-ide 2.1.5 → 2.6.1

package/packages/daemon/src/widgets/lib/grammar.ts

@@ -0,0 +1,126 @@
+/**
+ * The ONE interaction grammar shared by every TUI surface — the sidebar,
+ * explorer, changes, config, and the team cockpit/picker.
+ *
+ * Cohesion is muscle memory: `j`/`k` (+ arrows) move, `enter` activates, `/`
+ * filters, `esc` closes the topmost thing (filter → detail → widget), `q`
+ * quits, `?` toggles help. These keys mean the SAME thing everywhere, so a
+ * widget never invents its own drift for a universal verb.
+ *
+ * Widgets call {@link matchGrammar} FIRST in their key handler and act on the
+ * returned {@link GrammarAction}, falling through to their own widget-specific
+ * keys only when it returns `null`. The escape precedence is factored into the
+ * pure {@link dismiss} state-machine so "esc closes the filter before it quits"
+ * is defined (and tested) in one place.
+ *
+ * This module is the SINGLE SOURCE for the grammar: the per-widget help
+ * overlays and the cheat sheet both render their "in panels & sidebar" section
+ * from {@link GRAMMAR_HELP}, so documentation can never drift from behaviour.
+ *
+ * Pure — no io, no solid, no opentui — so it unit-tests as a plain table.
+ */
+
+/** The universal verbs every surface understands. */
+export type GrammarAction =
+  | "navDown"
+  | "navUp"
+  | "activate"
+  | "filter"
+  | "help"
+  | "dismiss"
+  | "quit";
+
+/** The subset of an @opentui key event the grammar needs. */
+export interface GrammarKeyEvent {
+  name: string;
+  ctrl?: boolean;
+  alt?: boolean;
+  meta?: boolean;
+  shift?: boolean;
+}
+
+/**
+ * Deterministic iteration order for {@link matchGrammar}. The grammar keys are
+ * mutually exclusive (no key appears in two actions), so order only fixes the
+ * lookup for readers/tests — it never changes a result.
+ */
+export const GRAMMAR_ACTION_ORDER: GrammarAction[] = [
+  "navDown",
+  "navUp",
+  "activate",
+  "filter",
+  "help",
+  "dismiss",
+  "quit",
+];
+
+/**
+ * The fixed key → action bindings. Unlike the team app's configurable
+ * `DEFAULT_KEYMAP`, the GRAMMAR itself is not user-configurable — its whole
+ * value is that it is the same everywhere. The team keymap's universal actions
+ * (up/down/enter/filter/help/quit) agree with these by construction.
+ */
+export const GRAMMAR_KEYS: Record<GrammarAction, string[]> = {
+  navDown: ["j", "down"],
+  navUp: ["k", "up"],
+  activate: ["return"],
+  filter: ["/"],
+  help: ["?"],
+  dismiss: ["escape"],
+  quit: ["q"],
+};
+
+/**
+ * Human-facing rows for the help overlays and the cheat sheet — rendered
+ * straight from this constant so the docs are sourced from the grammar itself.
+ */
+export const GRAMMAR_HELP: ReadonlyArray<{ keys: string; label: string }> = [
+  { keys: "j / ↓", label: "move down" },
+  { keys: "k / ↑", label: "move up" },
+  { keys: "enter", label: "activate / open" },
+  { keys: "/", label: "filter list" },
+  { keys: "esc", label: "close filter → detail → widget" },
+  { keys: "q", label: "quit" },
+  { keys: "?", label: "toggle this help" },
+];
+
+/**
+ * Map a key event to its {@link GrammarAction}, or `null` when the key is not
+ * part of the grammar (so the caller falls through to its widget-specific
+ * keys).
+ *
+ * `ctrl`/`alt`/`meta` combos are NEVER grammar — those namespaces belong to the
+ * widgets (`ctrl+s` save, `ctrl+c` quit, the `M-…` dock popups). `shift` is
+ * allowed through because `?` arrives as a shifted `/` on most layouts; no
+ * widget binds a `shift+<grammar key>` combo, so letting it pass is safe.
+ */
+export function matchGrammar(evt: GrammarKeyEvent): GrammarAction | null {
+  if (evt.ctrl || evt.alt || evt.meta) return null;
+  for (const action of GRAMMAR_ACTION_ORDER) {
+    if (GRAMMAR_KEYS[action].includes(evt.name)) return action;
+  }
+  return null;
+}
+
+/** Which layer an `esc` (or `q`) should close, given what is currently open. */
+export type DismissTarget = "filter" | "detail" | "widget";
+
+/** The open-overlay layers a surface can stack, topmost-wins. */
+export interface OverlayState {
+  /** A `/` filter prompt is open (typing narrows a list). */
+  filterOpen?: boolean;
+  /** A transient detail view is open (help overlay, field editor, preview). */
+  detailOpen?: boolean;
+}
+
+/**
+ * The escape precedence, as a pure function: esc closes the FILTER first, then
+ * an open DETAIL, and only when nothing is layered does it fall through to the
+ * WIDGET itself (quit / close the popup). Widgets call this to decide what a
+ * bare `esc` (grammar `dismiss`) should do without re-deriving the order.
+ */
+export function dismiss(state: OverlayState): DismissTarget {
+  if (state.filterOpen) return "filter";
+  if (state.detailOpen) return "detail";
+  return "widget";
+}

package/packages/daemon/src/widgets/lib/help-overlay.tsx

@@ -0,0 +1,101 @@
+/**
+ * The shared `?` help overlay — one box, every surface.
+ *
+ * Renders the UNIVERSAL interaction grammar (from {@link GRAMMAR_HELP}, the same
+ * constant the cheat sheet reads) above the caller's OWN widget-specific keys.
+ * Because the grammar rows come from `grammar.ts`, no surface can document
+ * `j`/`k`/`enter`/`/`/`esc`/`q`/`?` differently from how it behaves.
+ *
+ * Each surface keeps a `helpOpen` signal, routes `?` (grammar `help`) to toggle
+ * it and `esc`/`q` to close it, and renders `<HelpOverlay …>` in place of its
+ * body while open. Kept theme-driven and io-free so it drops into any widget.
+ */
+import { For, Show } from "solid-js";
+import { RGBA, TextAttributes } from "@opentui/core";
+import type { WidgetTheme } from "./theme.ts";
+import { GRAMMAR_HELP } from "./grammar.ts";
+
+function toRGBA(c: { r: number; g: number; b: number; a: number }): RGBA {
+  return RGBA.fromInts(c.r, c.g, c.b, c.a);
+}
+
+/** A widget-specific key row: the rendered key(s) and what they do. */
+export interface WidgetKey {
+  key: string;
+  label: string;
+}
+
+export interface HelpOverlayProps {
+  theme: WidgetTheme;
+  /** Surface name shown in the header (e.g. "explorer", "sidebar"). */
+  title: string;
+  /** The surface's own keys, listed under the shared grammar. */
+  widgetKeys: WidgetKey[];
+}
+
+/**
+ * A centered help card: a "grammar" section (shared verbs) then a section of
+ * the surface's own keys. Replaces the surface body while `?` is held open;
+ * `esc`/`q`/`?` close it.
+ */
+export function HelpOverlay(props: HelpOverlayProps) {
+  const keyCol = () => {
+    const widths = [
+      ...GRAMMAR_HELP.map((r) => r.keys.length),
+      ...props.widgetKeys.map((r) => r.key.length),
+    ];
+    return Math.max(6, ...widths);
+  };
+  return (
+    <box flexDirection="column" flexGrow={1} alignItems="center" paddingTop={2}>
+      <box
+        flexDirection="column"
+        border
+        borderColor={toRGBA(props.theme.accent)}
+        backgroundColor={toRGBA(props.theme.selected)}
+        paddingLeft={2}
+        paddingRight={2}
+        paddingTop={1}
+        paddingBottom={1}
+      >
+        <text fg={toRGBA(props.theme.accent)} attributes={TextAttributes.BOLD}>
+          {props.title} — help
+        </text>
+
+        <box paddingTop={1}>
+          <text fg={toRGBA(props.theme.fgMuted)} attributes={TextAttributes.BOLD}>
+            grammar
+          </text>
+        </box>
+        <For each={GRAMMAR_HELP}>
+          {(row) => (
+            <box flexDirection="row" gap={1}>
+              <text fg={toRGBA(props.theme.accent)}>{row.keys.padEnd(keyCol())}</text>
+              <text fg={toRGBA(props.theme.fg)}>{row.label}</text>
+            </box>
+          )}
+        </For>
+
+        <Show when={props.widgetKeys.length > 0}>
+          <box paddingTop={1}>
+            <text fg={toRGBA(props.theme.fgMuted)} attributes={TextAttributes.BOLD}>
+              {props.title}
+            </text>
+          </box>
+          <For each={props.widgetKeys}>
+            {(row) => (
+              <box flexDirection="row" gap={1}>
+                <text fg={toRGBA(props.theme.accent)}>{row.key.padEnd(keyCol())}</text>
+                <text fg={toRGBA(props.theme.fg)}>{row.label}</text>
+              </box>
+            )}
+          </For>
+        </Show>
+
+        <box paddingTop={1}>
+          <text fg={toRGBA(props.theme.fgMuted)}>esc / q / ? to close</text>
+        </box>
+      </box>
+    </box>
+  );
+}

package/packages/daemon/src/widgets/lib/pane-comms.ts

@@ -0,0 +1,209 @@
+import { execFileSync } from "node:child_process";
+import type { PaneInfo } from "@tmux-ide/contracts";
+
+export type { PaneInfo };
+
+type TmuxExecutor = (cmd: string, args: string[], options?: object) => string;
+
+let _executor: TmuxExecutor = (cmd, args, options) =>
+  execFileSync(cmd, args, { encoding: "utf-8", ...options }).toString();
+
+export function _setExecutor(fn: TmuxExecutor): () => void {
+  const prev = _executor;
+  _executor = fn;
+  return () => {
+    _executor = prev;
+  };
+}
+
+function tmux(...args: string[]): string {
+  try {
+    return _executor("tmux", args, {
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch (error) {
+    const stderr = (error as { stderr?: Buffer | string })?.stderr?.toString() ?? "";
+    if (stderr.includes("no server running") || stderr.includes("can't find session")) {
+      return "";
+    }
+    throw error;
+  }
+}
+
+export function listSessionPanes(session: string): PaneInfo[] {
+  const format = [
+    "#{pane_id}",
+    "#{pane_index}",
+    "#{pane_title}",
+    "#{pane_current_command}",
+    "#{pane_width}",
+    "#{pane_height}",
+    "#{pane_active}",
+    "#{@ide_role}",
+    "#{@ide_name}",
+    "#{@ide_type}",
+  ].join("\t");
+
+  const output = tmux("list-panes", "-t", session, "-F", format);
+  if (!output) return [];
+
+  return output
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const [id, index, title, cmd, width, height, active, role, name, type] = line.split("\t");
+      return {
+        id: id!,
+        index: parseInt(index!, 10),
+        title: title!,
+        currentCommand: cmd!,
+        width: parseInt(width!, 10),
+        height: parseInt(height!, 10),
+        active: active === "1",
+        role: (role || null) as PaneInfo["role"],
+        name: name || null,
+        type: type || null,
+      };
+    });
+}
+
+export function findPaneByTitle(session: string, title: string): string | null {
+  const panes = listSessionPanes(session);
+  const match = panes.find((p) => p.title === title);
+  return match?.id ?? null;
+}
+
+export function findPaneByPattern(session: string, pattern: string): string | null {
+  const panes = listSessionPanes(session);
+  const lower = pattern.toLowerCase();
+  const match = panes.find((p) => p.title.toLowerCase().includes(lower));
+  return match?.id ?? null;
+}
+
+export function findAdjacentPane(session: string, currentPaneId: string): string | null {
+  const panes = listSessionPanes(session);
+  const currentIdx = panes.findIndex((p) => p.id === currentPaneId);
+  if (currentIdx === -1 || panes.length < 2) return null;
+  const nextIdx = (currentIdx + 1) % panes.length;
+  return panes[nextIdx]!.id;
+}
+
+const BUSY_COMMANDS = new Set([
+  "claude",
+  "codex",
+  "vim",
+  "nvim",
+  "vi",
+  "nano",
+  "emacs",
+  "less",
+  "more",
+  "top",
+  "htop",
+  "man",
+]);
+
+const SHELL_COMMANDS = new Set(["zsh", "bash", "sh", "fish"]);
+
+export type PaneBusyStatus = "idle" | "busy" | "agent";
+
+export function isPaneBusy(session: string, paneId: string): boolean {
+  const panes = listSessionPanes(session);
+  const pane = panes.find((p) => p.id === paneId);
+  if (!pane) return true;
+  const cmd = pane.currentCommand.toLowerCase();
+  if (SHELL_COMMANDS.has(cmd)) return false;
+  if (BUSY_COMMANDS.has(cmd)) return true;
+  return true; // unknown command — assume busy
+}
+
+export function getPaneBusyStatus(session: string, paneId: string): PaneBusyStatus {
+  const panes = listSessionPanes(session);
+  const pane = panes.find((p) => p.id === paneId);
+  if (!pane) return "busy";
+  const cmd = pane.currentCommand.toLowerCase();
+  if (cmd.startsWith("claude") || cmd.startsWith("codex")) return "agent";
+  if (SHELL_COMMANDS.has(cmd)) return "idle";
+  return "busy";
+}
+
+export function sendText(session: string, paneId: string, text: string): void {
+  tmux("send-keys", "-t", paneId, "-l", "--", text);
+}
+
+// tmux pane ids (e.g. %10) are GLOBAL — they don't take a session prefix.
+// `tmux send-keys -t <session>:<%paneId>` makes tmux interpret the
+// session prefix and then look up `%paneId` as a window inside that
+// session, which fails ("can't find window: %10"). Pass the bare pane id.
+export function sendLiteralToPane(_session: string, paneId: string, text: string): void {
+  tmux("send-keys", "-t", paneId, "-l", "--", text);
+}
+
+export function sendEnterToPane(_session: string, paneId: string): void {
+  tmux("send-keys", "-t", paneId, "Enter");
+}
+
+function sleepMs(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function sendCommand(session: string, paneId: string, command: string): boolean {
+  const status = getPaneBusyStatus(session, paneId);
+  try {
+    tmux("send-keys", "-t", paneId, "-l", "--", command);
+  } catch {
+    return false;
+  }
+  if (status === "agent") {
+    // Claude Code shows a [Pasted text] preview for long input (roughly >200 chars).
+    // Short commands land directly in the prompt — just need a brief delay for the
+    // TUI to register the input. Long commands trigger the paste preview which needs
+    // two Enters: one to confirm the preview, one to submit the prompt.
+    if (command.length < 200) {
+      sleepMs(150);
+    } else {
+      sleepMs(5000);
+      tmux("send-keys", "-t", paneId, "Enter");
+      sleepMs(2000);
+    }
+    tmux("send-keys", "-t", paneId, "Enter");
+    return true;
+  }
+  tmux("send-keys", "-t", paneId, "Enter");
+  return true;
+}
+
+export function openFileInEditor(session: string, paneId: string, filePath: string): void {
+  const editor = process.env.EDITOR ?? "vim";
+  sendCommand(session, paneId, `${editor} ${filePath}`);
+}
+
+export interface TargetOptions {
+  title?: string;
+  titlePattern?: string;
+  paneId?: string;
+  selfPaneId?: string;
+}
+
+export function resolveTarget(session: string, opts: TargetOptions): string | null {
+  if (opts.paneId) return opts.paneId;
+  if (opts.title) return findPaneByTitle(session, opts.title);
+  if (opts.titlePattern) return findPaneByPattern(session, opts.titlePattern);
+  if (opts.selfPaneId) return findAdjacentPane(session, opts.selfPaneId);
+  return null;
+}
+
+/**
+ * Capture the last line of a tmux pane. Uses the mockable executor so tests
+ * can intercept the call instead of hitting a real tmux server.
+ */
+export function captureLastLine(paneId: string): string {
+  try {
+    return _executor("tmux", ["capture-pane", "-t", paneId, "-p", "-S", "-1"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}

package/packages/daemon/src/widgets/lib/theme.ts

@@ -0,0 +1,194 @@
+import { DEFAULT_THEME, type AppTheme } from "../../lib/app-config.ts";
+
+export type RGBA = { r: number; g: number; b: number; a: number };
+
+export interface WidgetTheme {
+  bg: RGBA;
+  fg: RGBA;
+  fgMuted: RGBA;
+  accent: RGBA;
+  border: RGBA;
+  /** Per-agent-status colors, shared with the tmux chrome via the app theme. */
+  statusBlocked: RGBA;
+  statusWorking: RGBA;
+  statusDone: RGBA;
+  statusIdle: RGBA;
+  statusUnknown: RGBA;
+  selected: RGBA;
+  selectedText: RGBA;
+  dirName: RGBA;
+  rowAlt: RGBA;
+  indentGuide: RGBA;
+  ignored: RGBA;
+  gitModified: RGBA;
+  gitAdded: RGBA;
+  gitDeleted: RGBA;
+  gitUntracked: RGBA;
+  diffAdded: RGBA;
+  diffAddedBg: RGBA;
+  diffRemoved: RGBA;
+  diffRemovedBg: RGBA;
+  diffContext: RGBA;
+  diffContextBg: RGBA;
+  diffHunk: RGBA;
+  diffLineNumber: RGBA;
+}
+
+function rgba(r: number, g: number, b: number, a = 255) {
+  return { r, g, b, a };
+}
+
+const DEFAULTS: WidgetTheme = {
+  bg: rgba(30, 30, 40),
+  fg: rgba(200, 200, 210),
+  fgMuted: rgba(120, 120, 140),
+  accent: rgba(130, 170, 255),
+  border: rgba(60, 60, 80),
+  statusBlocked: rgba(255, 95, 95),
+  statusWorking: rgba(255, 215, 95),
+  statusDone: rgba(135, 175, 255),
+  statusIdle: rgba(135, 215, 135),
+  statusUnknown: rgba(128, 128, 128),
+  selected: rgba(50, 50, 70),
+  selectedText: rgba(255, 255, 255),
+  dirName: rgba(100, 160, 255),
+  rowAlt: rgba(255, 255, 255, 5),
+  indentGuide: rgba(60, 60, 80),
+  ignored: rgba(80, 80, 100),
+  gitModified: rgba(230, 180, 80),
+  gitAdded: rgba(80, 200, 120),
+  gitDeleted: rgba(230, 80, 80),
+  gitUntracked: rgba(120, 120, 140),
+  diffAdded: rgba(80, 200, 120),
+  diffAddedBg: rgba(20, 60, 30),
+  diffRemoved: rgba(230, 80, 80),
+  diffRemovedBg: rgba(60, 20, 20),
+  diffContext: rgba(160, 160, 170),
+  diffContextBg: rgba(30, 30, 40),
+  diffHunk: rgba(100, 180, 220),
+  diffLineNumber: rgba(80, 80, 100),
+};
+
+/**
+ * Parse a tmux/CSS color string into RGBA.
+ * Supports: colourN / colorN (0-255), #rgb, #rrggbb.
+ */
+function parseColor(color: string): RGBA | null {
+  // tmux colour0–colour255
+  const tmuxMatch = color.match(/^colou?r(\d+)$/);
+  if (tmuxMatch) {
+    const rawIndex = tmuxMatch[1];
+    if (!rawIndex) return null;
+    const n = parseInt(rawIndex, 10);
+    if (n < 0 || n > 255) return null;
+
+    // Standard colors 0–15 (approximate to common terminal defaults)
+    const STANDARD: [number, number, number][] = [
+      [0, 0, 0],
+      [128, 0, 0],
+      [0, 128, 0],
+      [128, 128, 0],
+      [0, 0, 128],
+      [128, 0, 128],
+      [0, 128, 128],
+      [192, 192, 192],
+      [128, 128, 128],
+      [255, 0, 0],
+      [0, 255, 0],
+      [255, 255, 0],
+      [0, 0, 255],
+      [255, 0, 255],
+      [0, 255, 255],
+      [255, 255, 255],
+    ];
+    if (n < 16) {
+      const standard = STANDARD[n];
+      if (!standard) return null;
+      return rgba(standard[0], standard[1], standard[2]);
+    }
+
+    // 6×6×6 color cube (16–231)
+    if (n < 232) {
+      const idx = n - 16;
+      const LEVELS: number[] = [0, 95, 135, 175, 215, 255];
+      const r = LEVELS[Math.floor(idx / 36)];
+      const g = LEVELS[Math.floor((idx % 36) / 6)];
+      const b = LEVELS[idx % 6];
+      if (r == null || g == null || b == null) return null;
+      return rgba(r, g, b);
+    }
+
+    // Grayscale ramp (232–255)
+    const level = 8 + 10 * (n - 232);
+    return rgba(level, level, level);
+  }
+
+  // Hex: #rgb or #rrggbb
+  const hexMatch = color.match(/^#([0-9a-fA-F]{3,6})$/);
+  if (hexMatch) {
+    let hex = hexMatch[1];
+    if (!hex) return null;
+    if (hex.length === 3) {
+      const [r, g, b] = hex.split("");
+      if (!r || !g || !b) return null;
+      hex = r + r + g + g + b + b;
+    }
+    if (hex.length !== 6) return null;
+    return rgba(
+      parseInt(hex.slice(0, 2), 16),
+      parseInt(hex.slice(2, 4), 16),
+      parseInt(hex.slice(4, 6), 16),
+    );
+  }
+
+  return null;
+}
+
+/**
+ * Map the shared app-theme tokens ({@link AppTheme}) onto a {@link WidgetTheme}
+ * base: accent, muted→fgMuted, fg, and the per-status colors. This is the layer
+ * that makes the OpenTUI widgets share the tmux chrome's palette. Unmappable
+ * tokens (e.g. a hex the parser rejects) keep their default.
+ */
+function applyAppTheme(base: WidgetTheme, appTheme: AppTheme): void {
+  const assign = (prop: keyof WidgetTheme, token: string) => {
+    const parsed = parseColor(token);
+    if (parsed) base[prop] = parsed;
+  };
+  assign("accent", appTheme.accent);
+  assign("fgMuted", appTheme.muted);
+  assign("fg", appTheme.fg);
+  assign("statusBlocked", appTheme.status.blocked);
+  assign("statusWorking", appTheme.status.working);
+  assign("statusDone", appTheme.status.done);
+  assign("statusIdle", appTheme.status.idle);
+  assign("statusUnknown", appTheme.status.unknown);
+}
+
+/**
+ * Build a widget theme. The shared app-theme tokens (`appTheme`, defaulting to
+ * {@link DEFAULT_THEME}) form the base palette so widgets and chrome match; the
+ * per-project ide.yml `theme` (`config`: accent/border/bg/fg) overrides on top.
+ */
+export function createTheme(
+  config?: Record<string, string>,
+  appTheme: AppTheme = DEFAULT_THEME,
+): WidgetTheme {
+  const theme = { ...DEFAULTS };
+  applyAppTheme(theme, appTheme);
+  if (!config) return theme;
+  const MAP: Record<string, keyof WidgetTheme> = {
+    accent: "accent",
+    border: "border",
+    bg: "bg",
+    fg: "fg",
+  };
+  for (const [key, prop] of Object.entries(MAP)) {
+    const val = config[key];
+    if (val) {
+      const parsed = parseColor(val);
+      if (parsed) theme[prop] = parsed;
+    }
+  }
+  return theme;
+}