tmux-ide 2.6.1 → 2.8.0

package/packages/daemon/src/tui/mirror/host-terminal.ts

@@ -0,0 +1,49 @@
+/**
+ * Host-terminal modes owned by the unified app.
+ *
+ * OpenTUI renders each changed row as ANSI runs. With DECAWM (host autowrap)
+ * enabled, a wide/right-edge run can physically wrap into column 1 of the next
+ * row while OpenTUI's shadow records the intended cells. That strands pane text
+ * over the left sidebar until an outer full repaint. The app never relies on
+ * host autowrap—it positions runs absolutely—so disable it for the app's
+ * lifetime and restore it exactly once on every exit path.
+ */
+
+export const HOST_AUTOWRAP_DISABLE = "\x1b[?7l";
+export const HOST_AUTOWRAP_ENABLE = "\x1b[?7h";
+
+export interface HostTerminalExitLifecycle {
+  onExit(listener: () => void): void;
+  offExit(listener: () => void): void;
+}
+
+export interface HostAutowrapGuard {
+  restore(): void;
+}
+
+/**
+ * Disable host autowrap immediately and arm an exit fallback. `restore` is
+ * idempotent and removes the fallback before writing the enable sequence, so a
+ * normal renderer teardown followed by process exit cannot double-write it.
+ *
+ * The caller supplies a synchronous writer: process `exit` listeners cannot
+ * rely on queued/asynchronous stdout writes being flushed.
+ */
+export function installHostAutowrapGuard(
+  write: (sequence: string) => void,
+  lifecycle: HostTerminalExitLifecycle,
+): HostAutowrapGuard {
+  let restored = false;
+
+  const restore = () => {
+    if (restored) return;
+    restored = true;
+    lifecycle.offExit(restore);
+    write(HOST_AUTOWRAP_ENABLE);
+  };
+
+  write(HOST_AUTOWRAP_DISABLE);
+  lifecycle.onExit(restore);
+
+  return { restore };
+}

package/packages/daemon/src/tui/mirror/hosted.ts

