@checkstack/scripts 0.3.4 → 0.4.0

package/src/dev-tui/log-level.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "bun:test";
+import { detectLogLevel, isAlertLevel } from "./log-level.ts";
+
+const ESC = String.fromCharCode(27);
+
+describe("detectLogLevel", () => {
+  it("detects info from the winston dev format", () => {
+    expect(detectLogLevel({ line: "21:02:49 info: server started" })).toBe(
+      "info",
+    );
+  });
+
+  it("detects warn from the winston dev format", () => {
+    expect(
+      detectLogLevel({ line: "21:02:49 warn: sandbox not ready" }),
+    ).toBe("warn");
+  });
+
+  it("detects error from the winston dev format", () => {
+    expect(detectLogLevel({ line: "09:00:01 error: boom" })).toBe("error");
+  });
+
+  it("detects debug from the winston dev format", () => {
+    expect(detectLogLevel({ line: "09:00:01 debug: noisy detail" })).toBe(
+      "debug",
+    );
+  });
+
+  it("detects the level even when winston colorize wraps it in ANSI codes", () => {
+    // winston colorize() output wraps the level token in SGR color codes.
+    const line = `21:02:49 ${ESC}[32minfo${ESC}[39m: server started`;
+    expect(detectLogLevel({ line })).toBe("info");
+  });
+
+  it("detects a colorized warn level", () => {
+    const line = `21:02:49 ${ESC}[33mwarn${ESC}[39m: heads up`;
+    expect(detectLogLevel({ line })).toBe("warn");
+  });
+
+  it("treats winston verbose/silly/http as debug-tier", () => {
+    expect(detectLogLevel({ line: "21:02:49 verbose: trace" })).toBe("debug");
+    expect(detectLogLevel({ line: "21:02:49 silly: trace" })).toBe("debug");
+    expect(detectLogLevel({ line: "21:02:49 http: GET /" })).toBe("debug");
+  });
+
+  it("recognizes a bare level token without a leading timestamp", () => {
+    expect(detectLogLevel({ line: "error: vite failed to start" })).toBe(
+      "error",
+    );
+    expect(detectLogLevel({ line: "WARN: deprecated option" })).toBe("warn");
+  });
+
+  it("recognizes bracketed levels like [ERROR]", () => {
+    expect(detectLogLevel({ line: "[ERROR] something broke" })).toBe("error");
+    expect(detectLogLevel({ line: "VITE v8.0.0  [warning] foo" })).toBe(
+      "warn",
+    );
+  });
+
+  it("classifies vite errors that surface as the word Error", () => {
+    expect(
+      detectLogLevel({ line: "Error: Failed to resolve import" }),
+    ).toBe("error");
+  });
+
+  it("defaults to info for plain unprefixed output", () => {
+    expect(detectLogLevel({ line: "Local:   http://localhost:5173/" })).toBe(
+      "info",
+    );
+  });
+
+  it("defaults to info for an empty line", () => {
+    expect(detectLogLevel({ line: "" })).toBe("info");
+    expect(detectLogLevel({ line: "   " })).toBe("info");
+  });
+
+  it("does not misread the substring 'error' inside a word", () => {
+    expect(
+      detectLogLevel({ line: "21:02:49 info: cleared error cache" }),
+    ).toBe("info");
+  });
+});
+
+describe("isAlertLevel", () => {
+  it("flags warn and error as alert levels", () => {
+    expect(isAlertLevel("warn")).toBe(true);
+    expect(isAlertLevel("error")).toBe(true);
+  });
+
+  it("does not flag info or debug", () => {
+    expect(isAlertLevel("info")).toBe(false);
+    expect(isAlertLevel("debug")).toBe(false);
+  });
+});

package/src/dev-tui/log-level.ts

