@checkstack/scripts 0.3.4 → 0.4.0

package/src/dev-tui/alt-screen.ts

@@ -0,0 +1,65 @@
+import ansiEscapes from "ansi-escapes";
+
+/**
+ * Minimal writable sink the alternate-screen controller writes its escape
+ * sequences to. `process.stdout` satisfies this; tests pass a fake to capture
+ * the exact bytes written without touching a real terminal.
+ */
+export interface AltScreenStream {
+  write(data: string): boolean;
+}
+
+export interface AltScreen {
+  /** Switch the terminal into the alternate screen buffer (idempotent). */
+  enter(): void;
+  /** Restore the terminal's main screen buffer + cursor (idempotent). */
+  leave(): void;
+  /** Whether the alternate buffer is currently active. */
+  readonly isActive: boolean;
+}
+
+export interface CreateAltScreenInput {
+  /** Where to write the control sequences (defaults are wired by the caller). */
+  stream: AltScreenStream;
+}
+
+/**
+ * Controls the terminal's alternate screen buffer, the same mechanism vim and
+ * htop use: the TUI owns a clean, terminal-sized viewport that never scrolls
+ * the user's shell and leaves no artifacts on exit.
+ *
+ * `enter()` switches to the alternate buffer and hides the cursor; `leave()`
+ * shows the cursor and switches back to the main buffer. Both are idempotent so
+ * the controller can be invoked from multiple exit paths (`q`, SIGINT/SIGTERM,
+ * a thrown error, normal unmount) without double-toggling or getting the
+ * terminal stuck in the alternate buffer.
+ *
+ * The escape sequences come from `ansi-escapes` (already an ink dependency):
+ * `enterAlternativeScreen` is CSI `?1049h`, `exitAlternativeScreen` is CSI
+ * `?1049l`.
+ */
+export function createAltScreen({ stream }: CreateAltScreenInput): AltScreen {
+  let active = false;
+
+  return {
+    enter(): void {
+      if (active) {
+        return;
+      }
+      active = true;
+      stream.write(ansiEscapes.enterAlternativeScreen);
+      stream.write(ansiEscapes.cursorHide);
+    },
+    leave(): void {
+      if (!active) {
+        return;
+      }
+      active = false;
+      stream.write(ansiEscapes.cursorShow);
+      stream.write(ansiEscapes.exitAlternativeScreen);
+    },
+    get isActive(): boolean {
+      return active;
+    },
+  };
+}

package/src/dev-tui/cli.tsx

