@checkstack/scripts 0.3.3 → 0.4.0

package/src/dev-tui/supervisor.ts

@@ -0,0 +1,231 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import path from "node:path";
+import { detectLogLevel, type LogLevel } from "./log-level.ts";
+import { createLineSplitter } from "./text.ts";
+import { matchesReady } from "./readiness.ts";
+import { planKill } from "./kill-tree.ts";
+import { PROCESS_DEFS, type ProcessDef } from "./process-config.ts";
+import type { ProcessId, ProcessStatus } from "./types.ts";
+
+/** A single captured output line with its detected level and a sequence id. */
+export interface CapturedLine {
+  readonly source: ProcessId;
+  readonly level: LogLevel;
+  readonly text: string;
+  readonly seq: number;
+}
+
+export interface SupervisorEvents {
+  /** A new output line was captured from any process. */
+  line: (line: CapturedLine) => void;
+  /** A process changed status. */
+  status: (input: { id: ProcessId; status: ProcessStatus }) => void;
+}
+
+export interface Supervisor {
+  /** Start all processes. The deps task is started first. */
+  start(): void;
+  /** Restart a single process (kills its tree, then respawns). */
+  restart(id: ProcessId): void;
+  /**
+   * Stop the long-running children (backend + frontend) and their trees.
+   * Leaves the `-d` docker deps running, matching the existing `dev` script.
+   */
+  shutdown(): Promise<void>;
+  /** Current status of a process. */
+  statusOf(id: ProcessId): ProcessStatus;
+  /** Subscribe to captured output lines. */
+  onLine(listener: SupervisorEvents["line"]): void;
+  /** Subscribe to status transitions. */
+  onStatus(listener: SupervisorEvents["status"]): void;
+}
+
+interface RunningProcess {
+  readonly def: ProcessDef;
+  child?: ChildProcess;
+  status: ProcessStatus;
+}
+
+export interface CreateSupervisorInput {
+  /** Working directory to spawn children in (the repo root). */
+  cwd: string;
+}
+
+/**
+ * Spawns and supervises the dev processes. Children are spawned in their own
+ * process group (POSIX) so the entire watcher tree can be torn down cleanly.
+ * Output is split into lines, level-tagged, and emitted via `line` events;
+ * status transitions are emitted via `status` events. All UI state derives from
+ * these events, keeping the ink components thin.
+ */
+export function createSupervisor({ cwd }: CreateSupervisorInput): Supervisor {
+  const processes = new Map<ProcessId, RunningProcess>();
+  for (const def of PROCESS_DEFS) {
+    processes.set(def.id, { def, status: "stopped" });
+  }
+
+  const lineListeners: SupervisorEvents["line"][] = [];
+  const statusListeners: SupervisorEvents["status"][] = [];
+  let seq = 0;
+
+  const emitLine = (input: {
+    source: ProcessId;
+    text: string;
+  }): void => {
+    seq += 1;
+    const line: CapturedLine = {
+      source: input.source,
+      text: input.text,
+      level: detectLogLevel({ line: input.text }),
+      seq,
+    };
+    for (const listener of lineListeners) {
+      listener(line);
+    }
+  };
+
+  const setStatus = (id: ProcessId, status: ProcessStatus): void => {
+    const proc = processes.get(id);
+    if (!proc || proc.status === status) {
+      return;
+    }
+    proc.status = status;
+    for (const listener of statusListeners) {
+      listener({ id, status });
+    }
+  };
+
+  const handleOutput = (id: ProcessId, oneShot: boolean) => {
+    const split = createLineSplitter();
+    return (chunk: Buffer): void => {
+      const text = chunk.toString("utf8");
+      for (const text_ of split(text)) {
+        emitLine({ source: id, text: text_ });
+        if (!oneShot && matchesReady({ id, line: text_ })) {
+          setStatus(id, "ready");
+        }
+      }
+    };
+  };
+
+  const spawnProcess = (id: ProcessId): void => {
+    const proc = processes.get(id);
+    if (!proc) {
+      return;
+    }
+    const { def } = proc;
+
+    setStatus(id, "starting");
+
+    const child = spawn(def.command, [...def.args], {
+      // Each process runs in its own package dir (relative to the root cwd) so
+      // it streams that package's raw output; deps runs at the root.
+      cwd: def.cwd === undefined ? cwd : path.join(cwd, def.cwd),
+      // New process group on POSIX so we can kill the whole watcher tree.
+      // On Windows this is ignored; taskkill /T handles the tree instead.
+      detached: process.platform !== "win32",
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    proc.child = child;
+
+    const onData = handleOutput(id, def.oneShot);
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+
+    child.on("error", (error: Error) => {
+      emitLine({ source: id, text: `error: failed to spawn ${def.command}: ${error.message}` });
+      setStatus(id, "errored");
+    });
+
+    child.on("exit", (code: number | null) => {
+      proc.child = undefined;
+      if (def.oneShot) {
+        // deps: zero exit = ready; anything else = errored.
+        setStatus(id, code === 0 ? "ready" : "errored");
+      } else if (code === 0 || code === null) {
+        setStatus(id, "stopped");
+      } else {
+        setStatus(id, "errored");
+      }
+    });
+  };
+
+  const killProcess = (id: ProcessId): void => {
+    const proc = processes.get(id);
+    const child = proc?.child;
+    if (!proc || !child || child.pid === undefined) {
+      return;
+    }
+    const plan = planKill({ platform: process.platform, pid: child.pid });
+    try {
+      if (plan.kind === "signal") {
+        process.kill(plan.target, plan.signal);
+      } else {
+        spawn(plan.command, [...plan.args], { stdio: "ignore" });
+      }
+    } catch {
+      // Process already gone or group missing; nothing to do.
+    }
+  };
+
+  return {
+    start(): void {
+      for (const def of PROCESS_DEFS) {
+        spawnProcess(def.id);
+      }
+    },
+
+    restart(id: ProcessId): void {
+      killProcess(id);
+      // Respawn on the next tick so the old child's exit is processed first.
+      setTimeout(() => spawnProcess(id), 150);
+    },
+
+    statusOf(id: ProcessId): ProcessStatus {
+      return processes.get(id)?.status ?? "stopped";
+    },
+
+    onLine(listener: SupervisorEvents["line"]): void {
+      lineListeners.push(listener);
+    },
+
+    onStatus(listener: SupervisorEvents["status"]): void {
+      statusListeners.push(listener);
+    },
+
+    async shutdown(): Promise<void> {
+      // Only tear down the long-running children; leave docker deps (-d) up.
+      const longRunning = PROCESS_DEFS.filter((def) => !def.oneShot);
+      for (const def of longRunning) {
+        killProcess(def.id);
+      }
+      // Give children a moment to exit on SIGTERM, then force-kill survivors.
+      await new Promise<void>((resolve) => {
+        setTimeout(() => {
+          for (const def of longRunning) {
+            const proc = processes.get(def.id);
+            const child = proc?.child;
+            if (child?.pid !== undefined) {
+              const plan = planKill({
+                platform: process.platform,
+                pid: child.pid,
+                signal: "SIGKILL",
+              });
+              try {
+                if (plan.kind === "signal") {
+                  process.kill(plan.target, plan.signal);
+                } else {
+                  spawn(plan.command, [...plan.args], { stdio: "ignore" });
+                }
+              } catch {
+                // Already gone.
+              }
+            }
+          }
+          resolve();
+        }, 600);
+      });
+    },
+  };
+}

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

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "bun:test";
+import { stripAnsi, createLineSplitter } from "./text.ts";
+
+const ESC = String.fromCharCode(27);
+
+describe("stripAnsi", () => {
+  it("removes SGR color codes", () => {
+    expect(stripAnsi(`${ESC}[32minfo${ESC}[39m`)).toBe("info");
+  });
+
+  it("removes cursor and erase sequences", () => {
+    expect(stripAnsi(`${ESC}[2Khello${ESC}[1G`)).toBe("hello");
+  });
+
+  it("removes a two-character escape", () => {
+    expect(stripAnsi(`a${ESC}cb`)).toBe("ab");
+  });
+
+  it("leaves plain text untouched", () => {
+    expect(stripAnsi("no codes here")).toBe("no codes here");
+  });
+
+  it("handles an empty string", () => {
+    expect(stripAnsi("")).toBe("");
+  });
+});
+
+describe("createLineSplitter", () => {
+  it("splits a single chunk ending in a newline into one line", () => {
+    const split = createLineSplitter();
+    expect(split("hello\n")).toEqual(["hello"]);
+  });
+
+  it("buffers a partial line until the newline arrives", () => {
+    const split = createLineSplitter();
+    expect(split("hel")).toEqual([]);
+    expect(split("lo\n")).toEqual(["hello"]);
+  });
+
+  it("emits multiple complete lines from one chunk", () => {
+    const split = createLineSplitter();
+    expect(split("a\nb\nc\n")).toEqual(["a", "b", "c"]);
+  });
+
+  it("keeps the trailing partial line buffered across chunks", () => {
+    const split = createLineSplitter();
+    expect(split("a\nb")).toEqual(["a"]);
+    expect(split("c\n")).toEqual(["bc"]);
+  });
+
+  it("normalizes CRLF line endings", () => {
+    const split = createLineSplitter();
+    expect(split("a\r\nb\r\n")).toEqual(["a", "b"]);
+  });
+
+  it("strips a lone trailing carriage return inside a chunk", () => {
+    const split = createLineSplitter();
+    expect(split("progress\rdone\n")).toEqual(["progressdone"]);
+  });
+
+  it("flush() emits any buffered remainder without a newline", () => {
+    const split = createLineSplitter();
+    expect(split("dangling")).toEqual([]);
+    expect(split.flush()).toEqual(["dangling"]);
+  });
+
+  it("flush() emits nothing when the buffer is empty", () => {
+    const split = createLineSplitter();
+    expect(split("a\n")).toEqual(["a"]);
+    expect(split.flush()).toEqual([]);
+  });
+});

package/src/dev-tui/text.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure text helpers for the dev runner. DOM-free and dependency-free so they
+ * can be unit-tested with `bun:test` and reused by the (thin) ink components.
+ */
+
+const ESC = String.fromCodePoint(27); // ASCII 27, start of every ANSI escape sequence.
+
+/**
+ * Remove ANSI escape sequences from a string so downstream parsing (log-level
+ * detection, width measurement) sees plain text.
+ *
+ * Implemented as a small scanner rather than a control-character regex: it
+ * skips `ESC [ ... <final>` CSI sequences (colors, cursor moves, erases) and
+ * the shorter `ESC <byte>` two-character escapes, copying everything else
+ * verbatim.
+ */
+export function stripAnsi(input: string): string {
+  if (!input.includes(ESC)) {
+    return input;
+  }
+
+  let result = "";
+  let index = 0;
+  while (index < input.length) {
+    const char = input[index];
+    if (char !== ESC) {
+      result += char;
+      index += 1;
+      continue;
+    }
+
+    const next = input[index + 1];
+    if (next === "[") {
+      // CSI sequence: parameters/intermediates until a final byte in 0x40..0x7E.
+      let cursor = index + 2;
+      while (cursor < input.length) {
+        const code = input.codePointAt(cursor) ?? 0;
+        cursor += 1;
+        if (code >= 0x40 && code <= 0x7E) {
+          // CSI final byte reached.
+          break;
+        }
+      }
+      index = cursor;
+      continue;
+    }
+
+    // Two-character escape (e.g. ESC c). Skip the ESC and the following byte.
+    index += next === undefined ? 1 : 2;
+  }
+
+  return result;
+}
+
+export interface LineSplitter {
+  (chunk: string): string[];
+  /** Emit any buffered remainder that never terminated with a newline. */
+  flush(): string[];
+}
+
+/**
+ * Create a stateful splitter that turns an arbitrary stream of chunks into
+ * whole lines. Partial lines are buffered across chunks and CRLF / lone CR are
+ * normalized away so terminal redraw sequences do not produce phantom lines.
+ */
+export function createLineSplitter(): LineSplitter {
+  let buffer = "";
+
+  const split: LineSplitter = (chunk: string): string[] => {
+    buffer += chunk;
+    const lines: string[] = [];
+    let newlineIndex = buffer.indexOf("\n");
+    while (newlineIndex !== -1) {
+      const rawLine = buffer.slice(0, newlineIndex);
+      lines.push(normalizeLine(rawLine));
+      buffer = buffer.slice(newlineIndex + 1);
+      newlineIndex = buffer.indexOf("\n");
+    }
+    return lines;
+  };
+
+  split.flush = (): string[] => {
+    if (buffer.length === 0) {
+      return [];
+    }
+    const remainder = normalizeLine(buffer);
+    buffer = "";
+    return [remainder];
+  };
+
+  return split;
+}
+
+/**
+ * Drop carriage returns from a single (already newline-split) line. A trailing
+ * CR is the CRLF tail; an interior CR is a redraw cursor-return that we collapse
+ * so the visible text is preserved.
+ */
+function normalizeLine(line: string): string {
+  return line.replaceAll("\r", "");
+}

package/src/dev-tui/types.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { LogLevel } from "./log-level.ts";
+
+/**
+ * Stable identifier for one supervised process. Used as the alert source tag
+ * and the sidebar key, so it must be unique per process.
+ */
+export const processIdSchema = z.enum(["deps", "backend", "frontend"]);
+export type ProcessId = z.infer<typeof processIdSchema>;
+
+/**
+ * Lifecycle status of a supervised process, surfaced as a colored status dot.
+ */
+export const processStatusSchema = z.enum([
+  "starting",
+  "ready",
+  "errored",
+  "stopped",
+]);
+export type ProcessStatus = z.infer<typeof processStatusSchema>;
+
+/** A single aggregated alert (a warn/error line from any process). */
+export interface AlertEntry {
+  readonly source: ProcessId;
+  readonly level: LogLevel;
+  readonly text: string;
+  /** Monotonic sequence number used for stable newest-first ordering. */
+  readonly seq: number;
+}

package/src/scaffold/index.ts

@@ -0,0 +1,22 @@
+export {
+  rewriteWorkspaceVersions,
+  DEPENDENCY_SECTIONS,
+  type DependencySection,
+  type VersionResolver,
+  type RewritablePackageJson,
+  type RewriteResult,
+} from "./rewrite-workspace-versions";
+export { createWorkspaceMapResolver } from "./resolve-versions";
+export {
+  scaffoldPlugin,
+  scaffoldStandaloneRoot,
+  refreshMonorepoReferences,
+  resolveTargetDir,
+  TEMPLATES_DIR,
+  STANDALONE_ROOT_TEMPLATE_DIR,
+  type ScaffoldMode,
+  type ScaffoldIo,
+  type ScaffoldPluginOptions,
+  type ScaffoldPluginResult,
+  type ScaffoldStandaloneRootResult,
+} from "./scaffold-plugin";

package/src/scaffold/resolve-versions.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect, afterEach } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createWorkspaceMapResolver } from "./resolve-versions";
+
+const tmpDirs: string[] = [];
+
+function makeSiblingDir({ version }: { version: string }): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "resolve-versions-"));
+  tmpDirs.push(dir);
+  fs.writeFileSync(
+    path.join(dir, "package.json"),
+    JSON.stringify({ name: "@checkstack/common", version }),
+  );
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tmpDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("createWorkspaceMapResolver", () => {
+  it("resolves a workspace dep to a caret on the sibling's version", async () => {
+    const dir = makeSiblingDir({ version: "0.12.0" });
+    const resolve = createWorkspaceMapResolver({
+      workspaceMap: new Map([["@checkstack/common", dir]]),
+    });
+
+    expect(
+      await resolve({
+        packageName: "@checkstack/common",
+        workspaceRange: "workspace:*",
+      }),
+    ).toBe("^0.12.0");
+  });
+
+  it("returns undefined for a name not in the map", async () => {
+    const resolve = createWorkspaceMapResolver({ workspaceMap: new Map() });
+    expect(
+      await resolve({
+        packageName: "@checkstack/missing",
+        workspaceRange: "workspace:*",
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/scaffold/resolve-versions.ts

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { VersionResolver } from "./rewrite-workspace-versions";
+
+/**
+ * Version-resolution seam for {@link rewriteWorkspaceVersions}.
+ *
+ * The scaffolding engine and `plugin-pack` both need to turn a
+ * `workspace:*` range into a concrete one, but they source the concrete
+ * version differently:
+ *
+ *   - In a monorepo, the version is read from the sibling package's own
+ *     `package.json` on disk (a `name -> dir` workspace map). This is the
+ *     behaviour `plugin-pack` has always had.
+ *   - In a standalone scaffold (Phase 2), the version is resolved from the
+ *     registry's `latest` dist-tag via `npm view`. That resolver lives in
+ *     `create-checkstack-plugin`; the engine only sees the injected
+ *     {@link VersionResolver} interface, so it stays registry-agnostic.
+ *
+ * Keeping the resolver injected (rather than hardcoded) is also what lets
+ * the integration test point it at a local Verdaccio registry without any
+ * network access.
+ */
+
+function readJson<T>(filePath: string): T {
+  return JSON.parse(fs.readFileSync(filePath, "utf8")) as T;
+}
+
+/**
+ * Build a {@link VersionResolver} backed by a workspace `name -> dir` map.
+ * Each resolved range is a caret on the sibling's current version
+ * (`^<version>`), matching how `plugin-pack` has always rewritten and what
+ * the runtime compatibility checker's `semver.satisfies` expects.
+ *
+ * Returns `undefined` for names not present in the map; the caller decides
+ * whether an unresolved dep is fatal (`plugin-pack` throws, mirroring its
+ * previous behaviour).
+ */
+export function createWorkspaceMapResolver({
+  workspaceMap,
+}: {
+  workspaceMap: Map<string, string>;
+}): VersionResolver {
+  // The map read is synchronous, but the shared VersionResolver seam is
+  // async (the standalone npm-view resolver needs it), so this resolver is
+  // declared `async` to satisfy the shared Promise-returning signature.
+  return async ({ packageName }) => {
+    const dir = workspaceMap.get(packageName);
+    if (!dir) return;
+    const sibling = readJson<{ version: string }>(
+      path.join(dir, "package.json"),
+    );
+    return `^${sibling.version}`;
+  };
+}

package/src/scaffold/rewrite-workspace-versions.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "bun:test";
+import {
+  rewriteWorkspaceVersions,
+  type RewritablePackageJson,
+  type VersionResolver,
+} from "./rewrite-workspace-versions";
+
+const constantResolver =
+  (version: string): VersionResolver =>
+  () =>
+    Promise.resolve(version);
+
+describe("rewriteWorkspaceVersions", () => {
+  it("rewrites workspace ranges across all dependency sections", async () => {
+    const pkg: RewritablePackageJson = {
+      name: "@scope/widget-backend",
+      dependencies: {
+        "@checkstack/common": "workspace:*",
+        "@orpc/server": "^1.13.2",
+      },
+      devDependencies: {
+        "@checkstack/scripts": "workspace:^",
+      },
+      peerDependencies: {
+        "@checkstack/backend": "workspace:*",
+      },
+    };
+
+    const result = await rewriteWorkspaceVersions({
+      pkg,
+      resolveVersion: constantResolver("^1.2.3"),
+    });
+
+    expect(result.rewritten).toBe(true);
+    expect(result.unresolved).toEqual([]);
+    expect(pkg.dependencies).toEqual({
+      "@checkstack/common": "^1.2.3",
+      "@orpc/server": "^1.13.2",
+    });
+    expect(pkg.devDependencies).toEqual({ "@checkstack/scripts": "^1.2.3" });
+    expect(pkg.peerDependencies).toEqual({ "@checkstack/backend": "^1.2.3" });
+  });
+
+  it("leaves non-workspace ranges untouched and reports rewritten=false", async () => {
+    const pkg: RewritablePackageJson = {
+      name: "@scope/widget-backend",
+      dependencies: {
+        "@checkstack/common": "^0.12.0",
+        "drizzle-orm": "^0.45.1",
+      },
+    };
+
+    const result = await rewriteWorkspaceVersions({
+      pkg,
+      resolveVersion: constantResolver("^9.9.9"),
+    });
+
+    expect(result.rewritten).toBe(false);
+    expect(pkg.dependencies).toEqual({
+      "@checkstack/common": "^0.12.0",
+      "drizzle-orm": "^0.45.1",
+    });
+  });
+
+  it("records unresolved deps and does not mutate them", async () => {
+    const pkg: RewritablePackageJson = {
+      dependencies: {
+        "@checkstack/common": "workspace:*",
+        "@checkstack/missing": "workspace:*",
+      },
+    };
+    const resolver: VersionResolver = ({ packageName }) =>
+      Promise.resolve(
+        packageName === "@checkstack/common" ? "^1.0.0" : undefined,
+      );
+
+    const result = await rewriteWorkspaceVersions({
+      pkg,
+      resolveVersion: resolver,
+    });
+
+    expect(result.rewritten).toBe(true);
+    expect(result.unresolved).toEqual(["@checkstack/missing"]);
+    expect(pkg.dependencies?.["@checkstack/common"]).toBe("^1.0.0");
+    expect(pkg.dependencies?.["@checkstack/missing"]).toBe("workspace:*");
+  });
+
+  it("passes the original workspace range to the resolver", async () => {
+    const seen: string[] = [];
+    const pkg: RewritablePackageJson = {
+      dependencies: { "@checkstack/common": "workspace:^1.0.0" },
+    };
+    await rewriteWorkspaceVersions({
+      pkg,
+      resolveVersion: ({ workspaceRange }) => {
+        seen.push(workspaceRange);
+        return Promise.resolve("^1.0.0");
+      },
+    });
+    expect(seen).toEqual(["workspace:^1.0.0"]);
+  });
+});