tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/src/tui/mirror/ack-writer.ts

@@ -0,0 +1,77 @@
+/**
+ * AckWriter — ack-paced, coalescing writes into an async sink (M21.5).
+ *
+ * xterm-headless's `write()` is asynchronous: bytes queue in its WriteBuffer
+ * and parse on its own schedule, with a completion callback per write. Feeding
+ * every control-mode `%output` chunk straight in piles up unbounded entries in
+ * that internal queue during a flood. This writer paces instead: chunks
+ * arriving while a write is in flight buffer HERE, and the completion callback
+ * triggers exactly one follow-up write of everything buffered, joined. At most
+ * ONE sink write is ever outstanding, order and content are preserved
+ * byte-for-byte, and the caller (the control-channel reader loop) never waits.
+ *
+ * Pure core: the sink is injected (`term.write(data, done)` in production, a
+ * recording stub in tests); no timers, no io.
+ */
+export class AckWriter {
+  private queue: Uint8Array[] = [];
+  private inFlight = false;
+
+  /** `onAck` fires after EACH sink write completes — i.e. when those bytes are
+   *  actually visible in the sink (parsed, for xterm). Consumers that gate
+   *  rendering on "content changed" must re-arm on this, not on enqueue: with
+   *  pacing, an enqueue-time signal can be consumed before the parse lands and
+   *  the final frame would never render. */
+  constructor(
+    private readonly sink: (data: Uint8Array, done: () => void) => void,
+    private readonly onAck?: () => void,
+  ) {}
+
+  /** Enqueue bytes; writes through immediately when the sink is idle. */
+  write(data: Uint8Array): void {
+    if (data.length === 0) return;
+    this.queue.push(data);
+    this.pump();
+  }
+
+  /** Bytes buffered here awaiting the in-flight write's ack (tests only). */
+  pendingBytes(): number {
+    let n = 0;
+    for (const c of this.queue) n += c.length;
+    return n;
+  }
+
+  /** A sink write is currently outstanding (tests only). */
+  busy(): boolean {
+    return this.inFlight;
+  }
+
+  private pump(): void {
+    if (this.inFlight || this.queue.length === 0) return;
+    const chunks = this.queue;
+    this.queue = [];
+    const data = chunks.length === 1 ? chunks[0]! : concatBytes(chunks);
+    this.inFlight = true;
+    let acked = false;
+    this.sink(data, () => {
+      if (acked) return; // a double-fired callback must not unleash overlap
+      acked = true;
+      this.inFlight = false;
+      this.onAck?.();
+      this.pump();
+    });
+  }
+}
+
+/** Join byte chunks into one contiguous array (exported for tests). */
+export function concatBytes(chunks: readonly Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const c of chunks) total += c.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.length;
+  }
+  return out;
+}

package/packages/daemon/src/tui/mirror/agent-chip.ts