@@ -0,0 +1,89 @@
+#!/usr/bin/env bun
+import React from "react";
+import process from "node:process";
+import { render } from "ink";
+import { App } from "./App.tsx";
+import { createAltScreen } from "./alt-screen.ts";
+import { createSupervisor } from "./supervisor.ts";
+import { runPlainStreaming } from "./plain-runner.ts";
+import { createGracefulShutdown } from "./graceful-shutdown.ts";
+
+/**
+ * Entry point for the opt-in dev runner (`dev:tui`). On an interactive terminal
+ * it renders the ink TUI inside the ALTERNATE SCREEN BUFFER (like vim/htop) so
+ * the runner owns a clean, terminal-sized viewport: it never scrolls the user's
+ * shell and leaves no scrollback artifacts. When stdout is not a TTY (piped,
+ * redirected, CI) it degrades to a plain prefixed-stream runner that does NOT
+ * touch the alternate screen, so it never crashes ink's raw-mode requirements.
+ */
+function main(): void {
+  const cwd = process.cwd();
+  const isInteractive = Boolean(process.stdout.isTTY && process.stdin.isTTY);
+
+  const supervisor = createSupervisor({ cwd });
+
+  if (!isInteractive) {
+    runPlainStreaming({
+      supervisor,
+      onShutdownComplete: () => {
+        process.exit(0);
+      },
+    });
+    return;
+  }
+
+  const altScreen = createAltScreen({ stream: process.stdout });
+
+  // Guarantee the terminal is restored on EVERY exit path: normal unmount, `q`
+  // / Ctrl-C (handled inside the App, which unmounts), an uncaught error, and
+  // the OS signals. `leave()` is idempotent, so registering it on several paths
+  // is safe and the terminal can never get stuck in the alternate buffer.
+  let restored = false;
+  const restore = (): void => {
+    if (restored) {
+      return;
+    }
+    restored = true;
+    altScreen.leave();
+  };
+
+  // Every GRACEFUL exit path - ink unmount (`q` or Ctrl-C), SIGINT, SIGTERM -
+  // funnels through one handler that tears the supervised children down BEFORE
+  // the process dies, so Ctrl-C can never leave a stale backend bound to its
+  // port. The shared handler shuts down exactly once (an unmount racing a
+  // signal won't double-kill), and always restores the terminal + exits.
+  const gracefulExit = createGracefulShutdown({
+    shutdown: () => supervisor.shutdown(),
+    finalize: () => {
+      restore();
+      process.exit(0);
+    },
+  });
+  const onUncaught = (error: unknown): void => {
+    restore();
+    // Surface the failure on the (now restored) main screen before exiting.
+    console.error(error);
+    process.exit(1);
+  };
+
+  process.once("SIGINT", gracefulExit);
+  process.once("SIGTERM", gracefulExit);
+  process.once("uncaughtException", onUncaught);
+  process.once("unhandledRejection", onUncaught);
+  // `exit` is the final backstop: even if a path above is missed, the terminal
+  // is restored before the process is gone. It must be synchronous.
+  process.once("exit", restore);
+
+  altScreen.enter();
+
+  // `exitOnCtrlC: false`: ink must NOT exit on its own when Ctrl-C is pressed.
+  // The App's input handler maps Ctrl-C to the same quit() as `q` (which
+  // unmounts); letting ink auto-exit would tear the UI down and exit the
+  // process before the shutdown above runs, orphaning the backend.
+  const instance = render(<App supervisor={supervisor} onQuit={gracefulExit} />, {
+    exitOnCtrlC: false,
+  });
+  void instance.waitUntilExit().then(gracefulExit).catch(onUncaught);
+}
+
+main();

package/src/dev-tui/fake-supervisor.ts

@@ -0,0 +1,76 @@
+import type { CapturedLine, Supervisor } from "./supervisor.ts";
+import type { ProcessId, ProcessStatus } from "./types.ts";
+
+export interface FakeSupervisor extends Supervisor {
+  /** Push a captured line to all line listeners (test helper). */
+  emitLine(line: CapturedLine): void;
+  /** Push a status change to all status listeners (test helper). */
+  emitStatus(input: { id: ProcessId; status: ProcessStatus }): void;
+  /** Whether {@link Supervisor.start} was called. */
+  readonly started: boolean;
+  /** Ids passed to {@link Supervisor.restart}, in order. */
+  readonly restarted: readonly ProcessId[];
+  /** Whether {@link Supervisor.shutdown} was called. */
+  readonly didShutdown: boolean;
+}
+
+/**
+ * In-memory Supervisor stand-in for smoke tests. Spawns nothing: it lets a test
+ * drive line/status events deterministically and records lifecycle calls, so we
+ * can exercise the UI and the plain runner without real child processes.
+ */
+export function createFakeSupervisor(): FakeSupervisor {
+  const lineListeners: Array<(line: CapturedLine) => void> = [];
+  const statusListeners: Array<
+    (input: { id: ProcessId; status: ProcessStatus }) => void
+  > = [];
+  const statuses = new Map<ProcessId, ProcessStatus>([
+    ["deps", "starting"],
+    ["backend", "starting"],
+    ["frontend", "starting"],
+  ]);
+  const restarted: ProcessId[] = [];
+  let started = false;
+  let didShutdown = false;
+
+  return {
+    start(): void {
+      started = true;
+    },
+    restart(id: ProcessId): void {
+      restarted.push(id);
+    },
+    statusOf(id: ProcessId): ProcessStatus {
+      return statuses.get(id) ?? "stopped";
+    },
+    onLine(listener): void {
+      lineListeners.push(listener);
+    },
+    onStatus(listener): void {
+      statusListeners.push(listener);
+    },
+    async shutdown(): Promise<void> {
+      didShutdown = true;
+    },
+    emitLine(line: CapturedLine): void {
+      for (const listener of lineListeners) {
+        listener(line);
+      }
+    },
+    emitStatus(input: { id: ProcessId; status: ProcessStatus }): void {
+      statuses.set(input.id, input.status);
+      for (const listener of statusListeners) {
+        listener(input);
+      }
+    },
+    get started(): boolean {
+      return started;
+    },
+    get restarted(): readonly ProcessId[] {
+      return restarted;
+    },
+    get didShutdown(): boolean {
+      return didShutdown;
+    },
+  };
+}