@@ -0,0 +1,104 @@
+import { stripAnsi } from "./text.ts";
+
+/**
+ * Normalized log level used across the dev runner UI. The dev processes emit
+ * several formats (winston for the backend, vite/bun for the frontend), so we
+ * collapse every variant into these four buckets for coloring and alerting.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/**
+ * Map a raw level token (any case, any source format) to a normalized level.
+ * Winston's lower tiers (verbose/silly/http) collapse to "debug"; "warning"
+ * collapses to "warn"; "fatal" / "err" collapse to "error".
+ */
+function normalizeToken(token: string): LogLevel | undefined {
+  switch (token.toLowerCase()) {
+    case "error":
+    case "err":
+    case "fatal": {
+      return "error";
+    }
+    case "warn":
+    case "warning": {
+      return "warn";
+    }
+    case "info":
+    case "log":
+    case "notice": {
+      return "info";
+    }
+    case "debug":
+    case "verbose":
+    case "silly":
+    case "http":
+    case "trace": {
+      return "debug";
+    }
+    default: {
+      return undefined;
+    }
+  }
+}
+
+// `21:02:49 info: ...` (winston dev format) - optional timestamp, then a level
+// token, then a colon. The level word is matched as a whole token.
+const WINSTON_FORMAT =
+  /^(?:\d{2}:\d{2}:\d{2}\s+)?([A-Za-z]+):\s/;
+
+// Bracketed level tag, e.g. `[ERROR]`, `VITE  [warning]`.
+const BRACKET_FORMAT = /\[([A-Za-z]+)\]/;
+
+// Leading capitalized `Error:` that vite/node print for thrown errors.
+const LEADING_ERROR = /^(?:uncaught\s+)?error\b/i;
+
+export interface DetectLogLevelInput {
+  /** A single raw output line (may still contain ANSI color codes). */
+  line: string;
+}
+
+/**
+ * Classify a single raw output line into a normalized {@link LogLevel}.
+ *
+ * Strategy (first match wins):
+ *  1. Winston dev format `HH:mm:ss <level>:` or a bare `<level>:` prefix.
+ *  2. A bracketed `[LEVEL]` tag anywhere in the line.
+ *  3. A leading `Error:` (vite/node thrown errors).
+ *  4. Fallback to "info" so ordinary stdout stays readable.
+ */
+export function detectLogLevel({ line }: DetectLogLevelInput): LogLevel {
+  const plain = stripAnsi(line).trim();
+  if (plain.length === 0) {
+    return "info";
+  }
+
+  const winstonMatch = WINSTON_FORMAT.exec(plain);
+  if (winstonMatch) {
+    const level = normalizeToken(winstonMatch[1] ?? "");
+    if (level) {
+      return level;
+    }
+  }
+
+  const bracketMatch = BRACKET_FORMAT.exec(plain);
+  if (bracketMatch) {
+    const level = normalizeToken(bracketMatch[1] ?? "");
+    if (level) {
+      return level;
+    }
+  }
+
+  if (LEADING_ERROR.test(plain)) {
+    return "error";
+  }
+
+  return "info";
+}
+
+/**
+ * Whether a level should surface in the pinned Alerts panel. Only warnings and
+ * errors are aggregated so the panel stays signal, not noise.
+ */
+export function isAlertLevel(level: LogLevel): boolean {
+  return level === "warn" || level === "error";
+}

package/src/dev-tui/plain-runner.ts

@@ -0,0 +1,60 @@
+import process from "node:process";
+import { isAlertLevel } from "./log-level.ts";
+import type { Supervisor } from "./supervisor.ts";
+
+export interface RunPlainStreamingInput {
+  supervisor: Supervisor;
+  /** Sink for output (defaults to process.stdout). Injectable for smoke tests. */
+  write?: (text: string) => void;
+  /**
+   * Called after a clean shutdown completes (e.g. to exit the process). The
+   * entry point owns the actual `process.exit`; this module stays exit-free so
+   * it can be smoke-tested without tearing down the test runner.
+   */
+  onShutdownComplete?: () => void;
+}
+
+/**
+ * Non-TTY fallback: stream every process's output to stdout with a source
+ * prefix, never entering ink's raw mode. Used when piped or in CI so the runner
+ * degrades gracefully instead of crashing. Alerts (warn/error) are marked with
+ * a leading bang so they remain greppable even without the pinned panel.
+ *
+ * Returns the registered SIGINT/SIGTERM handler so callers (tests) can trigger
+ * a clean shutdown deterministically.
+ */
+export function runPlainStreaming({
+  supervisor,
+  write = (text: string): void => {
+    process.stdout.write(text);
+  },
+  onShutdownComplete,
+}: RunPlainStreamingInput): () => void {
+  supervisor.onLine((line) => {
+    const marker = isAlertLevel(line.level) ? "!" : " ";
+    write(`${marker}[${line.source}] ${line.text}\n`);
+  });
+
+  supervisor.onStatus(({ id, status }) => {
+    write(` [${id}] status: ${status}\n`);
+  });
+
+  let shuttingDown = false;
+  const shutdown = (): void => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    write("\n[dev-tui] shutting down backend + frontend (leaving docker deps up)\n");
+    void supervisor.shutdown().then(() => {
+      onShutdownComplete?.();
+    });
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  supervisor.start();
+
+  return shutdown;
+}