@@ -0,0 +1,97 @@
+/**
+ * Per-pane agent chips for the unified app (M22.3) — PURE.
+ *
+ * The fleet payload (`tmux-ide team --json`) carries per-pane agent entries
+ * (`agents: PaneAgentEntry[]`, M22.1). This module is the io-free half of the
+ * Terminal surface's pane chips: the paneId→entry join, the label builder, and
+ * the width-degrading truncation. The render side (app.tsx) styles the label
+ * with the app's own STATUS_COLOR/STATUS_GLYPH grammar — the OpenTUI-side
+ * mirror of the dock chip grammar in tui/chrome/chip.ts — so a pane chip in
+ * the app reads the same as its sidebar/home glyphs. The glyph travels IN as a
+ * parameter: this module carries no grammar constants of its own (they live
+ * with the app; see the status-grammar coordination note in the M22 board).
+ *
+ * Staleness is NOT re-implemented here: the report already applies the
+ * authority staleness window and falls back to scraping, so `state` is always
+ * the final answer — this module only joins and formats.
+ */
+import type { AgentStatus } from "../detect/classify.ts";
+
+/** The slice of a fleet `PaneAgentEntry` the chip needs (structural — the app
+ *  declares its fleet shapes locally instead of importing the data layer). */
+export interface ChipAgent {
+  /** tmux pane id (`%N`) — the mirror's pane ids are the same ids, so the join
+   *  is a straight map lookup. */
+  paneId: string;
+  /** Resolved agent kind (manifest id: `claude`, `codex`, …). */
+  kind: string;
+  /** Final per-pane status (authority when fresh, else scraped/tracked). */
+  state: AgentStatus;
+  /** Authority epoch (SECONDS) when the authority layer supplied the state;
+   *  null for scraped panes. Feeds the "blocked 4m" age suffix. */
+  since: number | null;
+}
+
+/**
+ * Flatten a fleet payload into a paneId→entry map. Tolerates sessions without
+ * an `agents` field (older payloads degrade to no chips, never a crash).
+ * First entry wins on a duplicate paneId (a session listed under two projects
+ * repeats its panes; pane ids are server-global so the entries are identical).
+ */
+export function agentsByPane(
+  projects: ReadonlyArray<{
+    sessions: ReadonlyArray<{ agents?: ReadonlyArray<ChipAgent> }>;
+  }>,
+): Map<string, ChipAgent> {
+  const map = new Map<string, ChipAgent>();
+  for (const p of projects)
+    for (const s of p.sessions)
+      for (const a of s.agents ?? []) if (!map.has(a.paneId)) map.set(a.paneId, a);
+  return map;
+}
+
+/**
+ * Compact age of a state stamp — "32s" / "4m" / "2h" / "3d" — or null when
+ * there is no authoritative timestamp (scraped pane). Negative skew clamps to
+ * "0s" rather than inventing time travel.
+ */
+export function stateAge(since: number | null, nowMs: number): string | null {
+  if (since === null) return null;
+  const s = Math.max(0, Math.floor(nowMs / 1000 - since));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+}
+
+/**
+ * Build a chip label that fits `budget` cells (the printable text, WITHOUT the
+ * one-cell padding the renderer adds each side). Degrades in steps rather than
+ * mid-word ellipsis so a narrow pane still reads:
+ *
+ *   `● claude · blocked 4m`   blocked, authority age known
+ *   `● claude · blocked`      blocked, scraped (no stamp)
+ *   `● claude`                any other state (color carries the state)
+ *   `●`                       narrow pane
+ *   null                      no room at all (or a hidden-worthy budget < 1)
+ *
+ * Only `blocked` spells its state out — it is the attention state; everything
+ * else leans on the glyph color, matching the dock chips' quiet default.
+ */
+export function chipLabel(
+  entry: ChipAgent,
+  glyph: string,
+  nowMs: number,
+  budget: number,
+): string | null {
+  const base = `${glyph} ${entry.kind}`;
+  const candidates: string[] = [];
+  if (entry.state === "blocked") {
+    const age = stateAge(entry.since, nowMs);
+    if (age) candidates.push(`${base} · blocked ${age}`);
+    candidates.push(`${base} · blocked`);
+  }
+  candidates.push(base, glyph);
+  for (const c of candidates) if (c.length <= budget) return c;
+  return null;
+}

package/packages/daemon/src/tui/mirror/agent-rows.ts