package/src/dev-tui/graceful-shutdown.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "bun:test";
+import { createGracefulShutdown } from "./graceful-shutdown.ts";
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 5));
+
+describe("createGracefulShutdown", () => {
+  it("runs shutdown to completion BEFORE finalize (no stale children on exit)", async () => {
+    const order: string[] = [];
+    const handler = createGracefulShutdown({
+      shutdown: async () => {
+        await tick();
+        order.push("shutdown");
+      },
+      finalize: () => order.push("finalize"),
+    });
+
+    handler();
+    await tick();
+    await tick();
+
+    expect(order).toEqual(["shutdown", "finalize"]);
+  });
+
+  it("is idempotent: repeated triggers (unmount + signal) shut down once", async () => {
+    let shutdowns = 0;
+    let finalizes = 0;
+    const handler = createGracefulShutdown({
+      shutdown: async () => {
+        shutdowns += 1;
+      },
+      finalize: () => {
+        finalizes += 1;
+      },
+    });
+
+    handler();
+    handler();
+    handler();
+    await tick();
+
+    expect(shutdowns).toBe(1);
+    expect(finalizes).toBe(1);
+  });
+
+  it("still finalizes when shutdown rejects (terminal restored, process exits)", async () => {
+    let finalized = false;
+    const handler = createGracefulShutdown({
+      shutdown: async () => {
+        throw new Error("kill failed");
+      },
+      finalize: () => {
+        finalized = true;
+      },
+    });
+
+    handler();
+    await tick();
+
+    expect(finalized).toBe(true);
+  });
+});

package/src/dev-tui/graceful-shutdown.ts

@@ -0,0 +1,32 @@
+/**
+ * Build a one-shot graceful-exit handler shared by every exit path of the dev
+ * runner (ink unmount via `q` / Ctrl-C, and external SIGINT / SIGTERM).
+ *
+ * The bug this guards against: pressing Ctrl-C (or receiving a signal) used to
+ * terminate the runner WITHOUT tearing down the supervised children, leaving a
+ * stale backend bound to its port. Routing every exit through this helper
+ * guarantees `shutdown()` runs to completion BEFORE the process is finalized,
+ * and the `started` latch makes it idempotent so two near-simultaneous triggers
+ * (e.g. an unmount and a signal) shut down only once. `finalize` still runs even
+ * if `shutdown` rejects, so the terminal is always restored and the process
+ * always exits.
+ */
+export function createGracefulShutdown(args: {
+  shutdown: () => Promise<void>;
+  finalize: () => void;
+}): () => void {
+  const { shutdown, finalize } = args;
+  let started = false;
+  return () => {
+    if (started) {
+      return;
+    }
+    started = true;
+    // `finally` runs `finalize` whether shutdown resolves or rejects; the
+    // trailing `catch` swallows a rejected shutdown so it never surfaces as an
+    // unhandled rejection (the terminal is still restored and we still exit).
+    void shutdown()
+      .finally(finalize)
+      .catch(() => {});
+  };
+}