@@ -0,0 +1,205 @@
+/**
+ * The detachable cockpit (M23.2) — tmux keeps the app itself alive.
+ *
+ * `tmux-ide app --detachable` (alias `--hosted`) doesn't run the app in the
+ * invoking terminal: it ensures an internal `_tmux-ide-app` session exists
+ * running the app full-screen, then attaches the terminal to it. ^q under
+ * hosting DETACHES the client (the app keeps running); re-invocation from any
+ * terminal — including a phone over ssh — reattaches the SAME cockpit with
+ * scroll positions, dialogs, and workspace context intact.
+ *
+ * These are the PURE pieces of that contract: the entry decision, the tmux
+ * argv builders, and the shell quoting for the host pane's command line. The
+ * io (spawning tmux, resolving bun vs the compiled binary) stays in the CLI;
+ * the app side only reads {@link HOSTED_ENV} to flip ^q from quit to detach.
+ */
+
+/** The internal host session. `_`-prefixed so every fleet surface (team --json,
+ *  sidebar, home) and the snapshot/restore path already filter it out. */
+export const APP_HOST_SESSION = "_tmux-ide-app";
+
+/** The env marker the launcher sets on the hosted app process. The app flips
+ *  ^q from "quit" to "detach the client" when it sees `=1`; the CLI treats it
+ *  as a recursion guard (a hosted app never re-hosts). */
+export const HOSTED_ENV = "TMUX_IDE_HOSTED";
+
+/** Everything the entry decision reads — flags, config, and the guard. */
+export interface HostedEntryInput {
+  /** `--detachable` (the primary flag). */
+  flagDetachable: boolean;
+  /** `--hosted` (the alias). */
+  flagHosted: boolean;
+  /** `app.detachable` from the typed config — makes bare `tmux-ide app` (and
+   *  the frontDoor entry) hosted without the flag. */
+  configDetachable: boolean;
+  /** Whether WE are already the hosted app ({@link HOSTED_ENV} set). */
+  hostedEnv: boolean;
+}
+
+/**
+ * PURE — should this `tmux-ide app` invocation run hosted? Flags and config
+ * both opt in; the env marker vetoes everything (the app inside the host
+ * session must launch plain, or it would try to attach to itself).
+ */
+export function wantsHostedApp(input: HostedEntryInput): boolean {
+  if (input.hostedEnv) return false;
+  return input.flagDetachable || input.flagHosted || input.configDetachable;
+}
+
+/**
+ * PURE — POSIX single-quote a word for a tmux `new-session` shell command
+ * (tmux hands the string to `sh -c`). Single quotes pass everything literally;
+ * an embedded `'` closes, escapes, and reopens.
+ */
+export function shellQuote(word: string): string {
+  return `'${word.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * PURE — the env vars the host pane's app process needs, assembled for the
+ * command line rather than tmux's session environment: the tmux server may
+ * have been started elsewhere with a different environment, so nothing can be
+ * assumed to inherit. PATH rides along for the same reason (the `bun` launch
+ * mode resolves the binary by name).
+ */
+export function hostedEnvVars(base: {
+  /** The user's real invocation dir (in-app prompts default here). */
+  cwd: string;
+  /** The node-runnable CLI path (`TMUX_IDE_CLI`) for in-app subprocesses. */
+  cli: string;
+  /** The invoking shell's PATH. */
+  path?: string;
+  /** `TMUX_IDE_HOME` / `TMUX_IDE_CONFIG` / `TMUX_IDE_TUI_BIN` pass-throughs
+   *  (set in test rigs; must reach the hosted app or it reads real state). */
+  home?: string;
+  config?: string;
+  tuiBin?: string;
+}): Record<string, string> {
+  const env: Record<string, string> = {
+    [HOSTED_ENV]: "1",
+    TMUX_IDE_CWD: base.cwd,
+    TMUX_IDE_CLI: base.cli,
+  };
+  if (base.path) env.PATH = base.path;
+  if (base.home) env.TMUX_IDE_HOME = base.home;
+  if (base.config) env.TMUX_IDE_CONFIG = base.config;
+  if (base.tuiBin) env.TMUX_IDE_TUI_BIN = base.tuiBin;
+  return env;
+}
+
+/**
+ * PURE — the shell command the host pane runs: `exec env K=V… bin args…`,
+ * every value quoted. `exec` replaces the pane's shell with the app so a quit
+ * (the palette verb) ends the pane — and with it the single-window session.
+ */
+export function hostedCommandLine(
+  bin: string,
+  argv: readonly string[],
+  env: Record<string, string>,
+): string {
+  const assigns = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`);
+  return ["exec", "env", ...assigns, shellQuote(bin), ...argv.map(shellQuote)].join(" ");
+}
+
+/** PURE — exact-match existence probe (`=` prefix: `has-session -t` would
+ *  otherwise PREFIX-match, e.g. a user session named `_tmux-ide-app-notes`). */
+export function hostExistsArgv(): string[] {
+  return ["has-session", "-t", `=${APP_HOST_SESSION}`];
+}
+
+/** PURE — create the detached host session running the app command line. */
+export function hostCreateArgv(opts: { cwd: string; commandLine: string }): string[] {
+  return ["new-session", "-d", "-s", APP_HOST_SESSION, "-c", opts.cwd, opts.commandLine];
+}
+
+/**
+ * The client events that re-assert `window-size latest` on the host (M25.5).
+ * Each hook's effect was MEASURED on tmux 3.7b in an isolated two-client rig
+ * (220x60 local + 120x40 ssh-sim):
+ *
+ * - `client-attached` / `client-focus-in` / `client-session-changed`: tmux
+ *   3.7b already re-adopts the event client's size natively on all of these
+ *   (attach ~8ms, focus-in ~17ms, switch-client ~17ms — window-resized hook
+ *   timestamps; detach of the latest client also re-adopts natively, ~13ms).
+ *   The hooks are NOT what makes those paths work; they are the SELF-HEAL for
+ *   the one measured way the host gets permanently stuck: any `resize-window`
+ *   against it (a stray tool or user command) flips `window-size` to manual —
+ *   after which NO client event re-adopts, ever (measured: a fresh 220x60
+ *   attach left a manually-80x24 host at 80x24). Re-asserting the option is
+ *   the heal (measured: instant re-adopt) — and it is safe to fire
+ *   redundantly: setting `window-size latest` when it is already latest just
+ *   recomputes the same size. Fire counts are bounded and linear (measured:
+ *   10 rapid focus alternations → exactly 20 focus-in fires; 10 attach cycles
+ *   → 10 attached + 10 session-changed fires — attach fires both — each a
+ *   single in-server set-option, no storm).
+ *
+ * NO `client-detached` hook: measured on 3.7b it never fires as a SESSION
+ * hook (the detaching client has already left the session when hooks are
+ * resolved — 0 fires across 10 detach cycles while the same rig's global
+ * hook logged every one), and the native detach re-adopt covers the path.
+ *
+ * Deliberately NOT `resize-window -a`: per the tmux manual, EVERY
+ * resize-window form — -a included — "will automatically set window-size to
+ * manual", i.e. it would cause the exact stuck state it is meant to fix. And
+ * no `run-shell`: these are tmux-native commands executed in-server
+ * (run-shell hooks serialize the server — prior measurement).
+ */
+export const HOST_RESIZE_HOOKS = [
+  "client-attached",
+  "client-focus-in",
+  "client-session-changed",
+] as const;
+
+/**
+ * PURE — the post-create/ensure session setup: status OFF so the app owns
+ * every row (under `status on` the host steals the bottom row and the app
+ * renders one short), and `window-size latest` pinned explicitly so the most
+ * recently active client dictates the size — a smaller second client
+ * letterboxes the larger one (tmux's own dot-fill), which is the documented
+ * behavior.
+ *
+ * M25.5 additions (each measured on 3.7b — see {@link HOST_RESIZE_HOOKS}):
+ *
+ * - `focus-events on` (server option — the ONE non-session-scoped line, and
+ *   the load-bearing one): it defaults OFF, so real terminals are never asked
+ *   for focus reporting and `client-focus-in` never fires. With it on, coming
+ *   BACK to a terminal that stayed attached re-adopts that client's size on
+ *   the focus event alone (measured: focus-in → client-active →
+ *   window-resized in ~17ms) — no keystroke needed. This is the user's exact
+ *   "reopen it on my computer locally" moment when the local client never
+ *   detached. Side effect is the widely-recommended one (panes that request
+ *   focus, e.g. editors, start receiving it).
+ * - the {@link HOST_RESIZE_HOOKS} self-heal hooks, session-scoped to the host
+ *   (zero effect on user sessions).
+ *
+ * The whole list is idempotent — the CLI applies it on EVERY ensure, not just
+ * create, so upgrading tmux-ide fixes an already-running cockpit on its next
+ * `tmux-ide app` (and un-sticks a manually-resized host).
+ *
+ * No `=` exact-match prefix here: tmux (measured on 3.7b) rejects it on
+ * `set-option` session targets ("no such session") even though has-session
+ * and attach accept it. Plain names are safe in THIS builder only because
+ * setup runs right after the exists-probe/create — the exact session exists,
+ * and tmux prefers an exact match over a prefix match when one does.
+ */
+export function hostSetupArgvs(): string[][] {
+  const heal = `set-option -w -t ${APP_HOST_SESSION}: window-size latest`;
+  return [
+    ["set-option", "-t", APP_HOST_SESSION, "status", "off"],
+    ["set-option", "-w", "-t", `${APP_HOST_SESSION}:`, "window-size", "latest"],
+    ["set-option", "-s", "focus-events", "on"],
+    ...HOST_RESIZE_HOOKS.map((hook) => ["set-hook", "-t", APP_HOST_SESSION, hook, heal]),
+  ];
+}
+
+/**
+ * PURE — how the invoking terminal reaches the cockpit: inside tmux the
+ * client is already attached to a server, so `switch-client` moves it (a
+ * nested `attach` would complain and double-render); a plain terminal
+ * attaches. Both exact-match the host name.
+ */
+export function hostAttachArgv(insideTmux: boolean): string[] {
+  return insideTmux
+    ? ["switch-client", "-t", `=${APP_HOST_SESSION}`]
+    : ["attach-session", "-t", `=${APP_HOST_SESSION}`];
+}

