tmux-ide 2.6.0 → 2.6.1

package/packages/daemon/src/tui/integrations/offer.ts

@@ -0,0 +1,145 @@
+/**
+ * The one-time INTEGRATION OFFER — shown the first time tmux-ide adopts a
+ * session on a machine that has Claude Code but hasn't installed the lifecycle
+ * hook.
+ *
+ * The onboarding gap: the Claude Code integration turns pane state from
+ * screen-scraping guesswork into ground truth, but nothing prompts the user to
+ * install it — they'd have to read the docs. This offer notices `claude` on
+ * PATH at adopt time and asks once: install now? [y/N]. `y` installs; anything
+ * else skips. Either way a marker is written so it never asks again.
+ *
+ * "Once" is enforced by a marker file (`<home>/integration-offered`, `<home>` =
+ * `TMUX_IDE_HOME` when set — so tests and the dev box never see it), exactly
+ * like the welcome card ({@link ../chrome/welcome.ts}). The offer is ALSO gated
+ * by config (`integrations.offer`), so it can be suppressed without touching the
+ * marker. {@link shouldOfferIntegration} is the PURE decision; the marker
+ * helpers and {@link maybeOfferIntegrationPopup} wire the io. It NEVER fails an
+ * adopt — every io path is best-effort.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { getAppConfig } from "../../lib/app-config.ts";
+import { claudeIntegrationStatus } from "./claude.ts";
+
+/**
+ * Absolute path to the "already offered" marker: `<home>/integration-offered`,
+ * where `<home>` is `TMUX_IDE_HOME` when set (tests / per-run overrides), else
+ * `~/.tmux-ide`. The env override lets a live test point the marker at a scratch
+ * dir so it never touches — or is confused by — the real user's marker.
+ */
+export function integrationOfferMarkerPath(): string {
+  const home = process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+  return join(home, "integration-offered");
+}
+
+/**
+ * PURE — the first-adopt offer decision. Show the offer only when ALL hold:
+ *   - `claudeOnPath`         Claude Code is installed on this machine,
+ *   - `integrationInstalled` is false (nothing to offer if it's already hooked),
+ *   - `markerPresent`        is false (we've never offered before), and
+ *   - `offerEnabled`         config hasn't disabled the offer.
+ * Kept pure so every gate is trivially unit-tested.
+ */
+export function shouldOfferIntegration(input: {
+  claudeOnPath: boolean;
+  integrationInstalled: boolean;
+  markerPresent: boolean;
+  offerEnabled: boolean;
+}): boolean {
+  return (
+    input.claudeOnPath && !input.integrationInstalled && !input.markerPresent && input.offerEnabled
+  );
+}
+
+/**
+ * Create the marker so the offer shows only once. Best-effort — a marker we
+ * can't write means the offer may show again, but it must never crash adopt.
+ */
+export function markIntegrationOffered(): void {
+  const path = integrationOfferMarkerPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, new Date().toISOString());
+  } catch {
+    // can't write the marker — degrade to "may offer again", never throw
+  }
+}
+
+/**
+ * PURE — the offer prompt text shown inside the popup. A single question with a
+ * one-line rationale; the `[y/N]` makes the safe default (skip) obvious.
+ */
+export function buildOfferText(): string {
+  const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;
+  const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;
+  const head = (s: string) => `\x1b[1;36m${s}\x1b[0m`;
+  return [
+    head(" Claude Code detected"),
+    "",
+    " Install the tmux-ide integration for ground-truth agent status?",
+    dim(" It hooks Claude Code's lifecycle so pane state is exact, not guessed."),
+    "",
+    ` ${bold("[y]")} install    ${bold("[N]")} skip (any other key)`,
+    dim(" Asked once — press a key."),
+  ].join("\n");
+}
+
+/**
+ * io — float the one-time offer popup on the CURRENT tmux client, best-effort.
+ *
+ * Called at the end of {@link ../chrome/statusline.ts adoptSession} (right after
+ * the welcome card). Gated by {@link shouldOfferIntegration} (PATH + integration
+ * status + marker + config) AND by being inside a tmux client — outside tmux
+ * there's nowhere to float the popup, so we neither show it nor burn the marker
+ * (the next in-tmux adopt still offers).
+ *
+ * The popup runs `tmux-ide integration offer`, which reads one key and installs
+ * on `y` (see bin/cli.ts). It's spawned DETACHED and unref'd so it never blocks
+ * the adopt. The marker is written immediately after the spawn attempt so a
+ * rapid `adopt --all` offers exactly once, not once per session — matching the
+ * welcome card's one-shot discipline.
+ */
+export function maybeOfferIntegrationPopup(): void {
+  let offer: boolean;
+  try {
+    const status = claudeIntegrationStatus();
+    offer = shouldOfferIntegration({
+      claudeOnPath: claudeOnPath(),
+      integrationInstalled: status.installed,
+      markerPresent: existsSync(integrationOfferMarkerPath()),
+      offerEnabled: getAppConfig().integrations.offer,
+    });
+  } catch {
+    return; // any probe failure → never risk the adopt, just don't offer
+  }
+  if (!offer) return;
+  if (!process.env.TMUX) return;
+  try {
+    const child = spawn(
+      "tmux",
+      ["display-popup", "-E", "-w", "64", "-h", "12", "tmux-ide integration offer"],
+      { stdio: "ignore", detached: true },
+    );
+    child.unref();
+  } catch {
+    // tmux missing / no client — best-effort, still mark so we don't retry forever
+  }
+  markIntegrationOffered();
+}
+
+/**
+ * io — is `claude` on PATH? A which-probe capped at 2s, swallowing every failure
+ * to false. Local (not {@link ../../lib/agent-discovery.ts}) to keep the adopt
+ * path's offer check a single cheap probe rather than the full agent sweep.
+ */
+function claudeOnPath(): boolean {
+  try {
+    execFileSync("which", ["claude"], { stdio: "ignore", timeout: 2000 });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/packages/daemon/src/tui/main.ts

@@ -0,0 +1,70 @@
+/**
+ * Dispatcher entry for the compiled `tmux-ide-tui` binary.
+ *
+ * `bun build --compile` bundles every TUI surface (the cockpit + widgets) into
+ * ONE standalone executable so the OpenTUI/Solid `.tsx` surfaces run on a clean
+ * `npm i -g tmux-ide` — no dev checkout, no `bun` runtime, no bunfig preload.
+ * The native OpenTUI dylib rides along via Bun's embedded-asset mechanism (the
+ * `import ... with { type: "file" }` in @opentui/core-*), and the Solid JSX
+ * transform happens at build time via the @opentui/solid bun plugin, so the
+ * binary carries only plain JS.
+ *
+ * Contract: `tmux-ide-tui <surface> [--flags…]`. The first positional selects
+ * the surface; the rest are the surface's own args (theme, session, dir, …),
+ * exactly as the `bun <entry> …` invocation passed them. We strip the surface
+ * token from `process.argv` before importing so each entry's top-level
+ * `parseArgs()` sees the same argv it always has.
+ *
+ * The `import()` calls use LITERAL specifiers on purpose: Bun's bundler only
+ * embeds dynamic imports it can resolve statically, and a literal switch keeps
+ * exactly one surface's top-level `render()` side effect from firing.
+ */
+
+const SURFACES = ["team", "explorer", "changes", "preview", "config", "setup", "sidebar"] as const;
+
+type Surface = (typeof SURFACES)[number];
+
+function isSurface(value: string | undefined): value is Surface {
+  return value !== undefined && (SURFACES as readonly string[]).includes(value);
+}
+
+async function main(): Promise<void> {
+  const surface = process.argv[2];
+
+  if (!isSurface(surface)) {
+    process.stderr.write(
+      `tmux-ide-tui: unknown surface ${surface ? `"${surface}"` : "(none given)"}.\n` +
+        `Usage: tmux-ide-tui <${SURFACES.join("|")}> [flags]\n`,
+    );
+    process.exit(2);
+  }
+
+  // Drop the surface token so each entry's `parseArgs()` sees only its flags.
+  process.argv.splice(2, 1);
+
+  switch (surface) {
+    case "team":
+      await import("./team/index.tsx");
+      break;
+    case "explorer":
+      await import("../widgets/explorer/index.tsx");
+      break;
+    case "changes":
+      await import("../widgets/changes/index.tsx");
+      break;
+    case "preview":
+      await import("../widgets/preview/index.tsx");
+      break;
+    case "config":
+      await import("../widgets/config/index.tsx");
+      break;
+    case "setup":
+      await import("../widgets/setup/index.tsx");
+      break;
+    case "sidebar":
+      await import("../widgets/sidebar/index.tsx");
+      break;
+  }
+}
+
+void main();

package/packages/daemon/src/tui/mirror/control-client.ts

@@ -0,0 +1,143 @@
+/**
+ * A tmux control-mode client.
+ *
+ * Spawns `tmux -C attach -t <target>` and speaks the control protocol over
+ * stdio: commands written to stdin get their replies back wrapped in
+ * `%begin`/`%end` blocks (FIFO order), while live pane bytes stream in as
+ * `%output` notifications between blocks. This is the same integration
+ * surface iTerm2 uses for its native tmux mode — tmux stays the multiplexer
+ * and persistence layer; the caller renders.
+ *
+ * stdout is read as latin1 (one JS char per byte) so pane bytes survive
+ * intact; `parseControlLine`/`decodeControlBytes` do the pure protocol work.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { parseControlLine, textToHexKeys } from "./control.ts";
+
+interface PendingReply {
+  resolve: (lines: string[]) => void;
+  reject: (err: Error) => void;
+  lines: string[];
+}
+
+export interface ControlClientOptions {
+  /** Session (or other tmux target) to attach the control client to. */
+  attachTarget: string;
+  /** Live pane bytes: `%output` events, decoded. */
+  onOutput?: (pane: string, data: Uint8Array) => void;
+  /** Non-output notifications (layout-change, window-add, …). */
+  onNotify?: (name: string, rest: string) => void;
+  /** Control client ended (tmux exited or detached us). */
+  onExit?: (reason: string | null) => void;
+}
+
+export class ControlModeClient {
+  private proc: ChildProcess | null = null;
+  private readonly pending: PendingReply[] = [];
+  private inReply = false;
+  private buffer = "";
+  private readonly opts: ControlClientOptions;
+
+  constructor(opts: ControlClientOptions) {
+    this.opts = opts;
+  }
+
+  /** Spawn the control client and resolve once tmux's greeting block passed. */
+  start(): Promise<void> {
+    const proc = spawn("tmux", ["-C", "attach", "-t", this.opts.attachTarget], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, TMUX: "" },
+    });
+    this.proc = proc;
+    proc.stdout!.setEncoding("latin1");
+    proc.stdout!.on("data", (chunk: string) => this.feed(chunk));
+    proc.on("exit", () => this.opts.onExit?.(null));
+
+    // tmux opens the conversation with an unsolicited %begin/%end greeting
+    // block; queue a resolver for it so `start()` settles when the protocol
+    // is actually live (and so the pending queue stays aligned).
+    return new Promise((resolve, reject) => {
+      this.pending.push({ resolve: () => resolve(), reject, lines: [] });
+      proc.on("error", reject);
+    });
+  }
+
+  /** Run a tmux command over the control channel, resolving its reply body. */
+  command(cmd: string): Promise<string[]> {
+    const proc = this.proc;
+    if (!proc?.stdin?.writable) return Promise.reject(new Error("control client not running"));
+    return new Promise((resolve, reject) => {
+      this.pending.push({ resolve, reject, lines: [] });
+      proc.stdin!.write(`${cmd}\n`);
+    });
+  }
+
+  /** Type literal text into a pane (UTF-8, sent as hex bytes — quote-proof). */
+  sendText(pane: string, text: string): Promise<string[]> {
+    return this.command(`send-keys -t ${pane} -H ${textToHexKeys(text).join(" ")}`);
+  }
+
+  /** Send a named tmux key (Enter, Escape, Up, C-c, …) to a pane. */
+  sendKey(pane: string, key: string): Promise<string[]> {
+    return this.command(`send-keys -t ${pane} ${key}`);
+  }
+
+  dispose(): void {
+    const proc = this.proc;
+    this.proc = null;
+    if (!proc) return;
+    try {
+      proc.stdin?.write("detach-client\n");
+    } catch {
+      // already gone
+    }
+    setTimeout(() => {
+      if (proc.exitCode === null) proc.kill();
+    }, 250).unref?.();
+  }
+
+  private feed(chunk: string): void {
+    this.buffer += chunk;
+    let nl: number;
+    while ((nl = this.buffer.indexOf("\n")) !== -1) {
+      // tmux terminates lines with \r\n in control mode; strip both.
+      let line = this.buffer.slice(0, nl);
+      if (line.endsWith("\r")) line = line.slice(0, -1);
+      this.buffer = this.buffer.slice(nl + 1);
+      this.handleLine(line);
+    }
+  }
+
+  private handleLine(line: string): void {
+    const event = parseControlLine(line, this.inReply);
+    switch (event.kind) {
+      case "begin":
+        this.inReply = true;
+        break;
+      case "reply-line":
+        this.pending[0]?.lines.push(event.line);
+        break;
+      case "end":
+      case "error": {
+        this.inReply = false;
+        const reply = this.pending.shift();
+        if (!reply) break; // unsolicited block (e.g. greeting after a race)
+        if (event.kind === "error") {
+          reply.reject(new Error(reply.lines.join("\n") || "tmux command failed"));
+        } else {
+          reply.resolve(reply.lines);
+        }
+        break;
+      }
+      case "output":
+        this.opts.onOutput?.(event.pane, event.data);
+        break;
+      case "exit":
+        this.opts.onExit?.(event.reason);
+        break;
+      case "notify":
+        this.opts.onNotify?.(event.name, event.rest);
+        break;
+    }
+  }
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Pure parsing for tmux control mode (`tmux -C`).
+ *
+ * In control mode tmux writes newline-terminated event lines: command replies
+ * arrive wrapped in `%begin`/`%end` (or `%error`) blocks, and asynchronous
+ * notifications (`%output`, `%layout-change`, `%exit`, …) arrive between
+ * blocks. Pane output bytes in `%output` are escaped — every C0 control byte
+ * and the backslash itself appear as three-digit octal escapes (`\015`,
+ * `\033`, `\134`) — so the decoder here resolves those back to raw BYTES.
+ *
+ * Everything in this module is pure so the protocol handling can be
+ * unit-tested without a live tmux. The client reads tmux's stdout with
+ * latin1 encoding (one JS char per byte); `decodeControlBytes` returns a
+ * Uint8Array that xterm's `write()` interprets as UTF-8, which keeps
+ * multi-byte characters intact end to end.
+ */
+
+export type ControlEvent =
+  | { kind: "begin"; num: number }
+  | { kind: "end"; num: number }
+  | { kind: "error"; num: number }
+  | { kind: "output"; pane: string; data: Uint8Array }
+  | { kind: "exit"; reason: string | null }
+  | { kind: "notify"; name: string; rest: string }
+  | { kind: "reply-line"; line: string };
+
+/** Decode a latin1 control-mode payload (with \ooo escapes) into raw bytes. */
+export function decodeControlBytes(escaped: string): Uint8Array {
+  const out = new Uint8Array(escaped.length);
+  let n = 0;
+  for (let i = 0; i < escaped.length; i++) {
+    const ch = escaped.charCodeAt(i);
+    if (
+      ch === 0x5c && // backslash
+      i + 3 < escaped.length + 1 &&
+      isOctal(escaped.charCodeAt(i + 1)) &&
+      isOctal(escaped.charCodeAt(i + 2)) &&
+      isOctal(escaped.charCodeAt(i + 3))
+    ) {
+      out[n++] = parseInt(escaped.slice(i + 1, i + 4), 8) & 0xff;
+      i += 3;
+    } else {
+      out[n++] = ch & 0xff;
+    }
+  }
+  return out.subarray(0, n);
+}
+
+function isOctal(code: number | undefined): boolean {
+  return code !== undefined && code >= 0x30 && code <= 0x37; // '0'..'7'
+}
+
+/**
+ * Parse one control-mode line into an event.
+ *
+ * `insideReply` matters because reply-block bodies are arbitrary command
+ * output — a line starting with `%` inside a block is still body text unless
+ * it's the block terminator itself.
+ */
+export function parseControlLine(line: string, insideReply: boolean): ControlEvent {
+  if (line.startsWith("%end ") || line.startsWith("%error ")) {
+    const isError = line.startsWith("%error ");
+    const num = Number(line.split(" ")[2] ?? -1);
+    return { kind: isError ? "error" : "end", num };
+  }
+  if (insideReply) return { kind: "reply-line", line };
+
+  if (line.startsWith("%begin ")) {
+    return { kind: "begin", num: Number(line.split(" ")[2] ?? -1) };
+  }
+  if (line.startsWith("%output ")) {
+    const rest = line.slice("%output ".length);
+    const space = rest.indexOf(" ");
+    const pane = space === -1 ? rest : rest.slice(0, space);
+    const payload = space === -1 ? "" : rest.slice(space + 1);
+    return { kind: "output", pane, data: decodeControlBytes(payload) };
+  }
+  if (line.startsWith("%exit")) {
+    const reason = line.length > "%exit ".length ? line.slice("%exit ".length) : null;
+    return { kind: "exit", reason };
+  }
+  if (line.startsWith("%")) {
+    const space = line.indexOf(" ");
+    const name = space === -1 ? line.slice(1) : line.slice(1, space);
+    return { kind: "notify", name, rest: space === -1 ? "" : line.slice(space + 1) };
+  }
+  // Shouldn't happen outside a reply block, but never throw on protocol noise.
+  return { kind: "reply-line", line };
+}
+
+/** Encode text as a `send-keys -H` hex-byte argv tail (UTF-8 bytes). */
+export function textToHexKeys(text: string): string[] {
+  const bytes = new TextEncoder().encode(text);
+  const hex: string[] = [];
+  for (const b of bytes) hex.push(b.toString(16).padStart(2, "0"));
+  return hex;
+}

