tmux-ide 2.1.5 → 2.6.1

package/packages/daemon/src/tui/mirror/viewer.tsx

@@ -0,0 +1,166 @@
+/**
+ * SPIKE viewer — renders ONE live tmux pane inside an OpenTUI app.
+ *
+ * The proof for the unified-TUI architecture: a control-mode client streams
+ * the pane's bytes into a headless terminal (PaneMirror), this app draws the
+ * grid, and keystrokes are forwarded back through `send-keys`. tmux stays the
+ * multiplexer underneath; tmux-ide owns the screen.
+ *
+ * Run (needs the repo-root bunfig preload):
+ *   bun packages/daemon/src/tui/mirror/viewer.tsx --target <session>
+ * Exit with ctrl+q (everything else is forwarded to the pane).
+ */
+import { parseArgs } from "node:util";
+import { render, useKeyboard, useTerminalDimensions } from "@opentui/solid";
+import { RGBA } from "@opentui/core";
+import { createSignal, onMount, onCleanup, For } from "solid-js";
+import { ControlModeClient } from "./control-client.ts";
+import { PaneMirror, type MirrorSnapshot } from "./pane-mirror.ts";
+
+const { values } = parseArgs({ options: { target: { type: "string" } } });
+const target = values.target ?? "_spike-target";
+
+// The 16 base ANSI palette colors, mapped for OpenTUI. Higher palette
+// entries fall back to the default foreground — fine for a spike.
+const PALETTE: Array<[number, number, number]> = [
+  [40, 40, 48],
+  [220, 90, 90],
+  [110, 200, 130],
+  [220, 200, 100],
+  [110, 150, 240],
+  [190, 120, 220],
+  [100, 200, 210],
+  [200, 200, 210],
+  [120, 120, 140],
+  [250, 120, 120],
+  [140, 230, 160],
+  [240, 220, 130],
+  [140, 180, 250],
+  [220, 150, 250],
+  [130, 230, 240],
+  [240, 240, 250],
+];
+
+/** Map named OpenTUI key events to tmux send-keys names. */
+const KEYMAP: Record<string, string> = {
+  return: "Enter",
+  backspace: "BSpace",
+  tab: "Tab",
+  escape: "Escape",
+  up: "Up",
+  down: "Down",
+  left: "Left",
+  right: "Right",
+  pageup: "PgUp",
+  pagedown: "PgDn",
+  home: "Home",
+  end: "End",
+  delete: "DC",
+  space: "Space",
+};
+
+render(() => {
+  const dims = useTerminalDimensions();
+  const cols = Math.max(20, dims().width - 2);
+  const rows = Math.max(5, dims().height - 3);
+
+  const mirror = new PaneMirror(cols, rows);
+  const [snap, setSnap] = createSignal<MirrorSnapshot>(mirror.snapshot());
+  const [status, setStatus] = createSignal(`attaching to ${target}…`);
+  let pane = "";
+  let dirty = false;
+
+  const client = new ControlModeClient({
+    attachTarget: target,
+    onOutput: (p, data) => {
+      if (p === pane || pane === "") {
+        mirror.write(data);
+        dirty = true;
+      }
+    },
+    onExit: () => {
+      setStatus("control client exited");
+    },
+  });
+
+  onMount(() => {
+    (async () => {
+      try {
+        await client.start();
+        // Pin our control client's size so tmux lays the window out to match
+        // the mirror grid, then seed with the pane's current content (-e keeps
+        // colors) so we don't start from a blank screen.
+        await client.command(`refresh-client -C ${cols}x${rows}`);
+        const panes = await client.command(`list-panes -t ${target} -F "#{pane_id}"`);
+        pane = panes[0] ?? "";
+        const seed = await client.command(`capture-pane -p -e -t ${pane}`);
+        mirror.write(seed.join("\r\n") + "\r\n");
+        dirty = true;
+        setStatus(`live: ${target} ${pane}  (ctrl+q to quit)`);
+      } catch (e) {
+        setStatus(`error: ${(e as Error).message}`);
+      }
+    })();
+
+    // Coalesce bursts: redraw at most ~30fps instead of per %output event.
+    const timer = setInterval(() => {
+      if (!dirty) return;
+      dirty = false;
+      setSnap(mirror.snapshot());
+    }, 33);
+    onCleanup(() => {
+      clearInterval(timer);
+      client.dispose();
+      mirror.dispose();
+    });
+  });
+
+  useKeyboard((evt) => {
+    if (evt.ctrl && evt.name === "q") {
+      client.dispose();
+      process.exit(0);
+    }
+    if (!pane) return;
+    if (evt.ctrl && evt.name.length === 1) {
+      void client.sendKey(pane, `C-${evt.name}`).catch(() => {});
+      return;
+    }
+    const named = KEYMAP[evt.name];
+    if (named) {
+      void client.sendKey(pane, named).catch(() => {});
+      return;
+    }
+    if (evt.name.length === 1 && !evt.meta && !evt.alt) {
+      void client.sendText(pane, evt.name).catch(() => {});
+    }
+  });
+
+  const fgFor = (idx: number | null): RGBA => {
+    if (idx === null || idx < 0 || idx > 15) return RGBA.fromInts(200, 200, 210, 255);
+    const [r, g, b] = PALETTE[idx]!;
+    return RGBA.fromInts(r, g, b, 255);
+  };
+
+  return (
+    <box flexDirection="column" flexGrow={1} backgroundColor={RGBA.fromInts(18, 18, 24, 255)}>
+      <box paddingLeft={1} flexDirection="row" gap={1}>
+        <text fg={RGBA.fromInts(130, 170, 255, 255)}>tmux-ide mirror</text>
+        <text fg={RGBA.fromInts(120, 120, 140, 255)}>{status()}</text>
+      </box>
+      <box flexDirection="column" flexGrow={1} paddingLeft={1}>
+        <For each={snap().rows}>
+          {(runs) => (
+            <box flexDirection="row">
+              <For each={runs}>{(run) => <text fg={fgFor(run.fg)}>{run.text}</text>}</For>
+            </box>
+          )}
+        </For>
+      </box>
+      <box paddingLeft={1}>
+        <text fg={RGBA.fromInts(120, 120, 140, 255)}>
+          {`cursor ${snap().cursorX},${snap().cursorY} · keys forwarded · ctrl+q quits`}
+        </text>
+      </box>
+    </box>
+  );
+});

