@pellux/goodvibes-tui 2.0.20 → 2.1.0

package/src/core/work-tree-focus.ts

@@ -0,0 +1,290 @@
+/**
+ * work-tree-focus.ts, moving the keyboard through the work tree.
+ *
+ * The navigable rows are the blocks the work tree registered with a
+ * `workTree` field: turn headers, beads, and agent lanes (their spawn or
+ * folded row), in screen order. Keys:
+ *
+ *   ↑ ↓     previous / next row
+ *   ←       fold: close an open body; on a lane's bead or spawn row fold the
+ *           lane to one ◉; on the spine fold the turn to its header
+ *   →       unfold: open a body (a second → shows the rest of a capped
+ *           body); unfold a folded lane or turn
+ *   Enter   open or close a bead's body; unfold a folded lane; fold or
+ *           unfold a turn
+ *
+ * Pure: reads the registry and collapse state, returns the collapse changes
+ * and the row to focus next. Nothing here stops, cancels or sends anything.
+ */
+
+import type { BlockMeta } from './conversation-types.ts';
+import type { TurnOutcome } from './work-tree-sources.ts';
+
+/** A turn's saved ending: the user message it answered (by index and fingerprint) and how it ended. */
+export interface TurnOutcomeRecord {
+  readonly index: number;
+  readonly fingerprint: string;
+  readonly outcome: TurnOutcome;
+}
+
+/** Most turn endings kept per session. */
+export const MAX_TURN_OUTCOMES = 500;
+
+export type NavBlock = BlockMeta & { readonly workTree: NonNullable<BlockMeta['workTree']> };
+
+export interface FocusChange {
+  /** Collapse keys to set (true = folded / closed). */
+  readonly set: ReadonlyArray<readonly [string, boolean]>;
+  /** The row to focus afterwards. */
+  readonly focus: string;
+}
+
+/** Navigable rows in screen order. */
+export function navigableRows(blocks: readonly BlockMeta[]): NavBlock[] {
+  return blocks.filter((b): b is NavBlock => b.workTree !== undefined).sort((a, b) => a.startLine - b.startLine);
+}
+
+export function findRow(blocks: readonly BlockMeta[], id: string): NavBlock | undefined {
+  return navigableRows(blocks).find((b) => b.workTree.id === id);
+}
+
+/** The row to focus on entering the work tree: the last one at or above `anchorLine` (else the last row). */
+export function initialFocus(blocks: readonly BlockMeta[], anchorLine: number): string | null {
+  const rows = navigableRows(blocks);
+  if (rows.length === 0) return null;
+  const above = rows.filter((b) => b.startLine <= anchorLine);
+  return (above[above.length - 1] ?? rows[rows.length - 1]!).workTree.id;
+}
+
+/** The row `delta` rows from `current` (clamped); null when there are none. */
+export function moveFocus(blocks: readonly BlockMeta[], current: string | null, delta: number): string | null {
+  const rows = navigableRows(blocks);
+  if (rows.length === 0) return null;
+  const at = current === null ? -1 : rows.findIndex((b) => b.workTree.id === current);
+  if (at < 0) return rows[delta < 0 ? rows.length - 1 : 0]!.workTree.id;
+  return rows[Math.max(0, Math.min(rows.length - 1, at + delta))]!.workTree.id;
+}
+
+/** The turn header a row belongs to (the nearest turn row above it). */
+function turnOf(blocks: readonly BlockMeta[], row: NavBlock): NavBlock | undefined {
+  const rows = navigableRows(blocks).filter((b) => b.workTree.kind === 'turn' && b.startLine <= row.startLine);
+  return rows[rows.length - 1];
+}
+
+function laneRow(blocks: readonly BlockMeta[], laneKey: string): NavBlock | undefined {
+  return navigableRows(blocks).find((b) => b.workTree.kind === 'lane' && b.workTree.laneKey === laneKey);
+}
+
+/** ← on the focused row. */
+export function foldFocused(blocks: readonly BlockMeta[], id: string): FocusChange | null {
+  const row = findRow(blocks, id);
+  if (!row) return null;
+  const wt = row.workTree;
+  if (wt.kind === 'bead') {
+    if (wt.open) return { set: [[row.collapseKey, true], ...(wt.moreKey ? [[wt.moreKey, false] as const] : [])], focus: id };
+    if (wt.laneKey) {
+      const lane = laneRow(blocks, wt.laneKey);
+      return { set: [[wt.laneKey, true]], focus: lane?.workTree.id ?? wt.laneKey };
+    }
+    const turn = turnOf(blocks, row);
+    return turn ? { set: [[turn.collapseKey, true]], focus: turn.workTree.id } : null;
+  }
+  if (wt.kind === 'lane') {
+    if (wt.open) return { set: [[row.collapseKey, true]], focus: id };
+    const turn = turnOf(blocks, row);
+    return turn ? { set: [[turn.collapseKey, true]], focus: turn.workTree.id } : null;
+  }
+  return wt.open ? { set: [[row.collapseKey, true]], focus: id } : null;
+}
+
+/** → on the focused row. */
+export function unfoldFocused(blocks: readonly BlockMeta[], id: string): FocusChange | null {
+  const row = findRow(blocks, id);
+  if (!row) return null;
+  const wt = row.workTree;
+  if (wt.kind === 'bead') {
+    if (!wt.hasBody) return null;
+    if (!wt.open) return { set: [[row.collapseKey, false]], focus: id };
+    if (wt.capped && wt.moreKey) return { set: [[wt.moreKey, true]], focus: id };
+    return null;
+  }
+  return wt.open ? null : { set: [[row.collapseKey, false]], focus: id };
+}
+
+/** Enter on the focused row. */
+export function activateFocused(blocks: readonly BlockMeta[], id: string): FocusChange | null {
+  const row = findRow(blocks, id);
+  if (!row) return null;
+  const wt = row.workTree;
+  if (wt.kind === 'bead') {
+    if (!wt.hasBody) return null;
+    return wt.open ? { set: [[row.collapseKey, true]], focus: id } : { set: [[row.collapseKey, false]], focus: id };
+  }
+  if (wt.kind === 'lane') return wt.open ? null : { set: [[row.collapseKey, false]], focus: id };
+  return { set: [[row.collapseKey, wt.open]], focus: id };
+}
+
+export interface WorkTreeControllerDeps {
+  /** The current block registry (flushed). */
+  readonly blocks: () => readonly BlockMeta[];
+  readonly collapseState: () => Map<string, boolean>;
+  readonly markDirty: () => void;
+  /** Exempts a key from search's close-time auto re-collapse (a deliberate user act). */
+  readonly noteUserTouch: (key: string) => void;
+  /** Whether the last build drew something live. */
+  readonly drewLive: () => boolean;
+}
+
+/** Collapse keys the work tree owns (work-tree-model.ts). */
+const FOLD_KEY = /^(turn_\d+|bead_|beadmore_|lane_)/;
+
+/**
+ * The work tree's keyboard focus, live repaint tick and fold state, owned by a
+ * ConversationManager (as `conversation.workTree`).
+ */
+export class WorkTreeController {
+  private focusId: string | null = null;
+  private liveFrame = 0;
+  private foldListener: (() => void) | null = null;
+  /** Failed and cancelled turn endings of this session, by user message index. */
+  private readonly outcomes = new Map<number, TurnOutcomeRecord>();
+  private readonly resetListeners = new Set<() => void>();
+
+  constructor(private readonly deps: WorkTreeControllerDeps) {}
+
+  /** The focused row id, or null while the keyboard is in the composer. */
+  get focus(): string | null { return this.focusId; }
+  /** Spinner frame for running beads. */
+  get frame(): number { return this.liveFrame; }
+  get focused(): boolean { return this.focusId !== null; }
+
+  /**
+   * The transcript was reset or replaced wholesale (a new or resumed session):
+   * focus, turn endings and anything keyed by message index belong to the old
+   * transcript and go.
+   */
+  reset(): void {
+    this.focusId = null;
+    this.outcomes.clear();
+    for (const listener of this.resetListeners) listener();
+  }
+
+  /** Be told when the transcript is reset (the timing store keys turns by message index). */
+  onReset(listener: () => void): () => void {
+    this.resetListeners.add(listener);
+    return () => { this.resetListeners.delete(listener); };
+  }
+
+  /**
+   * Record how a turn ended. Only failed and cancelled endings are kept (a
+   * completed turn is the default and says nothing extra). Returns whether the
+   * kept records changed.
+   */
+  recordTurnOutcome(record: TurnOutcomeRecord): boolean {
+    const had = this.outcomes.delete(record.index);
+    if (record.outcome === 'completed') return had;
+    this.outcomes.set(record.index, record);
+    while (this.outcomes.size > MAX_TURN_OUTCOMES) {
+      const oldest = this.outcomes.keys().next();
+      if (oldest.done) break;
+      this.outcomes.delete(oldest.value);
+    }
+    this.deps.markDirty();
+    return true;
+  }
+
+  /** The recorded ending of the turn answering the user message at `index`. */
+  turnOutcome(index: number): TurnOutcomeRecord | undefined {
+    return this.outcomes.get(index);
+  }
+
+  /** Every recorded turn ending, oldest first (the session sidecar keeps them). */
+  turnOutcomes(): TurnOutcomeRecord[] {
+    return [...this.outcomes.values()];
+  }
+
+  /** Restore saved turn endings (a resumed session keeps its failed and cancelled headers). */
+  restoreTurnOutcomes(records: Iterable<TurnOutcomeRecord>): void {
+    for (const record of records) this.recordTurnOutcome(record);
+    this.deps.markDirty();
+  }
+
+  /** Something the work tree draws changed outside the transcript (a ◈ summary landed): rebuild. */
+  invalidate(): void { this.deps.markDirty(); }
+
+  /** Be told when a fold decision changes (the session keeps them in its sidecar). */
+  onFoldChange(listener: (() => void) | null): void { this.foldListener = listener; }
+  notifyFoldChange(): void { this.foldListener?.(); }
+
+  /**
+   * Repaint live rows as time passes (a running bead spins, its time counts
+   * up). Call before each frame; it marks the transcript dirty only while the
+   * last build drew something live and the frame moved on.
+   */
+  tickLive(now = Date.now()): void {
+    const frame = Math.floor(now / 150);
+    if (frame === this.liveFrame) return;
+    this.liveFrame = frame;
+    if (this.deps.drewLive()) this.deps.markDirty();
+  }
+
+  /** Enter the work tree at the last row at or above `anchorLine`; false when there is nothing to focus. */
+  enter(anchorLine: number): boolean {
+    const id = initialFocus(this.deps.blocks(), anchorLine);
+    if (id === null) return false;
+    this.focusId = id;
+    this.deps.markDirty();
+    return true;
+  }
+
+  /** Leave the work tree (Esc). Never stops or cancels anything. */
+  leave(): void {
+    if (this.focusId === null) return;
+    this.focusId = null;
+    this.deps.markDirty();
+  }
+
+  move(delta: number): boolean {
+    const next = moveFocus(this.deps.blocks(), this.focusId, delta);
+    if (next === null || next === this.focusId) return false;
+    this.focusId = next;
+    this.deps.markDirty();
+    return true;
+  }
+
+  /** ← (fold), → (unfold) or Enter (activate) on the focused row. */
+  act(action: 'fold' | 'unfold' | 'activate'): boolean {
+    if (this.focusId === null) return false;
+    const blocks = this.deps.blocks();
+    const change = action === 'fold' ? foldFocused(blocks, this.focusId)
+      : action === 'unfold' ? unfoldFocused(blocks, this.focusId)
+        : activateFocused(blocks, this.focusId);
+    if (!change) return false;
+    const collapse = this.deps.collapseState();
+    for (const [key, value] of change.set) {
+      collapse.set(key, value);
+      this.deps.noteUserTouch(key);
+    }
+    this.focusId = change.focus;
+    this.deps.markDirty();
+    this.foldListener?.();
+    return true;
+  }
+
+  /** The focused row's block (copy, save and bookmark act on it). */
+  focusBlock(): BlockMeta | null {
+    return this.focusId === null ? null : findRow(this.deps.blocks(), this.focusId) ?? null;
+  }
+
+  /** Every work-tree fold decision (turns, lanes, open beads), oldest first. */
+  foldState(): Array<[string, boolean]> {
+    return [...this.deps.collapseState()].filter(([key]) => FOLD_KEY.test(key));
+  }
+
+  /** Restore saved fold decisions (a resumed session keeps its view). */
+  restoreFoldState(entries: Iterable<readonly [string, boolean]>): void {
+    const collapse = this.deps.collapseState();
+    for (const [key, value] of entries) if (FOLD_KEY.test(key)) collapse.set(key, value);
+    this.deps.markDirty();
+  }
+}

