@checkstack/scripts 0.3.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/scripts",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Checkstack tooling: plugin scaffolding, codegen, and the plugin-pack CLI used by external plugin authors.",
   "license": "Elastic-2.0",
   "type": "module",
@@ -10,6 +10,11 @@
   "bin": {
     "checkstack-scripts": "./src/cli.ts"
   },
+  "exports": {
+    "./scaffold": {
+      "import": "./src/scaffold/index.ts"
+    }
+  },
   "files": [
     "src",
     "README.md"
@@ -22,15 +27,20 @@
     "typecheck": "tsgo -b"
   },
   "dependencies": {
-    "@checkstack/common": "0.10.0",
-    "inquirer": "^13.4.1",
+    "@checkstack/common": "0.12.0",
+    "ansi-escapes": "^7.3.0",
     "handlebars": "^4.7.8",
-    "tar": "^7.4.3"
+    "ink": "^7.0.5",
+    "inquirer": "^13.4.1",
+    "react": "^19.2.7",
+    "tar": "^7.5.16",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@checkstack/tsconfig": "0.0.7",
-    "@types/inquirer": "^8.2.10",
     "@types/handlebars": "^4.1.0",
+    "@types/inquirer": "^8.2.10",
+    "@types/react": "^19.2.16",
     "typescript": "^5.0.0"
   }
 }

package/src/commands/create.ts

@@ -1,21 +1,18 @@
 #!/usr/bin/env bun
 import inquirer from "inquirer";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
 import {
   validatePluginName,
   pluginExists,
   packageExists,
   extractBaseName,
 } from "../utils/validation";
