pi-async 0.0.0-stage → 0.1.0

package/src/tui/panel.ts

@@ -0,0 +1,218 @@
+import { openSync, closeSync, fstatSync, readSync } from "node:fs";
+import type { PiCtx } from "../core/notify.ts";
+import type { TaskRegistry } from "../core/registry.ts";
+import type { TaskSnapshot } from "../core/task.ts";
+import { stripAnsi } from "../core/output.ts";
+import { clearDoneStatus } from "./status.ts";
+import { tuiHost } from "./host.ts";
+
+const isTui = (pi: unknown): boolean => {
+  // Event/command contexts carry mode; the factory API does not. Both paths must resolve.
+  const asCtx = pi as { mode?: string } | undefined;
+  return asCtx?.mode === "tui" || tuiHost()?.mode === "tui";
+};
+
+const UI_TAIL_BYTES = 128 * 1024;
+const PANEL_ROWS = 12;
+let historyClearedAt = 0;
+const visible = (value: unknown): string => stripAnsi(String(value ?? "")).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "").replace(/[\r\n\t]+/g, " ");
+function readUiOutput(task: TaskSnapshot, registry: TaskRegistry): { text: string; truncated: boolean } {
+  const outputPath = task.metadata.outputFile;
+  if (typeof outputPath !== "string") return { text: registry.logs(task.taskId, { maxBytes: UI_TAIL_BYTES, tail: true }).text, truncated: false };
+  try {
+    const fd = openSync(outputPath, "r");
+    try {
+      const size = fstatSync(fd).size;
+      const start = Math.max(0, size - UI_TAIL_BYTES);
+      const buffer = Buffer.alloc(Math.min(size, UI_TAIL_BYTES));
+      readSync(fd, buffer, 0, buffer.length, start);
+      return { text: stripAnsi(buffer.toString("utf8")), truncated: start > 0 };
+    } finally { closeSync(fd); }
+  } catch {
+    return { text: registry.logs(task.taskId, { maxBytes: UI_TAIL_BYTES, tail: true }).text, truncated: false };
+  }
+}
+
+const duration = (task: TaskSnapshot, now: number): string => {
+  const end = task.finishedAt ?? now;
+  const seconds = Math.floor(Math.max(0, end - (task.startedAt ?? task.createdAt)) / 1000);
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+};
+const frame = (title: string, body: string[], width: number, height: number): string[] => {
+  const w = Math.max(8, Math.floor(width));
+  const h = Math.max(4, Math.floor(height));
+  const fit = (text: string): string => Array.from(text).slice(0, w - 4).join("").padEnd(w - 4);
+  const content = [`╭─ ${fit(title)}─╮`, ...body.slice(0, h - 2).map((line) => `│ ${fit(line)} │`), `╰${"─".repeat(w - 2)}╯`];
+  while (content.length < height) content.splice(content.length - 1, 0, `│${" ".repeat(w - 2)}│`);
+  // The solid background masks chat rows beneath the overlay, as in legion-viz's live overlay.
+  return content;
+};
+
+export function registerPanelCommands(pi: PiCtx, registry: TaskRegistry): void {
+  // Commands/shortcuts are factory-time APIs (they exist on the factory pi); TUI
+  // gating comes from the bound event context. Handlers receive a rich ctx with ui.
+  const bound = tuiHost();
+  const host = pi as unknown as {
+    registerCommand?: (name: string, spec: { description: string; handler: (args: unknown, ctx: PiCtx) => void }) => void;
+    registerShortcut?: (key: string, spec: { description: string; handler: (ctx: PiCtx) => void }) => void;
+  };
+  if (!bound) return;
+  host.registerCommand?.("async", { description: "Open async task panel", handler: (_args, ctx) => openPanel(ctx, registry) });
+  host.registerCommand?.("async-clear", {
+    description: "Clear async task history",
+    handler: (_args, ctx) => {
+      if (!isTui(ctx)) return;
+      historyClearedAt = Date.now();
+      clearDoneStatus();
+    },
+  });
+  try {
+    host.registerShortcut?.(process.env.PI_ASYNC_DOCK_SHORTCUT ?? "ctrl+alt+a", { description: "Open async task panel", handler: (ctx) => openPanel(ctx, registry) });
+  } catch {
+    // The /async command remains the fallback when Pi reserves this shortcut.
+  }
+}
+
+export function openPanel(pi: PiCtx, registry: TaskRegistry, initialTaskId?: string): void {
+  // Event/command contexts carry a working ui; rail-click paths pass the factory
+  // pi, whose ui is undefined — fall back to the bound TUI host in that case.
+  const ctxUi = (pi as { ui?: Record<string, unknown> }).ui ?? tuiHost()?.ui;
+  const host = {
+    ui: ctxUi as {
+      copyToClipboard?: (text: string) => void;
+      custom?: (factory: (tui: unknown, theme: unknown, keybindings: unknown, done: (value?: unknown) => void) => unknown, options: unknown) => Promise<unknown>;
+      notify?: (message: string, level?: string) => void;
+      setStatus?: (key: string, text: string | undefined) => void;
+    } | undefined,
+  };
+  if (!isTui(pi) || typeof host.ui?.custom !== "function") return;
+  const snapshots = (): TaskSnapshot[] => registry.list({ includeHistory: true }).filter((task) => task.createdAt >= historyClearedAt || task.status === "running" || task.status === "pending");
+  const custom = host.ui.custom;
+  const factory = (tui: unknown, _theme: unknown, _keybindings: unknown, done: (value?: unknown) => void) => {
+    let selected = initialTaskId ?? snapshots()[0]?.taskId;
+    let detail = Boolean(initialTaskId);
+    let history = true;
+    let confirmKill = false;
+    let scroll = 0;
+    let follow = true;
+    let width = 100;
+    let height = process.stdout.rows ?? 24;
+    let lastLines: string[] = [];
+    const requestRender = (): void => {
+      (tui as { requestRender?: () => void } | undefined)?.requestRender?.();
+    };
+    const choose = (): TaskSnapshot | undefined => snapshots().find((task) => task.taskId === selected);
+    const renderBody = (): string[] => {
+      const tasks = snapshots().filter((task) => history || task.status === "running" || task.status === "pending");
+      if (!detail) {
+        return ["↑/↓ select · Enter details · h history · q close", ...tasks.map((task) => {
+          const output = task.status === "running" ? registry.logs(task.taskId, { maxBytes: UI_TAIL_BYTES, tail: true }).text.split(/\r?\n/).filter(Boolean).at(-1) : undefined;
+          return `${task.taskId === selected ? "▶" : " "} ${visible(task.name)} · ${task.status} · ${duration(task, Date.now())}${output ? ` · ${visible(output)}` : ""}`;
+        })];
+      }
+      const task = choose();
+      if (!task) return ["Task not found", "Esc return · q close"];
+      const output = readUiOutput(task, registry);
+      const outputLines = output.text.split(/\r?\n/).filter((line) => line.length > 0);
+      scroll = Math.min(scroll, Math.max(0, outputLines.length - PANEL_ROWS));
+      const tail = outputLines.slice(Math.max(0, outputLines.length - PANEL_ROWS - scroll), outputLines.length - scroll);
+      const meta = JSON.stringify(task.metadata);
+      return [
+        `${visible(task.name)} [${task.taskId}]`, `status: ${task.status} · elapsed: ${duration(task, Date.now())}`,
+        `command: ${visible(task.command)}`, `metadata: ${meta}`, `output${output.truncated ? " (tail truncated)" : ""}:`,
+        // registry.logs caps its own data at 50 KiB; the TUI intentionally reads a larger 128 KiB tail directly from the output file.
+        ...tail.map(visible), ...(confirmKill ? ["Kill this task? press k again to confirm; any other key cancels"] : []),
+        "Esc return · k kill · R rerun · c copy output path · ↑/↓ scroll",
+      ];
+    };
+    const render = (nextWidth?: number): string[] => {
+      width = nextWidth ?? width;
+      height = process.stdout.rows ?? height;
+      lastLines = renderBody();
+      const maxScroll = Math.max(0, lastLines.length - PANEL_ROWS);
+      if (follow) scroll = 0;
+      else scroll = Math.min(scroll, maxScroll);
+      return frame(detail ? "Async task detail" : "Async tasks", lastLines, width, height);
+    };
+    const move = (delta: number): void => {
+      const tasks = snapshots().filter((task) => history || task.status === "running" || task.status === "pending");
+      const index = tasks.findIndex((task) => task.taskId === selected);
+      const next = tasks[Math.max(0, Math.min(tasks.length - 1, index + delta))];
+      if (next) selected = next.taskId;
+      if (detail && delta < 0) { scroll += -delta; follow = false; }
+      else if (detail && delta > 0) { scroll = Math.max(0, scroll - delta); follow = scroll === 0; }
+      requestRender();
+    };
+    let latchedId: string | undefined;
+    return {
+      render,
+      handleInput(data: string): void {
+        const key = data.toLowerCase();
+        if (confirmKill && key !== "k") { confirmKill = false; requestRender(); return; }
+        if (key === "q") { done(undefined); return; }
+        if (data === "\u001b") { if (detail) { detail = false; confirmKill = false; requestRender(); } else done(undefined); return; }
+        if (key === "h" && !detail) { history = !history; requestRender(); return; }
+        if (data === "\r" || data === "\n") { detail = true; scroll = 0; follow = true; requestRender(); return; }
+        if (data === "\u001b[A" || data === "k") { if (detail && key === "k") {
+          if (!confirmKill) { confirmKill = true; requestRender(); return; }
+          confirmKill = false;
+          const task = choose();
+          if (task?.status === "running") void registry.kill(task.taskId, "user");
+          requestRender(); return;
+        } move(-1); return; }
+        if (data === "\u001b[B" || key === "j") { move(1); return; }
+        if (data === "R" && detail) {
+          const task = choose();
+          if (task) {
+            try { registry.submit({ command: task.command, name: task.name, mode: "background" }); }
+            catch (error) { host.ui?.notify?.(String(error), "error"); }
+          }
+          requestRender(); return;
+        }
+        if (data === "c" && detail) {
+          const path = choose()?.metadata.outputFile;
+          if (typeof path === "string") {
+            if (host.ui?.copyToClipboard) host.ui.copyToClipboard(path);
+            else host.ui?.notify?.(path, "info");
+          }
+        }
+      },
+      handleMouse(event: { type: string; y?: number; button?: string; wheelDelta?: number }): { handled: boolean } | undefined {
+        if (event.type === "wheel") {
+          const delta = Math.trunc(event.wheelDelta ?? 0);
+          if (detail) { scroll = Math.max(0, scroll + delta); follow = scroll === 0; }
+          else move(delta);
+          requestRender();
+          return { handled: true };
+        }
+        if (event.type === "press") {
+          latchedId = undefined;
+          if (detail) return undefined;
+          if (event.button !== "left") return undefined;
+          const index = (event.y ?? -1) - 2;
+          const tasks = snapshots().filter((task) => history || task.status === "running" || task.status === "pending");
+          const task = tasks[index];
+          if (!task) return undefined;
+          latchedId = task.taskId;
+          return { handled: true };
+        }
+        if (event.type !== "click" || event.button !== "left" || detail) return undefined;
+        const index = (event.y ?? -1) - 2;
+        const tasks = snapshots().filter((task) => history || task.status === "running" || task.status === "pending");
+        const task = tasks[index];
+        if (!latchedId || !task || task.taskId !== latchedId) { latchedId = undefined; return undefined; }
+        selected = latchedId;
+        detail = true;
+        scroll = 0;
+        follow = true;
+        latchedId = undefined;
+        requestRender();
+        return { handled: true };
+      },
+      dispose(): void { void width; },
+    };
+  };
+  // Required full-screen overlay geometry. custom() resolves undefined outside supported TUI contexts.
+  // The RPC peer's custom() returns a Promise even though the overlay is unavailable there; mode guards above prevent invocation.
+  void custom(factory, { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", row: 0, col: 0 } }).catch(() => undefined);
+}

package/src/tui/rail.ts

@@ -0,0 +1,153 @@
+import type { PiCtx } from "../core/notify.ts";
+import type { TaskRegistry } from "../core/registry.ts";
+import type { TaskSnapshot } from "../core/task.ts";
+import type { TUI, TuiMouseEvent } from "@earendil-works/pi-tui";
+import { openPanel } from "./panel.ts";
+import { tuiHost } from "./host.ts";
+
+type Theme = { fg(color: string, text: string): string; getFgAnsi?(color: string): string };
+export interface RailWidget {
+  render(width?: number): string[];
+  handleMouse(event: TuiMouseEvent): { handled: boolean } | undefined;
+  dispose?(): void;
+}
+
+/** Palette color selection adapted from legion-viz/palette.ts (MIT License). */
+const TYPE_TOKENS = ["syntaxVariable", "syntaxKeyword", "syntaxNumber", "syntaxFunction", "syntaxString", "syntaxType"];
+type Swatch = { kind: "rgb"; l: number; a: number; b: number } | { kind: "key"; key: string };
+function ansiFor(theme: Theme, token: string): string {
+  // SAFETY: The peer theme exposes fg(); getFgAnsi is feature-detected for newer TUI versions.
+  const color = theme as Theme;
+  try { return color.getFgAnsi?.(token) ?? color.fg(token, "\0").split("\0")[0] ?? token; } catch { return token; }
+}
+function oklab(r: number, g: number, b: number): Swatch {
+  const linear = (n: number): number => { const v = n / 255; return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+  const R = linear(r), G = linear(g), B = linear(b);
+  const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);
+  const m = Math.cbrt(0.2119034708 * R + 0.6806995451 * G + 0.1073969566 * B);
+  const s = Math.cbrt(0.0883024619 * R + 0.281718565 * G + 0.6299787005 * B);
+  return { kind: "rgb", l: 0.2104542553*l + 0.793617785*m - 0.0040720468*s, a: 1.9779984951*l - 2.428592205*m + 0.4505937099*s, b: 0.0259040371*l + 0.7827717662*m - 0.808675766*s };
+}
+function swatch(theme: Theme, token: string): Swatch {
+  const ansi = ansiFor(theme, token);
+  const rgb = /38;2;(\d+);(\d+);(\d+)/.exec(ansi);
+  if (rgb) return oklab(Number(rgb[1]), Number(rgb[2]), Number(rgb[3]));
+  const index = /38;5;(\d+)/.exec(ansi);
+  if (index) {
+    const n = Number(index[1]);
+    if (n >= 232) { const v = 8 + 10 * (n - 232); return oklab(v, v, v); }
+    if (n >= 16) { const i = n - 16, step = [0, 95, 135, 175, 215, 255]; return oklab(step[Math.floor(i / 36)]!, step[Math.floor(i / 6) % 6]!, step[i % 6]!); }
+    return { kind: "key", key: `p${n}` };
+  }
+  const basic = /(?:^|\[|;)(3[0-7]|9[0-7])m/.exec(ansi);
+  return { kind: "key", key: basic?.[1] ?? ansi };
+}
+function clashes(a: Swatch, b: Swatch): boolean {
+  if (a.kind === "key" && b.kind === "key") return a.key === b.key;
+  if (a.kind === "key" || b.kind === "key") return false;
+  return Math.hypot(a.l - b.l, a.a - b.a, a.b - b.b) < 0.025;
+}
+function typeColor(theme: Theme, mode: string, used: Swatch[]): string {
+  const modeIndex = ["background", "sync", "delayed"].indexOf(mode);
+  const preferred = TYPE_TOKENS[modeIndex < 0 ? 0 : modeIndex]!;
+  for (const token of [preferred, ...TYPE_TOKENS]) {
+    const color = swatch(theme, token);
+    if (!used.some((previous) => clashes(color, previous))) { used.push(color); return token; }
+  }
+  return preferred;
+}
+
+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, "");
+}
+
+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`;
+}
+
+/** Pure, unstyled rail rows; active tasks first and a hard ten-row limit. */
+export function renderRailRows(snapshots: TaskSnapshot[], width: number, now = Date.now()): string[] {
+  const rows = snapshots.filter((task) => task.status !== "pending")
+    .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)}`);
+  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);
+}
+
+/** 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;
+}
+
+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) => {
+    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 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 used = [swatch(theme, "error"), swatch(theme, "dim")];
+      return 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);
+      });
+    };
+    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)));
+          if (next === scroll) return undefined;
+          scroll = next; latchedId = undefined; tui.requestRender(); return { handled: true };
+        }
+        if (mouse.type === "press") {
+          latchedId = undefined;
+          if (mouse.button !== "left") return undefined;
+          const id = hitRows[mouse.y];
+          if (!id) return undefined;
+          latchedId = id; return { handled: true };
+        }
+        if (mouse.type !== "click" || mouse.button !== "left") return undefined;
+        const id = hitRows[mouse.y];
+        if (!latchedId || id !== latchedId) { latchedId = undefined; return undefined; }
+        const clicked = latchedId; latchedId = undefined; opts.onOpenTask?.(clicked); return { handled: true };
+      },
+      dispose(): void { latchedId = undefined; },
+    };
+  };
+}
+
+/** The sole rail widget registration point. */
+export function registerRail(pi: PiCtx, registry: TaskRegistry): void {
+  // TUI surfaces bind from event contexts; the factory API has no mode/ui.
+  const bound = tuiHost();
+  if (!bound) return;
+  const setWidget = bound.ui["setWidget"] as ((key: string, factory: ReturnType<typeof createRailFactory> | undefined, options?: { placement: "aboveEditor" }) => void) | undefined;
+  setWidget?.("pi-async-rail", createRailFactory(pi, registry, { onOpenTask: (id) => openPanel(pi, registry, id) }), { placement: "aboveEditor" });
+}

package/src/tui/status.ts

@@ -0,0 +1,42 @@
+import type { PiCtx } from "../core/notify.ts";
+import type { TaskRegistry } from "../core/registry.ts";
+import { reportActivity } from "../core/bus.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 `;
+}
+
+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;
+}
+
+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);
+  };
+  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?.();
+}