@@ -0,0 +1,133 @@
+/**
+ * The sidebar AGENTS section's pure model (M22.2) — PURE so it unit-tests
+ * without OpenTUI. app.tsx flattens the fleet payload's per-session
+ * `agents: PaneAgentEntry[]` (M22.1) into one fleet-wide list, sorts it
+ * attention-first, renders one row per agent (reusing app.tsx's existing
+ * STATUS_GLYPH / STATUS_COLOR grammar keyed by state — NOT reinvented here), and
+ * lets a click JUMP to the exact session/window/pane. Ordering, row-label
+ * truncation, state-age formatting, and the sidebar row hit-test all live here;
+ * the render/router just read them.
+ *
+ * The sort order mirrors {@link ../team/home.ts}'s `ROLLUP_ORDER` so the sidebar
+ * list and the header rollup chips agree on what "attention-first" means.
+ */
+import type { AgentStatus } from "../detect/classify.ts";
+import { ROLLUP_ORDER } from "../team/home.ts";
+
+/** The per-agent fields the sidebar needs — a structural subset of the fleet
+ *  payload's `PaneAgentEntry` (app.tsx keeps its fleet types local + io-free, so
+ *  this narrower shape is what it flattens into). */
+export interface AgentRowInput {
+  /** tmux pane id, e.g. `%5` — the exact pane a click focuses. */
+  paneId: string;
+  /** `window_index` of the tab this pane lives in — the window a click selects. */
+  windowIndex: number;
+  /** Owning session name — the workspace a click switches to. */
+  session: string;
+  /** Resolved agent kind (manifest id: `claude`, `codex`, …). */
+  kind: string;
+  /** Final per-pane status (drives the glyph + color, reusing the app grammar). */
+  state: AgentStatus;
+  /** Authority state's epoch-seconds stamp, or null for a scraped pane. */
+  since: number | null;
+}
+
+/** Attention-first rank: blocked, working, done, idle (from `ROLLUP_ORDER`), then
+ *  `unknown` last. Lower sorts earlier. */
+const STATE_RANK: Record<AgentStatus, number> = (() => {
+  const rank = {} as Record<AgentStatus, number>;
+  ROLLUP_ORDER.forEach((s, i) => (rank[s] = i));
+  rank.unknown = ROLLUP_ORDER.length;
+  return rank;
+})();
+
+/**
+ * PURE — order agents attention-first (blocked → working → done → idle →
+ * unknown), STABLE within a group so rows don't jitter between polls when states
+ * are unchanged (`Array.prototype.sort` is stable). Returns a new array; the
+ * input is untouched.
+ */
+export function sortAgentRows<T extends { state: AgentStatus }>(agents: readonly T[]): T[] {
+  return [...agents].sort((a, b) => STATE_RANK[a.state] - STATE_RANK[b.state]);
+}
+
+/**
+ * PURE — the label shown on a sidebar agent row: `"<kind> · <session>"`,
+ * truncated with a trailing ellipsis to at most `maxChars` columns (the sidebar
+ * is width-constrained and drag-resizable). `maxChars <= 0` yields "".
+ */
+export function agentRowLabel(kind: string, session: string, maxChars: number): string {
+  const full = `${kind} · ${session}`;
+  if (maxChars <= 0) return "";
+  if (full.length <= maxChars) return full;
+  if (maxChars === 1) return "…";
+  return full.slice(0, maxChars - 1) + "…";
+}
+
+/**
+ * PURE — the AGENTS section header, `"agents · <count>"`, truncated to
+ * `maxChars`. The count is always shown so the header doubles as the tally the
+ * card asks for.
+ */
+export function agentsHeaderLabel(count: number, maxChars: number): string {
+  const full = `agents · ${count}`;
+  if (maxChars <= 0) return "";
+  return full.length <= maxChars ? full : full.slice(0, Math.max(1, maxChars - 1)) + "…";
+}
+
+/** The quiet empty-state line shown under the header when no agents are running. */
+export const AGENTS_EMPTY_LINE = "no agents running — panes running claude or codex show up here";
+
+/**
+ * PURE — a compact state-age like `"blocked 4m"` from a `since` epoch-seconds
+ * stamp, for the hovered row. Returns null when there is no timestamp (a scraped
+ * pane) or the dwell rounds to zero — nothing worth showing. Granularity:
+ * seconds under a minute, then minutes, then hours.
+ */
+export function agentAgeLabel(
+  state: AgentStatus,
+  since: number | null,
+  nowSec: number,
+): string | null {
+  if (since == null) return null;
+  const secs = Math.max(0, Math.floor(nowSec - since));
+  let span: string;
+  if (secs < 60) span = `${secs}s`;
+  else if (secs < 3600) span = `${Math.floor(secs / 60)}m`;
+  else span = `${Math.floor(secs / 3600)}h`;
+  return `${state} ${span}`;
+}
+
+/** Blank rows the render leaves between the session list and the agents header
+ *  (the agents section's `marginTop`). Kept here so `sidebarHit` and the render
+ *  agree on the row the header sits on — a mismatch lands clicks one row off. */
+export const AGENTS_GAP_ROWS = 1;
+
+/** What a sidebar content row (a tab-bar-adjusted `gy`) targets. `agents-header`,
+ *  the gap row(s), and the empty-state row are inert (the router does nothing). */
+export type SidebarHit =
+  | { kind: "session"; index: number }
+  | { kind: "agent"; index: number }
+  | { kind: "agents-header" }
+  | null;
+
+/**
+ * PURE — map a sidebar content row `gy` (already `y - TABBAR_H`) to what it
+ * targets, shared by the click router and the hover resolver so a click can
+ * never land where a row isn't drawn. Layout, top to bottom: `gy 0` title,
+ * `gy 1` rule, then `sessionCount` session rows from `gy 2`, then
+ * `AGENTS_GAP_ROWS` blank row(s), then the agents section — one header row, then
+ * `agentCount` agent rows (or a single inert empty-state row when
+ * `agentCount === 0`).
+ */
+export function sidebarHit(gy: number, sessionCount: number, agentCount: number): SidebarHit {
+  if (gy < 2) return null;
+  const si = gy - 2;
+  if (si < sessionCount) return { kind: "session", index: si };
+  const headerGy = 2 + sessionCount + AGENTS_GAP_ROWS;
+  if (gy < headerGy) return null; // the gap row(s) between sessions and agents
+  if (gy === headerGy) return { kind: "agents-header" };
+  const ai = gy - headerGy - 1;
+  if (agentCount === 0 || ai < 0 || ai >= agentCount) return null;
+  return { kind: "agent", index: ai };
+}