package/src/core/work-tree-fold-store.ts

@@ -0,0 +1,143 @@
+/**
+ * work-tree-fold-store.ts, the work tree's fold state, kept per session.
+ *
+ * Which turns are folded, which agent lanes are folded, which beads are open
+ * and which opened bodies show everything, plus which turns failed or were
+ * cancelled (keyed by their user message's index and fingerprint, so a
+ * resumed header still says so): kept beside the session file as
+ * `<stem>.work-tree.json` (the same stem rule the session file uses, see
+ * sanitizeSessionName), so reopening a session keeps the view.
+ *
+ * Bounded (the most recent MAX_KEYS decisions), validated on load (anything
+ * that is not a known key shape with a boolean value is dropped), written
+ * atomically (temp file + rename), and swept: a sidecar whose session file is
+ * gone is removed by sweepOrphanWorkTreeFolds.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sanitizeSessionName } from '@pellux/goodvibes-sdk/platform/sessions';
+import { MAX_TURN_OUTCOMES, type TurnOutcomeRecord } from './work-tree-focus.ts';
+
+const SUFFIX = '.work-tree.json';
+const VERSION = 1;
+/** Most fold decisions kept per session. */
+export const MAX_FOLD_KEYS = 2000;
+/** A staging file older than this is crash residue. */
+const TMP_MAX_AGE_MS = 60 * 60 * 1000;
+
+/** Collapse keys the work tree owns (work-tree-model.ts). */
+const KEY_SHAPE = /^(turn_\d+|bead_[\w:./-]+|beadmore_[\w:./-]+|lane_[\w:./-]+)$/;
+
+export function isWorkTreeFoldKey(key: string): boolean {
+  return KEY_SHAPE.test(key);
+}
+
+function sidecarPath(sessionsDir: string, sessionId: string): string | null {
+  if (!sessionsDir || !sessionId) return null;
+  const stem = sanitizeSessionName(sessionId);
+  if (stem === '') return null;
+  return join(sessionsDir, `${stem}${SUFFIX}`);
+}
+
+/** Keep only work-tree keys with boolean values, the most recent MAX_FOLD_KEYS. */
+export function boundFoldState(entries: Iterable<readonly [string, unknown]>): Array<[string, boolean]> {
+  const out: Array<[string, boolean]> = [];
+  for (const [key, value] of entries) if (typeof value === 'boolean' && isWorkTreeFoldKey(key)) out.push([key, value]);
+  return out.length > MAX_FOLD_KEYS ? out.slice(out.length - MAX_FOLD_KEYS) : out;
+}
+
+/** Keep only well-formed failed/cancelled turn endings, the most recent MAX_TURN_OUTCOMES. */
+export function boundTurnOutcomes(records: Iterable<unknown>): TurnOutcomeRecord[] {
+  const out: TurnOutcomeRecord[] = [];
+  for (const record of records) {
+    if (!record || typeof record !== 'object') continue;
+    const r = record as Record<string, unknown>;
+    if (typeof r.index !== 'number' || !Number.isInteger(r.index) || r.index < 0) continue;
+    if (typeof r.fingerprint !== 'string' || r.fingerprint.length === 0 || r.fingerprint.length > 200) continue;
+    if (r.outcome !== 'failed' && r.outcome !== 'cancelled') continue;
+    out.push({ index: r.index, fingerprint: r.fingerprint, outcome: r.outcome });
+  }
+  return out.length > MAX_TURN_OUTCOMES ? out.slice(out.length - MAX_TURN_OUTCOMES) : out;
+}
+
+/**
+ * Write the session's fold state and its failed/cancelled turn endings.
+ * Best effort: a failed write never breaks the session.
+ */
+export function saveWorkTreeFolds(sessionsDir: string, sessionId: string, state: Iterable<readonly [string, boolean]>, turns: Iterable<TurnOutcomeRecord> = []): void {
+  const path = sidecarPath(sessionsDir, sessionId);
+  if (!path) return;
+  try {
+    mkdirSync(sessionsDir, { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    const outcomes = boundTurnOutcomes(turns);
+    writeFileSync(tmp, JSON.stringify({ version: VERSION, sessionId, folds: Object.fromEntries(boundFoldState(state)), ...(outcomes.length > 0 ? { turns: outcomes } : {}) }));
+    renameSync(tmp, path);
+  } catch {
+    // best effort; the view falls back to defaults on the next resume
+  }
+}
+
+/** Read the session's fold state; an absent or unreadable sidecar reads as empty. */
+export function loadWorkTreeFolds(sessionsDir: string, sessionId: string): Array<[string, boolean]> {
+  const path = sidecarPath(sessionsDir, sessionId);
+  if (!path || !existsSync(path)) return [];
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return [];
+    const folds = (parsed as { folds?: unknown }).folds;
+    if (!folds || typeof folds !== 'object' || Array.isArray(folds)) return [];
+    return boundFoldState(Object.entries(folds as Record<string, unknown>));
+  } catch {
+    return [];
+  }
+}
+
+/** Read the session's saved failed/cancelled turn endings; an absent or unreadable sidecar reads as none. */
+export function loadWorkTreeTurnOutcomes(sessionsDir: string, sessionId: string): TurnOutcomeRecord[] {
+  const path = sidecarPath(sessionsDir, sessionId);
+  if (!path || !existsSync(path)) return [];
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return [];
+    const turns = (parsed as { turns?: unknown }).turns;
+    return Array.isArray(turns) ? boundTurnOutcomes(turns) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Remove fold sidecars whose session file no longer exists, and staging files
+ * a crash left behind. Returns how many files were removed.
+ */
+export function sweepOrphanWorkTreeFolds(sessionsDir: string, now = Date.now()): number {
+  if (!sessionsDir || !existsSync(sessionsDir)) return 0;
+  let removed = 0;
+  let names: string[];
+  try {
+    names = readdirSync(sessionsDir);
+  } catch {
+    return 0;
+  }
+  const present = new Set(names);
+  for (const name of names) {
+    try {
+      if (name.includes(`${SUFFIX}.tmp-`)) {
+        if (now - statSync(join(sessionsDir, name)).mtimeMs > TMP_MAX_AGE_MS) { unlinkSync(join(sessionsDir, name)); removed++; }
+        continue;
+      }
+      if (!name.endsWith(SUFFIX)) continue;
+      const stem = name.slice(0, -SUFFIX.length);
+      // Settled for an hour first: a session folds things before its first save writes the session file.
+      if (!present.has(`${stem}.jsonl`) && now - statSync(join(sessionsDir, name)).mtimeMs > TMP_MAX_AGE_MS) {
+        unlinkSync(join(sessionsDir, name));
+        removed++;
+      }
+    } catch {
+      // a file that vanished or cannot be removed is left for the next sweep
+    }
+  }
+  return removed;
+}