package/src/dev-tui/process-config.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "bun:test";
+import { PROCESS_DEFS } from "./process-config.ts";
+
+describe("PROCESS_DEFS", () => {
+  it("never spawns a long-running task via bun --filter", () => {
+    // `bun run --filter` buffers + frames output through its task dashboard
+    // instead of streaming raw lines, which defeats the per-line level
+    // detection that feeds the Alerts panel. Each watcher must run its own
+    // package's dev script directly.
+    for (const def of PROCESS_DEFS) {
+      expect(def.args).not.toContain("--filter");
+    }
+  });
+
+  it("runs backend + frontend dev directly in their package dirs", () => {
+    const byId = Object.fromEntries(PROCESS_DEFS.map((def) => [def.id, def]));
+
+    expect(byId.backend?.command).toBe("bun");
+    expect(byId.backend?.args).toEqual(["run", "dev"]);
+    expect(byId.backend?.cwd).toBe("core/backend");
+    expect(byId.backend?.oneShot).toBe(false);
+
+    expect(byId.frontend?.command).toBe("bun");
+    expect(byId.frontend?.args).toEqual(["run", "dev"]);
+    expect(byId.frontend?.cwd).toBe("core/frontend");
+    expect(byId.frontend?.oneShot).toBe(false);
+  });
+
+  it("runs deps as a one-shot docker task at the repo root", () => {
+    const deps = PROCESS_DEFS.find((def) => def.id === "deps");
+    expect(deps?.command).toBe("docker");
+    expect(deps?.args).toEqual([
+      "compose",
+      "-f",
+      "docker-compose-dev.yml",
+      "up",
+      "-d",
+    ]);
+    expect(deps?.cwd).toBeUndefined();
+    expect(deps?.oneShot).toBe(true);
+  });
+});

package/src/dev-tui/process-config.ts

@@ -0,0 +1,61 @@
+import type { ProcessId } from "./types.ts";
+
+/** Static definition of one supervised process. */
+export interface ProcessDef {
+  readonly id: ProcessId;
+  /** Human-readable name shown in the sidebar. */
+  readonly label: string;
+  /** Executable to spawn. */
+  readonly command: string;
+  /** Arguments passed to the executable. */
+  readonly args: readonly string[];
+  /**
+   * Working directory for the process, RELATIVE to the runner's root cwd (the
+   * repo root). Undefined runs at the root. Each long-running dev task runs
+   * directly in its own package dir so it streams that package's RAW output
+   * (e.g. winston `HH:MM:SS warn:` lines) - never through bun's `--filter`
+   * multi-task runner, which buffers + frames output and would defeat the
+   * per-line level detection feeding the Alerts panel.
+   */
+  readonly cwd?: string;
+  /**
+   * Whether this is a one-shot task (docker compose up -d) vs a long-running
+   * watcher. One-shot tasks become "ready" on a zero exit code; long-running
+   * ones become "ready" on a readiness marker and "stopped"/"errored" on exit.
+   */
+  readonly oneShot: boolean;
+}
+
+/**
+ * The three supervised processes, in sidebar order. The runner spawns each
+ * command DIRECTLY (no `bun run --filter`): deps via docker at the repo root,
+ * and each dev watcher via its own package's `dev` script in that package's
+ * dir. Running the package script directly streams its raw output, which the
+ * per-line level detection (and the Alerts panel) depends on; bun's `--filter`
+ * runner instead buffers/frames output through its task dashboard.
+ */
+export const PROCESS_DEFS: readonly ProcessDef[] = [
+  {
+    id: "deps",
+    label: "deps (docker)",
+    command: "docker",
+    args: ["compose", "-f", "docker-compose-dev.yml", "up", "-d"],
+    oneShot: true,
+  },
+  {
+    id: "backend",
+    label: "backend",
+    command: "bun",
+    args: ["run", "dev"],
+    cwd: "core/backend",
+    oneShot: false,
+  },
+  {
+    id: "frontend",
+    label: "frontend",
+    command: "bun",
+    args: ["run", "dev"],
+    cwd: "core/frontend",
+    oneShot: false,
+  },
+];

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

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "bun:test";
+import { matchesReady, READY_PATTERNS } from "./readiness.ts";
+
+describe("matchesReady", () => {
+  it("treats a vite Local URL as ready for the frontend", () => {
+    expect(
+      matchesReady({
+        id: "frontend",
+        line: "  ➜  Local:   http://localhost:5173/",
+      }),
+    ).toBe(true);
+  });
+
+  it("treats vite 'ready in' as ready for the frontend", () => {
+    expect(
+      matchesReady({ id: "frontend", line: "VITE v8.0.0  ready in 312 ms" }),
+    ).toBe(true);
+  });
+
+  it("treats a backend listening message as ready", () => {
+    expect(
+      matchesReady({
+        id: "backend",
+        line: "21:02:49 info: server listening on http://localhost:3000",
+      }),
+    ).toBe(true);
+  });
+
+  it("treats a backend 'ready' message as ready", () => {
+    expect(
+      matchesReady({ id: "backend", line: "21:02:49 info: backend ready" }),
+    ).toBe(true);
+  });
+
+  it("does not mark ordinary output as ready", () => {
+    expect(
+      matchesReady({ id: "backend", line: "21:02:49 info: loading plugin" }),
+    ).toBe(false);
+    expect(
+      matchesReady({ id: "frontend", line: "transforming module foo.ts" }),
+    ).toBe(false);
+  });
+
+  it("matches case-insensitively", () => {
+    expect(
+      matchesReady({ id: "backend", line: "Server LISTENING on 3000" }),
+    ).toBe(true);
+  });
+
+  it("has a pattern set for every long-running process", () => {
+    expect(READY_PATTERNS.backend.length).toBeGreaterThan(0);
+    expect(READY_PATTERNS.frontend.length).toBeGreaterThan(0);
+  });
+});

