@checkstack/scripts 0.1.2 → 0.2.0

package/src/commands/dev-lifecycle.ts

@@ -0,0 +1,173 @@
+/**
+ * Backend child-process lifecycle (spawn → restart-on-watch →
+ * graceful-shutdown), extracted behind injectable seams so we can drive
+ * it from unit tests without launching real processes.
+ *
+ * Three injectable adapters:
+ *
+ *   - `spawner`: `spawn` the child and return a handle exposing `kill`
+ *     + an `onExit` hook. Real impl wraps `node:child_process.spawn`;
+ *     test impls use `EventEmitter`-backed fakes.
+ *   - `setHardKillTimer` / `clearHardKillTimer`: scheduling for the
+ *     SIGTERM-→-SIGKILL escalation.
+ *   - `onLog`: where to send human-readable status lines. Tests collect
+ *     them into an array; real impl uses `console.log`.
+ *
+ * The lifecycle's *behavior* is fully captured by these primitives:
+ * tests that drive them confirm the same code paths the real runtime
+ * exercises.
+ */
+
+export interface ChildHandle {
+  kill(signal: NodeJS.Signals): void;
+  onExit(handler: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+}
+
+export interface Spawner {
+  spawn(input: {
+    command: string;
+    args: string[];
+    env: Record<string, string | undefined>;
+  }): ChildHandle;
+}
+
+export interface LifecycleHooks {
+  /** Called when the child exits naturally (not as part of a restart). */
+  onNaturalExit: (code: number | null) => void;
+}
+
+export interface BackendLifecycleOptions {
+  spawnArgs: { command: string; args: string[]; env: Record<string, string | undefined> };
+  spawner: Spawner;
+  hooks: LifecycleHooks;
+  /** Inject log sink. Defaults to `console.log`. */
+  onLog?: (line: string) => void;
+  /** Schedule a SIGKILL fallback if SIGTERM doesn't bring the child down. */
+  setHardKillTimer?: (fn: () => void, ms: number) => unknown;
+  clearHardKillTimer?: (handle: unknown) => void;
+  hardKillDelayMs?: number;
+}
+
+export interface BackendLifecycle {
+  /** Start the child for the first time. */
+  start: () => void;
+  /** Trigger a restart (SIGTERM + respawn). Idempotent during a restart. */
+  restart: () => void;
+  /** Forward a shutdown signal to the child. Marks the lifecycle as done. */
+  shutdown: (signal: NodeJS.Signals) => void;
+}
+
+export function createBackendLifecycle({
+  spawnArgs,
+  spawner,
+  hooks,
+  onLog = (line) => console.log(line),
+  setHardKillTimer = (fn, ms) => setTimeout(fn, ms),
+  clearHardKillTimer = (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
+  hardKillDelayMs = 5000,
+}: BackendLifecycleOptions): BackendLifecycle {
+  let child: ChildHandle | undefined;
+  let restarting = false;
+  let shuttingDown = false;
+  let hardKillHandle: unknown;
+
+  const start = () => {
+    if (child) return; // start() must be called only once outside a restart
+    onLog(`▶ Starting backend (${spawnArgs.command} ${spawnArgs.args.join(" ")})`);
+    child = spawner.spawn(spawnArgs);
+    child.onExit((code, signal) => {
+      child = undefined;
+      // The hard-kill timer is no longer relevant once the child is
+      // gone — drop it before we possibly schedule another one.
+      if (hardKillHandle !== undefined) {
+        clearHardKillTimer(hardKillHandle);
+        hardKillHandle = undefined;
+      }
+      if (shuttingDown) return;
+      if (restarting) {
+        restarting = false;
+        // Recursive call into start() is safe: child is undefined here
+        // and the function early-returns when it's not.
+        spawnAfterRestart();
+        return;
+      }
+      onLog(
+        `Backend exited (code=${code ?? "null"}, signal=${signal ?? "none"})`,
+      );
+      hooks.onNaturalExit(code);
+    });
+  };
+
+  // Same as `start()` but issued during a restart, so logging differs
+  // and the early-return is bypassed (child has just been cleared).
+  const spawnAfterRestart = () => {
+    onLog(`▶ Starting backend (${spawnArgs.command} ${spawnArgs.args.join(" ")})`);
+    child = spawner.spawn(spawnArgs);
+    child.onExit((code, signal) => {
+      child = undefined;
+      if (hardKillHandle !== undefined) {
+        clearHardKillTimer(hardKillHandle);
+        hardKillHandle = undefined;
+      }
+      if (shuttingDown) return;
+      if (restarting) {
+        restarting = false;
+        spawnAfterRestart();
+        return;
+      }
+      onLog(
+        `Backend exited (code=${code ?? "null"}, signal=${signal ?? "none"})`,
+      );
+      hooks.onNaturalExit(code);
+    });
+  };
+
+  const restart = () => {
+    if (!child || restarting || shuttingDown) return;
+    restarting = true;
+    onLog("♻ Plugin source changed — restarting backend...");
+    child.kill("SIGTERM");
+    // Hard-kill fallback: if SIGTERM doesn't bring the child down in
+    // `hardKillDelayMs`, escalate. Otherwise the dev loop hangs forever
+    // when a plugin's cleanup handler is buggy.
+    hardKillHandle = setHardKillTimer(() => {
+      if (child && restarting) {
+        child.kill("SIGKILL");
+      }
+    }, hardKillDelayMs);
+  };
+
+  const shutdown = (signal: NodeJS.Signals) => {
+    shuttingDown = true;
+    if (child) child.kill(signal);
+  };
+
+  return { start, restart, shutdown };
+}
+
+/**
+ * Real `node:child_process.spawn`-backed Spawner. Production code uses
+ * this; tests inject a fake.
+ */
+export function nodeSpawner({
+  spawnFn,
+}: {
+  spawnFn: typeof import("node:child_process").spawn;
+}): Spawner {
+  return {
+    spawn({ command, args, env }) {
+      const proc = spawnFn(command, args, {
+        env: env as NodeJS.ProcessEnv,
+        stdio: "inherit",
+      });
+      return {
+        kill(signal) {
+          proc.kill(signal);
+        },
+        onExit(handler) {
+          proc.on("exit", handler);
+        },
+      };
+    },
+  };
+}

package/src/commands/dev-server.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env bun
+/**
+ * `bunx @checkstack/scripts dev` — local Checkstack dev server for plugin
+ * authors.
+ *
+ * Spawns the platform's production backend entry (`@checkstack/backend`)
+ * as a child process, with three env vars wiring it into "dev mode":
+ *
+ *   - CHECKSTACK_DEV_PLUGIN_PATH=<cwd>: tells the backend to skip
+ *     filesystem discovery and load the plugin in this directory as a
+ *     manual plugin.
+ *   - CHECKSTACK_DEV_EXTRA_PLUGIN_PATHS=<JSON array>: paths to
+ *     `@checkstack/*-backend` packages co-loaded as additional manual
+ *     plugins (resolved by walking the plugin's package.json#deps).
+ *   - CHECKSTACK_DEV_AUTH=true: bypasses login. Every access rule the
+ *     platform registers is auto-granted to a synthetic dev user.
+ *
+ * On every save under the plugin's `src/` (any file), we kill the child
+ * and respawn. Bun cold-starts in <1s for a single plugin, so the loop
+ * is fast enough for everyday work.
+ *
+ * The child process is the *real* `core/backend/src/index.ts` — same
+ * boot code as production. No alternative dev-only stack to drift from.
+ *
+ * Pure logic lives in `dev-internals.ts`, lifecycle in `dev-lifecycle.ts`,
+ * and Vite spawn in `dev-frontend.ts`. This file only wires real adapters
+ * to those building blocks.
+ */
+import path from "node:path";
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import { extractErrorMessage } from "@checkstack/common";
+import { resolveCorePluginDeps } from "./dev-deps-resolver";
+import { startFrontendDevServer } from "./dev-frontend";
+import {
+  parseDevArgs,
+  validatePluginPackageJson,
+  resolveBackendEntry,
+  shouldSpawnFrontend,
+  buildBackendChildEnv,
+  createDebouncedWatcher,
+} from "./dev-internals";
+import { createBackendLifecycle, nodeSpawner } from "./dev-lifecycle";
+
+export async function runDevServer(rawArgs: string[]): Promise<number> {
+  const args = parseDevArgs({ raw: rawArgs });
+  if (args.showHelp) {
+    printHelp();
+    return 0;
+  }
+
+  // 1. Validate package.json
+  const validation = validatePluginPackageJson({ cwd: args.cwd });
+  if (!validation.ok) {
+    if ("missingPackageJson" in validation) {
+      console.error(
+        `❌ No package.json found at ${args.cwd}. Run from a plugin's repo root.`,
+      );
+    } else {
+      console.error(
+        "❌ Plugin package.json failed install-time validation. The dev server boots the same code path as production, so the metadata must match what `plugin-pack` would accept:",
+      );
+      for (const issue of validation.issues) {
+        console.error(`   - ${issue}`);
+      }
+    }
+    return 1;
+  }
+  const pkg = validation.metadata;
+  console.log(
+    `🛠 Booting Checkstack dev server for ${pkg.name}@${pkg.version} (${pkg.checkstack.type})`,
+  );
+
+  // 2. Resolve @checkstack/backend entry
+  const backendEntry = resolveBackendEntry({ fromCwd: args.cwd });
+  if (!backendEntry) {
+    console.error(
+      "❌ Could not locate @checkstack/backend. Add it to your plugin's devDependencies, or install @checkstack/scripts which depends on it transitively.",
+    );
+    return 1;
+  }
+
+  // 3. Walk @checkstack/*-backend deps so we co-load the platform
+  // plugins the user's plugin needs at runtime.
+  const corePluginDeps = resolveCorePluginDeps({ pluginDir: args.cwd });
+  if (corePluginDeps.length > 0) {
+    console.log(
+      `📦 Co-loading ${corePluginDeps.length} core plugin dep${
+        corePluginDeps.length === 1 ? "" : "s"
+      }: ${corePluginDeps.map((d) => d.name).join(", ")}`,
+    );
+  }
+
+  // 4. Build the child env
+  const childEnv = buildBackendChildEnv({
+    args,
+    parentEnv: process.env,
+    extraPluginPaths: corePluginDeps.map((d) => d.modulePath),
+  });
+
+  // 5. Wire the backend lifecycle (spawn → restart → shutdown)
+  let exitCode: number | null = 0;
+  let shutdownResolve!: (code: number) => void;
+  const shutdownPromise = new Promise<number>((resolve) => {
+    shutdownResolve = resolve;
+  });
+  const lifecycle = createBackendLifecycle({
+    spawnArgs: {
+      command: "bun",
+      args: ["run", backendEntry],
+      env: childEnv,
+    },
+    spawner: nodeSpawner({ spawnFn: spawn }),
+    hooks: {
+      onNaturalExit: (code) => {
+        exitCode = code;
+        shutdownResolve(code ?? 0);
+      },
+    },
+  });
+
+  // 6. Watcher (debounced) → restart
+  const srcDir = path.join(args.cwd, "src");
+  if (args.watch && fs.existsSync(srcDir)) {
+    const watcher = createDebouncedWatcher({ onTrigger: lifecycle.restart });
+    fs.watch(srcDir, { recursive: true }, (_event, filename) => {
+      watcher.feed(filename ?? undefined);
+    });
+    console.log(`👀 Watching ${srcDir} for changes`);
+  }
+
+  // 7. Frontend dev server (Vite) when applicable
+  let viteServer:
+    | Awaited<ReturnType<typeof startFrontendDevServer>>
+    | undefined;
+  if (shouldSpawnFrontend(pkg)) {
+    try {
+      viteServer = await startFrontendDevServer({
+        pluginCwd: args.cwd,
+        port: args.frontendPort,
+        backendUrl: `http://localhost:${args.port}`,
+      });
+    } catch (error) {
+      console.error(
+        `⚠ Frontend dev server failed to start: ${extractErrorMessage(error)}`,
+      );
+      console.error(
+        "  The backend will still run — your -frontend plugin just won't have HMR.",
+      );
+    }
+  }
+
+  // 8. Signal forwarding
+  const onSignal = (signal: NodeJS.Signals) => {
+    lifecycle.shutdown(signal);
+    void viteServer?.close();
+    setTimeout(() => process.exit(exitCode ?? 0), 200).unref();
+  };
+  process.on("SIGINT", () => onSignal("SIGINT"));
+  process.on("SIGTERM", () => onSignal("SIGTERM"));
+
+  // 9. Boot
+  lifecycle.start();
+  return shutdownPromise;
+}
+
+function printHelp(): void {
+  console.log(String.raw`Usage: checkstack-scripts dev [options]
+
+Spins up a local Checkstack dev server with the current directory's
+plugin loaded. Same boot code as production — the only differences are:
+  * filesystem discovery is skipped (only your plugin loads)
+  * a synthetic dev auth grants every access rule (no login)
+  * the backend restarts on changes under ./src
+
+Options:
+  --cwd <dir>             Plugin directory (default: process.cwd())
+  --port <num>            Backend HTTP port (default: 3000 or $PORT)
+  --frontend-port <num>   Frontend Vite dev port (default: 5173 or $FRONTEND_PORT)
+  --db-url <url>          Postgres URL (default: $DATABASE_URL or
+                          postgresql://checkstack:checkstack@localhost:5432/checkstack)
+  --no-watch              Disable file watching / auto-restart
+  --help, -h              Show this message
+
+Prerequisites: a running Postgres reachable at --db-url. The simplest
+local setup is:
+
+  docker run --name checkstack-dev-pg -d -p 5432:5432 \
+    -e POSTGRES_USER=checkstack -e POSTGRES_PASSWORD=checkstack \
+    -e POSTGRES_DB=checkstack postgres:16-alpine
+`);
+}
+
+if (import.meta.main) {
+  const code = await runDevServer(process.argv.slice(2));
+  process.exit(code);
+}