@creativeintelligence/abbie 0.1.0

package/src/lib/tmux/bridge.ts

@@ -0,0 +1,439 @@
+/**
+ * tmux bridge - core primitives for interacting with tmux.
+ * Provides programmatic access to tmux sessions, windows, and panes.
+ */
+
+import { spawn } from "node:child_process";
+
+export interface TmuxWindow {
+  id: string;
+  index: number;
+  name: string;
+  active: boolean;
+  panes: number;
+  layout: string;
+}
+
+export interface TmuxPane {
+  index: number;
+  active: boolean;
+  width: number;
+  height: number;
+  currentCommand: string;
+  currentPath: string;
+}
+
+export interface TmuxSession {
+  name: string;
+  windows: number;
+  attached: boolean;
+  created: Date;
+}
+
+/**
+ * Execute a tmux command and return stdout.
+ */
+async function tmux(...args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("tmux", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolve(stdout.trim());
+      } else {
+        reject(new Error(`tmux ${args.join(" ")} failed: ${stderr || `exit code ${code}`}`));
+      }
+    });
+
+    proc.on("error", reject);
+  });
+}
+
+/**
+ * Check if tmux server is running.
+ */
+export async function isRunning(): Promise<boolean> {
+  try {
+    await tmux("list-sessions");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List all tmux sessions.
+ */
+export async function listSessions(): Promise<TmuxSession[]> {
+  try {
+    const output = await tmux(
+      "list-sessions",
+      "-F",
+      "#{session_name}\t#{session_windows}\t#{session_attached}\t#{session_created}",
+    );
+
+    if (!output) return [];
+
+    return output.split("\n").map((line) => {
+      const [name, windows, attached, created] = line.split("\t");
+      return {
+        name,
+        windows: parseInt(windows, 10),
+        attached: attached === "1",
+        created: new Date(parseInt(created, 10) * 1000),
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * List all windows in a session (defaults to current).
+ */
+export async function listWindows(session?: string): Promise<TmuxWindow[]> {
+  try {
+    const target = session ? ["-t", session] : [];
+    const output = await tmux(
+      "list-windows",
+      ...target,
+      "-F",
+      "#{window_id}\t#{window_index}\t#{window_name}\t#{window_active}\t#{window_panes}\t#{window_layout}",
+    );
+
+    if (!output) return [];
+
+    return output.split("\n").map((line) => {
+      const [id, index, name, active, panes, layout] = line.split("\t");
+      return {
+        id,
+        index: parseInt(index, 10),
+        name,
+        active: active === "1",
+        panes: parseInt(panes, 10),
+        layout,
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * List all panes in a window.
+ */
+export async function listPanes(window: string | number, session?: string): Promise<TmuxPane[]> {
+  try {
+    const target = session ? `${session}:${window}` : `${window}`;
+    const output = await tmux(
+      "list-panes",
+      "-t",
+      target,
+      "-F",
+      "#{pane_index}\t#{pane_active}\t#{pane_width}\t#{pane_height}\t#{pane_current_command}\t#{pane_current_path}",
+    );
+
+    if (!output) return [];
+
+    return output.split("\n").map((line) => {
+      const [index, active, width, height, currentCommand = "", currentPath = ""] =
+        line.split("\t");
+      return {
+        index: parseInt(index, 10),
+        active: active === "1",
+        width: parseInt(width, 10),
+        height: parseInt(height, 10),
+        currentCommand,
+        currentPath,
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Capture pane content (plain text, no ANSI).
+ */
+export async function capturePane(
+  window: string | number,
+  pane = 0,
+  options: { lines?: number; session?: string; startLine?: number } = {},
+): Promise<string> {
+  const { lines = 100, session, startLine } = options;
+  const target = session ? `${session}:${window}.${pane}` : `${window}.${pane}`;
+
+  // -p prints to stdout (no -e for plain text without ANSI)
+  const args = ["capture-pane", "-t", target, "-p"];
+
+  if (startLine !== undefined) {
+    args.push("-S", String(startLine));
+  } else {
+    args.push("-S", `-${lines}`);
+  }
+
+  try {
+    return await tmux(...args);
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Capture pane content with ANSI escape codes preserved.
+ */
+export async function capturePaneWithAnsi(
+  window: string | number,
+  pane = 0,
+  options: { lines?: number; session?: string; startLine?: number } = {},
+): Promise<string> {
+  const { lines = 100, session, startLine } = options;
+  const target = session ? `${session}:${window}.${pane}` : `${window}.${pane}`;
+
+  // -e preserves escape sequences (ANSI colors), -p prints to stdout
+  const args = ["capture-pane", "-t", target, "-p", "-e"];
+
+  if (startLine !== undefined) {
+    args.push("-S", String(startLine));
+  } else {
+    args.push("-S", `-${lines}`);
+  }
+
+  try {
+    return await tmux(...args);
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Send keys to a pane.
+ */
+export async function sendKeys(
+  window: string | number,
+  pane: number,
+  keys: string,
+  options: { session?: string; literal?: boolean } = {},
+): Promise<void> {
+  const { session, literal = false } = options;
+  const target = session ? `${session}:${window}.${pane}` : `${window}.${pane}`;
+
+  const args = ["send-keys", "-t", target];
+  if (literal) {
+    args.push("-l");
+  }
+  args.push(keys);
+
+  await tmux(...args);
+}
+
+/**
+ * Select a window.
+ */
+export async function selectWindow(window: string | number, session?: string): Promise<void> {
+  const target = session ? `${session}:${window}` : `${window}`;
+  await tmux("select-window", "-t", target);
+}
+
+/**
+ * Select a pane.
+ */
+export async function selectPane(
+  window: string | number,
+  pane: number,
+  session?: string,
+): Promise<void> {
+  const target = session ? `${session}:${window}.${pane}` : `${window}.${pane}`;
+  await tmux("select-pane", "-t", target);
+}
+
+/**
+ * Create a new window.
+ */
+export async function newWindow(options: {
+  name?: string;
+  cwd?: string;
+  session?: string;
+  command?: string;
+}): Promise<void> {
+  const { name, cwd, session, command } = options;
+  const args = ["new-window"];
+
+  // Trailing colon ensures tmux interprets as session (not window/pane match)
+  if (session) args.push("-t", `${session}:`);
+  if (name) args.push("-n", name);
+  if (cwd) args.push("-c", cwd);
+  if (command) args.push(command);
+
+  await tmux(...args);
+}
+
+/**
+ * Kill a window.
+ */
+export async function killWindow(window: string | number, session?: string): Promise<void> {
+  const target = session ? `${session}:${window}` : `${window}`;
+  await tmux("kill-window", "-t", target);
+}
+
+/**
+ * Reorder a window by moving it to a target index.
+ * Uses -r to renumber windows to avoid index collisions.
+ */
+export async function moveWindow(
+  sourceIndex: number,
+  targetIndex: number,
+  session?: string,
+): Promise<void> {
+  const source = session ? `${session}:${sourceIndex}` : String(sourceIndex);
+  const target = session ? `${session}:${targetIndex}` : String(targetIndex);
+  await tmux("move-window", "-r", "-s", source, "-t", target);
+}
+
+/**
+ * Move a window (by id or index string) to a target index.
+ * Prefer window ids (e.g. "@47") because indices change as we reorder.
+ */
+export async function moveWindowToIndex(
+  source: string,
+  targetIndex: number,
+  session?: string,
+): Promise<void> {
+  const sourceTarget = source.startsWith("@") ? source : session ? `${session}:${source}` : source;
+
+  const target = session ? `${session}:${targetIndex}` : String(targetIndex);
+  await tmux("move-window", "-r", "-s", sourceTarget, "-t", target);
+}
+
+/**
+ * Swap two windows by index.
+ * This is the safest way to reorder within a session because `move-window` cannot
+ * move into an index that's already in use.
+ */
+export async function swapWindows(
+  sourceIndex: number,
+  targetIndex: number,
+  session?: string,
+): Promise<void> {
+  const source = session ? `${session}:${sourceIndex}` : String(sourceIndex);
+  const target = session ? `${session}:${targetIndex}` : String(targetIndex);
+  await tmux("swap-window", "-s", source, "-t", target);
+}
+
+/**
+ * Get the current window name.
+ */
+export async function getCurrentWindow(session?: string): Promise<string | null> {
+  try {
+    const target = session ? ["-t", session] : [];
+    const output = await tmux("display-message", ...target, "-p", "#{window_name}");
+    return output || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the current pane's working directory.
+ */
+export async function getPaneCwd(
+  window: string | number,
+  pane = 0,
+  session?: string,
+): Promise<string | null> {
+  try {
+    const target = session ? `${session}:${window}.${pane}` : `${window}.${pane}`;
+    const output = await tmux("display-message", "-t", target, "-p", "#{pane_current_path}");
+    return output || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resize a pane to specific dimensions.
+ * Note: This resizes the pane within the window layout.
+ */
+export async function resizePane(
+  window: string | number,
+  pane: number,
+  cols: number,
+  rows: number,
+  session?: string,
+): Promise<void> {
+  const target = session ? `${session}:${window}.${pane}` : `${window}.${pane}`;
+  // resize-pane -x sets width, -y sets height
+  await tmux("resize-pane", "-t", target, "-x", String(cols), "-y", String(rows));
+}
+
+/**
+ * Get the pane ID (unique identifier like %0, %1, etc).
+ * Useful for nvim socket naming: /tmp/nvim-${paneId}.sock
+ */
+export async function getPaneId(
+  window: string | number,
+  pane = 0,
+  session?: string,
+): Promise<string | null> {
+  try {
+    const target = session ? `${session}:${window}.${pane}` : `${window}.${pane}`;
+    const output = await tmux("display-message", "-t", target, "-p", "#{pane_id}");
+    return output || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the pane's TTY path.
+ * Useful for correlating nvim instances to panes.
+ */
+export async function getPaneTty(
+  window: string | number,
+  pane = 0,
+  session?: string,
+): Promise<string | null> {
+  try {
+    const target = session ? `${session}:${window}.${pane}` : `${window}.${pane}`;
+    const output = await tmux("display-message", "-t", target, "-p", "#{pane_tty}");
+    return output || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get pane dimensions (width and height in columns/rows).
+ */
+export async function getPaneDimensions(
+  window: string | number,
+  pane = 0,
+  session?: string,
+): Promise<{ cols: number; rows: number } | null> {
+  try {
+    const target = session ? `${session}:${window}.${pane}` : `${window}.${pane}`;
+    const output = await tmux(
+      "display-message",
+      "-t",
+      target,
+      "-p",
+      "#{pane_width}x#{pane_height}",
+    );
+    const match = output?.match(/^(\d+)x(\d+)$/);
+    if (match) {
+      return { cols: parseInt(match[1], 10), rows: parseInt(match[2], 10) };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/tmux/context.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, test } from "bun:test";
+import { type SessionContext, type TmuxContext, toJson, toXml } from "./context.js";
+
+// Helper to create test context
+function createTestContext(overrides: Partial<TmuxContext> = {}): TmuxContext {
+  return {
+    generatedAt: "2025-01-26T12:00:00.000Z",
+    tmuxRunning: true,
+    truncated: false,
+    sessions: [],
+    ...overrides,
+  };
+}
+
+function createTestSession(name: string, windows: SessionContext["windows"] = []): SessionContext {
+  return {
+    name,
+    attached: true,
+    windows,
+  };
+}
+
+describe("toXml", () => {
+  test("generates valid XML for empty context", () => {
+    const context = createTestContext({ tmuxRunning: false });
+    const xml = toXml(context);
+
+    expect(xml).toContain("<tmux_context");
+    expect(xml).toContain('generated_at="2025-01-26T12:00:00.000Z"');
+    expect(xml).toContain('tmux_running="false"');
+    expect(xml).toContain('truncated="false"');
+    expect(xml).toContain("</tmux_context>");
+  });
+
+  test("includes truncation reason when truncated", () => {
+    const context = createTestContext({
+      truncated: true,
+      truncationReason: "max-bytes",
+    });
+    const xml = toXml(context);
+
+    expect(xml).toContain('truncated="true"');
+    expect(xml).toContain('truncation_reason="max-bytes"');
+  });
+
+  test("generates XML for session with windows and panes", () => {
+    const context = createTestContext({
+      sessions: [
+        createTestSession("work", [
+          {
+            id: "@1",
+            index: 1,
+            name: "editor",
+            active: true,
+            paneCount: 2,
+            panes: [
+              {
+                index: 0,
+                active: true,
+                cwd: "/home/user/project",
+                cmd: "nvim",
+                size: "120x40",
+                screen: "vim content here",
+                redacted: false,
+              },
+            ],
+          },
+        ]),
+      ],
+    });
+
+    const xml = toXml(context);
+
+    expect(xml).toContain('<session name="work" attached="true">');
+    expect(xml).toContain('<window id="@1" index="1" name="editor" active="true" panes="2">');
+    expect(xml).toContain(
+      '<pane index="0" active="true" cwd="/home/user/project" cmd="nvim" size="120x40">',
+    );
+    expect(xml).toContain('<screen redacted="false">');
+    expect(xml).toContain("vim content here");
+  });
+
+  test("escapes special XML characters", () => {
+    const context = createTestContext({
+      sessions: [
+        createTestSession("test&session", [
+          {
+            id: "@1",
+            index: 1,
+            name: "window<>name",
+            active: true,
+            paneCount: 1,
+            panes: [
+              {
+                index: 0,
+                active: true,
+                cwd: '/path/with"quotes',
+                cmd: "cmd'test",
+                size: "80x24",
+                screen: 'content with <tags> & "quotes"',
+                redacted: false,
+              },
+            ],
+          },
+        ]),
+      ],
+    });
+
+    const xml = toXml(context);
+
+    expect(xml).toContain('name="test&amp;session"');
+    expect(xml).toContain('name="window&lt;&gt;name"');
+    expect(xml).toContain('cwd="/path/with&quot;quotes"');
+    expect(xml).toContain('cmd="cmd&apos;test"');
+    expect(xml).toContain("content with &lt;tags&gt; &amp; &quot;quotes&quot;");
+  });
+
+  test("handles multiline screen content", () => {
+    const context = createTestContext({
+      sessions: [
+        createTestSession("test", [
+          {
+            id: "@1",
+            index: 1,
+            name: "shell",
+            active: true,
+            paneCount: 1,
+            panes: [
+              {
+                index: 0,
+                active: true,
+                cwd: "/home",
+                cmd: "zsh",
+                size: "80x24",
+                screen: "line1\nline2\nline3",
+                redacted: false,
+              },
+            ],
+          },
+        ]),
+      ],
+    });
+
+    const xml = toXml(context);
+
+    expect(xml).toContain("line1");
+    expect(xml).toContain("line2");
+    expect(xml).toContain("line3");
+  });
+
+  test("indicates redacted panes", () => {
+    const context = createTestContext({
+      sessions: [
+        createTestSession("test", [
+          {
+            id: "@1",
+            index: 1,
+            name: "shell",
+            active: true,
+            paneCount: 1,
+            panes: [
+              {
+                index: 0,
+                active: true,
+                cwd: "/home",
+                cmd: "zsh",
+                size: "80x24",
+                screen: "content with ***REDACTED***",
+                redacted: true,
+              },
+            ],
+          },
+        ]),
+      ],
+    });
+
+    const xml = toXml(context);
+    expect(xml).toContain('<screen redacted="true">');
+  });
+});
+
+describe("toJson", () => {
+  test("generates valid JSON", () => {
+    const context = createTestContext();
+    const json = toJson(context);
+    const parsed = JSON.parse(json);
+
+    expect(parsed.generatedAt).toBe("2025-01-26T12:00:00.000Z");
+    expect(parsed.tmuxRunning).toBe(true);
+    expect(parsed.truncated).toBe(false);
+    expect(parsed.sessions).toEqual([]);
+  });
+
+  test("includes all session data", () => {
+    const context = createTestContext({
+      sessions: [
+        createTestSession("work", [
+          {
+            id: "@1",
+            index: 1,
+            name: "editor",
+            active: true,
+            paneCount: 1,
+            panes: [
+              {
+                index: 0,
+                active: true,
+                cwd: "/project",
+                cmd: "nvim",
+                size: "120x40",
+                screen: "content",
+                redacted: false,
+              },
+            ],
+          },
+        ]),
+      ],
+    });
+
+    const json = toJson(context);
+    const parsed = JSON.parse(json);
+
+    expect(parsed.sessions).toHaveLength(1);
+    expect(parsed.sessions[0].name).toBe("work");
+    expect(parsed.sessions[0].windows).toHaveLength(1);
+    expect(parsed.sessions[0].windows[0].panes).toHaveLength(1);
+    expect(parsed.sessions[0].windows[0].panes[0].screen).toBe("content");
+  });
+
+  test("preserves truncation info", () => {
+    const context = createTestContext({
+      truncated: true,
+      truncationReason: "max-lines",
+    });
+
+    const json = toJson(context);
+    const parsed = JSON.parse(json);
+
+    expect(parsed.truncated).toBe(true);
+    expect(parsed.truncationReason).toBe("max-lines");
+  });
+});