package/src/dev-tui/readiness.ts

@@ -0,0 +1,44 @@
+import { stripAnsi } from "./text.ts";
+import type { ProcessId } from "./types.ts";
+
+/**
+ * Readiness detection for the long-running dev processes. A process starts in
+ * "starting" and flips to "ready" the first time one of its readiness markers
+ * appears in its output. Patterns are kept conservative so ordinary log lines
+ * do not trigger a false "ready".
+ *
+ * `deps` (docker compose) has no streaming readiness marker - its readiness is
+ * driven by the compose command's exit code, not by matching a line - so it has
+ * an empty pattern set here.
+ */
+export const READY_PATTERNS: Readonly<Record<ProcessId, readonly RegExp[]>> = {
+  deps: [],
+  backend: [
+    // winston: "... info: server listening on http://localhost:3000"
+    /\blistening\b/i,
+    // a generic "<something> ready" banner
+    /\bready\b/i,
+    // a bound HTTP url is a strong readiness signal
+    /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0):\d+/i,
+  ],
+  frontend: [
+    // vite dev server: "  ➜  Local:   http://localhost:5173/"
+    /\blocal:\s*https?:\/\//i,
+    // vite: "ready in 312 ms"
+    /\bready in\b/i,
+  ],
+};
+
+export interface MatchesReadyInput {
+  id: ProcessId;
+  /** A single raw output line (ANSI is stripped internally). */
+  line: string;
+}
+
+/**
+ * Whether a given output line indicates the named process has become ready.
+ */
+export function matchesReady({ id, line }: MatchesReadyInput): boolean {
+  const plain = stripAnsi(line);
+  return READY_PATTERNS[id].some((pattern) => pattern.test(plain));
+}

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

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "bun:test";
+import { createScrollback } from "./scrollback.ts";
+
+describe("createScrollback", () => {
+  it("stores appended lines in order", () => {
+    const sb = createScrollback({ capacity: 10 });
+    sb.append({ text: "first", level: "info" });
+    sb.append({ text: "second", level: "warn" });
+    expect(sb.lines().map((entry) => entry.text)).toEqual(["first", "second"]);
+  });
+
+  it("caps at capacity, dropping the oldest lines", () => {
+    const sb = createScrollback({ capacity: 3 });
+    for (let i = 1; i <= 5; i++) {
+      sb.append({ text: `l${i}`, level: "info" });
+    }
+    expect(sb.lines().map((entry) => entry.text)).toEqual(["l3", "l4", "l5"]);
+  });
+
+  it("reports the total number of lines ever appended", () => {
+    const sb = createScrollback({ capacity: 2 });
+    sb.append({ text: "a", level: "info" });
+    sb.append({ text: "b", level: "info" });
+    sb.append({ text: "c", level: "info" });
+    expect(sb.size()).toBe(2);
+    expect(sb.totalAppended()).toBe(3);
+  });
+
+  it("returns a windowed slice for the viewport, tailing by default", () => {
+    const sb = createScrollback({ capacity: 100 });
+    for (let i = 1; i <= 10; i++) {
+      sb.append({ text: `l${i}`, level: "info" });
+    }
+    // tail window of height 3 -> last 3 lines
+    const view = sb.window({ height: 3, scrollOffset: 0 });
+    expect(view.map((entry) => entry.text)).toEqual(["l8", "l9", "l10"]);
+  });
+
+  it("scrolls back by the given offset", () => {
+    const sb = createScrollback({ capacity: 100 });
+    for (let i = 1; i <= 10; i++) {
+      sb.append({ text: `l${i}`, level: "info" });
+    }
+    const view = sb.window({ height: 3, scrollOffset: 2 });
+    expect(view.map((entry) => entry.text)).toEqual(["l6", "l7", "l8"]);
+  });
+
+  it("clamps a scroll offset that exceeds the history", () => {
+    const sb = createScrollback({ capacity: 100 });
+    for (let i = 1; i <= 5; i++) {
+      sb.append({ text: `l${i}`, level: "info" });
+    }
+    const view = sb.window({ height: 3, scrollOffset: 999 });
+    expect(view.map((entry) => entry.text)).toEqual(["l1", "l2", "l3"]);
+  });
+
+  it("returns all lines when the viewport is taller than the history", () => {
+    const sb = createScrollback({ capacity: 100 });
+    sb.append({ text: "only", level: "warn" });
+    const view = sb.window({ height: 10, scrollOffset: 0 });
+    expect(view.map((entry) => entry.text)).toEqual(["only"]);
+  });
+
+  it("rejects a non-positive capacity", () => {
+    expect(() => createScrollback({ capacity: 0 })).toThrow();
+  });
+});
+
+describe("clampScrollOffset", () => {
+  it("is exercised indirectly via window()", () => {
+    const sb = createScrollback({ capacity: 100 });
+    for (let i = 1; i <= 4; i++) {
+      sb.append({ text: `l${i}`, level: "info" });
+    }
+    // maxOffset = size(4) - height(2) = 2
+    expect(
+      sb.window({ height: 2, scrollOffset: 2 }).map((entry) => entry.text),
+    ).toEqual(["l1", "l2"]);
+    expect(
+      sb.window({ height: 2, scrollOffset: 3 }).map((entry) => entry.text),
+    ).toEqual(["l1", "l2"]);
+  });
+});