package/packages/daemon/src/tui/mirror/pane-mirror.ts

@@ -0,0 +1,81 @@
+/**
+ * A pane mirror: a headless terminal emulator fed by tmux control-mode
+ * `%output` bytes, exposing a renderable grid snapshot.
+ *
+ * @xterm/headless is xterm.js without a DOM — a full VT parser (SGR, cursor,
+ * alt-screen, scroll regions) maintaining a cell buffer. We write raw pane
+ * bytes in and read the grid out; the TUI draws the snapshot. This is the
+ * seam between "tmux owns the PTYs" and "tmux-ide owns the pixels".
+ */
+import { Terminal } from "@xterm/headless";
+
+/** A run of same-colored text within a row. */
+export interface StyledRun {
+  text: string;
+  /** 256-palette index, or null for the default foreground. */
+  fg: number | null;
+  bold: boolean;
+}
+
+export interface MirrorSnapshot {
+  rows: StyledRun[][];
+  cursorX: number;
+  cursorY: number;
+}
+
+export class PaneMirror {
+  private readonly term: Terminal;
+  readonly cols: number;
+  readonly rows: number;
+
+  constructor(cols: number, rows: number) {
+    this.cols = cols;
+    this.rows = rows;
+    this.term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 0 });
+  }
+
+  /** Feed raw pane bytes (UTF-8) from a control-mode %output event. */
+  write(data: Uint8Array | string): void {
+    this.term.write(data);
+  }
+
+  resize(cols: number, rows: number): void {
+    this.term.resize(cols, rows);
+  }
+
+  /** Read the visible grid as rows of same-styled runs (plus the cursor). */
+  snapshot(): MirrorSnapshot {
+    const buf = this.term.buffer.active;
+    const rows: StyledRun[][] = [];
+    const cell = buf.getNullCell();
+
+    for (let y = 0; y < this.rows; y++) {
+      const line = buf.getLine(buf.viewportY + y);
+      const runs: StyledRun[] = [];
+      if (line) {
+        let text = "";
+        let fg: number | null = null;
+        let bold = false;
+        for (let x = 0; x < this.cols; x++) {
+          line.getCell(x, cell);
+          const cellFg = cell.isFgDefault() ? null : cell.isFgPalette() ? cell.getFgColor() : null;
+          const cellBold = cell.isBold() !== 0;
+          if (x > 0 && (cellFg !== fg || cellBold !== bold) && text.length > 0) {
+            runs.push({ text, fg, bold });
+            text = "";
+          }
+          fg = cellFg;
+          bold = cellBold;
+          text += cell.getChars() || " ";
+        }
+        if (text.length > 0) runs.push({ text, fg, bold });
+      }
+      rows.push(runs);
+    }
+    return { rows, cursorX: buf.cursorX, cursorY: buf.cursorY };
+  }
+
+  dispose(): void {
+    this.term.dispose();
+  }
+}