tmux-ide 2.6.0 → 2.7.0

package/packages/tmux-bridge/src/runner.ts

@@ -0,0 +1,91 @@
+import { execFileSync, spawn, type ExecFileSyncOptions } from "node:child_process";
+import { TmuxError } from "./errors.ts";
+
+const DEBUG = process.env.TMUX_IDE_DEBUG === "1";
+
+const SESSION_NOT_FOUND_PATTERNS = ["can't find session", "can't find window", "unknown target"];
+
+const TMUX_UNAVAILABLE_PATTERNS = [
+  "failed to connect to server",
+  "no server running",
+  "error connecting to",
+  "connection refused",
+];
+
+declare global {
+  // Toggled by the CLI's --verbose flag.
+  var __tmuxIdeVerbose: boolean | undefined;
+}
+
+type Executor = typeof execFileSync;
+type Spawner = typeof spawn;
+
+let _executor: Executor = execFileSync;
+let _spawner: Spawner = spawn;
+
+/** @internal Replace the executor for testing. Returns a restore function. */
+export function _setExecutor(fn: Executor): () => void {
+  const prev = _executor;
+  _executor = fn;
+  return () => {
+    _executor = prev;
+  };
+}
+
+/** @internal Replace the spawner for testing. Returns a restore function. */
+export function _setSpawner(fn: Spawner): () => void {
+  const prev = _spawner;
+  _spawner = fn;
+  return () => {
+    _spawner = prev;
+  };
+}
+
+/** @internal Access the spawner (used by monitor.ts to keep one mock surface). */
+export function _getSpawner(): Spawner {
+  return _spawner;
+}
+
+export function runTmux(args: string[], options: ExecFileSyncOptions = {}): string | Buffer {
+  if (DEBUG || globalThis.__tmuxIdeVerbose) {
+    console.error(`  [tmux] ${args.join(" ")}`);
+  }
+
+  const execOptions: ExecFileSyncOptions = {
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options,
+  };
+
+  try {
+    return _executor("tmux", args, execOptions);
+  } catch (error) {
+    throw classifyTmuxError(error);
+  }
+}
+
+function classifyTmuxError(error: unknown): TmuxError {
+  const detail = getErrorDetail(error).toLowerCase();
+
+  if (SESSION_NOT_FOUND_PATTERNS.some((pattern) => detail.includes(pattern))) {
+    return new TmuxError("tmux session was not found", "SESSION_NOT_FOUND", {
+      cause: error as Error,
+    });
+  }
+
+  if (TMUX_UNAVAILABLE_PATTERNS.some((pattern) => detail.includes(pattern))) {
+    return new TmuxError("tmux is unavailable or its socket is inaccessible", "TMUX_UNAVAILABLE", {
+      cause: error as Error,
+    });
+  }
+
+  return new TmuxError("tmux command failed", "TMUX_ERROR", {
+    cause: error as Error,
+  });
+}
+
+function getErrorDetail(error: unknown): string {
+  const stderr = (error as { stderr?: string | Buffer })?.stderr;
+  if (typeof stderr === "string" && stderr.length > 0) return stderr;
+  if (Buffer.isBuffer(stderr) && stderr.length > 0) return stderr.toString("utf-8");
+  return (error as Error)?.message ?? "";
+}

package/packages/tmux-bridge/src/sessions.ts