package/packages/daemon/src/tui/mirror/input-coalescer.ts

@@ -0,0 +1,105 @@
+/**
+ * InputCoalescer — the pure core of the input fast path (M21.5).
+ *
+ * Burst-typed LITERAL characters coalesce into one buffered run per pane and
+ * leave as a single `send-keys -H <hex…>` write per flush; named/ctrl keys
+ * (Enter, C-c, Up, …) are emitted immediately. THE ordering invariant: any
+ * buffered literal run flushes BEFORE a named key — or a literal for a
+ * DIFFERENT pane — is emitted, so bytes reach the pane in exactly the order
+ * the user produced them.
+ *
+ * Pure core, io shell: this class owns no timers and does no io. The caller
+ * injects `emit` (where flushed actions go — the control client's
+ * fire-and-forget write in production) and `schedule` (when a pending literal
+ * buffer should auto-flush — a microtask in production, a hand-cranked stub in
+ * tests). A microtask flush still happens inside the same macrotask that
+ * buffered the keystroke — strictly before the process can read more input —
+ * so coalescing adds no perceivable latency; it only merges keystrokes that
+ * arrived together.
+ *
+ * Flushes re-chunk the buffered run under {@link SEND_KEYS_CHUNK_BYTES} so a
+ * large paste routed through the same path never produces an oversized
+ * control-mode command.
+ */
+import { chunkByBytes } from "./selection.ts";
+
+/**
+ * Max UTF-8 payload bytes per `send-keys -H` write. Every byte travels as its
+ * own `xx` argv token, and each token hits tmux's yacc command parser — which
+ * is the REAL constraint, measured empirically against tmux 3.6b control mode
+ * (M21.5), not a line-length cap:
+ *
+ *   - HARD LIMIT: a 16 KB payload (≈16k tokens) is REJECTED outright with
+ *     `%error: yacc stack overflow` (yacc's ~10k-entry stack).
+ *   - PARSE COST is superlinear in tokens: one command's reply takes ~3 ms at
+ *     1 KB, ~9 ms at 2 KB, ~56 ms at 4 KB, ~170 ms at 8 KB — big chunks STALL
+ *     the tmux server (and every interleaved keystroke behind it).
+ *   - END-TO-END, a 100 KB paste lands byte-perfect in ~246/155/180/233/255/
+ *     561/1483 ms at 64/128/256/512/1024/2048/4096-byte chunks — the optimum
+ *     is ~128–256 B; the pre-M21.5 1024 was past the knee, and RAISING the
+ *     chunk (the naive read of "fewer commands = faster") is strictly worse.
+ *
+ * 256 B is chosen: within noise of the throughput optimum, ~1 ms of server
+ * parse per command (imperceptible for input interleaving), 5× headroom from
+ * nothing, and 40× from the yacc cliff.
+ */
+export const SEND_KEYS_CHUNK_BYTES = 256;
+
+/** One flushed input action, ready to become a control-mode write. */
+export type InputAction =
+  | { kind: "literal"; pane: string; text: string }
+  | { kind: "key"; pane: string; key: string };
+
+export class InputCoalescer {
+  private pane = "";
+  private buf = "";
+  private scheduled = false;
+
+  constructor(
+    private readonly emit: (action: InputAction) => void,
+    private readonly schedule: (flush: () => void) => void,
+    private readonly maxChunkBytes: number = SEND_KEYS_CHUNK_BYTES,
+  ) {}
+
+  /** Buffer literal text for `pane`; a pending run for ANOTHER pane flushes
+   *  first so cross-pane order is preserved. Schedules an auto-flush once per
+   *  pending run. */
+  literal(pane: string, text: string): void {
+    if (!pane || !text) return;
+    if (this.buf.length > 0 && this.pane !== pane) this.flush();
+    this.pane = pane;
+    this.buf += text;
+    if (!this.scheduled) {
+      this.scheduled = true;
+      this.schedule(() => {
+        this.scheduled = false;
+        this.flush();
+      });
+    }
+  }
+
+  /** Emit a named tmux key (Enter, C-c, Up, …) — pending literals flush first
+   *  (synchronously) so the key can never overtake buffered characters. */
+  key(pane: string, key: string): void {
+    if (!pane || !key) return;
+    this.flush();
+    this.emit({ kind: "key", pane, key });
+  }
+
+  /** Drain the pending literal run now (chunked under the byte cap). Also the
+   *  ordering barrier callers place before reply-matched structural commands. */
+  flush(): void {
+    if (this.buf.length === 0) return;
+    const pane = this.pane;
+    const text = this.buf;
+    this.buf = "";
+    for (const chunk of chunkByBytes(text, this.maxChunkBytes)) {
+      this.emit({ kind: "literal", pane, text: chunk });
+    }
+  }
+
+  /** Buffered-but-unflushed character count (tests/introspection only). */
+  pending(): number {
+    return this.buf.length;
+  }
+}

