pi-async 0.1.0 → 0.3.0

package/src/tui/rail.ts

@@ -1,6 +1,10 @@
 import type { PiCtx } from "../core/notify.ts";
 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 { 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";
@@ -9,6 +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;
+  // 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;
 }
 
@@ -58,71 +64,143 @@ function typeColor(theme: Theme, mode: string, used: Swatch[]): string {
 }
 
 const statePriority: Record<TaskSnapshot["status"], number> = { running: 0, pending: 1, completed: 2, failed: 3, killed: 4 };
-function stripAnsi(value: string): string {
-  return value.replace(/\u001b(?:\][\s\S]*?(?:\u0007|\u001b\\|\u009c)|\[[0-?]*[ -/]*[@-~]|[PX^_][\s\S]*?\u001b\\|[ -/]*[0-~])|\u009b[0-?]*[ -/]*[@-~]|\u009d[\s\S]*?(?:\u0007|\u001b\\|\u009c)/g, "");
+/** Alias for tests / callers still importing elapsed; single source is core/duration. */
+export { formatDuration as elapsed };
+/** Fit a row to at most `width` code points; never exceed the budget (empty when width<=0). */
+/** Truncate a rail row by terminal cell width (CJK/emoji-aware via #7). */
+export function fitRailRow(row: string, width: number): string {
+  return truncateToWidth(row, Math.max(0, Math.floor(width)));
 }
 
-function elapsed(snapshot: TaskSnapshot, now: number): string {
-  const seconds = Math.floor(Math.max(0, now - (snapshot.startedAt ?? snapshot.createdAt)) / 1000);
-  if (seconds < 60) return `${seconds}s`;
-  const minutes = Math.floor(seconds / 60);
-  return minutes < 60 ? `${minutes}m ${seconds % 60}s` : `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
-}
+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 ten-row limit. */
+/** 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.filter((task) => task.status !== "pending")
+  const rows = snapshots
     .slice().sort((a, b) => statePriority[a.status] - statePriority[b.status] || (b.startedAt ?? b.createdAt) - (a.startedAt ?? a.createdAt))
-    .slice(0, 10)
-    .map((task) => `▶ ${stripAnsi(task.name).replace(/[\r\n]+/g, " ")} · ${task.status} · ${elapsed(task, now)}`);
+    .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) => Array.from(row).length > limit ? `${Array.from(row).slice(0, Math.max(0, limit - 1)).join("")}…` : row);
+  return rows.map((row) => truncateToWidth(row, limit));
 }
 
-/** Terminal-task linger window on the rail, overridable for tests. */
-function lingerMsFromEnv(): number {
-  const raw = Number(process.env.PI_ASYNC_RAIL_LINGER_MS ?? 30_000);
-  return Number.isFinite(raw) && raw >= 0 ? raw : 30_000;
+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("");
 }
 
+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)
-      .sort((a, b) => statePriority[a.status] - statePriority[b.status] || (b.startedAt ?? b.createdAt) - (a.startedAt ?? b.createdAt));
+    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 render = (width = 120): string[] => {
-      const tasks = ordered();
-      scroll = Math.max(0, Math.min(scroll, Math.max(0, tasks.length - 10)));
-      const visible = tasks.slice(scroll, scroll + 10);
-      hitRows = visible.map((task) => task.taskId);
+      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);
+      const counts = railWindowCounts(all, now, lingerMs);
+      hitRows = ["", ...visible.map((task) => task.taskId)];
       const used = [swatch(theme, "error"), swatch(theme, "dim")];
-      return 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";
         if (task.status === "running") token = typeColor(theme, task.mode, used);
         else if (task.status === "completed") token = "success";
         else if (task.status === "failed") token = "error";
-        return theme.fg(token, row);
-      });
+        try {
+          return theme.fg(token, row) ?? row;
+        } catch {
+          return row;
+        }
+      })];
+      if (overflow) {
+        const hidden = tasks.length - visible.length;
+        const above = scroll;
+        const below = Math.max(0, tasks.length - scroll - visible.length);
+        const label = above > 0 && below > 0
+          ? `… +${hidden} more (↑${above} ↓${below})`
+          : above > 0
+            ? `… +${above} more ↑`
+            : `… +${below} more`;
+        const indicator = fitRailRow(label, width);
+        try {
+          rows.push(theme.fg("dim", indicator) ?? indicator);
+        } catch {
+          rows.push(indicator);
+        }
+        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,
       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 next = Math.max(0, Math.min(count - 10, scroll + Math.trunc(mouse.wheelDelta ?? 0)));
+          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 };
         }
@@ -138,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,42 +1,119 @@
 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";
 
-export function formatStatus(active: { running: number; pending: number }, done: number): string {
-  return ` ${active.running + active.pending} running · ${done} done `;
+export interface SummaryCounts {
+  running: number;
+  pending: number;
+  completed: number;
+  failed: number;
+  longestRunningStartedAt?: number;
+}
+
+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;
 
-export function disposeStatus(): void {
-  if (refreshInterval) clearInterval(refreshInterval);
-  refreshInterval = undefined;
-  refreshCurrent = undefined;
+/** Shared /async-clear watermark used by footer and panel (#31). */
+export function clearedAtMs(): number {
+  return clearedAt;
+}
+
+/**
+ * Shared clear predicate: running/pending always visible; otherwise compare
+ * finishedAt ?? createdAt against the watermark (footer semantics).
+ */
+export function survivesClearCutoff(
+  task: { status: string; createdAt: number; finishedAt?: number },
+  cutoffMs: number = clearedAt,
+): boolean {
+  if (task.status === "running" || task.status === "pending") return true;
+  return (task.finishedAt ?? task.createdAt) >= cutoffMs;
 }
 
 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) => task.status === "completed" && (task.finishedAt ?? task.createdAt) >= clearedAt).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);
 }

package/src/tui/width.ts

@@ -0,0 +1,53 @@
+/** East-Asian wide / fullwidth / common emoji ranges → 2 cells; else 1. */
+function charWidth(ch: string): number {
+  const cp = ch.codePointAt(0)!;
+  const wide =
+    (cp >= 0x1100 && cp <= 0x115f) ||
+    (cp >= 0x2e80 && cp <= 0xa4cf) ||
+    (cp >= 0xac00 && cp <= 0xd7a3) ||
+    (cp >= 0xf900 && cp <= 0xfaff) ||
+    (cp >= 0xfe30 && cp <= 0xfe6f) ||
+    (cp >= 0xff00 && cp <= 0xff60) ||
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f300 && cp <= 0x1f9ff);
+  return wide ? 2 : 1;
+}
+
+/** Terminal cell width of a string (CJK/emoji ≈ 2 cells). */
+export function displayWidth(text: string): number {
+  let w = 0;
+  for (const ch of text) w += charWidth(ch);
+  return w;
+}
+
+/** Truncate to a cell budget, never splitting a wide char, appending `…`. */
+export function truncateToWidth(text: string, limit: number): string {
+  const budget = Math.max(0, Math.floor(limit));
+  if (budget <= 0) return "";
+  if (displayWidth(text) <= budget) return text;
+  if (budget === 1) return "…";
+  let out = "";
+  let used = 0;
+  for (const ch of text) {
+    const cw = charWidth(ch);
+    if (used + cw > budget - 1) break;
+    out += ch;
+    used += cw;
+  }
+  return `${out}…`;
+}
+
+/** Hard-truncate by cells (no ellipsis) then pad with spaces to exact cell width. */
+export function fitWidth(text: string, limit: number): string {
+  const budget = Math.max(0, Math.floor(limit));
+  if (budget <= 0) return "";
+  let out = "";
+  let used = 0;
+  for (const ch of text) {
+    const cw = charWidth(ch);
+    if (used + cw > budget) break;
+    out += ch;
+    used += cw;
+  }
+  return out + " ".repeat(budget - used);
+}