tmux-ide 1.0.0 → 1.2.0

package/src/init.js

@@ -1,32 +1,24 @@
-import { existsSync, readFileSync } from "node:fs";
-import { resolve, basename } from "node:path";
-import { writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 import { detectStack, suggestConfig } from "./detect.js";
-import { printLayout } from "./lib/output.js";
+import { outputError, printLayout } from "./lib/output.js";
 
 export async function init({ template, json } = {}) {
   const dir = process.cwd();
   const configPath = resolve(dir, "ide.yml");
 
   if (existsSync(configPath)) {
-    if (json) {
-      console.error(JSON.stringify({ error: "ide.yml already exists", code: "EXISTS" }));
-    } else {
-      console.error("ide.yml already exists in this directory");
-    }
-    process.exit(1);
+    outputError("ide.yml already exists in this directory", "EXISTS");
   }
 
   // If a specific template is requested, use it
   if (template) {
-    const templatePath = resolve(import.meta.dirname, "..", "templates", `${template}.yml`);
+    const templatePath = resolve(__dirname, "..", "templates", `${template}.yml`);
     if (!existsSync(templatePath)) {
-      if (json) {
-        console.error(JSON.stringify({ error: `Template "${template}" not found`, code: "NOT_FOUND" }));
-      } else {
-        console.error(`Template "${template}" not found. Available: default, nextjs, convex, vite, python, go, agent-team, agent-team-nextjs, agent-team-monorepo`);
-      }
-      process.exit(1);
+      outputError(`Template "${template}" not found`, "NOT_FOUND");
     }
 
     let content = readFileSync(templatePath, "utf-8");
@@ -64,7 +56,7 @@ export async function init({ template, json } = {}) {
     }
   } else {
     // Fallback to default template
-    const templatePath = resolve(import.meta.dirname, "..", "templates", "default.yml");
+    const templatePath = resolve(__dirname, "..", "templates", "default.yml");
     let content = readFileSync(templatePath, "utf-8");
     content = content.replace(/^name: .+/m, `name: ${name}`);
     writeFileSync(configPath, content);

package/src/inspect.js

@@ -0,0 +1,127 @@
+import { resolve, basename } from "node:path";
+import { readConfig } from "./lib/yaml-io.js";
+import { validateConfig } from "./validate.js";
+import { outputError } from "./lib/output.js";
+import { getSessionState, listPanes } from "./lib/tmux.js";
+
+export function buildInspection(dir, { config, configPath, running, panes }) {
+  const errors = validateConfig(config);
+  const rows = Array.isArray(config?.rows) ? config.rows : [];
+  const resolvedRows = rows.map((row, rowIndex) => ({
+    index: rowIndex,
+    size: row.size ?? null,
+    panes: (Array.isArray(row?.panes) ? row.panes : []).map((pane, paneIndex) => ({
+      index: paneIndex,
+      title: pane.title ?? null,
+      command: pane.command ?? null,
+      dir: pane.dir ?? ".",
+      size: pane.size ?? null,
+      focus: pane.focus === true,
+      role: pane.role ?? null,
+      task: pane.task ?? null,
+      env: pane.env ?? {},
+    })),
+  }));
+
+  const focusPane =
+    resolvedRows
+      .flatMap((row) => row.panes.map((pane) => ({ row: row.index, pane })))
+      .find(({ pane }) => pane.focus) ?? null;
+  const session = config?.name ?? basename(dir);
+
+  return {
+    dir,
+    configPath,
+    valid: errors.length === 0,
+    errors,
+    session,
+    before: config?.before ?? null,
+    summary: {
+      rows: resolvedRows.length,
+      panes: resolvedRows.reduce((sum, row) => sum + row.panes.length, 0),
+      focus: focusPane ? `rows.${focusPane.row}.panes.${focusPane.pane.index}` : null,
+    },
+    team: config?.team ?? null,
+    theme: config?.theme ?? null,
+    focus: focusPane
+      ? {
+          row: focusPane.row,
+          pane: focusPane.pane.index,
+          title: focusPane.pane.title,
+        }
+      : null,
+    rows: resolvedRows,
+    rawConfig: config,
+    tmux: {
+      running,
+      panes,
+    },
+  };
+}
+
+export async function inspect(targetDir, { json } = {}) {
+  const dir = resolve(targetDir ?? ".");
+
+  let config;
+  let configPath;
+  try {
+    ({ config, configPath } = readConfig(dir));
+  } catch (error) {
+    outputError(`Cannot read ide.yml: ${error.message}`, "READ_ERROR");
+    return;
+  }
+
+  const session = config?.name ?? basename(dir);
+  const state = getSessionState(session);
+  const panes = state.running ? listPanes(session) : [];
+  const data = buildInspection(dir, { config, configPath, running: state.running, panes });
+
+  if (json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  console.log(`Directory: ${data.dir}`);
+  console.log(`Config:    ${data.configPath}`);
+  console.log(`Valid:     ${data.valid ? "yes" : "no"}`);
+  console.log(`Session:   ${data.session}`);
+  console.log(`Running:   ${data.tmux.running ? "yes" : "no"}`);
+  console.log(`Rows:      ${data.summary.rows}`);
+  console.log(`Panes:     ${data.summary.panes}`);
+  console.log(`Team:      ${data.team ? data.team.name : "disabled"}`);
+
+  if (data.focus) {
+    console.log(
+      `Focus:     row ${data.focus.row}, pane ${data.focus.pane}${data.focus.title ? ` (${data.focus.title})` : ""}`,
+    );
+  }
+
+  if (!data.valid) {
+    console.log("\nValidation Errors:");
+    for (const error of data.errors) {
+      console.log(`  - ${error}`);
+    }
+  }
+
+  console.log("\nResolved Layout:");
+  for (const row of data.rows) {
+    console.log(`  Row ${row.index}${row.size ? ` (${row.size})` : ""}`);
+    for (const pane of row.panes) {
+      const parts = [];
+      if (pane.title) parts.push(pane.title);
+      if (pane.command) parts.push(`cmd=${pane.command}`);
+      if (pane.dir && pane.dir !== ".") parts.push(`dir=${pane.dir}`);
+      if (pane.role) parts.push(`role=${pane.role}`);
+      if (pane.focus) parts.push("focus");
+      console.log(`    - pane ${pane.index}: ${parts.join(" | ") || "shell"}`);
+    }
+  }
+
+  if (data.tmux.running && data.tmux.panes.length > 0) {
+    console.log("\nLive Panes:");
+    for (const pane of data.tmux.panes) {
+      const active = pane.active ? " (active)" : "";
+      console.log(`  ${pane.index}: ${pane.title} [${pane.width}x${pane.height}]${active}`);
+    }
+  }
+}

package/src/launch.js

@@ -1,238 +1,245 @@
-import { resolve } from "node:path";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { readConfig, getSessionName } from "./lib/yaml-io.js";
 import { computeSizes, toSplitPercents } from "./lib/sizes.js";
-
-function tmux(cmd) {
-  execSync(`tmux ${cmd}`, { stdio: "inherit" });
+import { outputError } from "./lib/output.js";
+import { collectPaneStartupPlan } from "./lib/launch-plan.js";
+import { buildSessionOptions } from "./lib/session-options.js";
+import {
+  attachSession,
+  createDetachedSession,
+  getPaneCurrentCommand,
+  getSessionVariable,
+  hasSession,
+  runSessionCommand,
+  selectPane,
+  sendLiteral,
+  setPaneTitle,
+  setSessionEnvironment,
+  setSessionVariable,
+  splitPane,
+  startSessionMonitor,
+} from "./lib/tmux.js";
+import { validateConfig } from "./validate.js";
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
-function tmuxQuiet(cmd) {
-  try {
-    execSync(`tmux ${cmd}`, { stdio: "ignore" });
-  } catch {}
+function configHash(config) {
+  return createHash("sha256").update(JSON.stringify(config)).digest("hex").slice(0, 12);
 }
 
-export async function launch(targetDir) {
-  const dir = resolve(targetDir ?? ".");
-
-  let config;
-  try {
-    ({ config } = readConfig(dir));
-  } catch {
-    console.error(`No ide.yml found in ${dir}. Run "tmux-ide init" to create one.`);
-    process.exit(1);
-  }
-
-  // Validate config structure before building tmux session
-  if (!Array.isArray(config.rows) || config.rows.length === 0) {
-    console.error("Invalid ide.yml: 'rows' must be a non-empty array");
-    console.error("Run: tmux-ide validate");
-    process.exit(1);
-  }
-  for (const row of config.rows) {
-    if (!Array.isArray(row.panes) || row.panes.length === 0) {
-      console.error("Invalid ide.yml: each row must have a non-empty 'panes' array");
-      console.error("Run: tmux-ide validate");
-      process.exit(1);
-    }
-  }
-
-  const session = config.name ?? getSessionName(dir);
-  const rows = config.rows;
-  const theme = config.theme ?? {};
-  const team = config.team ?? null;
+export function waitForPaneCommand(
+  targetPane,
+  expectedCommands,
+  { attempts = 20, delayMs = 100, getCurrentCommand = getPaneCurrentCommand, sleep = sleepMs } = {},
+) {
+  const allowed = new Set(expectedCommands.map((command) => command.toLowerCase()));
 
-  // Run before hook
-  if (config.before) {
-    console.log(`Running: ${config.before}`);
+  for (let attempt = 0; attempt < attempts; attempt++) {
     try {
-      execSync(config.before, { cwd: dir, stdio: "inherit" });
-    } catch (e) {
-      console.error(`"before" hook failed: ${config.before}`);
-      process.exit(1);
+      const current = getCurrentCommand(targetPane)?.trim().toLowerCase();
+      if (allowed.has(current)) return true;
+    } catch {
+      // Fall through to retry; tmux can briefly report transitional state.
     }
-  }
 
-  // If session already exists, just attach to it
-  try {
-    execSync(`tmux has-session -t "${session}"`, { stdio: "ignore" });
-    console.log(`Session "${session}" is already running. Attaching...`);
-    tmux(`attach -t "${session}"`);
-    return;
-  } catch {
-    // Session doesn't exist, continue with creation
+    if (attempt < attempts - 1) {
+      sleep(delayMs);
+    }
   }
 
-  // Get terminal dimensions
-  const cols = process.stdout.columns ?? 200;
-  const lines = process.stdout.rows ?? 50;
-
-  // Create session with first pane
-  tmux(`new-session -d -s "${session}" -c "${dir}" -x ${cols} -y ${lines}`);
-
-  // Set agent teams env var if team config is present
-  if (team) {
-    tmux(`set-environment -t "${session}" CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1`);
-  }
+  return false;
+}
 
-  // Compute row sizes and convert to tmux split percentages
+export function buildPaneMap(rows, dir, rootPaneId, splitPane) {
   const rowSizes = computeSizes(rows);
   const rowSplitPercents = toSplitPercents(rowSizes);
 
-  // Phase 1: Create all rows (vertical splits) BEFORE any horizontal splits.
-  // This ensures each row spans the full window width.
-  const rowPaneIndices = [0]; // rowPaneIndices[i] = tmux pane index for row i
-  let nextPaneIndex = 1;
-
+  // Create all rows vertically first so each row spans the full width.
+  const rowPaneIds = [rootPaneId];
   for (let rowIdx = 1; rowIdx < rows.length; rowIdx++) {
-    const splitFrom = rowPaneIndices[rowIdx - 1];
-    tmux(
-      `split-window -t "${session}:0.${splitFrom}" -v -c "${dir}" -p ${rowSplitPercents[rowIdx - 1]}`
-    );
-    rowPaneIndices.push(nextPaneIndex);
-    nextPaneIndex++;
+    const splitFrom = rowPaneIds[rowIdx - 1];
+    const newPaneId = splitPane({
+      targetPane: splitFrom,
+      direction: "vertical",
+      cwd: dir,
+      percent: rowSplitPercents[rowIdx - 1],
+    });
+    rowPaneIds.push(newPaneId);
   }
 
-  // Phase 2: Create panes within each row (horizontal splits).
-  // paneMap[row][col] = tmux pane index
   const paneMap = [];
-  const firstPanesOfRows = new Set(rowPaneIndices);
+  const firstPanesOfRows = new Set(rowPaneIds);
 
   for (let rowIdx = 0; rowIdx < rows.length; rowIdx++) {
     const row = rows[rowIdx];
     const panes = row.panes ?? [];
-    const rowPane = rowPaneIndices[rowIdx];
-    const rowPanes = [rowPane];
+    const rowPaneId = rowPaneIds[rowIdx];
+    const rowPanes = [rowPaneId];
 
-    // Compute pane sizes within this row and convert to split percentages
     const paneSizes = computeSizes(panes);
     const paneSplitPercents = toSplitPercents(paneSizes);
 
-    // Split this row's panes horizontally
     for (let paneIdx = 1; paneIdx < panes.length; paneIdx++) {
       const pane = panes[paneIdx];
       const targetPane = rowPanes[paneIdx - 1];
-
-      // Per-pane working directory
       const paneDir = pane.dir ? resolve(dir, pane.dir) : dir;
-
-      tmux(
-        `split-window -t "${session}:0.${targetPane}" -h -c "${paneDir}" -p ${paneSplitPercents[paneIdx - 1]}`
-      );
-      rowPanes.push(nextPaneIndex);
-      nextPaneIndex++;
+      const newPaneId = splitPane({
+        targetPane,
+        direction: "horizontal",
+        cwd: paneDir,
+        percent: paneSplitPercents[paneIdx - 1],
+      });
+      rowPanes.push(newPaneId);
     }
 
     paneMap.push(rowPanes);
   }
 
-  // Build the command for a pane, transforming claude commands for team roles
-  function buildCommand(p) {
-    if (!p.command) return null;
-    if (!team || !p.role) return p.command;
-
-    if (p.role === "lead") {
-      return `claude --team "${team.name}"`;
-    } else if (p.role === "teammate") {
-      let cmd = `claude --teammate-mode in-process --team "${team.name}"`;
-      if (p.task) {
-        cmd += ` --task "${p.task.replace(/"/g, '\\"')}"`;
-      }
-      return cmd;
+  return { paneMap, firstPanesOfRows };
+}
+
+function loadLaunchConfig(dir) {
+  let config;
+
+  try {
+    ({ config } = readConfig(dir));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      outputError(
+        `No ide.yml found in ${dir}. Run "tmux-ide init" or "tmux-ide detect --write" to create one.`,
+        "CONFIG_NOT_FOUND",
+      );
     }
-    return p.command;
+
+    outputError(`Cannot read ide.yml: ${error.message}`, "READ_ERROR");
+  }
+
+  const errors = validateConfig(config);
+  if (errors.length > 0) {
+    outputError(
+      `Invalid ide.yml in ${dir}. Run "tmux-ide validate" for details.`,
+      "INVALID_CONFIG",
+    );
   }
 
-  // Send commands, set titles, handle env/focus/dir for first panes
-  // Two-pass approach for teams: lead + non-teammates first, then teammates
-  let focusPane = paneMap[0][0];
-  const teammateCommands = [];
+  return config;
+}
 
-  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 p = panes[paneIdx];
-      const tmuxPane = paneMap[rowIdx][paneIdx];
-
-      if (p.title) {
-        tmux(`select-pane -t "${session}:0.${tmuxPane}" -T "${p.title}"`);
-      }
-
-      // Per-pane directory for first panes of each row (created with project root)
-      if (p.dir && firstPanesOfRows.has(tmuxPane)) {
-        const paneDir = resolve(dir, p.dir);
-        tmux(`send-keys -t "${session}:0.${tmuxPane}" "cd ${paneDir}" C-m`);
-      }
-
-      // Environment variables
-      if (p.env && typeof p.env === "object") {
-        for (const [key, val] of Object.entries(p.env)) {
-          tmux(`send-keys -t "${session}:0.${tmuxPane}" "export ${key}=${val}" C-m`);
-        }
-      }
-
-      const cmd = buildCommand(p);
-      if (cmd) {
-        if (team && p.role === "teammate") {
-          // Defer teammate launches to second pass
-          teammateCommands.push({ pane: tmuxPane, cmd });
-        } else {
-          tmux(`send-keys -t "${session}:0.${tmuxPane}" "${cmd}" C-m`);
-        }
-      }
-
-      if (p.focus) {
-        focusPane = tmuxPane;
-      }
-    }
+function runBeforeHook(command, dir) {
+  if (!command) return;
+
+  console.log(`Running: ${command}`);
+
+  try {
+    execSync(command, { cwd: dir, stdio: "inherit" });
+  } catch {
+    outputError(`The before hook failed: ${command}`, "BEFORE_HOOK_FAILED");
   }
+}
+
+export async function launch(targetDir, { json = false, attach = true } = {}) {
+  const dir = resolve(targetDir ?? ".");
+  const config = loadLaunchConfig(dir);
+
+  const { name: fallbackName } = getSessionName(dir);
+  const session = config.name ?? fallbackName;
+  const rows = config.rows;
+  const theme = config.theme ?? {};
+  const team = config.team ?? null;
+
+  runBeforeHook(config.before, dir);
+
+  // If session already exists, check for config drift and attach
+  if (hasSession(session)) {
+    const currentHash = configHash(config);
+    const storedHash = getSessionVariable(session, "@config_hash");
+    const configChanged = Boolean(storedHash && currentHash !== storedHash);
+
+    if (json) {
+      console.log(JSON.stringify({ session, running: true, configChanged }));
+    } else if (configChanged) {
+      console.log(`Session "${session}" is running but ide.yml has changed.`);
+      console.log(`Run "tmux-ide restart" to apply changes.`);
+    } else {
+      console.log(`Session "${session}" is already running. Attaching...`);
+    }
 
-  // Second pass: launch teammates after a brief delay for the lead to initialize
-  if (teammateCommands.length > 0) {
-    execSync("sleep 2");
-    for (const { pane: p, cmd } of teammateCommands) {
-      tmux(`send-keys -t "${session}:0.${p}" "${cmd}" C-m`);
+    if (attach) {
+      attachSession(session);
     }
+    return;
   }
 
-  // Apply styling
-  const accent = theme.accent ?? "colour75";
-  const border = theme.border ?? "colour238";
-  const bg = theme.bg ?? "colour235";
-  const fg = theme.fg ?? "colour248";
+  // Get terminal dimensions
+  const cols = process.stdout.columns ?? 200;
+  const lines = process.stdout.rows ?? 50;
 
-  tmux(`set-option -t "${session}" pane-border-status top`);
-  tmux(
-    `set-option -t "${session}" pane-border-format " #{?pane_active,#[bold]▸,·} #T "`
-  );
-  tmux(`set-option -t "${session}" pane-border-style "fg=${border}"`);
-  tmux(`set-option -t "${session}" pane-active-border-style "fg=${accent}"`);
+  // Create session with first pane
+  const rootPaneId = createDetachedSession(session, dir, { cols, lines });
 
-  tmux(`set-option -t "${session}" status-style "bg=${bg},fg=${fg}"`);
-  tmux(
-    `set-option -t "${session}" status-left "#[fg=colour0,bg=${accent},bold]  ${session.toUpperCase()} IDE #[default] "`
-  );
-  tmux(`set-option -t "${session}" status-left-length 30`);
-  tmux(
-    `set-option -t "${session}" status-right "#[fg=colour243]%H:%M #[fg=${accent}]│ #[fg=${fg}]%b %d "`
-  );
-  tmux(`set-option -t "${session}" status-justify centre`);
-  tmux(
-    `set-option -t "${session}" window-status-current-format "#[fg=${accent},bold]●"`
+  // Set agent teams env var if team config is present
+  if (team) {
+    setSessionEnvironment(session, "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS", "1");
+  }
+
+  const { paneMap, firstPanesOfRows } = buildPaneMap(
+    rows,
+    dir,
+    rootPaneId,
+    ({ targetPane, direction, cwd, percent }) => splitPane(targetPane, direction, cwd, percent),
   );
-  tmux(
-    `set-option -t "${session}" window-status-format "#[fg=${border}]○"`
+
+  const { focusPane, paneActions } = collectPaneStartupPlan(rows, paneMap, firstPanesOfRows, dir);
+
+  for (const action of paneActions) {
+    if (action.title) {
+      setPaneTitle(action.targetPane, action.title);
+    }
+
+    if (action.chdir) {
+      sendLiteral(action.targetPane, `cd ${action.chdir}`);
+    }
+
+    for (const exportCommand of action.exports) {
+      sendLiteral(action.targetPane, exportCommand);
+    }
+
+    if (action.command) {
+      sendLiteral(action.targetPane, action.command);
+    }
+  }
+
+  for (const command of buildSessionOptions(session, { theme })) {
+    runSessionCommand(command);
+  }
+
+  // Store config hash for drift detection on re-launch
+  setSessionVariable(session, "@config_hash", configHash(config));
+
+  // Start background session monitor (port detection + agent status)
+  const monitorScript = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "lib",
+    "session-monitor.js",
   );
+  startSessionMonitor(session, monitorScript);
 
   // Focus the correct pane
-  tmux(`select-pane -t "${session}:0.${focusPane}"`);
+  selectPane(focusPane);
 
   // Launch summary
   const totalPanes = rows.reduce((sum, r) => sum + (r.panes?.length ?? 0), 0);
-  console.log(`Starting "${session}" (${rows.length} row${rows.length === 1 ? "" : "s"}, ${totalPanes} pane${totalPanes === 1 ? "" : "s"})...`);
+  console.log(
+    `Starting "${session}" (${rows.length} row${rows.length === 1 ? "" : "s"}, ${totalPanes} pane${totalPanes === 1 ? "" : "s"})...`,
+  );
 
   // Attach
-  tmux(`attach -t "${session}"`);
+  if (attach) {
+    attachSession(session);
+  }
 }

package/src/lib/errors.js

@@ -0,0 +1,35 @@
+export class IdeError extends Error {
+  constructor(message, { code, exitCode = 1, cause } = {}) {
+    super(message, { cause });
+    this.name = "IdeError";
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+
+  toJSON() {
+    const obj = { error: this.message, code: this.code };
+    if (this.cause) obj.cause = this.cause.message;
+    return obj;
+  }
+}
+
+export class ConfigError extends IdeError {
+  constructor(message, code, { cause } = {}) {
+    super(message, { code, exitCode: 1, cause });
+    this.name = "ConfigError";
+  }
+}
+
+export class TmuxError extends IdeError {
+  constructor(message, code, { cause } = {}) {
+    super(message, { code, exitCode: 1, cause });
+    this.name = "TmuxError";
+  }
+}
+
+export class SessionError extends IdeError {
+  constructor(message, code, { cause } = {}) {
+    super(message, { code, exitCode: 1, cause });
+    this.name = "SessionError";
+  }
+}