tmux-ide 1.0.0

package/src/lib/yaml-io.js

@@ -0,0 +1,26 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import yaml from "js-yaml";
+
+export function readConfig(dir) {
+  const configPath = resolve(dir, "ide.yml");
+  const raw = readFileSync(configPath, "utf-8");
+  const config = yaml.load(raw);
+  return { config, configPath };
+}
+
+export function writeConfig(dir, config) {
+  const configPath = resolve(dir, "ide.yml");
+  const out = yaml.dump(config, { lineWidth: -1, noRefs: true, quotingType: '"' });
+  writeFileSync(configPath, out);
+  return configPath;
+}
+
+export function getSessionName(dir) {
+  try {
+    const { config } = readConfig(dir);
+    return config.name ?? basename(dir);
+  } catch {
+    return basename(dir);
+  }
+}

package/src/ls.js

@@ -0,0 +1,42 @@
+import { execSync } from "node:child_process";
+
+export async function ls({ json } = {}) {
+  let raw;
+  try {
+    raw = execSync(
+      'tmux list-sessions -F "#{session_name}|#{session_created}|#{session_attached}"',
+      { encoding: "utf-8" }
+    ).trim();
+  } catch {
+    if (json) {
+      console.log(JSON.stringify({ sessions: [] }));
+    } else {
+      console.log("No tmux sessions running.");
+    }
+    return;
+  }
+
+  const sessions = raw.split("\n").map((line) => {
+    const [name, created, attached] = line.split("|");
+    return {
+      name,
+      created: new Date(parseInt(created) * 1000).toISOString(),
+      attached: attached !== "0",
+    };
+  });
+
+  if (json) {
+    console.log(JSON.stringify({ sessions }, null, 2));
+    return;
+  }
+
+  // Table output
+  console.log("SESSION".padEnd(24) + "CREATED".padEnd(22) + "ATTACHED");
+  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")
+    );
+  }
+}

package/src/restart.js

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

package/src/status.js

@@ -0,0 +1,53 @@
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { getSessionName } from "./lib/yaml-io.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;
+  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 {}
+
+  const data = { session, running, configExists, panes };
+
+  if (json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  console.log(`Session: ${session}`);
+  console.log(`Running: ${running ? "yes" : "no"}`);
+  console.log(`Config:  ${configExists ? "ide.yml found" : "no ide.yml"}`);
+
+  if (panes.length > 0) {
+    console.log(`\nPanes:`);
+    for (const p of panes) {
+      const active = p.active ? " (active)" : "";
+      console.log(`  ${p.index}: ${p.title} [${p.width}x${p.height}]${active}`);
+    }
+  }
+}

package/src/stop.js