package/src/dev-tui/kill-tree.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "bun:test";
+import { planKill } from "./kill-tree.ts";
+
+describe("planKill", () => {
+  it("uses taskkill with the tree flag on Windows", () => {
+    const plan = planKill({ platform: "win32", pid: 1234, signal: "SIGTERM" });
+    expect(plan.kind).toBe("spawn");
+    if (plan.kind !== "spawn") {
+      throw new Error("expected spawn plan");
+    }
+    expect(plan.command).toBe("taskkill");
+    expect(plan.args).toEqual(["/pid", "1234", "/T", "/F"]);
+  });
+
+  it("signals the negative pid (process group) on Linux", () => {
+    const plan = planKill({ platform: "linux", pid: 4321, signal: "SIGTERM" });
+    expect(plan.kind).toBe("signal");
+    if (plan.kind !== "signal") {
+      throw new Error("expected signal plan");
+    }
+    expect(plan.target).toBe(-4321);
+    expect(plan.signal).toBe("SIGTERM");
+  });
+
+  it("signals the negative pid on macOS", () => {
+    const plan = planKill({ platform: "darwin", pid: 99, signal: "SIGKILL" });
+    expect(plan.kind).toBe("signal");
+    if (plan.kind !== "signal") {
+      throw new Error("expected signal plan");
+    }
+    expect(plan.target).toBe(-99);
+    expect(plan.signal).toBe("SIGKILL");
+  });
+
+  it("defaults to SIGTERM when no signal is supplied", () => {
+    const plan = planKill({ platform: "linux", pid: 7 });
+    if (plan.kind !== "signal") {
+      throw new Error("expected signal plan");
+    }
+    expect(plan.signal).toBe("SIGTERM");
+  });
+
+  it("rejects a non-positive pid", () => {
+    expect(() => planKill({ platform: "linux", pid: 0 })).toThrow();
+    expect(() => planKill({ platform: "linux", pid: -5 })).toThrow();
+  });
+});

package/src/dev-tui/kill-tree.ts

@@ -0,0 +1,64 @@
+/**
+ * Cross-platform process-tree termination planning. Pure logic so it can be
+ * unit-tested without spawning anything: it computes WHAT to run/signal, and
+ * the supervisor executes the plan.
+ *
+ * - POSIX (linux/darwin): children are spawned with `detached: true`, which
+ *   puts each in its own process group. Signaling the negative pid delivers
+ *   the signal to the whole group, so `bun --watch` and its grandchildren die
+ *   too (no orphans).
+ * - Windows: there are no process groups; `taskkill /T` walks and kills the
+ *   whole tree by pid.
+ */
+
+export type KillSignal = "SIGTERM" | "SIGKILL" | "SIGINT";
+
+export type KillPlan =
+  | {
+      readonly kind: "signal";
+      /** Negative pid to target the process group. */
+      readonly target: number;
+      readonly signal: KillSignal;
+    }
+  | {
+      readonly kind: "spawn";
+      readonly command: string;
+      readonly args: readonly string[];
+    };
+
+export interface PlanKillInput {
+  /** `process.platform` value. */
+  platform: NodeJS.Platform;
+  /** The child's pid (positive). */
+  pid: number;
+  /** Signal to send on POSIX; ignored on Windows (taskkill always force-kills). */
+  signal?: KillSignal;
+}
+
+/**
+ * Compute the platform-appropriate way to kill a child process and its entire
+ * descendant tree.
+ */
+export function planKill({
+  platform,
+  pid,
+  signal = "SIGTERM",
+}: PlanKillInput): KillPlan {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error(`planKill requires a positive integer pid, got ${pid}`);
+  }
+
+  if (platform === "win32") {
+    return {
+      kind: "spawn",
+      command: "taskkill",
+      args: ["/pid", String(pid), "/T", "/F"],
+    };
+  }
+
+  return {
+    kind: "signal",
+    target: -pid,
+    signal,
+  };
+}

