tmux-ide 2.6.1 → 2.8.0

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

@@ -0,0 +1,155 @@
+/**
+ * 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;
+  /** Self-reported one-liner (`@agent_status_text`, sanitized by the report;
+   *  dropped with a stale authority stamp). Rides to the pane chips (M25.4). */
+  statusText?: string;
+  /** Self-reported display name (`@agent_display_name`) — row-label precedence
+   *  over the detected `kind` ({@link agentDisplayKind}). */
+  displayName?: string;
+}
+
+/** PURE — what an agent row is CALLED: the self-reported display name when one
+ *  is stamped (and fresh — the report already applied staleness), else the
+ *  detected kind. The one precedence rule every label surface shares. */
+export function agentDisplayKind(a: Pick<AgentRowInput, "kind" | "displayName">): string {
+  return a.displayName ?? a.kind;
+}
+
+/** 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";
+
+/** The always-present spawn chip on the AGENTS header row (and the empty-state
+ *  row) — THE discoverable "start a new agent" entry (M24.1). Right-aligned;
+ *  the render and the router share its span via `spansFromRight`. */
+export const AGENTS_ADD_CHIP = "[+ agent]";
+
+/**
+ * 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. The gap
+ *  row(s) are inert; `agents-header` opens the Team dialog (its right-aligned
+ *  `[+ agent]` chip spawns — the router x-tests the chip span first), and
+ *  `agents-empty` is the empty-state row (inert except its chip). */
+export type SidebarHit =
+  | { kind: "session"; index: number }
+  | { kind: "agent"; index: number }
+  | { kind: "agents-header" }
+  | { kind: "agents-empty" }
+  | 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 empty-state row when `agentCount === 0`,
+ * hit-tested as `agents-empty` so its `[+ agent]` chip stays clickable).
+ */
+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) return ai === 0 ? { kind: "agents-empty" } : null;
+  if (ai < 0 || ai >= agentCount) return null;
+  return { kind: "agent", index: ai };
+}

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