package/packages/daemon/src/tui/mirror/layout-parse.ts

@@ -0,0 +1,154 @@
+/**
+ * PURE — tmux layout-string and control-notification parsing (M23.5).
+ *
+ * `%layout-change` arrives sub-millisecond after the server applies a layout
+ * and ALWAYS precedes the first new-size `%output` (measured on tmux 3.7b:
+ * the follow-up output can trail by as little as 0.2ms). The mirror therefore
+ * derives pane geometry from the notification PAYLOAD itself instead of a
+ * debounced `list-panes` round-trip — these parsers are that push path.
+ *
+ * The layout grammar mirrors tmux's `layout_parse.c`: a 4-hex-digit checksum,
+ * a comma, then a cell. A cell is `WxH,X,Y` followed by either `,<paneId>`
+ * (a leaf; the numeric pane id sans `%`), `{…}` (horizontal split) or `[…]`
+ * (vertical split) with comma-separated child cells. The ROOT cell's WxH is
+ * the authoritative window size. Parse the VISIBLE layout — the THIRD field
+ * of `%layout-change @win <layout> <visible-layout> <flags>` — because zoom
+ * collapses it to the single zoomed pane (`*Z` in flags = zoomed); the second
+ * field keeps reporting the saved multi-pane layout.
+ *
+ * Everything here is unit-tested against layout strings captured from a real
+ * tmux 3.7b server (splits, zoom, storms) — no tmux at test time.
+ */
+
+/** One visible pane rectangle, in window cells. `id` is `%`-prefixed. */
+export interface LayoutLeaf {
+  id: string;
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** A parsed (visible) layout: the window size + the leaves in layout order. */
+export interface ParsedLayout {
+  /** The root cell's WxH — the authoritative window size. */
+  width: number;
+  height: number;
+  leaves: LayoutLeaf[];
+}
+
+/** Parse a tmux layout string (`csum,WxH,X,Y…`). Null on any malformed input
+ *  (the caller falls back to the slow list-panes path — never throw here). */
+export function parseLayout(layout: string): ParsedLayout | null {
+  if (!/^[0-9a-fA-F]{4},/.test(layout)) return null;
+  const s = layout.slice(5);
+  const leaves: LayoutLeaf[] = [];
+  const root = parseCell(s, 0, leaves);
+  if (!root || root.pos !== s.length) return null;
+  return { width: root.width, height: root.height, leaves };
+}
+
+/** Recursive-descent cell parse from `pos`; appends leaves in layout order. */
+function parseCell(
+  s: string,
+  pos: number,
+  leaves: LayoutLeaf[],
+): { width: number; height: number; pos: number } | null {
+  const dims = readDims(s, pos);
+  if (!dims) return null;
+  const { width, height, left, top } = dims;
+  pos = dims.pos;
+  const ch = s[pos];
+  if (ch === ",") {
+    // Leaf: the numeric pane id.
+    const id = readInt(s, pos + 1);
+    if (!id) return null;
+    leaves.push({ id: `%${id.value}`, left, top, width, height });
+    return { width, height, pos: id.pos };
+  }
+  if (ch === "{" || ch === "[") {
+    const close = ch === "{" ? "}" : "]";
+    pos++;
+    for (;;) {
+      const child = parseCell(s, pos, leaves);
+      if (!child) return null;
+      pos = child.pos;
+      if (s[pos] === ",") {
+        pos++;
+        continue;
+      }
+      if (s[pos] === close) return { width, height, pos: pos + 1 };
+      return null;
+    }
+  }
+  // A bare root leaf ends the string (`…,0,0,445`): ch is undefined only when
+  // the leaf id was consumed above, so anything else here is malformed.
+  return null;
+}
+
+/** Read `WxH,X,Y` at `pos`. */
+function readDims(
+  s: string,
+  pos: number,
+): { width: number; height: number; left: number; top: number; pos: number } | null {
+  const w = readInt(s, pos);
+  if (!w || s[w.pos] !== "x") return null;
+  const h = readInt(s, w.pos + 1);
+  if (!h || s[h.pos] !== ",") return null;
+  const x = readInt(s, h.pos + 1);
+  if (!x || s[x.pos] !== ",") return null;
+  const y = readInt(s, x.pos + 1);
+  if (!y) return null;
+  return { width: w.value, height: h.value, left: x.value, top: y.value, pos: y.pos };
+}
+
+/** Read a decimal integer at `pos` (at least one digit). */
+function readInt(s: string, pos: number): { value: number; pos: number } | null {
+  let end = pos;
+  while (end < s.length && s.charCodeAt(end) >= 0x30 && s.charCodeAt(end) <= 0x39) end++;
+  if (end === pos) return null;
+  return { value: Number(s.slice(pos, end)), pos: end };
+}
+
+/** A parsed `%layout-change` notification body. */
+export interface LayoutChange {
+  windowId: string;
+  /** The saved (full) layout — kept for debugging; geometry uses `visible`. */
+  layout: string;
+  /** The VISIBLE layout — collapses to the single zoomed pane under zoom. */
+  visible: string;
+  /** `Z` present in the flags field (`*Z`). */
+  zoomed: boolean;
+}
+
+/** Parse the body after `%layout-change ` (tmux 3.7b:
+ *  `@387 <layout> <visible-layout> *Z`). Null when the shape is off. */
+export function parseLayoutChange(rest: string): LayoutChange | null {
+  const parts = rest.trim().split(/\s+/);
+  const [windowId = "", layout = "", visible = "", flags = ""] = parts;
+  if (parts.length < 3 || !windowId.startsWith("@")) return null;
+  return { windowId, layout, visible, zoomed: flags.includes("Z") };
+}
+
+/** Parse the body after `%window-pane-changed ` (`@387 %443`). */
+export function parseWindowPaneChanged(rest: string): { windowId: string; paneId: string } | null {
+  const [windowId = "", paneId = ""] = rest.trim().split(/\s+/);
+  if (!windowId.startsWith("@") || !paneId.startsWith("%")) return null;
+  return { windowId, paneId };
+}
+
+/** Parse the body after `%session-window-changed ` (`$353 @388`). */
+export function parseSessionWindowChanged(rest: string): { windowId: string } | null {
+  const [, windowId = ""] = rest.trim().split(/\s+/);
+  if (!windowId.startsWith("@")) return null;
+  return { windowId };
+}
+
+/** Parse the body after `%subscription-changed ` for the mirror's `mouse`
+ *  subscription (tmux 3.7b: `mouse $353 @387 0 %445 : 1`). Null for other
+ *  subscription names or an off shape. */
+export function parseMouseSubscription(rest: string): { paneId: string; on: boolean } | null {
+  const m = /^mouse\s+\$\S+\s+@\S+\s+\S+\s+(%\S+)\s*:\s*(.*)$/.exec(rest.trim());
+  if (!m) return null;
+  return { paneId: m[1]!, on: m[2]!.trim() === "1" };
+}