tmux-ide 2.1.5 → 2.6.1

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-cli.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Compiles `bin/cli.ts` → `bin/cli.js` using esbuild.
+ *
+ * Scope (N1 of docs/npm-distribution-audit.md):
+ *  - Strip TypeScript so the CLI runs under stock node (no bun, no tsx).
+ *  - Inline the project's own `.ts` source (`packages/daemon/src/*.ts`,
+ *    workspace silos) into the single bin/cli.js entry. That's the bit
+ *    npm-install users cannot resolve themselves — `*.ts` extensions
+ *    aren't loadable under node and the published tarball has no
+ *    transpile step.
+ *  - Keep every third-party / bare-specifier import external. Native
+ *    bindings (node-pty, better-sqlite3, @parcel/watcher) and pure-JS
+ *    deps alike resolve from `node_modules/` at runtime, the same way
+ *    they would in any other published CLI.
+ *  - Preserve `#!/usr/bin/env node` as the shebang.
+ *
+ * Out of scope for N1 (handled by N2):
+ *  - Tarball `files` trimming.
+ *  - Workspace-package publish strategy (the cli.js bundle still
+ *    requires `@tmux-ide/contracts` + friends at runtime; N2 either
+ *    flips them public on npm or inlines them too).
+ *  - Dashboard `out/` self-contained shape (N3).
+ */
+
+import { build } from "esbuild";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { mkdirSync, readFileSync, chmodSync, statSync } from "node:fs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "..");
+const entry = resolve(repoRoot, "bin", "cli.ts");
+const outfile = resolve(repoRoot, "bin", "cli.js");
+
+mkdirSync(dirname(outfile), { recursive: true });
+
+await build({
+  entryPoints: [entry],
+  outfile,
+  bundle: true,
+  platform: "node",
+  target: "node20",
+  format: "esm",
+  // Third-party deps (`zod`, `ws`, `node-pty`, `@hono/...`, …) stay
+  // external — they're resolved from `node_modules` at runtime. The
+  // project's own workspace packages (`@tmux-ide/contracts`,
+  // `@tmux-ide/tmux-bridge`, …) are bundled in: pnpm-only `workspace:*`
+  // pointers won't resolve under `npm install`, so the bundle is the
+  // only sane way to ship our own TS code. Relative `.ts` imports are
+  // bundled too — the published tarball has no transpile step.
+  plugins: [
+    {
+      name: "external-non-workspace",
+      setup(b) {
+        b.onResolve({ filter: /.*/ }, (args) => {
+          if (args.kind === "entry-point") return undefined;
+          const id = args.path;
+          // Relative paths → bundle (let esbuild walk them).
+          if (id.startsWith(".") || id.startsWith("/")) return undefined;
+          // node: builtins → external.
+          if (id.startsWith("node:")) return { external: true };
+          // Workspace packages → bundle.
+          if (id.startsWith("@tmux-ide/")) return undefined;
+          // Everything else → external.
+          return { external: true };
+        });
+      },
+    },
+  ],
+  // Standard Hono / better-sqlite3 / node-pty dynamic-require patterns
+  // produce noisy esbuild warnings; silence them — they're benign for a
+  // CLI that delegates real work to the daemon.
+  logLevel: "warning",
+  // Keep the shebang on the output. esbuild strips it from the source
+  // during bundling, so we add it back via the banner option.
+  banner: { js: "#!/usr/bin/env node" },
+  // ESM output needs createRequire for any CJS interop the daemon code
+  // performs (e.g. better-sqlite3's wrapper).  esbuild's footer injection
+  // would be the wrong layer; we leave it to the daemon source.
+  sourcemap: false,
+  minify: false,
+});
+
+// Verify the shebang survived, the file is executable, and there's
+// exactly one shebang line — a regression here ships a broken bin.
+const compiled = readFileSync(outfile, "utf-8");
+if (!compiled.startsWith("#!/usr/bin/env node\n")) {
+  throw new Error(
+    `[build-cli] expected node shebang at offset 0, got: ${JSON.stringify(compiled.slice(0, 32))}`,
+  );
+}
+const shebangMatches = compiled.match(/^#!.*$/gm) ?? [];
+if (shebangMatches.length !== 1) {
+  throw new Error(
+    `[build-cli] expected exactly one shebang line, found ${shebangMatches.length}: ${shebangMatches.join(", ")}`,
+  );
+}
+chmodSync(outfile, 0o755);
+
+console.log(`[build-cli] wrote ${outfile} (${statSync(outfile).size} bytes)`);

package/scripts/build-tui.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env bun
+/**
+ * Compiles the TUI dispatcher (`packages/daemon/src/tui/main.ts`) into a single
+ * standalone `tmux-ide-tui` executable via `bun build --compile`.
+ *
+ * Why this exists: the cockpit/picker/sidebar/widget surfaces are OpenTUI/Solid
+ * `.tsx` that only run from a dev checkout (bun + bunfig preload for the JSX
+ * transform). This script produces a self-contained binary so those surfaces
+ * work on a clean `npm i -g tmux-ide` with no bun runtime present. The binary
+ * embeds the native OpenTUI dylib (Bun asset embedding) and pre-transforms JSX
+ * at build time, so nothing external is needed at runtime.
+ *
+ * Output: `packages/daemon/dist/tui/tmux-ide-tui` (gitignored; the CLI probes
+ * for it as the installed-mode fallback — see widgets/resolve.ts). Requires bun
+ * to build; it is NOT built by the default `pnpm build` (which must stay
+ * 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.
+ */
+
+import { createSolidTransformPlugin } from "@opentui/solid/bun-plugin";
+import { mkdirSync, existsSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+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");
+
+if (!existsSync(entry)) {
+  throw new Error(`[build-tui] entry not found: ${entry}`);
+}
+
+const targetArg = process.argv.indexOf("--target");
+const target =
+  targetArg !== -1 ? process.argv[targetArg + 1] : `bun-${process.platform}-${process.arch}`;
+
+mkdirSync(outDir, { recursive: true });
+
+const start = Date.now();
+const result = await Bun.build({
+  entrypoints: [entry],
+  target: "bun",
+  compile: { outfile, target },
+  plugins: [createSolidTransformPlugin()],
+});
+
+if (!result.success) {
+  for (const log of result.logs) console.error(log);
+  throw new Error("[build-tui] compile failed");
+}
+
+const bytes = statSync(outfile).size;
+const mb = (bytes / 1024 / 1024).toFixed(1);
+console.log(`[build-tui] wrote ${outfile} (${mb} MB, target ${target}, ${Date.now() - start}ms)`);