package/src/dev-tui/layout.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "bun:test";
+import { computeLayout } from "./layout.ts";
+
+const ALERT_CAPACITY = 8;
+
+describe("computeLayout", () => {
+  it("fills the terminal exactly when it is tall enough", () => {
+    const layout = computeLayout({
+      size: { rows: 24, columns: 80 },
+      alertCount: 0,
+      alertCapacity: ALERT_CAPACITY,
+    });
+    // Chrome = status(1) + main panel(3) + alerts panel(3) + footer(1) = 8.
+    // Content budget = 24 - 8 = 16, split as 1 alert row + 15 log rows.
+    expect(layout.totalRows).toBe(24);
+    expect(layout.logRows + layout.alertRows).toBe(16);
+    expect(layout.alertRows).toBe(1);
+    expect(layout.logRows).toBe(15);
+  });
+
+  it("never reports more rows than the terminal has, for any alert count", () => {
+    for (const rows of [10, 18, 24, 40, 60]) {
+      for (let alertCount = 0; alertCount <= ALERT_CAPACITY + 4; alertCount += 1) {
+        const layout = computeLayout({
+          size: { rows, columns: 80 },
+          alertCount,
+          alertCapacity: ALERT_CAPACITY,
+        });
+        expect(layout.totalRows).toBeLessThanOrEqual(rows);
+        expect(layout.logRows).toBeGreaterThanOrEqual(1);
+        expect(layout.alertRows).toBeGreaterThanOrEqual(1);
+      }
+    }
+  });
+
+  it("clamps the alerts list to the buffer capacity", () => {
+    const layout = computeLayout({
+      size: { rows: 60, columns: 80 },
+      alertCount: 100,
+      alertCapacity: ALERT_CAPACITY,
+    });
+    expect(layout.alertRows).toBe(ALERT_CAPACITY);
+  });
+
+  it("grows the alerts pane with the alert count up to capacity", () => {
+    const three = computeLayout({
+      size: { rows: 40, columns: 80 },
+      alertCount: 3,
+      alertCapacity: ALERT_CAPACITY,
+    });
+    expect(three.alertRows).toBe(3);
+  });
+
+  it("keeps at least one log and one alert row on a tiny terminal", () => {
+    const layout = computeLayout({
+      size: { rows: 4, columns: 80 },
+      alertCount: 5,
+      alertCapacity: ALERT_CAPACITY,
+    });
+    expect(layout.logRows).toBe(1);
+    expect(layout.alertRows).toBe(1);
+  });
+
+  it("uses more of the terminal than the pre-fix constant-16 reserve did", () => {
+    // The old code computed mainHeight = max(3, rows - 16) regardless of how
+    // many alerts were queued, wasting up to 8 rows when alerts were sparse.
+    // This locks in that the derived reserve never under-fills the terminal.
+    for (const rows of [24, 40, 60]) {
+      const oldMainHeight = Math.max(3, rows - 16);
+      const layout = computeLayout({
+        size: { rows, columns: 80 },
+        alertCount: 0,
+        alertCapacity: ALERT_CAPACITY,
+      });
+      expect(layout.logRows).toBeGreaterThan(oldMainHeight);
+    }
+  });
+
+  it("protects the log pane minimum when alerts would otherwise consume the budget", () => {
+    // rows=18 -> budget 10. With 8 alerts wanted, log must keep >= 1 row.
+    const layout = computeLayout({
+      size: { rows: 18, columns: 80 },
+      alertCount: ALERT_CAPACITY,
+      alertCapacity: ALERT_CAPACITY,
+    });
+    expect(layout.logRows).toBeGreaterThanOrEqual(1);
+    expect(layout.totalRows).toBeLessThanOrEqual(18);
+  });
+});

package/src/dev-tui/layout.ts