package/packages/daemon/src/tui/team/CONTROL.md

@@ -0,0 +1,50 @@
+# tmux-ide control surface
+
+A small, scriptable API over the tmux-ide fleet. Meant for agents and scripts
+that need to read cockpit state or block on a session's status.
+
+## `tmux-ide team --json`
+
+Prints the whole fleet as JSON (no TUI). Shape:
+
+```json
+{
+  "projects": [
+    {
+      "name": "web",
+      "dir": "/workspace/web",
+      "registered": true,
+      "running": true,
+      "status": "working",
+      "sessions": [{ "name": "web", "status": "working", "panes": 3, "attached": true }]
+    }
+  ]
+}
+```
+
+`status` is one of `blocked | working | done | idle | unknown`. `dir` may be
+`null` for ad-hoc sessions. Projects with no live session have `running:false`
+and an empty `sessions` array.
+
+## `tmux-ide wait agent-status <session> --status <status> [--timeout <ms>]`
+
+Blocks until `<session>` reaches `<status>`, polling every ~750ms.
+
+- `--status` — required, one of `blocked | working | done | idle | unknown`.
+- `--timeout` — milliseconds, default `60000`.
+- Exit `0` on match (prints a success line, or JSON with `--json`).
+- Exit `1` on timeout (message to stderr).
+
+A session that does not exist yet is not an error — `wait` keeps polling until
+it appears or the timeout elapses. `done` is a working→idle transition, so the
+poller keeps one status tracker alive across ticks to observe it.
+
+```bash
+tmux-ide wait agent-status build --status done --timeout 120000 && echo "build finished"
+```
+
+## `TMUX_IDE=1` env marker
+
+Sessions created by the cockpit have `TMUX_IDE=1` set in the tmux session
+environment. Agents inside a pane can check `$TMUX_IDE` to detect that they are
+running under tmux-ide.

package/packages/daemon/src/tui/team/entry.ts

