tmux-ide 1.3.1 → 2.1.0

package/src/inspect.ts

@@ -0,0 +1,212 @@
+import { resolve, basename } from "node:path";
+import { readConfig } from "./lib/yaml-io.ts";
+import { validateConfig } from "./validate.ts";
+import { outputError } from "./lib/output.ts";
+import { getSessionState, listPanes } from "./lib/tmux.ts";
+import { loadSkills } from "./lib/skill-registry.ts";
+import type { IdeConfig } from "./types.ts";
+
+interface ResolvedPane {
+  index: number;
+  title: string | null;
+  command: string | null;
+  dir: string;
+  size: string | null;
+  focus: boolean;
+  role: string | null;
+  task: string | null;
+  env: Record<string, unknown>;
+}
+
+interface ResolvedRow {
+  index: number;
+  size: string | null;
+  panes: ResolvedPane[];
+}
+
+interface SkillInfo {
+  name: string;
+  specialties: string[];
+}
+
+interface PaneSkillMapping {
+  pane: string;
+  skill: string;
+  resolved: boolean;
+}
+
+interface Inspection {
+  dir: string;
+  configPath: string;
+  valid: boolean;
+  errors: string[];
+  session: string;
+  before: string | null;
+  summary: { rows: number; panes: number; focus: string | null };
+  team: IdeConfig["team"] | null;
+  theme: IdeConfig["theme"] | null;
+  focus: { row: number; pane: number; title: string | null } | null;
+  rows: ResolvedRow[];
+  rawConfig: IdeConfig;
+  tmux: { running: boolean; panes: ReturnType<typeof listPanes> };
+  skills: SkillInfo[];
+  paneSkillMap: PaneSkillMapping[];
+}
+
+export function buildInspection(
+  dir: string,
+  {
+    config,
+    configPath,
+    running,
+    panes,
+  }: {
+    config: IdeConfig;
+    configPath: string;
+    running: boolean;
+    panes: ReturnType<typeof listPanes>;
+  },
+): Inspection {
+  const errors = validateConfig(config);
+  const rows = Array.isArray(config?.rows) ? config.rows : [];
+  const resolvedRows: ResolvedRow[] = 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);
+
+  // Skills
+  const allSkills = loadSkills(dir);
+  const skillNames = new Set(allSkills.map((s) => s.name));
+  const skills: SkillInfo[] = allSkills.map((s) => ({ name: s.name, specialties: s.specialties }));
+
+  const paneSkillMap: PaneSkillMapping[] = [];
+  for (const row of rows) {
+    for (const pane of row.panes ?? []) {
+      if (pane.skill) {
+        paneSkillMap.push({
+          pane: pane.title ?? "untitled",
+          skill: pane.skill,
+          resolved: skillNames.has(pane.skill),
+        });
+      }
+    }
+  }
+
+  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,
+    },
+    skills,
+    paneSkillMap,
+  };
+}
+
+export async function inspect(
+  targetDir: string | undefined,
+  { json }: { json?: boolean } = {},
+): Promise<void> {
+  const dir = resolve(targetDir ?? ".");
+
+  let config;
+  let configPath: string;
+  try {
+    ({ config, configPath } = readConfig(dir));
+  } catch (error) {
+    outputError(`Cannot read ide.yml: ${(error as 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: string[] = [];
+      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/integration.test.ts.skip

@@ -0,0 +1,276 @@
+import { describe, it, beforeAll, afterAll, expect } from "bun:test";
+import { execSync, execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { launch } from "./launch.ts";
+import { restart } from "./restart.ts";
+
+// Skip entire suite unless tmux is installed and we can create sessions.
+let tmuxAvailable = false;
+try {
+  execSync("tmux -V", { stdio: "ignore" });
+  const probeSession = `tmux-ide-test-probe-${process.pid}`;
+  try {
+    execSync(`tmux new-session -d -s "${probeSession}" -x 80 -y 24`, { stdio: "ignore" });
+    execSync(`tmux kill-session -t "${probeSession}"`, { stdio: "ignore" });
+    tmuxAvailable = true;
+  } catch {
+    // tmux is installed but session creation is blocked in this environment.
+  }
+} catch {
+  // tmux is not installed.
+}
+
+const describeIntegration = tmuxAvailable ? describe : describe.skip;
+
+describeIntegration("integration", () => {
+  let tmpDir;
+  const session = "tmux-ide-test-integration";
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const cli = join(__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() {
+    // Stop the session monitor before killing the tmux session
+    // to prevent orphaned monitor processes from accumulating.
+    try {
+      const pid = execSync(`tmux show-option -gqvt "${session}" @monitor_pid`, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+      if (pid) {
+        try {
+          process.kill(-parseInt(pid, 10), "SIGTERM");
+        } catch {
+          try {
+            process.kill(parseInt(pid, 10), "SIGTERM");
+          } catch {
+            /* already gone */
+          }
+        }
+      }
+    } catch {
+      // No monitor PID or session gone
+    }
+    try {
+      execSync(`tmux kill-session -t "${session}"`, { stdio: "ignore" });
+    } catch {
+      // Session was already absent.
+    }
+  }
+
+  function createSession() {
+    execSync(`tmux new-session -d -s "${session}" -x 80 -y 24`, { stdio: "ignore" });
+  }
+
+  beforeAll(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "tmux-ide-test-"));
+    writeFileSync(
+      join(tmpDir, "ide.yml"),
+      `name: ${session}\nrows:\n  - panes:\n      - title: Shell\n`,
+    );
+  });
+
+  afterAll(() => {
+    killSession();
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("status --json reports not running when no session exists", () => {
+    killSession();
+    const result = runJSON(["status"]);
+    expect(result.running).toBe(false);
+  });
+
+  it("status --json reports running after session is created", () => {
+    killSession();
+    createSession();
+    const result = runJSON(["status"]);
+    expect(result.running).toBe(true);
+    killSession();
+  });
+
+  it("inspect --json includes live tmux pane state when the session is running", () => {
+    killSession();
+    createSession();
+    const result = runJSON(["inspect"]);
+
+    expect(result.session).toBe(session);
+    expect(result.tmux.running).toBe(true);
+    expect(Array.isArray(result.tmux.panes)).toBeTruthy();
+    expect(result.tmux.panes.length >= 1).toBeTruthy();
+
+    killSession();
+  });
+
+  it("launch creates the configured session without attaching when requested", async () => {
+    killSession();
+
+    await launch(tmpDir, { attach: false });
+
+    const result = runJSON(["status"]);
+    expect(result.running).toBe(true);
+    expect(result.panes.length >= 1).toBeTruthy();
+
+    killSession();
+  });
+
+  it("launch reuses an existing session instead of creating a new layout", async () => {
+    killSession();
+    await launch(tmpDir, { attach: false });
+
+    writeFileSync(
+      join(tmpDir, "ide.yml"),
+      `name: ${session}\nrows:\n  - panes:\n      - title: Changed\n      - title: Shell\n`,
+    );
+
+    await launch(tmpDir, { attach: false });
+
+    const result = runJSON(["status"]);
+    expect(result.running).toBe(true);
+    expect(result.panes.map((pane) => pane.title)).toEqual(["Shell"]);
+
+    killSession();
+  });
+
+  it("launch runs a successful before hook before creating the session", async () => {
+    killSession();
+    writeFileSync(
+      join(tmpDir, "ide.yml"),
+      `name: ${session}\nbefore: node -e "require('node:fs').writeFileSync('before.ok','ok')"\nrows:\n  - panes:\n      - title: Shell\n`,
+    );
+
+    await launch(tmpDir, { attach: false });
+
+    expect(runJSON(["status"]).running).toBe(true);
+    expect(existsSync(join(tmpDir, "before.ok"))).toBe(true);
+    killSession();
+  });
+
+  it("launch does not create a session when the before hook fails", async () => {
+    killSession();
+    writeFileSync(
+      join(tmpDir, "ide.yml"),
+      `name: ${session}\nbefore: node -e "process.exit(3)"\nrows:\n  - panes:\n      - title: Shell\n`,
+    );
+
+    await expect(launch(tmpDir, { attach: false })).rejects.toThrow(/before hook failed/i);
+    expect(runJSON(["status"]).running).toBe(false);
+  });
+
+  it("restart recreates the session without attaching when requested", async () => {
+    killSession();
+    writeFileSync(
+      join(tmpDir, "ide.yml"),
+      `name: ${session}\nrows:\n  - panes:\n      - title: Shell\n`,
+    );
+    createSession();
+
+    await restart(tmpDir, { attach: false });
+
+    const result = runJSON(["status"]);
+    expect(result.running).toBe(true);
+    expect(result.panes.length >= 1).toBeTruthy();
+
+    killSession();
+  });
+
+  it("restart applies the updated layout from ide.yml", async () => {
+    killSession();
+    writeFileSync(
+      join(tmpDir, "ide.yml"),
+      `name: ${session}\nrows:\n  - panes:\n      - title: Shell\n`,
+    );
+    await launch(tmpDir, { attach: false });
+
+    writeFileSync(
+      join(tmpDir, "ide.yml"),
+      `name: ${session}\nrows:\n  - panes:\n      - title: Claude\n      - title: Shell\n`,
+    );
+
+    await restart(tmpDir, { attach: false });
+
+    const result = runJSON(["status"]);
+    expect(result.running).toBe(true);
+    expect(result.panes.length).toBe(2);
+    expect(result.panes.map((pane) => pane.title)).toEqual(["Claude", "Shell"]);
+
+    killSession();
+  });
+
+  it("launch applies a team layout without interactive attach", async () => {
+    killSession();
+    writeFileSync(
+      join(tmpDir, "ide.yml"),
+      `name: ${session}\nteam:\n  name: test-team\nrows:\n  - panes:\n      - title: Lead\n        command: claude\n        role: lead\n      - title: Worker\n        command: claude\n        role: teammate\n        task: Review changes\n`,
+    );
+
+    await launch(tmpDir, { attach: false });
+
+    const result = runJSON(["inspect"]);
+    expect(result.valid).toBe(true);
+    expect(result.team.name).toBe("test-team");
+    expect(result.tmux.running).toBe(true);
+    expect(result.tmux.panes.map((pane) => pane.title)).toEqual(["Lead", "Worker"]);
+
+    killSession();
+  });
+
+  it("launch creates the expected pane layout for a team config", async () => {
+    killSession();
+    writeFileSync(
+      join(tmpDir, "ide.yml"),
+      `name: ${session}\nteam:\n  name: review-team\nrows:\n  - panes:\n      - title: Lead\n        command: claude\n        role: lead\n      - title: Reviewer\n        command: claude\n        role: teammate\n        task: Review the diff\n`,
+    );
+
+    await launch(tmpDir, { attach: false });
+
+    const statusResult = runJSON(["status"]);
+    const inspectResult = runJSON(["inspect"]);
+    expect(statusResult.running).toBe(true);
+    expect(statusResult.panes.length).toBe(2);
+    expect(inspectResult.team.name).toBe("review-team");
+    expect(inspectResult.summary.panes).toBe(2);
+
+    killSession();
+  });
+
+  it("stop --json kills a running session", () => {
+    createSession();
+    run(["stop"]);
+    // Verify it's gone
+    const result = runJSON(["status"]);
+    expect(result.running).toBe(false);
+  });
+
+  it("validate --json reports valid for our test config", () => {
+    const result = runJSON(["validate"]);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+  });
+
+  it("doctor --json passes checks", () => {
+    const result = runJSON(["doctor"]);
+    expect(result.ok).toBe(true);
+  });
+
+  it("config --json dumps config", () => {
+    const result = runJSON(["config"]);
+    expect(result.name).toBe(session);
+    expect(Array.isArray(result.rows)).toBeTruthy();
+  });
+
+  it("ls --json returns sessions list", () => {
+    const result = runJSON(["ls"]);
+    expect(Array.isArray(result.sessions)).toBeTruthy();
+  });
+});

package/src/js-yaml.d.ts

@@ -0,0 +1,10 @@
+declare module "js-yaml" {
+  function load(input: string): unknown;
+  function dump(
+    input: unknown,
+    options?: { lineWidth?: number; noRefs?: boolean; quotingType?: string },
+  ): string;
+  const _default: { load: typeof load; dump: typeof dump };
+  export default _default;
+  export { load, dump };
+}

package/src/launch.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, beforeEach, afterEach, expect } from "bun:test";
+import { mkdtempSync, rmSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildPaneMap, waitForPaneCommand, ensureTaskDocs } from "./launch.ts";
+
+describe("buildPaneMap", () => {
+  it("uses returned pane ids instead of assuming sequential numbering", () => {
+    const rows = [
+      {
+        size: "60%",
+        panes: [{ title: "A" }, { title: "B" }],
+      },
+      {
+        panes: [{ title: "C" }, { title: "D", dir: "apps/api" }],
+      },
+    ];
+    const splitCalls = [];
+    const returnedPaneIds = ["%42", "%99", "%7"];
+
+    const { paneMap, firstPanesOfRows } = buildPaneMap(
+      rows,
+      "/workspace",
+      "%1",
+      ({ targetPane, direction, cwd, percent }) => {
+        splitCalls.push({ targetPane, direction, cwd, percent });
+        return returnedPaneIds.shift();
+      },
+    );
+
+    expect(splitCalls).toEqual([
+      { targetPane: "%1", direction: "vertical", cwd: "/workspace", percent: 40 },
+      { targetPane: "%1", direction: "horizontal", cwd: "/workspace", percent: 50 },
+      { targetPane: "%42", direction: "horizontal", cwd: "/workspace/apps/api", percent: 50 },
+    ]);
+
+    expect(paneMap).toEqual([
+      ["%1", "%99"],
+      ["%42", "%7"],
+    ]);
+    expect([...firstPanesOfRows]).toEqual(["%1", "%42"]);
+  });
+
+  it("chains additional row splits from the returned row pane ids", () => {
+    const rows = [
+      { size: "50%", panes: [{ title: "Lead" }] },
+      { size: "30%", panes: [{ title: "Worker" }] },
+      { panes: [{ title: "Shell" }] },
+    ];
+    const splitCalls = [];
+    const returnedPaneIds = ["%21", "%34"];
+
+    const { paneMap, firstPanesOfRows } = buildPaneMap(
+      rows,
+      "/workspace",
+      "%5",
+      ({ targetPane, direction, cwd, percent }) => {
+        splitCalls.push({ targetPane, direction, cwd, percent });
+        return returnedPaneIds.shift();
+      },
+    );
+
+    expect(splitCalls).toEqual([
+      { targetPane: "%5", direction: "vertical", cwd: "/workspace", percent: 50 },
+      { targetPane: "%21", direction: "vertical", cwd: "/workspace", percent: 40 },
+    ]);
+    expect(paneMap).toEqual([["%5"], ["%21"], ["%34"]]);
+    expect([...firstPanesOfRows]).toEqual(["%5", "%21", "%34"]);
+  });
+});
+
+describe("waitForPaneCommand", () => {
+  it("returns true once the pane reports an expected command", () => {
+    const seenSleeps = [];
+    const commands = ["zsh", "zsh", "claude"];
+
+    const result = waitForPaneCommand("%1", ["claude"], {
+      attempts: 5,
+      delayMs: 25,
+      getCurrentCommand: () => commands.shift(),
+      sleep: (ms) => seenSleeps.push(ms),
+    });
+
+    expect(result).toBe(true);
+    expect(seenSleeps).toEqual([25, 25]);
+  });
+
+  it("returns false after exhausting retries", () => {
+    const seenSleeps = [];
+
+    const result = waitForPaneCommand("%1", ["claude"], {
+      attempts: 3,
+      delayMs: 10,
+      getCurrentCommand: () => "zsh",
+      sleep: (ms) => seenSleeps.push(ms),
+    });
+
+    expect(result).toBe(false);
+    expect(seenSleeps).toEqual([10, 10]);
+  });
+});
+
+describe("ensureTaskDocs", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "tmux-ide-launch-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("creates CLAUDE.md with task docs when file does not exist", () => {
+    ensureTaskDocs(tmpDir);
+    const content = readFileSync(join(tmpDir, "CLAUDE.md"), "utf-8");
+    expect(content.includes("## Task Management")).toBeTruthy();
+    expect(content.includes("tmux-ide mission set")).toBeTruthy();
+    expect(content.includes("tmux-ide task create")).toBeTruthy();
+    expect(content.includes("--proof")).toBeTruthy();
+    expect(content.includes("--depends")).toBeTruthy();
+  });
+
+  it("appends task docs to existing CLAUDE.md", () => {
+    writeFileSync(join(tmpDir, "CLAUDE.md"), "# My Project\n\nExisting content.\n");
+    ensureTaskDocs(tmpDir);
+    const content = readFileSync(join(tmpDir, "CLAUDE.md"), "utf-8");
+    expect(content.startsWith("# My Project\n\nExisting content.\n")).toBeTruthy();
+    expect(content.includes("## Task Management")).toBeTruthy();
+  });
+
+  it("does not duplicate if section already exists", () => {
+    writeFileSync(join(tmpDir, "CLAUDE.md"), "# Project\n\n## Task Management\n\nAlready here.\n");
+    ensureTaskDocs(tmpDir);
+    const content = readFileSync(join(tmpDir, "CLAUDE.md"), "utf-8");
+    const count = content.split("## Task Management").length - 1;
+    expect(count).toBe(1);
+    expect(content.includes("Already here.")).toBeTruthy();
+    expect(!content.includes("tmux-ide mission set")).toBeTruthy();
+  });
+
+  it("is idempotent when called twice", () => {
+    ensureTaskDocs(tmpDir);
+    const first = readFileSync(join(tmpDir, "CLAUDE.md"), "utf-8");
+    ensureTaskDocs(tmpDir);
+    const second = readFileSync(join(tmpDir, "CLAUDE.md"), "utf-8");
+    expect(first).toBe(second);
+  });
+});