package/src/dev-tui/scrollback.ts

@@ -0,0 +1,82 @@
+import type { LogLevel } from "./log-level.ts";
+
+/** One stored output line with its detected level (for coloring). */
+export interface ScrollbackLine {
+  readonly text: string;
+  readonly level: LogLevel;
+}
+
+export interface ScrollbackWindowInput {
+  /** Number of visible rows in the main pane. */
+  height: number;
+  /**
+   * How many lines above the tail to scroll. 0 = follow the newest output;
+   * larger values move the window towards older history (clamped).
+   */
+  scrollOffset: number;
+}
+
+export interface Scrollback {
+  append(line: ScrollbackLine): void;
+  /** All retained lines, oldest-first (defensive copy). */
+  lines(): ScrollbackLine[];
+  /** Number of lines currently retained (<= capacity). */
+  size(): number;
+  /** Number of lines ever appended (for an overflow indicator). */
+  totalAppended(): number;
+  /** The slice of lines visible for a given viewport height and scroll offset. */
+  window(input: ScrollbackWindowInput): ScrollbackLine[];
+}
+
+export interface CreateScrollbackInput {
+  /** Maximum number of lines to retain per process. */
+  capacity: number;
+}
+
+/**
+ * Bounded scrollback buffer for one process's output. Keeps the last
+ * `capacity` lines and exposes a `window()` that follows the tail by default
+ * and supports scrolling back through retained history.
+ */
+export function createScrollback({
+  capacity,
+}: CreateScrollbackInput): Scrollback {
+  if (!Number.isInteger(capacity) || capacity <= 0) {
+    throw new Error(
+      `Scrollback capacity must be a positive integer, got ${capacity}`,
+    );
+  }
+
+  let buffer: ScrollbackLine[] = [];
+  let total = 0;
+
+  return {
+    append(line: ScrollbackLine): void {
+      buffer.push(line);
+      total += 1;
+      if (buffer.length > capacity) {
+        buffer = buffer.slice(buffer.length - capacity);
+      }
+    },
+    lines(): ScrollbackLine[] {
+      return [...buffer];
+    },
+    size(): number {
+      return buffer.length;
+    },
+    totalAppended(): number {
+      return total;
+    },
+    window({ height, scrollOffset }: ScrollbackWindowInput): ScrollbackLine[] {
+      const visibleHeight = Math.max(1, Math.floor(height));
+      if (buffer.length <= visibleHeight) {
+        return [...buffer];
+      }
+      const maxOffset = buffer.length - visibleHeight;
+      const offset = Math.min(Math.max(0, Math.floor(scrollOffset)), maxOffset);
+      const end = buffer.length - offset;
+      const start = end - visibleHeight;
+      return buffer.slice(start, end);
+    },
+  };
+}