@@ -0,0 +1,342 @@
+/**
+ * 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";
+import { isSpawnWhere, type LastSpawn } from "./agent-lifecycle.ts";
+
+/** 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;
+
+/** How many per-context "again" spawn memories persist (M24.1). Oldest fall off. */
+export const SPAWN_MEMORY_CAP = 20;
+
+/** How many custom spawn commands the recents list keeps (M24.1, global). */
+export const CUSTOM_COMMANDS_CAP = 5;
+
+/** How many palette actions the usage history remembers (M24.4). LRU by
+ *  last use — the map is insertion-ordered oldest-first, like lastSpawns. */
+export const PALETTE_USAGE_CAP = 50;
+
+/** One palette action's usage record (M24.4): how often it ran and when last.
+ *  Keyed by the STABLE action key ({@link ./palette.ts}'s paletteActionKey) so
+ *  a relabeled action keeps its history. */
+export interface PaletteUsageEntry {
+  count: number;
+  /** Epoch seconds of the most recent run. */
+  lastUsed: number;
+}
+
+/** 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[];
+  /** The "again" memory (M24.1): spawn-context key (a project/session dir, or
+   *  `session:<name>` when no dir is known) → the last spawn there. Insertion-
+   *  ordered LRU capped at {@link SPAWN_MEMORY_CAP}. */
+  lastSpawns: Record<string, LastSpawn>;
+  /** Recent CUSTOM spawn commands (M24.1), most-recent first, deduped, global
+   *  (not per-project), capped at {@link CUSTOM_COMMANDS_CAP}. */
+  customCommands: string[];
+  /** Palette usage history (M24.4): stable action key → {count, lastUsed}.
+   *  Insertion-ordered LRU (oldest first) capped at {@link PALETTE_USAGE_CAP};
+   *  drives the empty-query "recent" group and the ranking tie-break. */
+  paletteUsage: Record<string, PaletteUsageEntry>;
+  /** Files surface (M24.6): show dotfiles (H toggle). Default hidden. */
+  filesShowHidden: boolean;
+  /** Files surface (M24.6): show gitignored entries (I toggle). Default hidden. */
+  filesShowIgnored: boolean;
+}
+
+export const DEFAULT_APP_STATE: AppState = {
+  lastTab: "home",
+  contextSession: null,
+  openFile: null,
+  diffFile: null,
+  sidebarW: SIDEBAR_W_DEFAULT,
+  recentFolders: [],
+  lastSpawns: {},
+  customCommands: [],
+  paletteUsage: {},
+  filesShowHidden: false,
+  filesShowIgnored: false,
+};
+
+/** PURE — the "again" memory key for a spawn context: the concrete dir when
+ *  known, else the session name (namespaced so a dirless session can't collide
+ *  with a path), else null — nothing stable to remember under. */
+export function spawnMemoryKey(dir: string | null, session?: string): string | null {
+  if (dir && dir.length > 0) return dir;
+  if (session && session.length > 0) return `session:${session}`;
+  return null;
+}
+
+/**
+ * PURE — the spawn-memory map after remembering `spawn` under `key`: the key
+ * moves to newest (re-inserted last), and when the map outgrows `cap` the
+ * OLDEST entries drop (JS objects preserve string-key insertion order — the
+ * same order JSON round-trips, so the LRU survives restarts).
+ */
+export function rememberSpawn(
+  map: Readonly<Record<string, LastSpawn>>,
+  key: string,
+  spawn: LastSpawn,
+  cap: number = SPAWN_MEMORY_CAP,
+): Record<string, LastSpawn> {
+  const out: Record<string, LastSpawn> = {};
+  for (const [k, v] of Object.entries(map)) if (k !== key) out[k] = v;
+  out[key] = spawn;
+  const keys = Object.keys(out);
+  for (let i = 0; i < keys.length - cap; i++) delete out[keys[i]!];
+  return out;
+}
+
+/**
+ * PURE — the palette-usage map after running the action keyed `key` at
+ * `nowSec`: count bumps, lastUsed updates, and the key moves to newest
+ * (re-inserted last — the rememberSpawn LRU idiom, so JSON round-trips keep the
+ * eviction order). Past `cap`, the OLDEST-used entries drop. Blank keys no-op.
+ */
+export function recordPaletteUse(
+  map: Readonly<Record<string, PaletteUsageEntry>>,
+  key: string,
+  nowSec: number,
+  cap: number = PALETTE_USAGE_CAP,
+): Record<string, PaletteUsageEntry> {
+  if (key.length === 0) return { ...map };
+  const out: Record<string, PaletteUsageEntry> = {};
+  for (const [k, v] of Object.entries(map)) if (k !== key) out[k] = v;
+  out[key] = { count: (map[key]?.count ?? 0) + 1, lastUsed: nowSec };
+  const keys = Object.keys(out);
+  for (let i = 0; i < keys.length - cap; i++) delete out[keys[i]!];
+  return out;
+}
+
+/** PURE — a persisted palette-usage value coerced clean: non-object → {},
+ *  entries with a mistyped/non-finite count or lastUsed drop, order kept,
+ *  capped from the OLD end (like sanitizeSpawns). */
+function sanitizePaletteUsage(v: unknown): Record<string, PaletteUsageEntry> {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+  const out: Record<string, PaletteUsageEntry> = {};
+  for (const [key, raw] of Object.entries(v as Record<string, unknown>)) {
+    if (key.length === 0) continue;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const o = raw as Record<string, unknown>;
+    if (typeof o.count !== "number" || !Number.isFinite(o.count) || o.count < 1) continue;
+    if (typeof o.lastUsed !== "number" || !Number.isFinite(o.lastUsed)) continue;
+    out[key] = { count: Math.floor(o.count), lastUsed: Math.floor(o.lastUsed) };
+  }
+  const keys = Object.keys(out);
+  for (let i = 0; i < keys.length - PALETTE_USAGE_CAP; i++) delete out[keys[i]!];
+  return out;
+}
+
+/** PURE — the custom-command recents after running `command`: moved to the
+ *  front, deduped, capped. Blank commands leave the list unchanged. */
+export function addCustomCommand(
+  list: readonly string[],
+  command: string,
+  cap: number = CUSTOM_COMMANDS_CAP,
+): string[] {
+  const cmd = command.trim();
+  if (cmd.length === 0) return [...list];
+  return [cmd, ...list.filter((c) => c !== cmd)].slice(0, cap);
+}
+
+/** PURE — one persisted spawn coerced to a clean {@link LastSpawn}, or null
+ *  when any field is missing/mistyped (the whole entry drops). */
+function sanitizeSpawn(v: unknown): LastSpawn | null {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  const o = v as Record<string, unknown>;
+  if (typeof o.kind !== "string" || o.kind.length === 0) return null;
+  if (typeof o.command !== "string" || o.command.length === 0) return null;
+  if (!isSpawnWhere(o.placement)) return null;
+  return { kind: o.kind, command: o.command, placement: o.placement };
+}
+
+/** PURE — a persisted spawn-memory value coerced clean: non-object → {},
+ *  malformed entries drop, order kept, capped from the OLD end. */
+function sanitizeSpawns(v: unknown): Record<string, LastSpawn> {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+  const out: Record<string, LastSpawn> = {};
+  for (const [key, raw] of Object.entries(v as Record<string, unknown>)) {
+    if (key.length === 0) continue;
+    const spawn = sanitizeSpawn(raw);
+    if (spawn) out[key] = spawn;
+  }
+  const keys = Object.keys(out);
+  for (let i = 0; i < keys.length - SPAWN_MEMORY_CAP; i++) delete out[keys[i]!];
+  return out;
+}
+
+/** PURE — a persisted string list coerced clean: non-empty, deduped (first
+ *  wins), capped at `cap`. Anything not a string[] yields []. */
+function sanitizeStringList(v: unknown, cap: number): 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 >= cap) break;
+  }
+  return out;
+}
+
+/** 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[] {
+  return sanitizeStringList(v, RECENTS_CAP);
+}
+
+/** 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),
+    lastSpawns: sanitizeSpawns(obj.lastSpawns),
+    customCommands: sanitizeStringList(obj.customCommands, CUSTOM_COMMANDS_CAP),
+    paletteUsage: sanitizePaletteUsage(obj.paletteUsage),
+    filesShowHidden: obj.filesShowHidden === true,
+    filesShowIgnored: obj.filesShowIgnored === true,
+  };
+}
+
+/** PURE — serialize an {@link AppState} to the exact JSON shape 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),
+    lastSpawns: sanitizeSpawns(state.lastSpawns),
+    customCommands: sanitizeStringList(state.customCommands, CUSTOM_COMMANDS_CAP),
+    paletteUsage: sanitizePaletteUsage(state.paletteUsage),
+    filesShowHidden: state.filesShowHidden === true,
+    filesShowIgnored: state.filesShowIgnored === true,
+  };
+  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
+  }
+}