package/packages/daemon/src/tui/mirror/app-state.ts

@@ -0,0 +1,179 @@
+/**
+ * Persisted app state for the unified IDE (M18.4) — the one small JSON that
+ * makes the app remember where you were: the last surface TAB, the workspace
+ * CONTEXT session, and the file that was open in the editor / selected in the
+ * diff panel.
+ *
+ * PURE parse/serialize live here so they unit-test as tables (like
+ * {@link ./editor-buffer.ts} / {@link ./diff-model.ts}); the io wrappers
+ * ({@link loadAppState}/{@link saveAppState}) are thin. The file lives at
+ * `~/.tmux-ide/app-state.json`, overridable via `TMUX_IDE_HOME` (tests /
+ * per-run isolation point the whole home elsewhere).
+ *
+ * {@link parseAppState} is TOLERANT: a missing file, malformed JSON, or a
+ * mistyped field each falls back to its default and it never throws — the same
+ * discipline as {@link ../../lib/app-config.ts}. Restoring stale state must
+ * never crash the launch.
+ */
+import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** The four top-level surfaces. `terminal` is the SessionMirror, `files` the
+ *  editor + file list, `diff` the git panel, `home` the fleet cockpit. */
+export type Tab = "home" | "terminal" | "files" | "diff";
+
+const TABS: readonly Tab[] = ["home", "terminal", "files", "diff"];
+
+/** PURE — is `x` one of the four tab keys? */
+export function isTab(x: unknown): x is Tab {
+  return typeof x === "string" && (TABS as readonly string[]).includes(x);
+}
+
+/** Sidebar-width bounds (M19.3). The user drags the sidebar/main boundary; the
+ *  resulting width is clamped to this range and persisted. `DEFAULT` is the
+ *  historical fixed width. */
+export const SIDEBAR_W_MIN = 16;
+export const SIDEBAR_W_MAX = 48;
+export const SIDEBAR_W_DEFAULT = 24;
+
+/** PURE — clamp a candidate sidebar width to `[SIDEBAR_W_MIN, SIDEBAR_W_MAX]`,
+ *  falling back to the default for a non-finite value. */
+export function clampSidebarWidth(w: number): number {
+  if (!Number.isFinite(w)) return SIDEBAR_W_DEFAULT;
+  return Math.max(SIDEBAR_W_MIN, Math.min(SIDEBAR_W_MAX, Math.round(w)));
+}
+
+/** How many recently-opened folders home remembers (M22.5). Oldest fall off. */
+export const RECENTS_CAP = 8;
+
+/** The persisted shape. `null` means "nothing remembered" for that slot. */
+export interface AppState {
+  /** The tab the app was showing when it last saved. */
+  lastTab: Tab;
+  /** The workspace-context session name (drives terminal target + files/diff dir). */
+  contextSession: string | null;
+  /** Absolute path of the file open in the editor. */
+  openFile: string | null;
+  /** Repo-relative path of the file selected in the diff panel. */
+  diffFile: string | null;
+  /** The sidebar column width (M19.3), clamped to the bounds above. */
+  sidebarW: number;
+  /** Recently-opened folder paths (M22.5), most-recent first, deduped and
+   *  capped at {@link RECENTS_CAP}. Home renders these under a "recent" header. */
+  recentFolders: string[];
+}
+
+export const DEFAULT_APP_STATE: AppState = {
+  lastTab: "home",
+  contextSession: null,
+  openFile: null,
+  diffFile: null,
+  sidebarW: SIDEBAR_W_DEFAULT,
+  recentFolders: [],
+};
+
+/** PURE — the recents list after opening `dir`: it moves to the front,
+ *  any earlier occurrence is removed (dedupe), and the tail past `cap` drops.
+ *  Blank paths are ignored (return the list unchanged). */
+export function addRecentFolder(
+  list: readonly string[],
+  dir: string,
+  cap: number = RECENTS_CAP,
+): string[] {
+  if (dir.length === 0) return [...list];
+  return [dir, ...list.filter((d) => d !== dir)].slice(0, cap);
+}
+
+/** PURE — a persisted recents value coerced to clean strings: non-empty,
+ *  deduped (first wins), capped. Anything not a string[] yields []. */
+function sanitizeRecents(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  const out: string[] = [];
+  for (const item of v) {
+    if (typeof item === "string" && item.length > 0 && !out.includes(item)) out.push(item);
+    if (out.length >= RECENTS_CAP) break;
+  }
+  return out;
+}
+
+/** The tmux-ide home dir: `TMUX_IDE_HOME` when set, else `~/.tmux-ide`. */
+export function appStateHome(): string {
+  return process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+}
+
+/** Absolute path to `app-state.json` under {@link appStateHome}. */
+export function appStatePath(): string {
+  return join(appStateHome(), "app-state.json");
+}
+
+/** A string field that must be non-empty, else `null`. */
+function optString(v: unknown): string | null {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+/**
+ * PURE — parse a raw JSON string into a fully-populated {@link AppState}. Any
+ * missing/mistyped field falls back to its default; invalid JSON yields the
+ * defaults. Never throws.
+ */
+export function parseAppState(raw: string): AppState {
+  let obj: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return { ...DEFAULT_APP_STATE };
+    obj = parsed as Record<string, unknown>;
+  } catch {
+    return { ...DEFAULT_APP_STATE };
+  }
+  return {
+    lastTab: isTab(obj.lastTab) ? obj.lastTab : DEFAULT_APP_STATE.lastTab,
+    contextSession: optString(obj.contextSession),
+    openFile: optString(obj.openFile),
+    diffFile: optString(obj.diffFile),
+    sidebarW:
+      typeof obj.sidebarW === "number"
+        ? clampSidebarWidth(obj.sidebarW)
+        : DEFAULT_APP_STATE.sidebarW,
+    recentFolders: sanitizeRecents(obj.recentFolders),
+  };
+}
+
+/** PURE — serialize an {@link AppState} to the exact four-key JSON we persist
+ *  (extra runtime keys are dropped; stable key order for tidy diffs). */
+export function serializeAppState(state: AppState): string {
+  const clean: AppState = {
+    lastTab: isTab(state.lastTab) ? state.lastTab : "home",
+    contextSession: optString(state.contextSession),
+    openFile: optString(state.openFile),
+    diffFile: optString(state.diffFile),
+    sidebarW: clampSidebarWidth(state.sidebarW),
+    recentFolders: sanitizeRecents(state.recentFolders),
+  };
+  return JSON.stringify(clean, null, 2);
+}
+
+/** Read the persisted state (one-shot at launch — NOT on the render loop).
+ *  Missing/unreadable file → defaults. */
+export function loadAppState(): AppState {
+  const path = appStatePath();
+  if (!existsSync(path)) return { ...DEFAULT_APP_STATE };
+  try {
+    return parseAppState(readFileSync(path, "utf8"));
+  } catch {
+    return { ...DEFAULT_APP_STATE };
+  }
+}
+
+/** Write the state asynchronously (debounced by the caller), creating the home
+ *  dir if needed. Swallows io errors — persistence is best-effort. */
+export async function saveAppState(state: AppState): Promise<void> {
+  const path = appStatePath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    await writeFile(path, serializeAppState(state));
+  } catch {
+    // best-effort: a failed save must never disturb the running app
+  }
+}