@@ -0,0 +1,126 @@
+import type { SessionState } from "@tmux-ide/contracts";
+import { TmuxError } from "./errors.ts";
+import { runTmux } from "./runner.ts";
+
+export function getSessionState(session: string): SessionState {
+  try {
+    runTmux(["has-session", "-t", session]);
+    return { running: true, reason: null };
+  } catch (error) {
+    if (error instanceof TmuxError) {
+      if (error.code === "SESSION_NOT_FOUND") {
+        return { running: false, reason: "SESSION_NOT_FOUND" };
+      }
+      if (error.code === "TMUX_UNAVAILABLE") {
+        return { running: false, reason: "TMUX_UNAVAILABLE" };
+      }
+    }
+    throw error;
+  }
+}
+
+export function attachSession(session: string): void {
+  runTmux(["attach", "-t", session], { stdio: "inherit" });
+}
+
+export function hasSession(session: string): boolean {
+  try {
+    runTmux(["has-session", "-t", session]);
+    return true;
+  } catch (error) {
+    if (
+      error instanceof TmuxError &&
+      (error.code === "SESSION_NOT_FOUND" || error.code === "TMUX_UNAVAILABLE")
+    ) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Resolve the cwd of a tmux session by reading its first pane's
+ * `pane_current_path`. Used as a fallback when looking up a project that
+ * isn't in the registry but does have a live tmux session — e.g. when
+ * the user opens the dashboard against tmux sessions they spawned by
+ * other means. Returns null if the session has no panes or tmux can't
+ * resolve the path.
+ */
+export function getSessionCwd(session: string): string | null {
+  try {
+    const raw = runTmux(["display-message", "-p", "-t", session, "#{pane_current_path}"], {
+      encoding: "utf-8",
+    }) as string;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function killSession(session: string): { stopped: boolean; reason: string | null } {
+  try {
+    runTmux(["kill-session", "-t", session]);
+    return { stopped: true, reason: null };
+  } catch (error) {
+    if (error instanceof TmuxError) {
+      if (error.code === "SESSION_NOT_FOUND") {
+        return { stopped: false, reason: "SESSION_NOT_FOUND" };
+      }
+      if (error.code === "TMUX_UNAVAILABLE") {
+        return { stopped: false, reason: "TMUX_UNAVAILABLE" };
+      }
+    }
+    throw error;
+  }
+}
+
+export function createDetachedSession(
+  session: string,
+  cwd: string,
+  { cols, lines }: { cols?: number; lines?: number } = {},
+): string {
+  return (
+    runTmux(
+      [
+        "new-session",
+        "-d",
+        "-P",
+        "-F",
+        "#{pane_id}",
+        "-s",
+        session,
+        "-c",
+        cwd,
+        "-x",
+        String(cols ?? 200),
+        "-y",
+        String(lines ?? 50),
+      ],
+      { encoding: "utf-8" },
+    ) as string
+  ).trim();
+}
+
+export function setSessionEnvironment(session: string, key: string, value: string | number): void {
+  runTmux(["set-environment", "-t", session, key, String(value)]);
+}
+
+export function getSessionVariable(session: string, name: string): string | null {
+  try {
+    const raw = runTmux(["show-option", "-qvt", session, name], {
+      encoding: "utf-8",
+    }) as string;
+    return raw.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function setSessionVariable(session: string, name: string, value: string): void {
+  runTmux(["set-option", "-t", session, name, value]);
+}
+
+export function runSessionCommand(args: string[]): void {
+  runTmux(args, { stdio: "inherit" });
+}

package/packages/tmux-bridge/src/targeting.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "bun:test";
+import { resolveTarget, type TmuxPaneTarget } from "./targeting.ts";
+import type { TmuxPaneInfo } from "./panes.ts";
+
+const PANES: TmuxPaneInfo[] = [
+  { index: 0, title: "Lead", width: 80, height: 24, active: true },
+  { index: 1, title: "Reviewer", width: 80, height: 24, active: false },
+  { index: 2, title: "Reviewer", width: 80, height: 24, active: false },
+  { index: 3, title: "Shell", width: 80, height: 24, active: false },
+];
+
+describe("resolveTarget — byId", () => {
+  it("accepts an opaque %N tmux id and passes it through", () => {
+    const result = resolveTarget(PANES, { kind: "byId", id: "%42" }, "sess");
+    expect(result.target).toBe("%42");
+  });
+
+  it("treats bare-numeric id as a pane index", () => {
+    const result = resolveTarget(PANES, { kind: "byId", id: "1" }, "sess");
+    expect(result.target).toBe("sess.1");
+    expect(result.pane.title).toBe("Reviewer");
+  });
+
+  it("throws for non-numeric, non-%N ids", () => {
+    expect(() => resolveTarget(PANES, { kind: "byId", id: "not-a-number" }, "sess")).toThrow(
+      /Invalid pane id/,
+    );
+  });
+
+  it("throws when bare-numeric id doesn't match any pane", () => {
+    expect(() => resolveTarget(PANES, { kind: "byId", id: "99" }, "sess")).toThrow(/not found/i);
+  });
+});
+
+describe("resolveTarget — byIndex", () => {
+  it("resolves by exact index match", () => {
+    const result = resolveTarget(PANES, { kind: "byIndex", index: 3 }, "sess");
+    expect(result.target).toBe("sess.3");
+    expect(result.pane.title).toBe("Shell");
+  });
+
+  it("throws when index is missing", () => {
+    expect(() => resolveTarget(PANES, { kind: "byIndex", index: 99 }, "sess")).toThrow(
+      /not found/i,
+    );
+  });
+
+  it("omits the session prefix when no session is supplied", () => {
+    const result = resolveTarget(PANES, { kind: "byIndex", index: 0 });
+    expect(result.target).toBe("0");
+  });
+});
+
+describe("resolveTarget — byTitle", () => {
+  it("resolves a unique title", () => {
+    const result = resolveTarget(PANES, { kind: "byTitle", title: "Lead" }, "sess");
+    expect(result.target).toBe("sess.0");
+    expect(result.pane.index).toBe(0);
+  });
+
+  it("throws on ambiguous titles", () => {
+    expect(() => resolveTarget(PANES, { kind: "byTitle", title: "Reviewer" }, "sess")).toThrow(
+      /ambiguous/i,
+    );
+  });
+
+  it("throws when no pane matches", () => {
+    expect(() => resolveTarget(PANES, { kind: "byTitle", title: "Nonexistent" }, "sess")).toThrow(
+      /not found/i,
+    );
+  });
+});
+
+describe("resolveTarget — byRole", () => {
+  it("throws because byRole must be resolved by the daemon, not the bridge", () => {
+    expect(() => resolveTarget(PANES, { kind: "byRole", role: "lead" }, "sess")).toThrow(
+      /byRole.*daemon/i,
+    );
+  });
+});
+
+describe("resolveTarget — addressing-mode disambiguation", () => {
+  it("byIndex 1 and byId '1' resolve to the same pane (parity)", () => {
+    const a = resolveTarget(PANES, { kind: "byIndex", index: 1 }, "sess");
+    const b = resolveTarget(PANES, { kind: "byId", id: "1" }, "sess");
+    expect(a.target).toBe(b.target);
+    expect(a.pane.index).toBe(b.pane.index);
+  });
+
+  it("a numeric title doesn't collide with a numeric index", () => {
+    const panes: TmuxPaneInfo[] = [
+      { index: 0, title: "1", width: 80, height: 24, active: true },
+      { index: 1, title: "Lead", width: 80, height: 24, active: false },
+    ];
+    const byTitle = resolveTarget(panes, { kind: "byTitle", title: "1" }, "sess");
+    const byIndex = resolveTarget(panes, { kind: "byIndex", index: 1 }, "sess");
+    expect(byTitle.pane.index).toBe(0);
+    expect(byIndex.pane.index).toBe(1);
+  });
+
+  it("uses the first matching index when multiple panes share a title via byIndex", () => {
+    const target: TmuxPaneTarget = { kind: "byIndex", index: 2 };
+    const result = resolveTarget(PANES, target, "sess");
+    expect(result.pane.index).toBe(2);
+    expect(result.pane.title).toBe("Reviewer");
+  });
+});

package/packages/tmux-bridge/src/targeting.ts

@@ -0,0 +1,90 @@
+import type { TmuxPaneTarget } from "@tmux-ide/contracts";
+import type { TmuxPaneInfo } from "./panes.ts";
+
+export type { TmuxPaneTarget } from "@tmux-ide/contracts";
+
+export interface ResolvedPane {
+  /** tmux target string suitable for passing to `-t` */
+  target: string;
+  pane: TmuxPaneInfo;
+}
+
+/**
+ * Resolve a typed `TmuxPaneTarget` against a list of panes (typically
+ * obtained from `listPanes(session)`).
+ *
+ * Disambiguation rules — the order is important; `byId` matches against
+ * the listing's tmux-format `pane_index` field for symmetry with how the
+ * CLI passes `%N`-style ids and bare integers, but `byIndex` is preferred
+ * when the caller actually knows it's an index. `byTitle` resolves to the
+ * single matching pane and throws if there are zero or more than one.
+ *
+ * `byRole` is resolved one layer up (in the daemon, against the ide.yml
+ * role map) and translated to one of the other modes before reaching here;
+ * if a `byRole` target arrives at the bridge, that's a layering bug and
+ * we throw rather than silently no-op.
+ */
+export function resolveTarget(
+  panes: readonly TmuxPaneInfo[],
+  target: TmuxPaneTarget,
+  session?: string,
+): ResolvedPane {
+  switch (target.kind) {
+    case "byId": {
+      // Pane id may be either a tmux %N id (kept as opaque string) or a
+      // bare numeric index. We don't have the %N id in TmuxPaneInfo, so
+      // accept "%N" as opaque (caller knows the id) and fall through to
+      // index-matching for bare numerics.
+      if (target.id.startsWith("%")) {
+        // Opaque: trust the caller. We can't validate against panes[].
+        return {
+          target: target.id,
+          pane: panes[0] ?? {
+            index: -1,
+            title: undefined,
+            width: 0,
+            height: 0,
+            active: false,
+          },
+        };
+      }
+      const numeric = Number.parseInt(target.id, 10);
+      if (!Number.isFinite(numeric)) {
+        throw new Error(`Invalid pane id: ${target.id}`);
+      }
+      const found = panes.find((p) => p.index === numeric);
+      if (!found) {
+        throw new Error(`Pane not found by id: ${target.id}`);
+      }
+      return { target: paneTarget(session, found.index), pane: found };
+    }
+    case "byIndex": {
+      const found = panes.find((p) => p.index === target.index);
+      if (!found) {
+        throw new Error(`Pane not found by index: ${target.index}`);
+      }
+      return { target: paneTarget(session, found.index), pane: found };
+    }
+    case "byTitle": {
+      const matches = panes.filter((p) => p.title === target.title);
+      if (matches.length === 0) {
+        throw new Error(`Pane not found by title: ${target.title}`);
+      }
+      if (matches.length > 1) {
+        throw new Error(`Ambiguous pane title "${target.title}" matches ${matches.length} panes`);
+      }
+      return {
+        target: paneTarget(session, matches[0]!.index),
+        pane: matches[0]!,
+      };
+    }
+    case "byRole":
+      throw new Error(
+        `byRole targets must be resolved at the daemon layer before reaching the bridge (got role="${target.role}")`,
+      );
+  }
+}
+
+function paneTarget(session: string | undefined, index: number): string {
+  return session ? `${session}.${index}` : String(index);
+}

package/scripts/build-tui.mjs

@@ -16,7 +16,9 @@
  * node-only for CI) — run `pnpm build:tui` on a machine with bun.
  *
  * Cross-compile: pass `--target bun-<os>-<arch>` (e.g. bun-linux-x64) to build
- * for another platform. Defaults to the host target.
+ * for another platform. Defaults to the host target. Pass `--outfile <path>` to
+ * write somewhere other than the default dist path (the release workflow uses
+ * this to emit per-platform artifacts side by side).
  */
 
 import { createSolidTransformPlugin } from "@opentui/solid/bun-plugin";
@@ -27,8 +29,7 @@ import { fileURLToPath } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "..");
 const entry = resolve(repoRoot, "packages/daemon/src/tui/main.ts");
-const outDir = resolve(repoRoot, "packages/daemon/dist/tui");
-const outfile = resolve(outDir, "tmux-ide-tui");
+const defaultOutDir = resolve(repoRoot, "packages/daemon/dist/tui");
 
 if (!existsSync(entry)) {
   throw new Error(`[build-tui] entry not found: ${entry}`);
@@ -38,7 +39,13 @@ const targetArg = process.argv.indexOf("--target");
 const target =
   targetArg !== -1 ? process.argv[targetArg + 1] : `bun-${process.platform}-${process.arch}`;
 
-mkdirSync(outDir, { recursive: true });
+const outfileArg = process.argv.indexOf("--outfile");
+const outfile =
+  outfileArg !== -1
+    ? resolve(process.argv[outfileArg + 1])
+    : resolve(defaultOutDir, "tmux-ide-tui");
+
+mkdirSync(dirname(outfile), { recursive: true });
 
 const start = Date.now();
 const result = await Bun.build({