tmux-agent 0.1.0

package/src/lib/ui/popupSelect.ts

@@ -0,0 +1,561 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { tmuxExec } from "../tmux/exec";
+import { checkPopupSupport } from "./popupSupport";
+
+export type PopupSelectChoice =
+  | string
+  | { label?: string; value?: string; detail?: string };
+
+export type PopupSelectSpec = {
+  mode?: "single" | "multi";
+  title?: string;
+  message?: string;
+  prompt?: string;
+  preview?: string;
+  width?: number | string;
+  height?: number | string;
+  timeout_ms?: number;
+  wait_for_focus_timeout_ms?: number;
+  wait_for_result_timeout_ms?: number;
+  focus_poll_interval_ms?: number;
+  choices?: PopupSelectChoice[];
+  output?: "minimal" | "verbose";
+  min_selected?: number;
+  max_selected?: number;
+  allow_custom_input?: boolean;
+  custom_input_key?: string;
+  defer_if_unfocused?: boolean;
+  defer_until_pane_active?: boolean;
+  start_delay_ms?: number;
+};
+
+export type PopupSelectNormalizedSpec = {
+  mode: "single" | "multi";
+  title: string;
+  message: string;
+  prompt: string;
+  preview: string;
+  width?: number | string;
+  height?: number | string;
+  timeoutMs: number | null;
+  waitForFocusTimeoutMs: number | null;
+  waitForResultTimeoutMs: number | null;
+  focusPollIntervalMs: number;
+  output: "minimal" | "verbose";
+  minSelected: number;
+  maxSelected: number | null;
+  allowCustomInput: boolean;
+  customInputKey: string;
+  deferIfUnfocused: boolean;
+  deferUntilPaneActive: boolean;
+  startDelayMs: number;
+  choices: { label: string; value: string; detail: string }[];
+};
+
+export type PopupSelectResult = {
+  mode: "single" | "multi";
+  selectedValues: string[];
+  customInput?: string;
+  customInputVia?: string;
+};
+
+function parseNumber(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const num = Number(value.trim());
+    return Number.isFinite(num) ? num : null;
+  }
+  return null;
+}
+
+function parseBool(value: unknown, defaultValue: boolean): boolean {
+  if (value === undefined || value === null) {
+    return defaultValue;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value !== 0;
+  }
+  if (typeof value === "string") {
+    const v = value.trim().toLowerCase();
+    if (["1", "true", "yes", "y", "on"].includes(v)) {
+      return true;
+    }
+    if (["0", "false", "no", "n", "off"].includes(v)) {
+      return false;
+    }
+  }
+  return defaultValue;
+}
+
+function normalizeTimeout(value: unknown, defaultMs: number): number | null {
+  const raw = parseNumber(value);
+  const timeoutMs = raw === null ? defaultMs : Math.floor(raw);
+  if (timeoutMs <= 0) {
+    return null;
+  }
+  return timeoutMs;
+}
+
+function normalizeTimeoutFallback(value: unknown, fallback: number | null): number | null {
+  const raw = parseNumber(value);
+  if (raw === null) {
+    return fallback;
+  }
+  const timeoutMs = Math.floor(raw);
+  if (timeoutMs <= 0) {
+    return null;
+  }
+  return timeoutMs;
+}
+
+function normalizePollInterval(value: unknown, defaultMs: number): number {
+  const raw = parseNumber(value);
+  const interval = Math.floor(raw ?? defaultMs);
+  if (!Number.isFinite(interval)) {
+    return defaultMs;
+  }
+  return Math.max(50, Math.min(interval, 2000));
+}
+
+function parseSize(axis: "width" | "height", value: unknown): number | string | undefined {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  if (typeof value === "number") {
+    const n = Math.floor(value);
+    return n > 0 ? n : undefined;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return undefined;
+    }
+    if (trimmed.toLowerCase() === "auto") {
+      return undefined;
+    }
+    if (trimmed.endsWith("%")) {
+      const pctRaw = trimmed.slice(0, -1).trim();
+      const pct = Number(pctRaw);
+      if (!Number.isFinite(pct) || pct <= 0) {
+        throw new Error(`invalid ${axis}`);
+      }
+      return `${pct}%`;
+    }
+    const n = Number(trimmed);
+    if (!Number.isFinite(n) || n <= 0) {
+      throw new Error(`invalid ${axis}`);
+    }
+    return Math.floor(n);
+  }
+  return undefined;
+}
+
+function parseMode(value: unknown): "single" | "multi" {
+  const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (raw === "multi") {
+    return "multi";
+  }
+  return "single";
+}
+
+function parseOutput(value: unknown): "minimal" | "verbose" {
+  const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (raw === "verbose") {
+    return "verbose";
+  }
+  return "minimal";
+}
+
+function parseChoices(value: unknown): { label: string; value: string; detail: string }[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error("choices is required");
+  }
+  const out: { label: string; value: string; detail: string }[] = [];
+  for (let i = 0; i < value.length; i += 1) {
+    const raw = value[i] as PopupSelectChoice;
+    if (typeof raw === "string") {
+      const label = raw.trim();
+      if (!label) {
+        continue;
+      }
+      out.push({ label, value: label, detail: "" });
+      continue;
+    }
+    if (raw && typeof raw === "object") {
+      const label = String(raw.label ?? raw.value ?? "").trim();
+      const val = String(raw.value ?? raw.label ?? "").trim();
+      const detail = String(raw.detail ?? "").trim();
+      if (!label || !val) {
+        continue;
+      }
+      out.push({ label, value: val, detail });
+      continue;
+    }
+  }
+  if (out.length === 0) {
+    throw new Error("choices is empty");
+  }
+  return out;
+}
+
+export function normalizePopupSelectSpec(spec: PopupSelectSpec): PopupSelectNormalizedSpec {
+  const mode = parseMode(spec.mode);
+  const timeoutMs = normalizeTimeout(spec.timeout_ms, 3600000);
+
+  const minSelectedRaw = parseNumber(spec.min_selected);
+  const minSelected = Math.max(0, Math.floor(minSelectedRaw ?? (mode === "multi" ? 0 : 1)));
+
+  const maxSelectedRaw = parseNumber(spec.max_selected);
+  const maxSelected =
+    maxSelectedRaw === null ? null : Math.max(0, Math.floor(maxSelectedRaw));
+
+  const allowCustomInput = parseBool(spec.allow_custom_input, false);
+  const customInputKey = (spec.custom_input_key ?? "ctrl-e").trim() || "ctrl-e";
+
+  return {
+    mode,
+    title: String(spec.title ?? "Select").trim() || "Select",
+    message: String(spec.message ?? "").trim(),
+    prompt: String(spec.prompt ?? "> ").trim() || "> ",
+    preview: String(spec.preview ?? "").trim(),
+    width: parseSize("width", spec.width),
+    height: parseSize("height", spec.height),
+    timeoutMs,
+    waitForFocusTimeoutMs: normalizeTimeoutFallback(spec.wait_for_focus_timeout_ms, timeoutMs),
+    waitForResultTimeoutMs: normalizeTimeoutFallback(spec.wait_for_result_timeout_ms, timeoutMs),
+    focusPollIntervalMs: normalizePollInterval(spec.focus_poll_interval_ms, 250),
+    output: parseOutput(spec.output),
+    minSelected,
+    maxSelected,
+    allowCustomInput,
+    customInputKey,
+    deferIfUnfocused: parseBool(spec.defer_if_unfocused, true),
+    deferUntilPaneActive: parseBool(spec.defer_until_pane_active, true),
+    startDelayMs: Math.max(0, Math.floor(parseNumber(spec.start_delay_ms) ?? 0)),
+    choices: parseChoices(spec.choices)
+  };
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+type TmuxClientSnapshot = {
+  name: string;
+  tty: string;
+  flags: Set<string>;
+  sessionId: string;
+  sessionName: string;
+  windowId: string;
+  paneId: string;
+};
+
+function parseClientFlags(raw: string): Set<string> {
+  return new Set(
+    raw
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean)
+  );
+}
+
+async function listClients(): Promise<TmuxClientSnapshot[]> {
+  const fmt =
+    "#{client_name}\t#{client_tty}\t#{client_flags}\t#{session_id}\t#{session_name}\t#{window_id}\t#{pane_id}";
+  const result = await tmuxExec(["list-clients", "-F", fmt]);
+  const lines = result.stdout.split(/\r?\n/).filter((line) => line.trim().length > 0);
+  const clients: TmuxClientSnapshot[] = [];
+  for (const line of lines) {
+    const parts = line.split("\t");
+    if (parts.length !== 7) {
+      continue;
+    }
+    const [name, tty, flagsRaw, sessionId, sessionName, windowId, paneId] = parts.map((part) =>
+      part.trim()
+    );
+    if (!name) {
+      continue;
+    }
+    clients.push({
+      name,
+      tty,
+      flags: parseClientFlags(flagsRaw),
+      sessionId,
+      sessionName,
+      windowId,
+      paneId
+    });
+  }
+  return clients;
+}
+
+function pickFrontClient(clients: TmuxClientSnapshot[]): TmuxClientSnapshot | null {
+  const focused = clients.find((c) => c.flags.has("focused"));
+  if (focused) {
+    return focused;
+  }
+  if (clients.length === 1) {
+    return clients[0];
+  }
+  return null;
+}
+
+function pickClientForOrigin(
+  clients: TmuxClientSnapshot[],
+  origin: { windowId: string; paneId: string },
+  options: { requirePaneActive: boolean }
+): TmuxClientSnapshot | null {
+  const front = pickFrontClient(clients);
+  if (options.requirePaneActive) {
+    if (front && front.paneId === origin.paneId) {
+      return front;
+    }
+    for (const client of clients) {
+      if (client.paneId === origin.paneId) {
+        return client;
+      }
+    }
+    return null;
+  }
+
+  if (front && front.windowId === origin.windowId) {
+    return front;
+  }
+  for (const client of clients) {
+    if (client.windowId === origin.windowId) {
+      return client;
+    }
+  }
+  return null;
+}
+
+async function getPaneWindowId(paneId: string): Promise<string> {
+  const result = await tmuxExec(["display-message", "-p", "-t", paneId, "#{window_id}"]);
+  const windowId = result.stdout.trim();
+  if (!windowId) {
+    throw new Error("failed to resolve origin window");
+  }
+  return windowId;
+}
+
+async function resolvePopupClientTarget(
+  origin: { windowId: string; paneId: string },
+  spec: PopupSelectNormalizedSpec
+): Promise<string | undefined> {
+  const started = Date.now();
+  const requirePaneActive = spec.deferUntilPaneActive;
+
+  while (true) {
+    const clients = await listClients();
+    const candidate = pickClientForOrigin(clients, origin, { requirePaneActive });
+    if (candidate) {
+      return candidate.name;
+    }
+
+    if (!spec.deferIfUnfocused) {
+      return pickFrontClient(clients)?.name;
+    }
+
+    if (spec.waitForFocusTimeoutMs !== null && Date.now() - started >= spec.waitForFocusTimeoutMs) {
+      throw new Error("ui select timed out waiting for focus");
+    }
+
+    await sleep(spec.focusPollIntervalMs);
+  }
+}
+
+function splitChoiceLine(line: string): { label: string; value: string; detail: string } | null {
+  const [label, value, detail] = line.split("\t");
+  if (!label || !value) {
+    return null;
+  }
+  return { label, value, detail: detail ?? "" };
+}
+
+function parseFzfOutput(
+  raw: string,
+  spec: PopupSelectNormalizedSpec
+): { selected: string[]; customInput?: string; via?: string } {
+  const lines = raw
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+
+  if (!spec.allowCustomInput) {
+    const values: string[] = [];
+    for (const line of lines) {
+      const parsed = splitChoiceLine(line);
+      if (!parsed) {
+        continue;
+      }
+      values.push(parsed.value);
+    }
+    return { selected: values };
+  }
+
+  const query = lines[0] ?? "";
+  const key = lines[1] ?? "";
+  const selectedLines = lines.slice(2);
+
+  if (key && key.toLowerCase() === spec.customInputKey.toLowerCase()) {
+    const trimmed = query.trim();
+    if (!trimmed) {
+      throw new Error("custom input is empty");
+    }
+    return { selected: [], customInput: trimmed, via: spec.customInputKey };
+  }
+
+  const values: string[] = [];
+  for (const line of selectedLines) {
+    const parsed = splitChoiceLine(line);
+    if (!parsed) {
+      continue;
+    }
+    values.push(parsed.value);
+  }
+  return { selected: values, ...(query ? { query } : {}) } as {
+    selected: string[];
+    customInput?: string;
+    via?: string;
+  };
+}
+
+export async function popupSelect(spec: PopupSelectSpec): Promise<PopupSelectResult> {
+  const support = await checkPopupSupport();
+  if (!support.ok) {
+    throw new Error(support.reason || "popup is not supported");
+  }
+
+  const paneId = String(process.env.TMUX_PANE || "").trim();
+  if (!paneId) {
+    throw new Error("ui select requires tmux client context; run inside tmux");
+  }
+
+  const normalized = normalizePopupSelectSpec(spec);
+
+  const originWindowId = await getPaneWindowId(paneId);
+  const clientTarget = await resolvePopupClientTarget(
+    { windowId: originWindowId, paneId },
+    normalized
+  );
+
+  if (normalized.startDelayMs > 0) {
+    await sleep(normalized.startDelayMs);
+  }
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "agent-tmux-ui-"));
+  const inputPath = path.join(tmpDir, "choices.txt");
+  const outPath = path.join(tmpDir, "out.txt");
+  const codePath = path.join(tmpDir, "exit_code.txt");
+  const scriptPath = path.join(tmpDir, "popup.sh");
+
+  try {
+    const lines = normalized.choices
+      .map((choice) => `${choice.label}\t${choice.value}\t${choice.detail || ""}`)
+      .join("\n");
+    await fs.writeFile(inputPath, `${lines}\n`, "utf8");
+
+    const fzfArgs: string[] = [];
+    fzfArgs.push("--delimiter=\t", "--with-nth=1,3", `--prompt=${normalized.prompt}`);
+    if (normalized.mode === "multi") {
+      fzfArgs.push("--multi");
+    }
+    if (normalized.allowCustomInput) {
+      fzfArgs.push("--print-query", `--expect=${normalized.customInputKey}`);
+    }
+    if (normalized.preview) {
+      fzfArgs.push(`--preview=${normalized.preview}`);
+    }
+
+    const script = `#!/usr/bin/env bash
+set -euo pipefail
+INPUT=${JSON.stringify(inputPath)}
+OUT=${JSON.stringify(outPath)}
+CODE=${JSON.stringify(codePath)}
+set +e
+cat "$INPUT" | fzf ${fzfArgs.map((arg) => JSON.stringify(arg)).join(" ")} > "$OUT"
+EC=$?
+set -e
+printf '%s' "$EC" > "$CODE"
+exit 0
+`;
+    await fs.writeFile(scriptPath, script, { encoding: "utf8", mode: 0o700 });
+
+    const popupArgs: string[] = ["display-popup", "-E"];
+    if (clientTarget) {
+      popupArgs.push("-c", clientTarget);
+    }
+    popupArgs.push("-t", paneId, "-T", normalized.title);
+    if (normalized.width) {
+      popupArgs.push("-w", String(normalized.width));
+    }
+    if (normalized.height) {
+      popupArgs.push("-h", String(normalized.height));
+    }
+    popupArgs.push(`bash ${shellQuote(scriptPath)}`);
+
+    const popupPromise = tmuxExec(popupArgs);
+    const timeoutMs = normalized.waitForResultTimeoutMs;
+    if (timeoutMs !== null) {
+      await Promise.race([
+        popupPromise,
+        (async () => {
+          await sleep(timeoutMs);
+          throw new Error("ui select timed out");
+        })()
+      ]);
+    } else {
+      await popupPromise;
+    }
+
+    const exitCodeRaw = (await fs.readFile(codePath, "utf8")).trim();
+    const exitCode = Number(exitCodeRaw);
+    if (!Number.isFinite(exitCode) || exitCode !== 0) {
+      throw new Error("ui select cancelled");
+    }
+
+    const rawOut = await fs.readFile(outPath, "utf8");
+    const parsed = parseFzfOutput(rawOut, normalized);
+
+    const selectedValues = parsed.selected;
+    if (normalized.mode === "single" && selectedValues.length > 1) {
+      throw new Error("ui select returned multiple values for single mode");
+    }
+    if (normalized.mode === "single" && selectedValues.length === 0 && !parsed.customInput) {
+      throw new Error("no selection");
+    }
+
+    const count = parsed.customInput ? 1 : selectedValues.length;
+    if (normalized.mode === "multi") {
+      if (count < normalized.minSelected) {
+        throw new Error(`min_selected not satisfied: ${count} < ${normalized.minSelected}`);
+      }
+      if (normalized.maxSelected !== null && count > normalized.maxSelected) {
+        throw new Error(`max_selected exceeded: ${count} > ${normalized.maxSelected}`);
+      }
+    }
+
+    return {
+      mode: normalized.mode,
+      selectedValues,
+      ...(parsed.customInput ? { customInput: parsed.customInput, customInputVia: parsed.via } : {})
+    };
+  } finally {
+    try {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+}

package/src/lib/ui/popupSupport.ts

@@ -0,0 +1,84 @@
+import { spawn } from "node:child_process";
+
+export type PopupSupport = {
+  ok: boolean;
+  reason?: string;
+};
+
+function hasTmuxEnv(): boolean {
+  return Boolean(process.env.TMUX && process.env.TMUX_PANE);
+}
+
+async function runCommand(command: string, args: string[]): Promise<string> {
+  return await new Promise<string>((resolve, reject) => {
+    const child = spawn(command, args);
+    let stdout = "";
+    let stderr = "";
+    if (child.stdout) {
+      child.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+    }
+    if (child.stderr) {
+      child.stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+    }
+    child.on("error", (error) => {
+      reject(error);
+    });
+    child.on("close", (code) => {
+      const exitCode = code ?? 0;
+      if (exitCode !== 0) {
+        reject(new Error(stderr.trim() || stdout.trim() || `${command} failed`));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+async function supportsDisplayPopup(): Promise<boolean> {
+  try {
+    const output = await runCommand("tmux", ["list-commands"]);
+    return output.includes("display-popup");
+  } catch {
+    return false;
+  }
+}
+
+async function hasFzf(): Promise<boolean> {
+  try {
+    await runCommand("fzf", ["--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function checkPopupSupport(): Promise<PopupSupport> {
+  if (!hasTmuxEnv()) {
+    return {
+      ok: false,
+      reason: "ui select must run inside tmux (missing TMUX env)"
+    };
+  }
+
+  const popupSupported = await supportsDisplayPopup();
+  if (!popupSupported) {
+    return {
+      ok: false,
+      reason: "tmux does not support display-popup"
+    };
+  }
+
+  const fzfOk = await hasFzf();
+  if (!fzfOk) {
+    return {
+      ok: false,
+      reason: "fzf is required for ui select"
+    };
+  }
+
+  return { ok: true };
+}