tmux-ide 1.0.0 → 1.2.0

package/src/lib/launch-plan.js

@@ -0,0 +1,49 @@
+import { resolve } from "node:path";
+
+export function buildPaneCommand(pane) {
+  if (!pane.command) return null;
+  return pane.command;
+}
+
+export function collectPaneStartupPlan(rows, paneMap, firstPanesOfRows, dir) {
+  let focusPane = paneMap[0][0];
+  const paneActions = [];
+
+  for (let rowIdx = 0; rowIdx < rows.length; rowIdx++) {
+    const row = rows[rowIdx];
+    const panes = row.panes ?? [];
+
+    for (let paneIdx = 0; paneIdx < panes.length; paneIdx++) {
+      const pane = panes[paneIdx];
+      const tmuxPane = paneMap[rowIdx][paneIdx];
+      const action = {
+        targetPane: tmuxPane,
+        title: pane.title ?? null,
+        chdir: null,
+        exports: [],
+        command: null,
+      };
+
+      if (pane.dir && firstPanesOfRows.has(tmuxPane)) {
+        action.chdir = resolve(dir, pane.dir);
+      }
+
+      if (pane.env && typeof pane.env === "object") {
+        action.exports = Object.entries(pane.env).map(([key, value]) => `export ${key}=${value}`);
+      }
+
+      const command = buildPaneCommand(pane);
+      if (command) {
+        action.command = command;
+      }
+
+      if (pane.focus) {
+        focusPane = tmuxPane;
+      }
+
+      paneActions.push(action);
+    }
+  }
+
+  return { focusPane, paneActions };
+}

package/src/lib/output.js

@@ -1,12 +1,4 @@
-export function output(data, { json } = {}) {
-  if (json) {
-    console.log(JSON.stringify(data, null, 2));
-  } else if (typeof data === "string") {
-    console.log(data);
-  } else {
-    console.log(data);
-  }
-}
+import { IdeError } from "./errors.js";
 
 export function printLayout(config) {
   const INNER = 40;
@@ -26,47 +18,51 @@ export function printLayout(config) {
 
     // Top border or mid divider
     if (r === 0) {
-      let top = "  ┌";
+      let top = "  \u250c";
       for (let i = 0; i < count; i++) {
-        top += "─".repeat(widths[i]);
-        top += i < count - 1 ? "┬" : "┐";
+        top += "\u2500".repeat(widths[i]);
+        top += i < count - 1 ? "\u252c" : "\u2510";
       }
       console.log(top);
     } else {
-      console.log("  ├" + "─".repeat(INNER + count - 1) + "┤");
+      console.log("  \u251c" + "\u2500".repeat(INNER + count - 1) + "\u2524");
     }
 
     // Content line
     const sizeLabel = rows[r].size ?? "";
-    let line = "  │";
+    let line = "  \u2502";
     for (let i = 0; i < count; i++) {
       const title = panes[i]?.title ?? "";
       const w = widths[i];
       const pad = Math.max(0, w - title.length);
       const left = Math.floor(pad / 2);
       const right = pad - left;
-      line += " ".repeat(left) + title + " ".repeat(right) + "│";
+      line += " ".repeat(left) + title + " ".repeat(right) + "\u2502";
     }
     if (sizeLabel) line += "  " + sizeLabel;
     console.log(line);
 
     // Bottom border (last row only)
     if (r === rows.length - 1) {
-      let bot = "  └";
+      let bot = "  \u2514";
       for (let i = 0; i < count; i++) {
-        bot += "─".repeat(widths[i]);
-        bot += i < count - 1 ? "┴" : "┘";
+        bot += "\u2500".repeat(widths[i]);
+        bot += i < count - 1 ? "\u2534" : "\u2518";
       }
       console.log(bot);
     }
   }
 }
 
