pi-async 0.2.0 → 0.3.0

package/src/tui/rail.ts

@@ -3,8 +3,8 @@ import type { TaskRegistry } from "../core/registry.ts";
 import type { TaskSnapshot } from "../core/task.ts";
 import { visibleText } from "../core/output.ts";
 import { formatDuration } from "../core/duration.ts";
-import { envNumber } from "../core/env.ts";
-import { truncateToWidth } from "./width.ts";
+import { inRailWindow, railLingerMs, railWindowCounts, summarySegments, type SummaryCounts } from "./status.ts";
+import { displayWidth, truncateToWidth } from "./width.ts";
 import type { TUI, TuiMouseEvent } from "@earendil-works/pi-tui";
 import { openPanel } from "./panel.ts";
 import { tuiHost } from "./host.ts";
@@ -13,7 +13,8 @@ type Theme = { fg(color: string, text: string): string; getFgAnsi?(color: string
 export interface RailWidget {
   render(width?: number): string[];
   handleMouse(event: TuiMouseEvent): { handled: boolean } | undefined;
-  handleInput?(data: string): { handled?: boolean } | void;
+  // 0.3.0 §2.9: the rail has no keyboard scrolling (it never receives focus), so
+  // `handleInput` / `RAIL_PAGE` were removed. Mouse wheel + click remain.
   dispose?(): void;
 }
 
@@ -71,61 +72,90 @@ export function fitRailRow(row: string, width: number): string {
   return truncateToWidth(row, Math.max(0, Math.floor(width)));
 }
 
-/** Pure, unstyled rail rows; active tasks first and a hard ten-row limit. */
+export const RAIL_MAX_LINES = 4;
+export const RAIL_TASK_SLOTS = 3;
+export const RAIL_TASK_SLOTS_OVERFLOW = 2;
+
+/** Pure, unstyled rail rows; active tasks first and a hard three-row limit. */
 export function renderRailRows(snapshots: TaskSnapshot[], width: number, now = Date.now()): string[] {
   const rows = snapshots
     .slice().sort((a, b) => statePriority[a.status] - statePriority[b.status] || (b.startedAt ?? b.createdAt) - (a.startedAt ?? a.createdAt))
-    .slice(0, 10)
+    .slice(0, RAIL_TASK_SLOTS)
     .map((task) => `▶ ${visibleText(task.name)} · ${task.status} · ${formatDuration(task, now)}`);
   const limit = Math.max(0, Math.floor(width));
   return rows.map((row) => truncateToWidth(row, limit));
 }
 
-/** Terminal-task linger window on the rail, overridable for tests. */
-function lingerMsFromEnv(): number {
-  return envNumber("PI_ASYNC_RAIL_LINGER_MS", 30_000, { integer: true, min: 0 });
+let railTicker: ReturnType<typeof setInterval> | undefined;
+
+function coloredSummary(counts: SummaryCounts, now: number, width: number, theme: Theme): string {
+  const plainSegments = summarySegments(counts, now);
+  let kept = plainSegments.map((segment) => ({ ...segment }));
+  const plain = () => kept.map((segment) => segment.text).join("");
+  const removableSegments = [
+    (segment: SummarySegmentLike) => segment.token === "error",
+    (segment: SummarySegmentLike) => segment.token === "success",
+    (segment: SummarySegmentLike) => segment.text.startsWith(" · ") && segment.token === "dim" && !segment.text.includes("pending"),
+    (segment: SummarySegmentLike) => segment.text.includes(" pending"),
+  ];
+  while (displayWidth(plain()) > Math.max(0, Math.floor(width))) {
+    const predicate = removableSegments.find((remove) => kept.some(remove));
+    if (!predicate) break;
+    kept = kept.filter((segment) => !predicate(segment));
+  }
+  const truncated = truncateToWidth(plain(), Math.max(0, Math.floor(width)));
+  let offset = 0;
+  return kept.map((segment) => {
+    const text = truncated.slice(offset, offset + segment.text.length);
+    offset += segment.text.length;
+    if (!text) return "";
+    try { return theme.fg(segment.token, text) ?? text; } catch { return text; }
+  }).join("");
 }
 
-const RAIL_PAGE = 5;
+type SummarySegmentLike = { text: string; token: string };
 
 export function createRailFactory(pi: PiCtx, registry: TaskRegistry, opts: { onOpenTask?: (taskId: string) => void } = {}): (tui: TUI, theme: Theme) => RailWidget {
   // Factory signature includes the extension context for future host-specific rail integrations.
   void pi;
   return (tui, theme) => {
+    if (railTicker) clearInterval(railTicker);
+    const ticker = setInterval(() => {
+      // A disposed/failing host must not crash the timer (same class as the retired heartbeat).
+      try { tui.requestRender(); } catch { /* repaint is best-effort */ }
+    }, 1_000);
+    railTicker = ticker;
+    ticker.unref?.();
     let scroll = 0;
     let hitRows: string[] = [];
     let latchedId: string | undefined;
     // Terminal tasks linger briefly so the user sees the outcome, then drop off
     // the rail (CONTRACT §8: idle sessions render nothing). Live tasks always show.
-    const lingerMs = lingerMsFromEnv();
-    const ordered = (now = Date.now()): TaskSnapshot[] => registry.list({ includeHistory: true })
-      .filter((task) => task.status === "running" || task.status === "pending"
-        || (now - (task.finishedAt ?? task.startedAt ?? task.createdAt)) < lingerMs)
+    const lingerMs = railLingerMs();
+    // Rows and summary counts are drawn from one snapshot + one window so `✓N`
+    // always has a matching row (0.3.0 §2.9).
+    const listAll = (): TaskSnapshot[] => {
+      try { return registry.list({ includeHistory: true }); } catch { return []; }
+    };
+    const ordered = (all: TaskSnapshot[], now = Date.now()): TaskSnapshot[] => all
+      .filter((task) => inRailWindow(task, now, lingerMs))
       .sort((a, b) => statePriority[a.status] - statePriority[b.status] || (b.startedAt ?? b.createdAt) - (a.startedAt ?? a.createdAt));
     const clampScroll = (count: number, taskSlots: number): void => {
       scroll = Math.max(0, Math.min(scroll, Math.max(0, count - taskSlots)));
     };
-    const applyScroll = (delta: number): boolean => {
-      const count = ordered().length;
-      if (count <= 10) return false;
-      const taskSlots = 9; // reserve one row for the overflow indicator
-      const next = Math.max(0, Math.min(count - taskSlots, scroll + delta));
-      if (next === scroll) return false;
-      scroll = next;
-      latchedId = undefined;
-      tui.requestRender();
-      return true;
-    };
     const render = (width = 120): string[] => {
-      const tasks = ordered();
-      const overflow = tasks.length > 10;
-      // Reserve one of the ≤10 rows for the overflow indicator when needed.
-      const taskSlots = overflow ? 9 : 10;
+      const now = Date.now();
+      const all = listAll();
+      const tasks = ordered(all, now);
+      if (tasks.length === 0) { hitRows = []; return []; }
+      const overflow = tasks.length > RAIL_TASK_SLOTS;
+      const taskSlots = overflow ? RAIL_TASK_SLOTS_OVERFLOW : RAIL_TASK_SLOTS;
       clampScroll(tasks.length, taskSlots);
       const visible = tasks.slice(scroll, scroll + taskSlots);
-      hitRows = visible.map((task) => task.taskId);
+      const counts = railWindowCounts(all, now, lingerMs);
+      hitRows = ["", ...visible.map((task) => task.taskId)];
       const used = [swatch(theme, "error"), swatch(theme, "dim")];
-      const rows = renderRailRows(visible, width).map((row, index) => {
+      const rows = [coloredSummary(counts, now, width, theme), ...renderRailRows(visible, width).map((row, index) => {
         const task = visible[index];
         if (!task) return row;
         let token = "dim";
@@ -137,7 +167,7 @@ export function createRailFactory(pi: PiCtx, registry: TaskRegistry, opts: { onO
         } catch {
           return row;
         }
-      });
+      })];
       if (overflow) {
         const hidden = tasks.length - visible.length;
         const above = scroll;
@@ -155,26 +185,21 @@ export function createRailFactory(pi: PiCtx, registry: TaskRegistry, opts: { onO
         }
         hitRows.push(""); // overflow row is not a task hit target
       }
+      // Bind the ≤4 invariant to RAIL_MAX_LINES so retuning the slot constants cannot silently break it.
+      if (rows.length > RAIL_MAX_LINES) {
+        rows.length = RAIL_MAX_LINES;
+        hitRows.length = RAIL_MAX_LINES;
+      }
       return rows;
     };
     return {
       render,
-      handleInput(data: string): { handled?: boolean } | void {
-        // PageUp / PageDown, and Ctrl+↑ / Ctrl+↓ when the rail has focus.
-        if (data === "\u001b[5~" || data === "\u001b[1;5A") {
-          return applyScroll(-RAIL_PAGE) ? { handled: true } : undefined;
-        }
-        if (data === "\u001b[6~" || data === "\u001b[1;5B") {
-          return applyScroll(RAIL_PAGE) ? { handled: true } : undefined;
-        }
-        return undefined;
-      },
       handleMouse(event: TuiMouseEvent): { handled: boolean } | undefined {
         const mouse = event as TuiMouseEvent & { type: string; y: number; button?: string; wheelDelta?: number };
         if (mouse.type === "wheel") {
-          const count = ordered().length;
-          if (count <= 10) return undefined;
-          const taskSlots = 9;
+          const count = ordered(listAll()).length;
+          if (count <= RAIL_TASK_SLOTS) return undefined;
+          const taskSlots = RAIL_TASK_SLOTS_OVERFLOW;
           const next = Math.max(0, Math.min(count - taskSlots, scroll + Math.trunc(mouse.wheelDelta ?? 0)));
           if (next === scroll) return undefined;
           scroll = next; latchedId = undefined; tui.requestRender(); return { handled: true };
@@ -191,7 +216,13 @@ export function createRailFactory(pi: PiCtx, registry: TaskRegistry, opts: { onO
         if (!latchedId || id !== latchedId) { latchedId = undefined; return undefined; }
         const clicked = latchedId; latchedId = undefined; opts.onOpenTask?.(clicked); return { handled: true };
       },
-      dispose(): void { latchedId = undefined; },
+      dispose(): void {
+        latchedId = undefined;
+        if (railTicker === ticker) {
+          clearInterval(ticker);
+          railTicker = undefined;
+        }
+      },
     };
   };
 }

package/src/tui/status.ts

@@ -1,19 +1,42 @@
 import type { PiCtx } from "../core/notify.ts";
 import type { TaskRegistry } from "../core/registry.ts";
+import type { TaskSnapshot } from "../core/task.ts";
 import { reportActivity } from "../core/bus.ts";
+import { envNumber } from "../core/env.ts";
+import { formatElapsedMs } from "../core/duration.ts";
 import { tuiHost } from "./host.ts";
 
-const TERMINAL = new Set(["completed", "failed", "killed"]);
+export interface SummaryCounts {
+  running: number;
+  pending: number;
+  completed: number;
+  failed: number;
+  longestRunningStartedAt?: number;
+}
 
-/** Footer: running excludes pending; pending segment only when > 0; done = all terminal. */
-export function formatStatus(active: { running: number; pending: number }, done: number): string {
-  const pending = active.pending > 0 ? ` · ${active.pending} pending` : "";
-  return ` ${active.running} running${pending} · ${done} done `;
+export type SummaryToken = "accent" | "dim" | "success" | "error";
+export interface SummarySegment { text: string; token: SummaryToken }
+
+export function summarySegments(c: SummaryCounts, now = Date.now()): SummarySegment[] {
+  const elapsed = c.running > 0 && c.longestRunningStartedAt !== undefined
+    ? formatElapsedMs(now - c.longestRunningStartedAt)
+    : "—";
+  return [
+    { text: "▶", token: c.running + c.pending > 0 ? "accent" : "dim" },
+    { text: ` ${c.running} running`, token: "accent" },
+    ...(c.pending > 0 ? [{ text: ` · ${c.pending} pending`, token: "dim" as const }] : []),
+    { text: ` · ${elapsed}`, token: "dim" },
+    // ✓ and ✗ are symmetric: both only appear when non-zero, so an all-failed run shows no green 0.
+    ...(c.completed > 0 ? [{ text: ` · ✓${c.completed}`, token: "success" as const }] : []),
+    ...(c.failed > 0 ? [{ text: ` · ✗${c.failed}`, token: "error" as const }] : []),
+  ];
+}
+
+export function formatSummary(c: SummaryCounts, now = Date.now()): string {
+  return summarySegments(c, now).map((segment) => segment.text).join("");
 }
 
 let clearedAt = 0;
-let refreshCurrent: (() => void) | undefined;
-let refreshInterval: ReturnType<typeof setInterval> | undefined;
 
 /** Shared /async-clear watermark used by footer and panel (#31). */
 export function clearedAtMs(): number {
@@ -32,32 +55,65 @@ export function survivesClearCutoff(
   return (task.finishedAt ?? task.createdAt) >= cutoffMs;
 }
 
-export function disposeStatus(): void {
-  if (refreshInterval) clearInterval(refreshInterval);
-  refreshInterval = undefined;
-  refreshCurrent = undefined;
-}
-
 export function clearDoneStatus(): void {
   clearedAt = Date.now();
-  refreshCurrent?.();
 }
 
-export function initStatus(pi: PiCtx, registry: TaskRegistry): void {
-  disposeStatus();
-  // TUI surfaces bind from event contexts; the factory API has no mode/ui.
-  const bound = tuiHost();
-  if (!bound) return;
-  const setStatus = bound.ui["setStatus"] as ((key: string, text: string | undefined) => void) | undefined;
-  const refresh = (): void => {
-    const active = registry.activeCount();
-    const done = registry.list({ includeHistory: true }).filter((task) => TERMINAL.has(task.status) && survivesClearCutoff(task)).length;
-    setStatus?.("pi-async", formatStatus(active, done));
-    reportActivity(pi, active);
+const TERMINAL = new Set(["completed", "failed", "killed"]);
+
+/** Terminal-task linger window on the rail, overridable for tests. */
+export function railLingerMs(): number {
+  return envNumber("PI_ASYNC_RAIL_LINGER_MS", 30_000, { integer: true, min: 0 });
+}
+
+/**
+ * The single rail visibility window: live tasks always show, terminal tasks linger.
+ * Rows and summary counts both go through this predicate so `✓N` can never show a
+ * number without a matching row (0.3.0 §2.9).
+ */
+export function inRailWindow(
+  task: { status: string; createdAt: number; startedAt?: number; finishedAt?: number },
+  now = Date.now(),
+  lingerMs = railLingerMs(),
+): boolean {
+  if (task.status === "running" || task.status === "pending") return true;
+  return now - (task.finishedAt ?? task.startedAt ?? task.createdAt) < lingerMs;
+}
+
+/** Counts drawn from exactly the rows the rail renders (same linger window + clear watermark). */
+export function railWindowCounts(tasks: TaskSnapshot[], now = Date.now(), lingerMs = railLingerMs()): SummaryCounts {
+  const window = tasks.filter((task) => inRailWindow(task, now, lingerMs));
+  const running = window.filter((task) => task.status === "running");
+  const pending = window.filter((task) => task.status === "pending").length;
+  const terminal = window.filter((task) => TERMINAL.has(task.status) && survivesClearCutoff(task));
+  return {
+    running: running.length,
+    pending,
+    completed: terminal.filter((task) => task.status === "completed").length,
+    failed: terminal.filter((task) => task.status === "failed" || task.status === "killed").length,
+    ...(running.length ? { longestRunningStartedAt: Math.min(...running.map((task) => task.startedAt ?? task.createdAt)) } : {}),
   };
-  refreshCurrent = refresh;
-  refresh();
-  // Registry intentionally exposes no event subscription API; keep the footer current without replacing its core events.
-  refreshInterval = setInterval(refresh, 1_000);
-  refreshInterval.unref?.();
+}
+
+/** Opt-in single-line footer (`PI_ASYNC_FOOTER=1`); the rail is the default status surface. */
+export function footerEnabled(): boolean {
+  return process.env.PI_ASYNC_FOOTER === "1";
+}
+
+/** Publish the summary line when the footer is opted in; no timers, callers drive it. */
+export function refreshFooter(registry: TaskRegistry, now = Date.now()): void {
+  if (!footerEnabled()) return;
+  const ui = tuiHost()?.ui as { setStatus?: (key: string, text: string | undefined) => void } | undefined;
+  if (typeof ui?.setStatus !== "function") return;
+  try {
+    ui.setStatus("pi-async", formatSummary(railWindowCounts(registry.list({ includeHistory: true }), now)));
+  } catch {
+    // Status rendering is best-effort: a host that rejects setStatus must not break the session.
+  }
+}
+
+export function initStatus(pi: PiCtx, registry: TaskRegistry): void {
+  if (!tuiHost()) return;
+  reportActivity(pi, registry.activeCount());
+  refreshFooter(registry);
 }