tmux-ide 1.0.0 → 1.1.0

package/src/lib/tmux.js

@@ -0,0 +1,200 @@
+import { execFileSync } from "node:child_process";
+
+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",
+];
+
+export class TmuxError extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.name = "TmuxError";
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+export function getSessionState(session) {
+  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) {
+  runTmux(["attach", "-t", session], { stdio: "inherit" });
+}
+
+export function hasSession(session) {
+  try {
+    runTmux(["has-session", "-t", session]);
+    return true;
+  } catch (error) {
+    if (error instanceof TmuxError && error.code === "SESSION_NOT_FOUND") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export function killSession(session) {
+  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 listPanes(session) {
+  const raw = runTmux(
+    [
+      "list-panes",
+      "-t",
+      session,
+      "-F",
+      "#{pane_index}|#{pane_title}|#{pane_width}|#{pane_height}|#{pane_active}",
+    ],
+    { encoding: "utf-8" },
+  ).trim();
+
+  if (!raw) return [];
+
+  return raw.split("\n").map((line) => {
+    const [index, title, width, height, active] = line.split("|");
+    return {
+      index: Number.parseInt(index, 10),
+      title,
+      width: Number.parseInt(width, 10),
+      height: Number.parseInt(height, 10),
+      active: active === "1",
+    };
+  });
+}
+
+export function createDetachedSession(session, cwd, { cols, lines } = {}) {
+  return runTmux(
+    [
+      "new-session",
+      "-d",
+      "-P",
+      "-F",
+      "#{pane_id}",
+      "-s",
+      session,
+      "-c",
+      cwd,
+      "-x",
+      String(cols ?? 200),
+      "-y",
+      String(lines ?? 50),
+    ],
+    { encoding: "utf-8" },
+  ).trim();
+}
+
+export function setSessionEnvironment(session, key, value) {
+  runTmux(["set-environment", "-t", session, key, String(value)]);
+}
+
+export function splitPane(targetPane, direction, cwd, percent) {
+  return runTmux(
+    [
+      "split-window",
+      "-P",
+      "-F",
+      "#{pane_id}",
+      "-t",
+      targetPane,
+      direction === "vertical" ? "-v" : "-h",
+      "-c",
+      cwd,
+      "-p",
+      String(percent),
+    ],
+    { encoding: "utf-8" },
+  ).trim();
+}
+
+export function sendLiteral(targetPane, text) {
+  runTmux(["send-keys", "-t", targetPane, "-l", "--", text], { stdio: "inherit" });
+  runTmux(["send-keys", "-t", targetPane, "Enter"], { stdio: "inherit" });
+}
+
+export function getPaneCurrentCommand(targetPane) {
+  return runTmux(["display-message", "-p", "-t", targetPane, "#{pane_current_command}"], {
+    encoding: "utf-8",
+  }).trim();
+}
+
+export function selectPane(targetPane) {
+  runTmux(["select-pane", "-t", targetPane], { stdio: "inherit" });
+}
+
+export function setPaneTitle(targetPane, title) {
+  runTmux(["select-pane", "-t", targetPane, "-T", title], { stdio: "inherit" });
+}
+
+export function runSessionCommand(args) {
+  runTmux(args, { stdio: "inherit" });
+}
+
+function runTmux(args, options = {}) {
+  const execOptions = {
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options,
+  };
+
+  try {
+    return execFileSync("tmux", args, execOptions);
+  } catch (error) {
+    throw classifyTmuxError(error);
+  }
+}
+
+function classifyTmuxError(error) {
+  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", error);
+  }
+
+  if (TMUX_UNAVAILABLE_PATTERNS.some((pattern) => detail.includes(pattern))) {
+    return new TmuxError(
+      "tmux is unavailable or its socket is inaccessible",
+      "TMUX_UNAVAILABLE",
+      error,
+    );
+  }
+
+  return new TmuxError("tmux command failed", "TMUX_ERROR", error);
+}
+
+function getErrorDetail(error) {
+  const stderr = error?.stderr;
+  if (typeof stderr === "string" && stderr.length > 0) return stderr;
+  if (Buffer.isBuffer(stderr) && stderr.length > 0) return stderr.toString("utf-8");
+  return error?.message ?? "";
+}

package/src/ls.js

@@ -5,7 +5,7 @@ export async function ls({ json } = {}) {
   try {
     raw = execSync(
       'tmux list-sessions -F "#{session_name}|#{session_created}|#{session_attached}"',
-      { encoding: "utf-8" }
+      { encoding: "utf-8" },
     ).trim();
   } catch {
     if (json) {
@@ -35,8 +35,6 @@ export async function ls({ json } = {}) {
   console.log("─".repeat(54));
   for (const s of sessions) {
     const date = new Date(s.created).toLocaleString();
-    console.log(
-      s.name.padEnd(24) + date.padEnd(22) + (s.attached ? "yes" : "no")
-    );
+    console.log(s.name.padEnd(24) + date.padEnd(22) + (s.attached ? "yes" : "no"));
   }
 }

package/src/restart.js

@@ -1,23 +1,16 @@
 import { resolve } from "node:path";
-import { execSync } from "node:child_process";
 import { getSessionName } from "./lib/yaml-io.js";
 import { launch } from "./launch.js";
+import { killSession } from "./lib/tmux.js";
 
-export async function restart(targetDir) {
+export async function restart(targetDir, { json, attach } = {}) {
   const dir = resolve(targetDir ?? ".");
   const session = getSessionName(dir);
+  const result = killSession(session);
 
-  let wasRunning = false;
-  try {
-    execSync(`tmux kill-session -t "${session}"`, { stdio: "ignore" });
-    wasRunning = true;
-  } catch {
-    // Session wasn't running — that's fine
-  }
-
-  if (wasRunning) {
+  if (result.stopped) {
     console.log(`Stopped session "${session}"`);
   }
 
-  await launch(dir);
+  await launch(dir, { json, attach });
 }

package/src/status.js

@@ -1,36 +1,18 @@
 import { resolve } from "node:path";
 import { existsSync } from "node:fs";
-import { execSync } from "node:child_process";
 import { getSessionName } from "./lib/yaml-io.js";
+import { getSessionState, listPanes } from "./lib/tmux.js";
 
 export async function status(targetDir, { json } = {}) {
   const dir = resolve(targetDir ?? ".");
   const session = getSessionName(dir);
   const configExists = existsSync(resolve(dir, "ide.yml"));
 
-  let running = false;
+  const state = getSessionState(session);
+  const running = state.running;
   let panes = [];
 
-  try {
-    execSync(`tmux has-session -t "${session}"`, { stdio: "ignore" });
-    running = true;
-
-    const raw = execSync(
-      `tmux list-panes -t "${session}" -F "#{pane_index}|#{pane_title}|#{pane_width}|#{pane_height}|#{pane_active}"`,
-      { encoding: "utf-8" }
-    ).trim();
-
-    panes = raw.split("\n").map((line) => {
-      const [index, title, width, height, active] = line.split("|");
-      return {
-        index: parseInt(index),
-        title,
-        width: parseInt(width),
-        height: parseInt(height),
-        active: active === "1",
-      };
-    });
-  } catch {}
+  if (running) panes = listPanes(session);
 
   const data = { session, running, configExists, panes };
 

package/src/stop.js

@@ -1,23 +1,24 @@
 import { resolve } from "node:path";
-import { execSync } from "node:child_process";
 import { getSessionName } from "./lib/yaml-io.js";
+import { outputError } from "./lib/output.js";
+import { killSession } from "./lib/tmux.js";
 
 export async function stop(targetDir, { json } = {}) {
   const dir = resolve(targetDir ?? ".");
   const session = getSessionName(dir);
+  const result = killSession(session);
 
-  try {
-    execSync(`tmux kill-session -t "${session}"`, { stdio: "inherit" });
+  if (result.stopped) {
     if (json) {
       console.log(JSON.stringify({ stopped: session }));
     } else {
       console.log(`Stopped session "${session}"`);
     }
-  } catch {
-    if (json) {
-      console.error(JSON.stringify({ error: `No active session "${session}" found`, code: "NOT_RUNNING" }));
-    } else {
-      console.error(`No active session "${session}" found`);
-    }
+    return;
   }
+
+  outputError(`No active session "${session}" found`, "NOT_RUNNING", {
+    json,
+    exitCode: 1,
+  });
 }

package/src/validate.js

@@ -94,22 +94,6 @@ export function validateConfig(config) {
     }
   }
 
-  // Cross-validate team roles
-  if (config.team && Array.isArray(config.rows)) {
-    let leadCount = 0;
-    for (const row of config.rows) {
-      if (!Array.isArray(row.panes)) continue;
-      for (const pane of row.panes) {
-        if (pane.role === "lead") leadCount++;
-      }
-    }
-    if (leadCount === 0) {
-      errors.push("team config requires exactly one pane with role: lead");
-    } else if (leadCount > 1) {
-      errors.push("team config allows only one pane with role: lead");
-    }
-  }
-
   if (config.theme !== undefined) {
     if (config.theme == null || typeof config.theme !== "object" || Array.isArray(config.theme)) {
       errors.push("'theme' must be an object");

package/src/detect.test.js

@@ -1,115 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import { suggestConfig } from "./detect.js";
-
-describe("suggestConfig", () => {
-  it("creates Next.js config with pnpm", () => {
-    const config = suggestConfig("/project", {
-      packageManager: "pnpm",
-      frameworks: ["next"],
-      devCommand: "pnpm dev",
-      language: "javascript",
-    });
-    assert.strictEqual(config.rows[0].size, "70%");
-    assert.strictEqual(config.rows[0].panes.length, 2);
-    const bottom = config.rows[1].panes;
-    assert.strictEqual(bottom[0].title, "Next.js");
-    assert.strictEqual(bottom[0].command, "pnpm dev");
-    assert.strictEqual(bottom[bottom.length - 1].title, "Shell");
-  });
-
-  it("creates Next.js + Convex config with 3 Claude panes", () => {
-    const config = suggestConfig("/project", {
-      packageManager: "pnpm",
-      frameworks: ["next", "convex"],
-      devCommand: "pnpm dev",
-      language: "javascript",
-    });
-    assert.strictEqual(config.rows[0].panes.length, 3);
-    const bottom = config.rows[1].panes;
-    const titles = bottom.map((p) => p.title);
-    assert.ok(titles.includes("Next.js"));
-    assert.ok(titles.includes("Convex"));
-    assert.ok(titles.includes("Shell"));
-  });
-
-  it("creates Go config", () => {
-    const config = suggestConfig("/project", {
-      packageManager: null,
-      frameworks: ["go"],
-      devCommand: null,
-      language: "go",
-    });
-    const bottom = config.rows[1].panes;
-    assert.strictEqual(bottom[0].title, "Go");
-    assert.strictEqual(bottom[0].command, "go run .");
-  });
-
-  it("creates Cargo config", () => {
-    const config = suggestConfig("/project", {
-      packageManager: null,
-      frameworks: ["cargo"],
-      devCommand: null,
-      language: "rust",
-    });
-    const bottom = config.rows[1].panes;
-    assert.strictEqual(bottom[0].title, "Cargo");
-    assert.strictEqual(bottom[0].command, "cargo watch -x run");
-  });
-
-  it("falls back to dev command when no framework detected", () => {
-    const config = suggestConfig("/project", {
-      packageManager: "npm",
-      frameworks: [],
-      devCommand: "npm run dev",
-      language: "javascript",
-    });
-    const bottom = config.rows[1].panes;
-    assert.strictEqual(bottom[0].title, "Dev Server");
-    assert.strictEqual(bottom[0].command, "npm run dev");
-  });
-
-  it("creates minimal config with just shell when nothing detected", () => {
-    const config = suggestConfig("/project", {
-      packageManager: null,
-      frameworks: [],
-      devCommand: null,
-      language: null,
-    });
-    const bottom = config.rows[1].panes;
-    assert.strictEqual(bottom.length, 1);
-    assert.strictEqual(bottom[0].title, "Shell");
-  });
-
-  it("uses npm run for npm package manager", () => {
-    const config = suggestConfig("/project", {
-      packageManager: "npm",
-      frameworks: ["next"],
-      devCommand: "npm run dev",
-      language: "javascript",
-    });
-    const bottom = config.rows[1].panes;
-    assert.strictEqual(bottom[0].command, "npm run dev");
-  });
-
-  it("uses bun for bun package manager", () => {
-    const config = suggestConfig("/project", {
-      packageManager: "bun",
-      frameworks: ["vite"],
-      devCommand: "bun dev",
-      language: "javascript",
-    });
-    const bottom = config.rows[1].panes;
-    assert.strictEqual(bottom[0].command, "bun dev");
-  });
-
-  it("uses project directory basename as session name", () => {
-    const config = suggestConfig("/home/user/my-app", {
-      packageManager: null,
-      frameworks: [],
-      devCommand: null,
-      language: null,
-    });
-    assert.strictEqual(config.name, "my-app");
-  });
-});

package/src/integration.test.js

@@ -1,94 +0,0 @@
-import { describe, it, before, after } from "node:test";
-import assert from "node:assert/strict";
-import { execSync, execFileSync } from "node:child_process";
-import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-
-// Skip entire suite if tmux is not available
-let tmuxAvailable = false;
-try {
-  execSync("tmux -V", { stdio: "ignore" });
-  tmuxAvailable = true;
-} catch {}
-
-describe("integration", { skip: !tmuxAvailable && "tmux not available" }, () => {
-  let tmpDir;
-  const session = "tmux-ide-test-integration";
-  const cli = join(import.meta.dirname, "..", "bin", "cli.js");
-
-  function run(args) {
-    return execFileSync("node", [cli, ...args], { cwd: tmpDir, encoding: "utf-8" });
-  }
-
-  function runJSON(args) {
-    return JSON.parse(run([...args, "--json"]));
-  }
-
-  function killSession() {
-    try {
-      execSync(`tmux kill-session -t "${session}"`, { stdio: "ignore" });
-    } catch {}
-  }
-
-  function createSession() {
-    execSync(`tmux new-session -d -s "${session}" -x 80 -y 24`, { stdio: "ignore" });
-  }
-
-  before(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), "tmux-ide-test-"));
-    writeFileSync(
-      join(tmpDir, "ide.yml"),
-      `name: ${session}\nrows:\n  - panes:\n      - title: Shell\n`
-    );
-  });
-
-  after(() => {
-    killSession();
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it("status --json reports not running when no session exists", () => {
-    killSession();
-    const result = runJSON(["status"]);
-    assert.strictEqual(result.running, false);
-  });
-
-  it("status --json reports running after session is created", () => {
-    killSession();
-    createSession();
-    const result = runJSON(["status"]);
-    assert.strictEqual(result.running, true);
-    killSession();
-  });
-
-  it("stop --json kills a running session", () => {
-    createSession();
-    run(["stop"]);
-    // Verify it's gone
-    const result = runJSON(["status"]);
-    assert.strictEqual(result.running, false);
-  });
-
-  it("validate --json reports valid for our test config", () => {
-    const result = runJSON(["validate"]);
-    assert.strictEqual(result.valid, true);
-    assert.deepStrictEqual(result.errors, []);
-  });
-
-  it("doctor --json passes checks", () => {
-    const result = runJSON(["doctor"]);
-    assert.strictEqual(result.ok, true);
-  });
-
-  it("config --json dumps config", () => {
-    const result = runJSON(["config"]);
-    assert.strictEqual(result.name, session);
-    assert.ok(Array.isArray(result.rows));
-  });
-
-  it("ls --json returns sessions list", () => {
-    const result = runJSON(["ls"]);
-    assert.ok(Array.isArray(result.sessions));
-  });
-});

package/src/lib/dot-path.test.js

@@ -1,67 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import { getByPath, setByPath } from "./dot-path.js";
-
-describe("getByPath", () => {
-  it("gets a top-level key", () => {
-    assert.strictEqual(getByPath({ name: "test" }, "name"), "test");
-  });
-
-  it("gets a nested value", () => {
-    const obj = { rows: [{ panes: [{ title: "Shell" }] }] };
-    assert.strictEqual(getByPath(obj, "rows.0.panes.0.title"), "Shell");
-  });
-
-  it("returns undefined for non-existent path", () => {
-    assert.strictEqual(getByPath({}, "a.b.c"), undefined);
-  });
-
-  it("returns undefined for partially valid path", () => {
-    assert.strictEqual(getByPath({ a: { b: 1 } }, "a.b.c"), undefined);
-  });
-});
-
-describe("setByPath", () => {
-  it("sets a top-level key", () => {
-    const obj = {};
-    setByPath(obj, "name", "test");
-    assert.deepStrictEqual(obj, { name: "test" });
-  });
-
-  it("sets a nested value", () => {
-    const obj = { rows: [{ panes: [{ title: "old" }] }] };
-    setByPath(obj, "rows.0.panes.0.title", "new");
-    assert.strictEqual(obj.rows[0].panes[0].title, "new");
-  });
-
-  it("creates arrays for numeric keys", () => {
-    const obj = {};
-    setByPath(obj, "rows.0.title", "test");
-    assert.ok(Array.isArray(obj.rows));
-    assert.strictEqual(obj.rows[0].title, "test");
-  });
-
-  it("creates objects for string keys", () => {
-    const obj = {};
-    setByPath(obj, "a.b.c", "val");
-    assert.deepStrictEqual(obj, { a: { b: { c: "val" } } });
-  });
-
-  it("handles duplicate segment values (regression)", () => {
-    // Bug: rows.0.panes.0 — both "0" segments caused indexOf to return
-    // the same index, breaking the lookahead for array vs object creation
-    const obj = {};
-    setByPath(obj, "rows.0.panes.0", "value");
-    assert.ok(Array.isArray(obj.rows), "rows should be an array");
-    assert.ok(Array.isArray(obj.rows[0].panes), "panes should be an array");
-    assert.strictEqual(obj.rows[0].panes[0], "value");
-  });
-
-  it("handles deeper duplicate segments", () => {
-    const obj = {};
-    setByPath(obj, "a.0.b.0.c", "deep");
-    assert.ok(Array.isArray(obj.a));
-    assert.ok(Array.isArray(obj.a[0].b));
-    assert.strictEqual(obj.a[0].b[0].c, "deep");
-  });
-});

package/src/lib/sizes.test.js

@@ -1,74 +0,0 @@
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import { computeSizes, toSplitPercents } from "./sizes.js";
-
-describe("computeSizes", () => {
-  it("distributes remaining space to items without size", () => {
-    const result = computeSizes([{ size: "70%" }, {}]);
-    assert.deepStrictEqual(result, [70, 30]);
-  });
-
-  it("passes through all explicit sizes", () => {
-    const result = computeSizes([{ size: "60%" }, { size: "40%" }]);
-    assert.deepStrictEqual(result, [60, 40]);
-  });
-
-  it("splits equally when no sizes specified", () => {
-    const result = computeSizes([{}, {}, {}]);
-    const expected = [100 / 3, 100 / 3, 100 / 3];
-    assert.deepStrictEqual(result, expected);
-  });
-
-  it("handles 3 items with mixed sizes", () => {
-    const result = computeSizes([{ size: "60%" }, { size: "25%" }, {}]);
-    assert.deepStrictEqual(result, [60, 25, 15]);
-  });
-
-  it("handles single item without size", () => {
-    const result = computeSizes([{}]);
-    assert.deepStrictEqual(result, [100]);
-  });
-
-  it("handles single item with size", () => {
-    const result = computeSizes([{ size: "50%" }]);
-    assert.deepStrictEqual(result, [50]);
-  });
-
-  it("handles empty array", () => {
-    const result = computeSizes([]);
-    assert.deepStrictEqual(result, []);
-  });
-
-  it("clamps remaining to zero when sizes exceed 100", () => {
-    const result = computeSizes([{ size: "80%" }, { size: "30%" }, {}]);
-    assert.deepStrictEqual(result, [80, 30, 0]);
-  });
-});
-
-describe("toSplitPercents", () => {
-  it("converts 70/30 to [30]", () => {
-    assert.deepStrictEqual(toSplitPercents([70, 30]), [30]);
-  });
-
-  it("converts 60/25/15 correctly", () => {
-    const result = toSplitPercents([60, 25, 15]);
-    assert.deepStrictEqual(result, [40, 38]);
-  });
-
-  it("converts equal 50/50 to [50]", () => {
-    assert.deepStrictEqual(toSplitPercents([50, 50]), [50]);
-  });
-
-  it("converts equal thirds", () => {
-    const result = toSplitPercents([100 / 3, 100 / 3, 100 / 3]);
-    assert.deepStrictEqual(result, [67, 50]);
-  });
-
-  it("returns empty array for single item", () => {
-    assert.deepStrictEqual(toSplitPercents([100]), []);
-  });
-
-  it("returns empty array for empty input", () => {
-    assert.deepStrictEqual(toSplitPercents([]), []);
-  });
-});