-export function outputError(message, code, { json } = {}) {
+export function outputError(message, code, { exitCode = 1 } = {}) {
+  throw new IdeError(message, { code, exitCode });
+}
+
+export function printCommandError(error, { json = false } = {}) {
   if (json) {
-    console.error(JSON.stringify({ error: message, code }, null, 2));
+    console.error(JSON.stringify(error.toJSON(), null, 2));
   } else {
-    console.error(message);
+    console.error(error.message);
   }
-  process.exit(code ?? 1);
+  process.exit(error.exitCode ?? 1);
 }

package/src/lib/session-monitor.js

@@ -0,0 +1,179 @@
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+
+const INTERVAL = 1000;
+const SPINNERS = /^[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠂⠒⠢⠆⠐⠠⠄◐◓◑◒|/\\-] /;
+
+// --- Port detection (pure helpers) ---
+
+function getListeningPids() {
+  // Returns Set of PIDs that have a listening TCP port in range 1024-20000
+  try {
+    const raw = execFileSync("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-FpPn"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const pids = new Set();
+    let currentPid = null;
+    for (const line of raw.split("\n")) {
+      if (line.startsWith("p")) {
+        currentPid = line.slice(1);
+      } else if (line.startsWith("n") && currentPid) {
+        const match = line.match(/:(\d+)$/);
+        if (match) {
+          const port = parseInt(match[1], 10);
+          if (port >= 1024 && port <= 20000) pids.add(currentPid);
+        }
+      }
+    }
+    return pids;
+  } catch {
+    return new Set();
+  }
+}
+
+function getProcessTree() {
+  // Returns Map<pid, ppid>
+  try {
+    const raw = execFileSync("ps", ["-axo", "pid=,ppid="], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const tree = new Map();
+    for (const line of raw.trim().split("\n")) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length === 2) tree.set(parts[0], parts[1]);
+    }
+    return tree;
+  } catch {
+    return new Map();
+  }
+}
+
+export function computePortPanes(panes, { listeners, tree } = {}) {
+  // Walk up from each listening PID to find which pane owns it
+  if (!listeners) listeners = getListeningPids();
+  if (!tree) tree = getProcessTree();
+  if (listeners.size === 0) return new Set();
+
+  const panePids = new Map(panes.map((p) => [p.pid, p.id]));
+  const result = new Set();
+
+  for (const listenerPid of listeners) {
+    let pid = listenerPid;
+    while (pid && pid !== "0") {
+      if (panePids.has(pid)) {
+        result.add(panePids.get(pid));
+        break;
+      }
+      pid = tree.get(pid);
+    }
+  }
+  return result;
+}
+
+// --- Agent detection ---
+
+export function computeAgentStates(panes) {
+  // Returns Map<paneId, "busy" | "idle" | null>
+  const states = new Map();
+  for (const pane of panes) {
+    const cmd = (pane.cmd ?? "").toLowerCase();
+    if (!cmd.includes("claude") && !cmd.includes("codex")) {
+      states.set(pane.id, null);
+      continue;
+    }
+    states.set(pane.id, SPINNERS.test(pane.title ?? "") ? "busy" : "idle");
+  }
+  return states;
+}
+
+// --- Main loop (only runs when executed directly) ---
+
+const isMainModule = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMainModule) {
+  const session = process.argv[2];
+  if (!session) process.exit(1);
+
+  function tmux(...args) {
+    return execFileSync("tmux", args, { encoding: "utf-8" }).trim();
+  }
+
+  function tmuxSilent(...args) {
+    try {
+      return tmux(...args);
+    } catch {
+      return "";
+    }
+  }
+
+  function sessionExists() {
+    try {
+      tmux("has-session", "-t", session);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function hasClients() {
+    return tmuxSilent("list-clients").length > 0;
+  }
+
+  function listPanes() {
+    const raw = tmuxSilent(
+      "list-panes",
+      "-t",
+      session,
+      "-F",
+      "#{pane_id}\t#{pane_pid}\t#{pane_current_command}\t#{pane_title}",
+    );
+    if (!raw) return [];
+    return raw.split("\n").map((line) => {
+      const [id, pid, cmd, title] = line.split("\t");
+      return { id, pid, cmd, title };
+    });
+  }
+
+  let lastState = "";
+
+  function tick() {
+    if (!sessionExists()) process.exit(0);
+    if (!hasClients()) return; // skip when nobody is watching
+
+    const panes = listPanes();
+    if (panes.length === 0) return;
+
+    const portPanes = computePortPanes(panes);
+    const agentStates = computeAgentStates(panes);
+
+    // Build state fingerprint for change detection
+    const stateKey = panes
+      .map((p) => {
+        const port = portPanes.has(p.id) ? "1" : "0";
+        const agent = agentStates.get(p.id) ?? "-";
+        return `${p.id}:${port}:${agent}`;
+      })
+      .join("|");
+
+    if (stateKey === lastState) return;
+
+    // Apply changes
+    for (const pane of panes) {
+      const hasPort = portPanes.has(pane.id) ? "1" : "0";
+      const agent = agentStates.get(pane.id);
+
+      tmuxSilent("set-option", "-pqt", pane.id, "@has_port", hasPort);
+      tmuxSilent("set-option", "-pqt", pane.id, "@agent_busy", agent === "busy" ? "1" : "0");
+      tmuxSilent("set-option", "-pqt", pane.id, "@agent_idle", agent === "idle" ? "1" : "0");
+    }
+
+    tmuxSilent("refresh-client", "-S");
+    lastState = stateKey;
+  }
+
+  setInterval(tick, INTERVAL);
+  tick(); // run immediately
+}

package/src/lib/session-options.js

@@ -0,0 +1,95 @@
+/**
+ * Composable builders for tmux session configuration.
+ * Each returns an array of tmux command arrays.
+ */
+
+export function buildSessionOptions(session, { theme = {} } = {}) {
+  return [
+    ...themeOptions(session, theme),
+    ...borderOptions(session, theme),
+    ...behaviorOptions(session),
+    ...statusBarOptions(session, theme),
+    ...keyBindings(),
+  ];
+}
+
+export function themeOptions(session, theme) {
+  const accent = theme.accent ?? "colour75";
+  const border = theme.border ?? "colour238";
+  const bg = theme.bg ?? "colour235";
+  const fg = theme.fg ?? "colour248";
+
+  return [
+    ["set-option", "-t", session, "status-style", `bg=${bg},fg=${fg}`],
+    ["set-option", "-t", session, "pane-border-style", `fg=${border}`],
+    ["set-option", "-t", session, "pane-active-border-style", `fg=${accent}`],
+  ];
+}
+
+export function borderOptions(session, theme) {
+  const accent = theme.accent ?? "colour75";
+  const border = theme.border ?? "colour238";
+  const fg = theme.fg ?? "colour248";
+
+  return [
+    ["set-option", "-t", session, "pane-border-status", "top"],
+    [
+      "set-option",
+      "-t",
+      session,
+      "pane-border-format",
+      ` #{?pane_active,#[fg=${accent}#,bold]▸ #T  #[fg=${fg}]#{pane_current_path},#[fg=${border}]· #T  #{pane_current_path}} `,
+    ],
+  ];
+}
+
+export function behaviorOptions(session) {
+  return [
+    ["set-option", "-t", session, "mouse", "on"],
+    ["set-option", "-t", session, "escape-time", "0"],
+    ["set-option", "-t", session, "status-interval", "1"],
+  ];
+}
+
+export function statusBarOptions(session, theme) {
+  const accent = theme.accent ?? "colour75";
+  const border = theme.border ?? "colour238";
+  const fg = theme.fg ?? "colour248";
+
+  // Pane tab components — each is a self-contained piece
+  const agentIndicator = [
+    `#{?#{==:#{@agent_busy},1},#[fg=${accent}]⏺ ,`,
+    `#{?#{==:#{@agent_idle},1},#[fg=${border}]● ,}}`,
+  ].join("");
+  const portIndicator = `#{?#{==:#{@has_port},1},#[fg=green]⏺ ,}`;
+  const paneStyle = `#{?pane_active,#[fg=${accent}],#[fg=${border}]}`;
+  const paneTab = `${agentIndicator}${portIndicator}${paneStyle}#[range=pane|#{pane_id}] #T #[norange]#[default]`;
+  const separator = `#{?loop_last_flag,,#[fg=${border}]│}`;
+
+  return [
+    [
+      "set-option",
+      "-t",
+      session,
+      "status-left",
+      `#[fg=colour0,bg=${accent},bold]  ${session.toUpperCase()} IDE #[default] `,
+    ],
+    ["set-option", "-t", session, "status-left-length", "30"],
+    [
+      "set-option",
+      "-t",
+      session,
+      "status-right",
+      `#[fg=colour243]%H:%M #[fg=${accent}]│ #[fg=${fg}]%b %d `,
+    ],
+    ["set-option", "-t", session, "status-justify", "centre"],
+    ["set-option", "-t", session, "window-status-current-format", `#[fg=${accent},bold]●`],
+    ["set-option", "-t", session, "window-status-format", `#[fg=${border}]○`],
+    ["set-option", "-t", session, "status", "2"],
+    ["set-option", "-t", session, "status-format[1]", `  #{P:${paneTab}${separator}}`],
+  ];
+}
+
+export function keyBindings() {
+  return [["bind-key", "-n", "MouseDown1StatusDefault", "select-pane", "-t", "="]];
+}

package/src/lib/tmux.js

@@ -0,0 +1,234 @@
+import { execFileSync, spawn } from "node:child_process";
+import { TmuxError } from "./errors.js";
+
+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",
+];
+
+export { TmuxError };
+
+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" });
+}
+
+export function startSessionMonitor(session, monitorScript) {
+  const child = spawn("node", [monitorScript, session], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  // Store PID as tmux session variable for later cleanup
+  runTmux(["set-option", "-t", session, "@monitor_pid", String(child.pid)]);
+}
+
+export function stopSessionMonitor(session) {
+  try {
+    const pid = runTmux(["show-option", "-gqvt", session, "@monitor_pid"], {
+      encoding: "utf-8",
+    }).trim();
+    if (pid) process.kill(parseInt(pid, 10));
+  } catch {
+    /* session or process already gone */
+  }
+}
+
+export function getSessionVariable(session, name) {
+  try {
+    const raw = runTmux(["show-option", "-gqvt", session, name], {
+      encoding: "utf-8",
+    });
+    return raw.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function setSessionVariable(session, name, value) {
+  runTmux(["set-option", "-t", session, name, value]);
+}
+
+function runTmux(args, options = {}) {
+  if (DEBUG || globalThis.__tmuxIdeVerbose) {
+    console.error(`  [tmux] ${args.join(" ")}`);
+  }
+
+  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", { cause: 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,
+    });
+  }
+
+  return new TmuxError("tmux command failed", "TMUX_ERROR", { cause: 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/lib/yaml-io.js

@@ -19,8 +19,8 @@ export function writeConfig(dir, config) {
 export function getSessionName(dir) {
   try {
     const { config } = readConfig(dir);
-    return config.name ?? basename(dir);
+    return { name: config.name ?? basename(dir), source: config.name ? "config" : "fallback" };
   } catch {
-    return basename(dir);
+    return { name: basename(dir), source: "fallback" };
   }
 }

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 { name: 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 });
 }