@@ -0,0 +1,23 @@
+import { resolve } from "node:path";
+import { execSync } from "node:child_process";
+import { getSessionName } from "./lib/yaml-io.js";
+
+export async function stop(targetDir, { json } = {}) {
+  const dir = resolve(targetDir ?? ".");
+  const session = getSessionName(dir);
+
+  try {
+    execSync(`tmux kill-session -t "${session}"`, { stdio: "inherit" });
+    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`);
+    }
+  }
+}

package/src/validate.js

@@ -0,0 +1,170 @@
+import { resolve } from "node:path";
+import { readConfig } from "./lib/yaml-io.js";
+import { outputError } from "./lib/output.js";
+
+export function validateConfig(config) {
+  const errors = [];
+
+  if (config == null || typeof config !== "object" || Array.isArray(config)) {
+    errors.push("config must be an object");
+    return errors;
+  }
+
+  if (config.name !== undefined && typeof config.name !== "string") {
+    errors.push("'name' must be a string");
+  }
+
+  if (config.before !== undefined && typeof config.before !== "string") {
+    errors.push("'before' must be a string");
+  }
+
+  if (!Array.isArray(config.rows)) {
+    errors.push("'rows' must be an array");
+  } else if (config.rows.length === 0) {
+    errors.push("'rows' must not be empty");
+  } else {
+    for (let i = 0; i < config.rows.length; i++) {
+      const row = config.rows[i];
+      if (!row.panes || !Array.isArray(row.panes)) {
+        errors.push(`rows[${i}].panes must be an array`);
+        continue;
+      }
+      if (row.panes.length === 0) {
+        errors.push(`rows[${i}].panes must not be empty`);
+      }
+      if (row.size !== undefined) {
+        validateSize(row.size, `rows[${i}].size`, errors);
+      }
+      for (let j = 0; j < row.panes.length; j++) {
+        const pane = row.panes[j];
+        if (pane.title !== undefined && typeof pane.title !== "string") {
+          errors.push(`rows[${i}].panes[${j}].title must be a string`);
+        }
+        if (pane.command !== undefined && typeof pane.command !== "string") {
+          errors.push(`rows[${i}].panes[${j}].command must be a string`);
+        }
+        if (pane.dir !== undefined && typeof pane.dir !== "string") {
+          errors.push(`rows[${i}].panes[${j}].dir must be a string`);
+        }
+        if (pane.focus !== undefined && typeof pane.focus !== "boolean") {
+          errors.push(`rows[${i}].panes[${j}].focus must be a boolean`);
+        }
+        if (pane.env !== undefined) {
+          if (pane.env == null || typeof pane.env !== "object" || Array.isArray(pane.env)) {
+            errors.push(`rows[${i}].panes[${j}].env must be an object`);
+          } else {
+            for (const [key, val] of Object.entries(pane.env)) {
+              if (typeof val !== "string" && typeof val !== "number") {
+                errors.push(`rows[${i}].panes[${j}].env.${key} must be a string or number`);
+              }
+            }
+          }
+        }
+        if (pane.size !== undefined) {
+          validateSize(pane.size, `rows[${i}].panes[${j}].size`, errors);
+        }
+        if (pane.role !== undefined) {
+          if (pane.role !== "lead" && pane.role !== "teammate") {
+            errors.push(`rows[${i}].panes[${j}].role must be "lead" or "teammate"`);
+          }
+        }
+        if (pane.task !== undefined && typeof pane.task !== "string") {
+          errors.push(`rows[${i}].panes[${j}].task must be a string`);
+        }
+      }
+    }
+  }
+
+  // Validate team config
+  if (config.team !== undefined) {
+    if (config.team == null || typeof config.team !== "object" || Array.isArray(config.team)) {
+      errors.push("'team' must be an object");
+    } else {
+      if (config.team.name === undefined) {
+        errors.push("'team.name' is required when team is specified");
+      } else if (typeof config.team.name !== "string") {
+        errors.push("'team.name' must be a string");
+      }
+      if (config.team.model !== undefined && typeof config.team.model !== "string") {
+        errors.push("'team.model' must be a string");
+      }
+      if (config.team.permissions !== undefined && !Array.isArray(config.team.permissions)) {
+        errors.push("'team.permissions' must be an array");
+      }
+    }
+  }
+
+  // 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");
+    } else {
+      for (const key of ["accent", "border", "bg", "fg"]) {
+        if (config.theme[key] !== undefined && typeof config.theme[key] !== "string") {
+          errors.push(`theme.${key} must be a string`);
+        }
+      }
+    }
+  }
+
+  return errors;
+}
+
+function validateSize(value, path, errors) {
+  const s = String(value);
+  if (!/^\d+%$/.test(s)) {
+    errors.push(`${path} "${value}" must be a percentage (e.g. "50%")`);
+    return;
+  }
+  const num = parseInt(s, 10);
+  if (num === 0) {
+    errors.push(`${path} must not be 0%`);
+  } else if (num > 100) {
+    errors.push(`${path} must not exceed 100%`);
+  }
+}
+
+export async function validate(targetDir, { json } = {}) {
+  const dir = resolve(targetDir ?? ".");
+  let config;
+
+  try {
+    ({ config } = readConfig(dir));
+  } catch (e) {
+    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR", { json });
+    return;
+  }
+
+  const errors = validateConfig(config);
+  const valid = errors.length === 0;
+
+  if (json) {
+    console.log(JSON.stringify({ valid, errors }, null, 2));
+    return;
+  }
+
+  if (valid) {
+    console.log("✓ ide.yml is valid");
+  } else {
+    console.log("✗ ide.yml has errors:");
+    for (const e of errors) {
+      console.log(`  - ${e}`);
+    }
+    process.exitCode = 1;
+  }
+}

package/src/validate.test.js

@@ -0,0 +1,141 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { validateConfig } from "./validate.js";
+
+describe("validateConfig", () => {
+  it("accepts a valid minimal config", () => {
+    const errors = validateConfig({ rows: [{ panes: [{}] }] });
+    assert.deepStrictEqual(errors, []);
+  });
+
+  it("accepts a valid full config", () => {
+    const errors = validateConfig({
+      name: "my-project",
+      before: "pnpm install",
+      rows: [
+        {
+          size: "70%",
+          panes: [
+            { title: "Editor", command: "vim", dir: "src", size: "60%", focus: true, env: { PORT: 3000, HOST: "localhost" } },
+            { title: "Shell" },
+          ],
+        },
+        {
+          panes: [{ title: "Dev", command: "pnpm dev" }],
+        },
+      ],
+      theme: { accent: "colour75", border: "colour238", bg: "colour235", fg: "colour248" },
+    });
+    assert.deepStrictEqual(errors, []);
+  });
+
+  it("rejects null config", () => {
+    const errors = validateConfig(null);
+    assert.deepStrictEqual(errors, ["config must be an object"]);
+  });
+
+  it("rejects string config", () => {
+    const errors = validateConfig("hello");
+    assert.deepStrictEqual(errors, ["config must be an object"]);
+  });
+
+  it("rejects array config", () => {
+    const errors = validateConfig([]);
+    assert.deepStrictEqual(errors, ["config must be an object"]);
+  });
+
+  it("requires rows to be an array", () => {
+    const errors = validateConfig({ rows: "nope" });
+    assert.ok(errors.includes("'rows' must be an array"));
+  });
+
+  it("requires rows to be non-empty", () => {
+    const errors = validateConfig({ rows: [] });
+    assert.ok(errors.includes("'rows' must not be empty"));
+  });
+
+  it("requires rows to have a panes array", () => {
+    const errors = validateConfig({ rows: [{}] });
+    assert.ok(errors.includes("rows[0].panes must be an array"));
+  });
+
+  it("requires panes to be non-empty", () => {
+    const errors = validateConfig({ rows: [{ panes: [] }] });
+    assert.ok(errors.includes("rows[0].panes must not be empty"));
+  });
+
+  it("rejects non-string name", () => {
+    const errors = validateConfig({ name: 123, rows: [{ panes: [{}] }] });
+    assert.ok(errors.includes("'name' must be a string"));
+  });
+
+  it("rejects non-string before", () => {
+    const errors = validateConfig({ before: true, rows: [{ panes: [{}] }] });
+    assert.ok(errors.includes("'before' must be a string"));
+  });
+
+  it("rejects non-string pane.title", () => {
+    const errors = validateConfig({ rows: [{ panes: [{ title: 42 }] }] });
+    assert.ok(errors.includes("rows[0].panes[0].title must be a string"));
+  });
+
+  it("rejects non-string pane.command", () => {
+    const errors = validateConfig({ rows: [{ panes: [{ command: false }] }] });
+    assert.ok(errors.includes("rows[0].panes[0].command must be a string"));
+  });
+
+  it("rejects non-string pane.dir", () => {
+    const errors = validateConfig({ rows: [{ panes: [{ dir: [] }] }] });
+    assert.ok(errors.includes("rows[0].panes[0].dir must be a string"));
+  });
+
+  it("rejects non-boolean pane.focus", () => {
+    const errors = validateConfig({ rows: [{ panes: [{ focus: "yes" }] }] });
+    assert.ok(errors.includes("rows[0].panes[0].focus must be a boolean"));
+  });
+
+  it("rejects non-object pane.env", () => {
+    const errors = validateConfig({ rows: [{ panes: [{ env: "PORT=3000" }] }] });
+    assert.ok(errors.includes("rows[0].panes[0].env must be an object"));
+  });
+
+  it("rejects invalid env values", () => {
+    const errors = validateConfig({ rows: [{ panes: [{ env: { PORT: true } }] }] });
+    assert.ok(errors.includes("rows[0].panes[0].env.PORT must be a string or number"));
+  });
+
+  it("rejects size without % suffix", () => {
+    const errors = validateConfig({ rows: [{ size: "70", panes: [{}] }] });
+    assert.ok(errors.some((e) => e.includes('must be a percentage')));
+  });
+
+  it("rejects 0% size", () => {
+    const errors = validateConfig({ rows: [{ size: "0%", panes: [{}] }] });
+    assert.ok(errors.some((e) => e.includes("must not be 0%")));
+  });
+
+  it("rejects >100% size", () => {
+    const errors = validateConfig({ rows: [{ panes: [{ size: "150%" }] }] });
+    assert.ok(errors.some((e) => e.includes("must not exceed 100%")));
+  });
+
+  it("validates theme fields as strings", () => {
+    const errors = validateConfig({ rows: [{ panes: [{}] }], theme: { accent: 123 } });
+    assert.ok(errors.includes("theme.accent must be a string"));
+  });
+
+  it("rejects non-object theme", () => {
+    const errors = validateConfig({ rows: [{ panes: [{}] }], theme: "blue" });
+    assert.ok(errors.includes("'theme' must be an object"));
+  });
+
+  it("collects multiple errors at once", () => {
+    const errors = validateConfig({
+      name: 123,
+      before: [],
+      rows: [{ panes: [{ title: 42, focus: "yes", size: "0%" }] }],
+      theme: "nope",
+    });
+    assert.ok(errors.length >= 4);
+  });
+});

package/templates/agent-team-monorepo.yml

@@ -0,0 +1,31 @@
+name: my-monorepo
+
+team:
+  name: my-monorepo
+
+rows:
+  - size: 70%
+    panes:
+      - title: Lead — Architect
+        command: claude
+        role: lead
+        focus: true
+      - title: Frontend Agent
+        command: claude
+        role: teammate
+        task: "Work on the frontend application"
+        dir: apps/web
+      - title: Backend Agent
+        command: claude
+        role: teammate
+        task: "Work on the backend services"
+        dir: apps/api
+
+  - panes:
+      - title: Frontend
+        command: pnpm dev
+        dir: apps/web
+      - title: Backend
+        command: pnpm dev
+        dir: apps/api
+      - title: Shell

package/templates/agent-team-nextjs.yml

@@ -0,0 +1,27 @@
+name: my-app
+
+team:
+  name: my-app
+
+before: pnpm install
+
+rows:
+  - size: 70%
+    panes:
+      - title: Lead
+        command: claude
+        role: lead
+        focus: true
+      - title: Frontend
+        command: claude
+        role: teammate
+        task: "Work on React components and pages"
+      - title: Backend
+        command: claude
+        role: teammate
+        task: "Work on API routes and server logic"
+
+  - panes:
+      - title: Next.js
+        command: pnpm dev
+      - title: Shell

package/templates/agent-team.yml

@@ -0,0 +1,23 @@
+name: my-project
+
+team:
+  name: my-project
+
+rows:
+  - size: 70%
+    panes:
+      - title: Lead
+        command: claude
+        role: lead
+        focus: true
+      - title: Teammate 1
+        command: claude
+        role: teammate
+      - title: Teammate 2
+        command: claude
+        role: teammate
+
+  - panes:
+      - title: Dev Server
+        # command: npm run dev
+      - title: Shell

package/templates/convex.yml

@@ -0,0 +1,19 @@
+name: my-app
+
+rows:
+  - size: 70%
+    panes:
+      - title: Claude 1 — feature
+        command: claude
+      - title: Claude 2 — review
+        command: claude
+      - title: Claude 3 — explore
+        command: claude
+
+  - panes:
+      - title: Next.js
+        command: pnpm dev
+      - title: Convex
+        command: npx convex dev
+      - title: Shell
+        focus: true

package/templates/default.yml

@@ -0,0 +1,20 @@
+name: my-project
+
+# before: npm install  # optional pre-launch hook
+
+rows:
+  - size: 70%
+    panes:
+      - title: Claude 1
+        command: claude
+      - title: Claude 2
+        command: claude
+
+  - panes:
+      - title: Dev Server
+        # command: npm run dev
+        # dir: apps/web       # per-pane working directory
+        # env:                 # per-pane environment variables
+        #   PORT: 3000
+      - title: Shell
+        # focus: true          # give this pane initial focus

package/templates/go.yml

@@ -0,0 +1,15 @@
+name: my-app
+
+rows:
+  - size: 70%
+    panes:
+      - title: Claude 1 — feature
+        command: claude
+      - title: Claude 2 — review
+        command: claude
+
+  - panes:
+      - title: Go
+        command: go run .
+      - title: Shell
+        focus: true

package/templates/nextjs.yml

@@ -0,0 +1,17 @@
+name: my-app
+
+rows:
+  - size: 70%
+    panes:
+      - title: Claude 1 — feature
+        command: claude
+      - title: Claude 2 — review
+        command: claude
+      - title: Claude 3 — explore
+        command: claude
+
+  - panes:
+      - title: Next.js
+        command: pnpm dev
+      - title: Shell
+        focus: true

package/templates/python.yml

@@ -0,0 +1,15 @@
+name: my-app
+
+rows:
+  - size: 70%
+    panes:
+      - title: Claude 1 — feature
+        command: claude
+      - title: Claude 2 — review
+        command: claude
+
+  - panes:
+      - title: Server
+        # command: uvicorn main:app --reload
+      - title: Shell
+        focus: true

package/templates/vite.yml

@@ -0,0 +1,15 @@
+name: my-app
+
+rows:
+  - size: 70%
+    panes:
+      - title: Claude 1 — feature
+        command: claude
+      - title: Claude 2 — review
+        command: claude
+
+  - panes:
+      - title: Vite
+        command: pnpm dev
+      - title: Shell
+        focus: true