@@ -0,0 +1,11 @@
+/**
+ * Front-door decision for bare `tmux-ide` / `tmux-ide start`: open the team
+ * cockpit (the multi-project TUI) instead of launching a single project.
+ *
+ * The cockpit is the default entry when there's no single-project `ide.yml` to
+ * launch here, or when `--team` forces it. When an `ide.yml` is present, bare
+ * invocation still launches that project (backward compatible).
+ */
+export function shouldOpenCockpit(hasIdeYml: boolean, teamFlag: boolean): boolean {
+  return teamFlag || !hasIdeYml;
+}

package/packages/daemon/src/tui/team/fuzzy.ts

@@ -0,0 +1,133 @@
+/**
+ * Dependency-free fuzzy subsequence matcher for the team TUI's quick-jump
+ * filter. Pure so it can be unit-tested in isolation from `index.tsx` (which
+ * runs `render(...)` on import).
+ *
+ * The match is a case-insensitive SUBSEQUENCE test: every char of the query
+ * must appear in the target in order (not necessarily contiguously). Scoring
+ * rewards matches that feel "meaningful" to a human — contiguous runs, matches
+ * anchored at the start of the string, and matches right after a separator
+ * (so typing "web" ranks the "web" in `wavyr-website` well).
+ */
+
+/** A char that starts a new "word" — a match right after one scores a bonus. */
+const SEPARATORS = new Set(["/", "-", "_", " ", "."]);
+
+export interface FuzzyMatch<T> {
+  item: T;
+  score: number;
+  positions: number[];
+}
+
+/** Per-char position bonuses. */
+const START_BONUS = 10; // matched char is the first char of the target
+const SEPARATOR_BONUS = 8; // matched char follows a separator (word start)
+const CONTIGUOUS_BONUS = 5; // matched char is adjacent to the previous match
+const BASE = 1; // every matched char is worth at least this
+
+/**
+ * Case-insensitive subsequence match of `query` against `target`.
+ *
+ * Returns `null` when `query` is not a subsequence of `target`. An empty query
+ * matches everything with score 0 and no positions. Otherwise returns the
+ * matched indices in `target` plus a heuristic score (higher is better).
+ *
+ * Uses a small dynamic program to find the highest-scoring alignment among all
+ * valid subsequences — a greedy leftmost scan would anchor on the first
+ * occurrence of each char and miss word-boundary matches (e.g. "web" should
+ * favour the "web" after the "-" in `wavyr-website`, not the leading "w").
+ */
+export function fuzzyMatch(
+  query: string,
+  target: string,
+): { score: number; positions: number[] } | null {
+  if (query.length === 0) return { score: 0, positions: [] };
+
+  const q = query.toLowerCase();
+  const t = target.toLowerCase();
+  const m = q.length;
+  const n = t.length;
+
+  /** Position-context bonus for placing a matched char at target index j. */
+  const positionBonus = (j: number): number => {
+    if (j === 0) return START_BONUS;
+    if (SEPARATORS.has(t[j - 1]!)) return SEPARATOR_BONUS;
+    return 0;
+  };
+
+  const NEG = Number.NEGATIVE_INFINITY;
+  // f[i][j] = best score for matching q[i..] with q[i] placed at target index j
+  // (only meaningful when t[j] === q[i]); nextPos[i][j] = chosen index for q[i+1].
+  const f: number[][] = [];
+  const nextPos: number[][] = [];
+  for (let i = 0; i < m; i++) {
+    f.push(new Array<number>(n).fill(NEG));
+    nextPos.push(new Array<number>(n).fill(-1));
+  }
+
+  const last = m - 1;
+  for (let j = 0; j < n; j++) {
+    if (t[j] === q[last]) f[last]![j] = BASE + positionBonus(j);
+  }
+
+  for (let i = m - 2; i >= 0; i--) {
+    const ch = q[i]!;
+    const fi = f[i]!;
+    const fnext = f[i + 1]!;
+    const ni = nextPos[i]!;
+    for (let j = 0; j < n; j++) {
+      if (t[j] !== ch) continue;
+      let best = NEG;
+      let bestNext = -1;
+      for (let j2 = j + 1; j2 < n; j2++) {
+        const sub = fnext[j2]!;
+        if (sub === NEG) continue;
+        const val = (j2 === j + 1 ? CONTIGUOUS_BONUS : 0) + sub;
+        if (val > best) {
+          best = val;
+          bestNext = j2;
+        }
+      }
+      if (best === NEG) continue; // q[i+1..] cannot be placed after j
+      fi[j] = BASE + positionBonus(j) + best;
+      ni[j] = bestNext;
+    }
+  }
+
+  // Best starting placement for q[0] (leftmost on ties, keeping it deterministic).
+  let bestScore = NEG;
+  let start = -1;
+  const f0 = f[0]!;
+  for (let j = 0; j < n; j++) {
+    if (f0[j]! > bestScore) {
+      bestScore = f0[j]!;
+      start = j;
+    }
+  }
+  if (start === -1) return null;
+
+  const positions: number[] = [];
+  let j = start;
+  for (let i = 0; i < m && j !== -1; i++) {
+    positions.push(j);
+    j = nextPos[i]![j]!;
+  }
+  return { score: bestScore, positions };
+}
+
+/**
+ * Filter `items` by `query`, keeping only fuzzy matches, sorted by score
+ * descending. The sort is STABLE — items with equal scores keep their input
+ * order. An empty query returns every item (score 0) in original order.
+ */
+export function fuzzyFilter<T>(query: string, items: T[], key: (t: T) => string): FuzzyMatch<T>[] {
+  const matches: FuzzyMatch<T>[] = [];
+  for (const item of items) {
+    const m = fuzzyMatch(query, key(item));
+    if (m) matches.push({ item, score: m.score, positions: m.positions });
+  }
+  // Stable sort by score desc: Array.prototype.sort is stable in modern JS, so
+  // equal scores preserve the push (input) order.
+  matches.sort((a, b) => b.score - a.score);
+  return matches;
+}