@@ -0,0 +1,126 @@
+/**
+ * Pure layout math for the dev-runner TUI. Computes how many rows the focused
+ * log pane and the alerts list may use so the rendered frame is provably never
+ * taller than the terminal.
+ *
+ * The reserve is derived from the ACTUAL component structure rather than a
+ * magic number, so adding/removing chrome stays honest:
+ *
+ *   row  component
+ *   ---  ----------------------------------------------------------------
+ *    1   status bar (single padded row)
+ *    1   main pane: round-border top edge
+ *    1   main pane: panel title row
+ *    N   main pane: log content rows            <- LOG_ROWS (clamped)
+ *    1   main pane: round-border bottom edge
+ *    1   alerts pane: round-border top edge
+ *    1   alerts pane: panel title row
+ *    M   alerts pane: alert content rows         <- ALERT_ROWS (clamped)
+ *    1   alerts pane: round-border bottom edge
+ *    1   footer key hints (single row)
+ *
+ * A round-bordered Panel costs 2 rows of border plus 1 title row, so each panel
+ * adds 3 rows of chrome around its content. The sidebar shares the main pane's
+ * row band, so it never contributes additional vertical rows.
+ */
+
+/** Injectable terminal dimensions (overrides ink's `useStdout`). */
+export interface TerminalSize {
+  readonly rows: number;
+  readonly columns: number;
+}
+
+/** Fallback size when no TTY size is available (matches ink's own default). */
+export const DEFAULT_TERMINAL_SIZE: TerminalSize = { rows: 24, columns: 80 };
+
+/** Fixed sidebar width so its labels truncate instead of wrapping. */
+export const SIDEBAR_WIDTH = 22;
+
+/** Single padded status row at the top of the frame. */
+const STATUS_BAR_ROWS = 1;
+
+/** Single footer row of key hints at the bottom of the frame. */
+const FOOTER_ROWS = 1;
+
+/** A round-bordered Panel with a title costs 2 border rows + 1 title row. */
+const PANEL_CHROME_ROWS = 3;
+
+/**
+ * The alerts pane always renders at least one content row: either the queued
+ * alerts (1..capacity) or the single "No warnings or errors yet." placeholder.
+ */
+const MIN_ALERT_ROWS = 1;
+
+/** The main log pane must keep at least one visible content row. */
+const MIN_LOG_ROWS = 1;
+
+export interface ComputeLayoutInput {
+  /** Terminal dimensions the frame must fit within. */
+  size: TerminalSize;
+  /** How many alerts are queued (0 renders the placeholder row). */
+  alertCount: number;
+  /** Hard cap on alert rows (the alert buffer capacity). */
+  alertCapacity: number;
+}
+
+export interface DevTuiLayout {
+  /** Rows the focused log pane content may use (>= 1). */
+  readonly logRows: number;
+  /** Rows the alerts list may use (>= 1, <= capacity). */
+  readonly alertRows: number;
+  /** Total rows the rendered frame occupies (provably <= size.rows). */
+  readonly totalRows: number;
+}
+
+/**
+ * Distribute the terminal's rows across the fixed chrome, the alerts list, and
+ * the focused log pane. Alerts are clamped first (they are pinned and bounded
+ * by capacity); the log pane then absorbs whatever vertical space remains. Both
+ * are floored at one row so a tiny terminal still renders a coherent frame.
+ *
+ * Guarantee: `logRows + alertRows + chrome === min(totalRows, size.rows)` when
+ * the terminal is tall enough, and never exceeds `size.rows`.
+ */
+export function computeLayout({
+  size,
+  alertCount,
+  alertCapacity,
+}: ComputeLayoutInput): DevTuiLayout {
+  const terminalRows = Math.max(1, Math.floor(size.rows));
+
+  // Chrome that is always present regardless of content height.
+  const fixedChrome =
+    STATUS_BAR_ROWS + PANEL_CHROME_ROWS + PANEL_CHROME_ROWS + FOOTER_ROWS;
+
+  // Alerts content the pane wants to show (placeholder counts as one row),
+  // capped by the buffer capacity so a flood can never grow the pane.
+  const cappedCapacity = Math.max(MIN_ALERT_ROWS, Math.floor(alertCapacity));
+  const desiredAlertRows = Math.max(MIN_ALERT_ROWS, Math.floor(alertCount));
+  const wantedAlertRows = Math.min(desiredAlertRows, cappedCapacity);
+
+  // Rows left for the variable content after fixed chrome.
+  const contentBudget = terminalRows - fixedChrome;
+
+  if (contentBudget < MIN_LOG_ROWS + MIN_ALERT_ROWS) {
+    // Terminal is too short to honor every minimum. Give each variable region
+    // its single-row minimum and accept that a genuinely tiny terminal cannot
+    // show full chrome; the totalRows we report still reflects exactly what the
+    // components occupy so callers can reason about it.
+    return {
+      logRows: MIN_LOG_ROWS,
+      alertRows: MIN_ALERT_ROWS,
+      totalRows: fixedChrome + MIN_LOG_ROWS + MIN_ALERT_ROWS,
+    };
+  }
+
+  // Alerts take what they want, but never so much that the log pane drops below
+  // its minimum.
+  const alertRows = Math.min(wantedAlertRows, contentBudget - MIN_LOG_ROWS);
+  const logRows = contentBudget - alertRows;
+
+  return {
+    logRows,
+    alertRows,
+    totalRows: fixedChrome + logRows + alertRows,
+  };
+}