+import { registerHelpers, prepareTemplateData } from "../utils/template";
 import {
-  registerHelpers,
-  copyTemplate,
-  prepareTemplateData,
-} from "../utils/template";
-import { fileURLToPath } from "node:url";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  scaffoldPlugin,
+  refreshMonorepoReferences,
+  type ScaffoldMode,
+} from "../scaffold/scaffold-plugin";
 
 interface PluginTypeChoice {
   name: string;
@@ -191,18 +188,18 @@ export async function createCommand() {
     `\n📦 Creating ${pluginType} ${locationLabel}: ${templateData.pluginName}`
   );
 
-  const templateDir = path.join(__dirname, "..", "templates", pluginType);
-  const targetDir = path.join(
+  const mode: ScaffoldMode = {
+    kind: "monorepo",
     rootDir,
-    packageLocation,
-    templateData.pluginName
-  );
+    location: packageLocation,
+  };
 
   try {
-    const createdFiles = copyTemplate({
-      templateDir,
-      targetDir,
-      data: templateData,
+    const { targetDir, createdFiles } = await scaffoldPlugin({
+      mode,
+      baseName: pluginBaseName,
+      description,
+      pluginType,
     });
 
     console.log(
@@ -222,12 +219,8 @@ export async function createCommand() {
     // solution tsconfig so the new package is wired into the typecheck
     // graph. Affects only tsconfig.json files; safe to rerun any time.
     console.log("\n🔗 Refreshing TypeScript project references...");
-    const refResult = spawnSync(
-      "bun",
-      ["run", "typecheck:references:generate"],
-      { stdio: "inherit" },
-    );
-    if (refResult.status !== 0) {
+    const refStatus = refreshMonorepoReferences({ mode });
+    if (refStatus !== 0) {
       console.warn(
         "⚠️  Failed to refresh references automatically. " +
           "Run `bun run typecheck:references:generate` manually before typechecking.",

package/src/commands/plugin-pack.ts

@@ -10,6 +10,11 @@ import {
   type InstallPackageMetadata,
   type PluginBundleManifest,
 } from "@checkstack/common";
+import {
+  rewriteWorkspaceVersions,
+  type RewritablePackageJson,
+} from "../scaffold/rewrite-workspace-versions";
+import { createWorkspaceMapResolver } from "../scaffold/resolve-versions";
 
 /**
  * `plugin-pack` CLI.
@@ -315,35 +320,19 @@ async function packPackage({
 }): Promise<string> {
   const pkgJsonPath = path.join(pkgDir, "package.json");
   const original = fs.readFileSync(pkgJsonPath, "utf8");
-  const pkg = JSON.parse(original) as InstallPackageMetadata & {
-    devDependencies?: Record<string, string>;
-    peerDependencies?: Record<string, string>;
-  };
+  const pkg = JSON.parse(original) as InstallPackageMetadata &
+    RewritablePackageJson;
 
-  let rewritten = false;
-  for (const section of [
-    "dependencies",
-    "devDependencies",
-    "peerDependencies",
-  ] as const) {
-    const block = pkg[section];
-    if (!block) continue;
-    for (const [name, range] of Object.entries(block)) {
-      if (range.startsWith("workspace:")) {
-        const targetDir = workspaceMap.get(name);
-        if (!targetDir) {
-          throw new Error(
-            `Cannot resolve workspace dep '${name}' (declared in '${pkg.name}'). ` +
-              `Either move the package into the workspace or replace the workspace range with a concrete version.`,
-          );
-        }
-        const targetPkg = readJson<{ version: string }>(
-          path.join(targetDir, "package.json"),
-        );
-        block[name] = `^${targetPkg.version}`;
-        rewritten = true;
-      }
-    }
+  const { rewritten, unresolved } = await rewriteWorkspaceVersions({
+    pkg,
+    resolveVersion: createWorkspaceMapResolver({ workspaceMap }),
+  });
+  if (unresolved.length > 0) {
+    const name = unresolved[0];
+    throw new Error(
+      `Cannot resolve workspace dep '${name}' (declared in '${pkg.name}'). ` +
+        `Either move the package into the workspace or replace the workspace range with a concrete version.`,
+    );
   }
 
   try {

package/src/dev-tui/App.render.test.tsx

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "bun:test";
+import React from "react";
+import { renderToString } from "ink";
+import { App } from "./App.tsx";
+import { createFakeSupervisor } from "./fake-supervisor.ts";
+import { computeLayout } from "./layout.ts";
+import type { ScrollbackLine } from "./scrollback.ts";
+
+const ALERTS_CAPACITY = 8;
+
+/** Strip ANSI SGR sequences so we can measure printable width and content. */
+function stripAnsi(value: string): string {
+  // Build the ESC (0x1b) prefix without a literal control char in the source,
+  // so we avoid both a control-char regex and any lint suppression.
+  const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+  return value.replace(ansiPattern, "");
+}
+
+/**
+ * Seed the focused (backend) pane with MANY lines that are each LONGER than the
+ * terminal width, so the only way the frame can stay within bounds is the
+ * height clamp plus per-line truncation working together.
+ */
+function manyLongLines(count: number, columns: number): ScrollbackLine[] {
+  const lines: ScrollbackLine[] = [];
+  for (let index = 0; index < count; index += 1) {
+    lines.push({
+      level: "info",
+      text: `line-${index}-`.padEnd(columns * 2, "x"),
+    });
+  }
+  return lines;
+}
+
+describe("App height clamp (DOM-free render test)", () => {
+  const columns = 80;
+  // More lines than any tested terminal is tall, each wider than `columns`.
+  const seededLineCount = 200;
+
+  for (const rows of [24, 40]) {
+    it(`never overflows ${rows} rows when the focused pane floods output`, () => {
+      const supervisor = createFakeSupervisor();
+      const frame = renderToString(
+        <App
+          supervisor={supervisor}
+          size={{ rows, columns }}
+          initialFocused="backend"
+          preloadLines={{ backend: manyLongLines(seededLineCount, columns) }}
+        />,
+        { columns },
+      );
+
+      const lines = frame.split("\n");
+
+      // 1. The frame must never be taller than the terminal. This is the hard
+      //    invariant the clamp guarantees.
+      expect(lines.length).toBeLessThanOrEqual(rows);
+
+      // 2. The clamp fills the terminal exactly (no overflow, no wasted band).
+      expect(lines.length).toBe(rows);
+
+      // 3. The pinned chrome must still be on-screen (not pushed off the bottom).
+      const plain = stripAnsi(frame);
+      expect(plain).toContain("quit");
+      expect(plain).toContain("alerts");
+
+      // 4. Per-line truncation holds: no rendered row exceeds the width.
+      for (const line of lines) {
+        expect(stripAnsi(line).length).toBeLessThanOrEqual(columns);
+      }
+
+      // 5. The focused pane shows EXACTLY the computed log-row budget worth of
+      //    seeded lines. The seeded lines start with "line-<n>-", so counting
+      //    those rows tells us how many log rows actually rendered. The pre-fix
+      //    `rows - 16` reserve under-filled this (e.g. 8 rows at rows=24 instead
+      //    of the correct 15), so this assertion discriminates the fix.
+      const expectedLogRows = computeLayout({
+        size: { rows, columns },
+        alertCount: 0,
+        alertCapacity: ALERTS_CAPACITY,
+      }).logRows;
+      const logRowsRendered = lines.filter((line) =>
+        stripAnsi(line).includes("line-"),
+      ).length;
+      expect(logRowsRendered).toBe(expectedLogRows);
+    });
+  }
+
+  it("keeps the footer and alerts visible when alerts fill to capacity and logs flood", () => {
+    const supervisor = createFakeSupervisor();
+    const seededAlerts = Array.from({ length: 8 }, (_, index) => ({
+      source: "backend" as const,
+      level: "error" as const,
+      text: `alert-${index}-`.padEnd(columns * 2, "y"),
+      seq: index,
+    }));
+    const frame = renderToString(
+      <App
+        supervisor={supervisor}
+        size={{ rows: 24, columns }}
+        initialFocused="backend"
+        preloadLines={{ backend: manyLongLines(seededLineCount, columns) }}
+        initialAlerts={seededAlerts}
+      />,
+      { columns },
+    );
+    const lines = frame.split("\n");
+    expect(lines.length).toBeLessThanOrEqual(24);
+    const plain = stripAnsi(frame);
+    expect(plain).toContain("quit");
+    expect(plain).toContain("alerts (8)");
+    for (const line of lines) {
+      expect(stripAnsi(line).length).toBeLessThanOrEqual(columns);
+    }
+  });
+
+  it("renders the seeded flood as the visible content of the focused pane", () => {
+    const supervisor = createFakeSupervisor();
+    const frame = renderToString(
+      <App
+        supervisor={supervisor}
+        size={{ rows: 24, columns }}
+        initialFocused="backend"
+        preloadLines={{ backend: manyLongLines(seededLineCount, columns) }}
+      />,
+      { columns },
+    );
+    // The seam actually seeds the focused pane: at least one of the flooded
+    // backend lines is visible (so the clamp is being exercised against real
+    // content, not an empty placeholder).
+    const plain = stripAnsi(frame);
+    expect(plain).toContain("line-");
+    expect(plain).not.toContain("Waiting for output...");
+  });
+});

package/src/dev-tui/App.smoke.test.tsx

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "bun:test";
+import React from "react";
+import { renderToString } from "ink";
+import { App, ShutdownScreen } from "./App.tsx";
+import { SPINNER_FRAMES } from "../tui/index.ts";
+import { createFakeSupervisor } from "./fake-supervisor.ts";
+import { runPlainStreaming } from "./plain-runner.ts";
+
+describe("App initial frame (DOM-free smoke test)", () => {
+  it("renders the chrome without throwing and starts the supervisor", () => {
+    const supervisor = createFakeSupervisor();
+    const frame = renderToString(<App supervisor={supervisor} />, {
+      columns: 100,
+    });
+
+    // App name + footer hints + every process label render in the first frame.
+    expect(frame).toContain("checkstack dev");
+    expect(frame).toContain("backend");
+    expect(frame).toContain("frontend");
+    expect(frame).toContain("deps");
+    expect(frame).toContain("alerts");
+    expect(frame).toContain("quit");
+
+    // The mount effect kicks off the supervisor.
+    expect(supervisor.started).toBe(true);
+  });
+});
+
+describe("ShutdownScreen", () => {
+  it("shows the shutdown heading + a spinner while services stop", () => {
+    const frame = renderToString(
+      <ShutdownScreen
+        width={80}
+        height={20}
+        frame={0}
+        statuses={{ deps: "ready", backend: "starting", frontend: "starting" }}
+      />,
+    );
+    expect(frame).toContain("Shutting down checkstack dev");
+    // Long-running services are listed and still spinning (not yet stopped).
+    expect(frame).toContain("backend");
+    expect(frame).toContain("frontend");
+    expect(frame).toContain(SPINNER_FRAMES[0]);
+    // The one-shot deps process is left running, so it is not listed.
+    expect(frame).not.toContain("✓");
+  });
+
+  it("marks a stopped service with a check", () => {
+    const frame = renderToString(
+      <ShutdownScreen
+        width={80}
+        height={20}
+        frame={0}
+        statuses={{ deps: "ready", backend: "stopped", frontend: "starting" }}
+      />,
+    );
+    expect(frame).toContain("✓");
+    expect(frame).toContain("stopped");
+  });
+
+  it("treats a non-zero exit during shutdown as stopped, not an error", () => {
+    // We killed the process on purpose; dev servers (e.g. Vite) often exit 143/1
+    // on SIGTERM, which the supervisor records as 'errored'. During teardown
+    // that is expected - show a check, never a cross.
+    const frame = renderToString(
+      <ShutdownScreen
+        width={80}
+        height={20}
+        frame={0}
+        statuses={{ deps: "ready", backend: "stopped", frontend: "errored" }}
+      />,
+    );
+    expect(frame).not.toContain("✗");
+    // Both long-running services are shown as stopped (two checks).
+    expect(frame.match(/✓/g) ?? []).toHaveLength(2);
+  });
+});
+
+describe("runPlainStreaming (non-TTY fallback)", () => {
+  it("starts the supervisor and prefixes each line with its source", () => {
+    const supervisor = createFakeSupervisor();
+    const out: string[] = [];
+    runPlainStreaming({
+      supervisor,
+      write: (text) => out.push(text),
+    });
+
+    expect(supervisor.started).toBe(true);
+
+    supervisor.emitLine({
+      source: "backend",
+      level: "info",
+      text: "21:02:49 info: hello",
+      seq: 1,
+    });
+    expect(out.join("")).toContain("[backend] 21:02:49 info: hello");
+  });
+
+  it("marks warn/error lines with a leading bang so they stay greppable", () => {
+    const supervisor = createFakeSupervisor();
+    const out: string[] = [];
+    runPlainStreaming({ supervisor, write: (text) => out.push(text) });
+
+    supervisor.emitLine({
+      source: "backend",
+      level: "warn",
+      text: "sandbox not ready",
+      seq: 1,
+    });
+    expect(out.some((chunk) => chunk.startsWith("!"))).toBe(true);
+  });
+
+  it("emits status transitions", () => {
+    const supervisor = createFakeSupervisor();
+    const out: string[] = [];
+    runPlainStreaming({ supervisor, write: (text) => out.push(text) });
+
+    supervisor.emitStatus({ id: "frontend", status: "ready" });
+    expect(out.join("")).toContain("[frontend] status: ready");
+  });
+
+  it("shuts down the supervisor and invokes the completion callback", async () => {
+    const supervisor = createFakeSupervisor();
+    const out: string[] = [];
+    let completed = false;
+    const shutdown = runPlainStreaming({
+      supervisor,
+      write: (text) => out.push(text),
+      onShutdownComplete: () => {
+        completed = true;
+      },
+    });
+
+    shutdown();
+    // Allow the shutdown microtask to resolve.
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(supervisor.didShutdown).toBe(true);
+    expect(completed).toBe(true);
+    expect(out.join("")).toContain("shutting down");
+  });
+});