package/packages/daemon/src/tui/team/home.ts

@@ -0,0 +1,170 @@
+/**
+ * Pure model helpers for the cockpit's HOME screen — the surface bare
+ * `tmux-ide` opens when there's no single-project `ide.yml` to launch.
+ *
+ * The `.tsx` renders these plain-data shapes: the header's fleet rollup counts,
+ * the empty-fleet hero actions, the in-app panel keys (e/g/,), and the footer
+ * hint line. Keeping them here (io-free, opentui-free) means the header/footer/
+ * empty-state logic unit-tests as tables, and the panel keys + footer stay
+ * sourced from the grammar and the panel registry so they can't drift from the
+ * chrome binds or the widget set.
+ */
+import type { AgentStatus } from "../detect/classify.ts";
+import type { TeamProject } from "./projects.ts";
+import { GRAMMAR_KEYS } from "../../widgets/lib/grammar.ts";
+import { PANEL_POPUPS, type PanelPopup } from "../chrome/panels.ts";
+
+/** Live-session status tallies across the whole fleet, for the home header. */
+export interface FleetRollup {
+  blocked: number;
+  working: number;
+  done: number;
+  idle: number;
+  unknown: number;
+  /** Total live sessions counted. */
+  sessions: number;
+  /** Total projects (registered + ad-hoc) in the fleet. */
+  projects: number;
+}
+
+/**
+ * PURE — tally every live session's status across the fleet. Counts SESSIONS
+ * (the unit a person acts on), not panes: a project with three sessions
+ * contributes three to the rollup.
+ */
+export function fleetRollup(projects: TeamProject[]): FleetRollup {
+  const r: FleetRollup = {
+    blocked: 0,
+    working: 0,
+    done: 0,
+    idle: 0,
+    unknown: 0,
+    sessions: 0,
+    projects: projects.length,
+  };
+  for (const p of projects) {
+    for (const s of p.sessions) {
+      r[s.status] += 1;
+      r.sessions += 1;
+    }
+  }
+  return r;
+}
+
+/** A header rollup chip: a status and its count, colored by the status token. */
+export interface RollupChip {
+  status: AgentStatus;
+  count: number;
+}
+
+/** The rollup chips shown in the header, in severity order — the meaningful
+ *  agent states (blocked/working/done) plus idle to round out the total. */
+export const ROLLUP_ORDER: AgentStatus[] = ["blocked", "working", "done", "idle"];
+
+/** PURE — the ordered header chips for a rollup. */
+export function rollupChips(r: FleetRollup): RollupChip[] {
+  return ROLLUP_ORDER.map((status) => ({ status, count: r[status] }));
+}
+
+/**
+ * PURE — true when the fleet has nothing to show: no registered projects and no
+ * live sessions (ad-hoc projects only exist for live sessions, and registered
+ * projects always appear, so an empty list means a truly empty fleet). The home
+ * screen swaps to the hero box in this state.
+ */
+export function isFleetEmpty(projects: TeamProject[]): boolean {
+  return projects.length === 0;
+}
+
+/** An empty-fleet hero call-to-action: the key and what it does. */
+export interface HeroAction {
+  key: string;
+  label: string;
+}
+
+/** PURE — the empty-fleet hero's action rows. `l` opens the add-a-project-dir
+ *  prompt (the entry point to get a launchable project into the fleet). */
+export function emptyFleetActions(): HeroAction[] {
+  return [
+    { key: "n", label: "new session" },
+    { key: "l", label: "launch a project dir" },
+    { key: "q", label: "quit" },
+  ];
+}
+
+/**
+ * The cockpit's IN-APP panel keys — plain letters matched against a bare
+ * keypress in the home handler, distinct from the tmux root-table `M-e`/`M-g`/
+ * `M-,` chrome binds. `,` opens config to echo its `M-,` bind.
+ */
+export const HOME_PANEL_KEYS: Record<string, PanelPopup["widget"]> = {
+  e: "explorer",
+  g: "changes",
+  ",": "config",
+};
+
+/** PURE — the panel a home keypress opens, or null when it isn't a panel key. */
+export function panelForKey(name: string): PanelPopup["widget"] | null {
+  return HOME_PANEL_KEYS[name] ?? null;
+}
+
+/** PURE — the in-app key that opens `widget`, or "" when unbound. */
+export function keyForPanel(widget: PanelPopup["widget"]): string {
+  const found = Object.entries(HOME_PANEL_KEYS).find(([, w]) => w === widget);
+  return found ? found[0] : "";
+}
+
+/** One footer / help hint: the key glyph(s) and the verb. */
+export interface FooterHint {
+  keys: string;
+  label: string;
+}
+
+/**
+ * PURE — the panel hints, DERIVED from the panel registry + the in-app keys so
+ * adding a panel or re-keying it updates the footer and help automatically.
+ * `use` picks the label source: the terse `widget` name for the footer, the
+ * registry `label` (e.g. "⊞ Files") for the roomier help overlay.
+ */
+export function panelHints(use: "widget" | "label" = "widget"): FooterHint[] {
+  return PANEL_POPUPS.map((p) => ({
+    keys: keyForPanel(p.widget),
+    label: use === "label" ? p.label : p.widget,
+  }));
+}
+
+/**
+ * PURE — the home footer hint line. The universal verbs' KEY glyphs come from
+ * {@link GRAMMAR_KEYS} (so the footer can't advertise a key the grammar doesn't
+ * bind), interleaved with the cockpit's own session + panel keys. Rendered as a
+ * single flex row by the `.tsx`.
+ */
+export function homeFooterHints(): FooterHint[] {
+  return [
+    { keys: "↑↓", label: "nav" },
+    { keys: "↵", label: "attach/launch" },
+    { keys: "n", label: "new" },
+    { keys: "l", label: "launch" },
+    ...panelHints("widget"),
+    { keys: GRAMMAR_KEYS.filter[0]!, label: "filter" },
+    { keys: GRAMMAR_KEYS.help[0]!, label: "help" },
+    { keys: GRAMMAR_KEYS.quit[0]!, label: "quit" },
+  ];
+}
+
+/**
+ * PURE — the compact PICKER popup's footer hints. The picker ends in a
+ * switch-client + close, so it advertises that. The discoverable universal verbs
+ * (filter / help / dismiss) come from {@link GRAMMAR_KEYS} so the footer can't
+ * advertise a key the grammar doesn't bind — in particular `? help`, which
+ * surfaces the full keybindings overlay from inside the popup.
+ */
+export function pickerFooterHints(): FooterHint[] {
+  return [
+    { keys: "↵", label: "switch" },
+    { keys: "l", label: "launch" },
+    { keys: GRAMMAR_KEYS.filter[0]!, label: "find" },
+    { keys: GRAMMAR_KEYS.help[0]!, label: "help" },
+    { keys: "esc", label: "close" },
+  ];
+}