@webjsdev/cli 0.10.58 → 0.10.60

package/lib/create.js

@@ -18,24 +18,10 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
+import { postgresCompose, postgresCi } from './db-rewrite.js';
 import { assertValidAppName, toDatabaseName } from './app-name.js';
 import { isGalleryAppShellFile } from './gallery-shell-files.js';
-
-/**
- * Detect which package manager invoked us. Reads `npm_config_user_agent`,
- * which npm / pnpm / yarn / bun all set when running scripts or `npx`.
- * Falls back to `npm` when nothing is detected (matches what most users
- * actually have installed).
- *
- * @returns {'npm'|'pnpm'|'yarn'|'bun'}
- */
-function detectPackageManager() {
-  const ua = process.env.npm_config_user_agent || '';
-  if (ua.startsWith('pnpm/')) return 'pnpm';
-  if (ua.startsWith('yarn/')) return 'yarn';
-  if (ua.startsWith('bun/')) return 'bun';
-  return 'npm';
-}
+import { detectPackageManager } from './package-manager.js';
 
 /**
  * Run `<pm> install` inside the scaffolded app. Returns true on success.
@@ -327,7 +313,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   // with the explicit flag winning over detection. A bun-flavored app SERVES on
   // Bun (its dev/start scripts force `--bun`), commits `bun.lock`, sets
   // `trustedDependencies`, and ships a bun Dockerfile / CI / agent docs.
-  const runtime = opts.runtime || (detectPackageManager() === 'bun' ? 'bun' : 'node');
+  // Runtime detection reads ONLY the invoking tool (no lockfile walk): a
+  // global `webjs create` run inside someone else's Bun workspace should not
+  // silently flip the new app to serving on Bun.
+  const runtime = opts.runtime || (detectPackageManager({ cwd: null, prefer: 'agent' }) === 'bun' ? 'bun' : 'node');
   const VALID_RUNTIMES = ['node', 'bun'];
   if (!VALID_RUNTIMES.includes(runtime)) {
     throw new Error(`Unknown --runtime '${runtime}'. Only ${VALID_RUNTIMES.join(' / ')} are supported.`);
@@ -475,7 +464,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // The Tailwind v4 CLI that css:build runs to compile public/input.css into
       // the static public/tailwind.css the layout links. UI templates only (the
       // api template has no CSS). Build tooling, never shipped to the runtime.
-      ...(isApi ? {} : { '@tailwindcss/cli': '^4.1.0' }),
+      // `tailwindcss` itself is declared too (#1493): public/input.css starts
+      // with `@import "tailwindcss"`, so the app imports that package directly.
+      // Leaving it transitive (via @tailwindcss/cli) breaks under bun's isolated
+      // linker and pnpm, which link only declared packages into the app's
+      // node_modules, so the compile fails with `Can't resolve 'tailwindcss'`.
+      ...(isApi ? {} : { '@tailwindcss/cli': '^4.1.0', tailwindcss: '^4.1.0' }),
       // tsserver plugin, wired into tsconfig below. Gives the language
       // INTELLIGENCE (go-to-def, completions, diagnostics, hover inside html``
       // templates) in any tsserver editor with NO editor plugin installed,
@@ -523,8 +517,18 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // `npm audit fix --force` proposes: its @web/test-runner-chrome@1 still
     // declares puppeteer-core ^24, so the same vulnerable chain resolves and
     // the audit stays red after a breaking major.
+    //
+    // basic-ftp (#1492) is the same kind of floor for the same runner: it is
+    // reached through puppeteer-core's proxy-agent chain and 6.2.2 is its fixed
+    // release (GHSA-c475-qrg2-pj4r), so an install that still resolves an older
+    // chain cannot land below it.
+    //
+    // Overrides are honoured ONLY at a workspace root. When this app is a
+    // member of an npm or bun workspace, move this block into the root
+    // package.json (`webjs doctor` warns with WORKSPACE_OVERRIDES until then).
     overrides: {
       'puppeteer-core': '^25.7.0',
+      'basic-ftp': '^6.2.2',
     },
     // Dev + start task orchestration (#550). `webjs dev` / `webjs start` read
     // `before` and run it in-process, so `npm run dev` / `start` (thin aliases
@@ -576,6 +580,23 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // everything else keeps its default warn. Add a code with "off" to
       // silence it, or "error" to make it fatal too.
       doctor: { gate: { UNMARKED_ASSET_LINKS: 'error' } },
+      // The dependency audit's allowlist (#1492), the ONE place an accepted
+      // advisory is listed, each with the reason it is safe. `webjs audit`
+      // (the CI step below) fails on every other advisory at `level` or above,
+      // and prints an entry as stale once the audit stops reporting it, so
+      // remove it then. Only accept an advisory with NO patched release that
+      // the app's users cannot reach; anything with a fix gets upgraded.
+      audit: {
+        level: 'high',
+        ignore: [
+          {
+            id: 'GHSA-vfj7-8cjw-p6xm',
+            reason: 'braces <=3.0.3 (no patched release) is reached only through dev tooling: the Tailwind '
+              + 'CLI file watcher and the test runner globber, on glob patterns this repo writes. Nothing '
+              + 'in the served app expands a pattern from request input.',
+          },
+        ],
+      },
       // Local CI (#1471), the Rails `bin/ci` posture. `npm run ci` runs this
       // list on a developer machine and the generated GitHub workflow runs the
       // SAME list through the same command, so the two cannot drift. Bare
@@ -593,10 +614,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
               { title: 'Conventions', run: 'webjs check' },
               { title: 'Health', run: 'webjs doctor' },
               { title: 'Types', run: 'webjs typecheck' },
-              {
-                title: 'Security: dependency audit',
-                run: isBun ? 'bun audit --audit-level=high' : 'npm audit --audit-level=high',
-              },
+              // `webjs audit` (#1492) runs `npm audit` or `bun audit` (by the
+              // nearest lockfile) and fails at webjs.audit.level, minus the
+              // advisories webjs.audit.ignore accepts below.
+              { title: 'Security: dependency audit', run: 'webjs audit' },
               {
                 title: 'Tests',
                 steps: [
@@ -733,6 +754,14 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'compose.yaml': bunifyCompose,
     '.github/workflows/ci.yml': bunifyCi,
   };
+  // Database axis (#1490): the compose + CI templates are the SQLite shape, so
+  // a --db postgres app derives its variant (a Postgres service, DATABASE_URL
+  // pointed at it) by a pure transform, like the Bun rewrite above. Applied
+  // FIRST; the two touch disjoint lines, so they compose. SQLite copies as is.
+  const DB_REWRITE = dialect === 'postgres' ? {
+    'compose.yaml': (c) => postgresCompose(c, toDatabaseName(name)),
+    '.github/workflows/ci.yml': (c) => postgresCi(c, toDatabaseName(name)),
+  } : {};
   for (const f of templateFiles) {
     // `--skip-ci` drops only the workflow; the PR template still ships.
     if (skipCi && f === '.github/workflows/ci.yml') continue;
@@ -754,6 +783,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
         const playbook = await readFile(join(TEMPLATES, 'partials', playbookFile), 'utf8');
         content = content.replace('{{PLAYBOOK}}', () => playbook.trimEnd());
       }
+      if (DB_REWRITE[f]) content = DB_REWRITE[f](content);
       if (isBun) {
         if (PROSE_REWRITE.has(f)) content = bunifyProse(content);
         else if (FILE_REWRITE[f]) content = FILE_REWRITE[f](content);
@@ -1663,8 +1693,11 @@ ThemeToggle.register('theme-toggle');
   // that exercise the scaffold without paying the install cost.
   // In bun mode, install with bun regardless of the invoking PM, so the app
   // commits `bun.lock` (text JSONC, git-diffable) instead of `package-lock.json`
-  // (#541). Otherwise honour the invoking PM (npm / pnpm / yarn / bun).
-  const pm = isBun ? 'bun' : detectPackageManager();
+  // (#541). Otherwise honour the invoking PM (npm / pnpm / yarn / bun), and when
+  // nothing invoked us through a package manager (a global `webjs` bin), the
+  // lockfile of the enclosing project or workspace (#1494), so an app created
+  // inside a bun workspace does not get a stray package-lock.json.
+  const pm = isBun ? 'bun' : detectPackageManager({ cwd: dirname(appDir), prefer: 'agent' });
   let installed = false;
   let generatedMigration = false;
   if (shouldInstall) {

package/lib/db-rewrite.js

@@ -0,0 +1,137 @@
+/**
+ * Database-dialect rewrites for the deploy files (#1490).
+ *
+ * The canonical `compose.yaml` and `.github/workflows/ci.yml` templates are the
+ * SQLite shape (a `file:` DATABASE_URL, a named volume for the db file). A
+ * `--db postgres` app needs a real Postgres in both places, so these pure
+ * transforms DERIVE the Postgres variant from the canonical template, the same
+ * way `runtime-rewrite.js` derives the Bun variant. There is no parallel
+ * Postgres template to drift, and SQLite output stays byte-identical because
+ * nothing here runs for it.
+ *
+ * Order: create.js applies these BEFORE the Bun rewrites. They only touch the
+ * DATABASE_URL lines, the volume, and add a database service, none of which
+ * the Bun rewrites match (those swap `node -e` healthchecks, `npm` commands and
+ * the setup-node block), so the two axes compose in either order. Every anchor
+ * is asserted, so a template edit that moves one fails loudly in the scaffold
+ * tests instead of shipping a half-rewritten file.
+ *
+ * The credentials are local-only (a throwaway compose volume, an ephemeral CI
+ * service container), never a production value; production points
+ * DATABASE_URL at its own managed Postgres.
+ *
+ * @module db-rewrite
+ */
+
+/** Local Postgres user + password for compose and CI (never production). */
+export const LOCAL_PG_USER = 'webjs';
+export const LOCAL_PG_PASSWORD = 'webjs';
+/** The Postgres image both files run. */
+export const PG_IMAGE = 'postgres:17-alpine';
+
+/**
+ * @param {string} s
+ * @param {string} from
+ * @param {string} to
+ * @param {string} file
+ */
+function replaceOnce(s, from, to, file) {
+  if (!s.includes(from)) {
+    throw new Error(`db-rewrite: ${file} template no longer contains the anchor ${JSON.stringify(from.slice(0, 60))}`);
+  }
+  return s.replace(from, () => to);
+}
+
+/**
+ * Rewrite compose.yaml for a Postgres app: a sibling `db` service with a
+ * `pg_isready` healthcheck and its own named volume, the app's DATABASE_URL
+ * pointed at it, and `depends_on` with `service_healthy` so the app's boot-time
+ * `webjs db migrate` never races the database's startup.
+ *
+ * @param {string} s
+ * @param {string} dbName fold-stable database name (toDatabaseName(appName))
+ * @returns {string}
+ */
+export function postgresCompose(s, dbName) {
+  const url = `postgres://${LOCAL_PG_USER}:${LOCAL_PG_PASSWORD}@db:5432/${dbName}`;
+  let out = s;
+  out = replaceOnce(out, 'using the same Dockerfile, one service.',
+    'using the same Dockerfile, plus a Postgres service.', 'compose.yaml');
+  out = replaceOnce(out,
+    "# In production your host provides DATABASE_URL + AUTH_SECRET. Locally this\n" +
+    "# uses the scaffold's SQLite file on a named volume so data survives\n" +
+    '# `compose down`.',
+    '# In production your host provides DATABASE_URL + AUTH_SECRET. Locally this\n' +
+    '# runs Postgres in the `db` service on a named volume so data survives\n' +
+    '# `compose down`.',
+    'compose.yaml');
+  out = replaceOnce(out,
+    '      # SQLite on a volume for local dev. For production, scaffold with\n' +
+    '      # --db postgres (or swap db/columns.server.ts + db/connection.server.ts\n' +
+    '      # for the pg variant) and point DATABASE_URL at your managed Postgres.\n' +
+    '      DATABASE_URL: file:/data/dev.db\n',
+    '      # The `db` service below. In production, point DATABASE_URL at your\n' +
+    '      # managed Postgres instead.\n' +
+    `      DATABASE_URL: ${url}\n`,
+    'compose.yaml');
+  // The app no longer owns a db file, so it needs no volume; it waits for a
+  // healthy database instead, because `webjs start` migrates before serving.
+  out = replaceOnce(out,
+    '    volumes:\n      - app-data:/data\n',
+    '    depends_on:\n      db:\n        condition: service_healthy\n',
+    'compose.yaml');
+  out = replaceOnce(out,
+    '\nvolumes:\n  app-data:\n',
+    '\n' +
+    '  db:\n' +
+    `    image: ${PG_IMAGE}\n` +
+    '    environment:\n' +
+    `      POSTGRES_USER: ${LOCAL_PG_USER}\n` +
+    `      POSTGRES_PASSWORD: ${LOCAL_PG_PASSWORD}\n` +
+    `      POSTGRES_DB: ${dbName}\n` +
+    '    volumes:\n' +
+    '      - db-data:/var/lib/postgresql/data\n' +
+    '    healthcheck:\n' +
+    `      test: ["CMD-SHELL", "pg_isready -U ${LOCAL_PG_USER} -d ${dbName}"]\n` +
+    '      interval: 5s\n' +
+    '      timeout: 3s\n' +
+    '      retries: 10\n' +
+    '\n' +
+    'volumes:\n' +
+    '  db-data:\n',
+    'compose.yaml');
+  return out;
+}
+
+/**
+ * Rewrite the GitHub Actions CI workflow for a Postgres app: a `postgres`
+ * service container with a health check (the job waits until it is healthy
+ * before the first step) and DATABASE_URL pointed at it on localhost.
+ *
+ * @param {string} s
+ * @param {string} dbName
+ * @returns {string}
+ */
+export function postgresCi(s, dbName) {
+  return replaceOnce(s,
+    '    env:\n      DATABASE_URL: file:./ci.db\n',
+    '    env:\n' +
+    `      DATABASE_URL: postgres://${LOCAL_PG_USER}:${LOCAL_PG_PASSWORD}@localhost:5432/${dbName}\n` +
+    '    # The app is scaffolded with --db postgres, so CI runs against a real\n' +
+    '    # Postgres. The job waits for the health check before the first step.\n' +
+    '    services:\n' +
+    '      postgres:\n' +
+    `        image: ${PG_IMAGE}\n` +
+    '        env:\n' +
+    `          POSTGRES_USER: ${LOCAL_PG_USER}\n` +
+    `          POSTGRES_PASSWORD: ${LOCAL_PG_PASSWORD}\n` +
+    `          POSTGRES_DB: ${dbName}\n` +
+    '        ports:\n' +
+    '          - 5432:5432\n' +
+    '        options: >-\n' +
+    `          --health-cmd "pg_isready -U ${LOCAL_PG_USER} -d ${dbName}"\n` +
+    '          --health-interval 5s\n' +
+    '          --health-timeout 5s\n' +
+    '          --health-retries 10\n',
+    '.github/workflows/ci.yml');
+}

package/lib/dev-reload.js

@@ -0,0 +1,382 @@
+/**
+ * The `webjs dev` reload supervisor (#1521): runs the dev server in a child
+ * process, restarts it when a watched file changes, and brings it back when it
+ * crashes. Replaces `node --watch`, which crashed on the first watcher error it
+ * could not handle (an EACCES on another user's `sed -i` temp file, a file that
+ * vanished between the directory event and the watch call) and left the
+ * preview dead until someone restarted `webjs dev` by hand.
+ *
+ * Three pieces, each testable on its own:
+ * - `watchRestartPaths` watches the planned dirs recursively and the planned
+ *   root files, handles every watcher error with a warning, and follows a
+ *   watched dir that is created or removed after start.
+ * - `createSupervisor` is the restart state machine. It takes injected spawn
+ *   and timer functions, so its behaviour is tested without a process.
+ * - `superviseDevServer` wires both to a real child, the signals, and a
+ *   last-resort `uncaughtException` guard that swallows only watcher errors.
+ *
+ * The planning (which runtime, which paths, restart on change or only on a
+ * crash) stays in `dev-supervisor.js`.
+ */
+import { spawn } from 'node:child_process';
+import { watch, statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Quiet window between a file event and the restart. `node --watch` used
+ * 200ms; one editor save or `sed -i` lands its events within a few ms of each
+ * other, so 50ms still coalesces a save while starting the restart 150ms
+ * sooner.
+ */
+export const RESTART_DEBOUNCE_MS = 50;
+
+/**
+ * Delays before restarting a child that exited on its own (a crash), indexed
+ * by consecutive crash count and capped at the last entry. A file change
+ * restarts it at once regardless, so the backoff only matters when nothing is
+ * being edited: the preview comes back within seconds, and a child that fails
+ * deterministically at boot is retried every 10s instead of in a tight loop.
+ */
+export const CRASH_BACKOFF_MS = [500, 1000, 2000, 5000, 10000];
+
+/** A child that stayed up this long resets the crash backoff. */
+export const STABLE_MS = 10_000;
+
+/**
+ * How long a restarting child gets to exit after SIGTERM before SIGKILL. The
+ * server's own drain allows 10s, which is right for a deploy and far too long
+ * to hold an edit back in dev.
+ */
+export const KILL_TIMEOUT_MS = 2000;
+
+/**
+ * Paths inside a watched dir whose changes never restart the server: the same
+ * noise the server's in-process watcher ignores (`shouldIgnoreWatchPath` in
+ * `@webjsdev/server`), restated here so the CLI does not depend on a server
+ * internal.
+ *
+ * @param {string} rel  path relative to the app root
+ * @returns {boolean}
+ */
+export function shouldIgnoreRestartPath(rel) {
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(rel || '');
+}
+
+/**
+ * Whether an error came from a file watcher. Node marks every `fs.watch`
+ * failure with `syscall: 'watch'`.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isWatchError(err) {
+  return !!err && typeof err === 'object' && /** @type {any} */ (err).syscall === 'watch';
+}
+
+/**
+ * The `webjs.dev.regenerate[].output` paths (#967), normalized to `/` with no
+ * leading `./`. The server writes these on request, so one that lives under a
+ * watched dir must not restart the server, or a request would restart the
+ * process that is serving it. Unreadable config yields no outputs.
+ *
+ * @param {string} cwd
+ * @returns {Set<string>}
+ */
+export function readRegenerateOutputs(cwd) {
+  const out = new Set();
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    const rules = pkg && pkg.webjs && pkg.webjs.dev && pkg.webjs.dev.regenerate;
+    if (Array.isArray(rules)) {
+      for (const r of rules) {
+        if (r && typeof r.output === 'string') out.add(r.output.replace(/\\/g, '/').replace(/^\.\//, ''));
+      }
+    }
+  } catch {}
+  return out;
+}
+
+/**
+ * Watch the restart paths of an app. Each dir in `dirs` is watched
+ * recursively; the app root is watched non-recursively, which catches an edit
+ * to a root file in `files` and a dir in `dirs` appearing or disappearing.
+ * Every watcher error goes to `onError` and never throws.
+ *
+ * @param {string} cwd  the app root
+ * @param {{
+ *   dirs: string[],
+ *   files: string[],
+ *   ignore: (rel: string) => boolean,
+ *   onChange: (rel: string) => void,
+ *   onError: (err: NodeJS.ErrnoException) => void,
+ *   watchFn?: typeof watch,
+ * }} opts
+ * @returns {() => void} closes every watcher
+ */
+export function watchRestartPaths(cwd, { dirs, files, ignore, onChange, onError, watchFn = watch }) {
+  /** @type {Map<string, import('node:fs').FSWatcher>} */
+  const watchers = new Map();
+  let closed = false;
+  const isDir = (name) => {
+    try { return statSync(join(cwd, name)).isDirectory(); } catch { return false; }
+  };
+  const guard = (w) => {
+    w.on('error', (err) => onError(err));
+    return w;
+  };
+  const watchDir = (name) => {
+    if (closed || watchers.has(name) || !isDir(name)) return;
+    try {
+      watchers.set(name, guard(watchFn(join(cwd, name), { recursive: true }, (_type, filename) => {
+        const rel = filename ? join(name, String(filename)) : name;
+        if (!ignore(rel)) onChange(rel);
+      })));
+    } catch (err) {
+      onError(/** @type {NodeJS.ErrnoException} */ (err));
+    }
+  };
+  const unwatchDir = (name) => {
+    const w = watchers.get(name);
+    if (!w) return;
+    try { w.close(); } catch {}
+    watchers.delete(name);
+  };
+
+  /** @type {import('node:fs').FSWatcher | null} */
+  let root = null;
+  try {
+    root = guard(watchFn(cwd, (_type, filename) => {
+      const name = filename ? String(filename) : '';
+      if (dirs.includes(name)) {
+        // A watched dir was created, replaced, or removed.
+        if (isDir(name)) watchDir(name); else unwatchDir(name);
+        onChange(name);
+      } else if (files.includes(name)) {
+        onChange(name);
+      }
+    }));
+  } catch (err) {
+    onError(/** @type {NodeJS.ErrnoException} */ (err));
+  }
+  for (const d of dirs) watchDir(d);
+
+  return () => {
+    closed = true;
+    try { root?.close(); } catch {}
+    for (const name of [...watchers.keys()]) unwatchDir(name);
+  };
+}
+
+/**
+ * @typedef {{
+ *   pid?: number,
+ *   kill: (signal?: NodeJS.Signals) => boolean | void,
+ *   once: (event: 'exit', fn: (code: number | null, signal: NodeJS.Signals | null) => void) => unknown,
+ * }} ChildLike
+ */
+
+/**
+ * The restart state machine.
+ *
+ * - `change(path)` (debounced): restart a running child when `restartOnChange`
+ *   (Node), or start a child that is not running (either runtime, after a
+ *   crash).
+ * - A restart sends SIGTERM, escalates to SIGKILL after `killTimeoutMs`, and
+ *   spawns the replacement the moment the old child exits, never on a poll.
+ * - A child that exits on its own is restarted after the crash backoff, or at
+ *   once on the next change.
+ * - `stop()` stops everything and resolves once no child is left.
+ *
+ * @param {{
+ *   spawnChild: () => ChildLike,
+ *   restartOnChange: boolean,
+ *   log?: (line: string) => void,
+ *   timers?: { setTimeout: typeof setTimeout, clearTimeout: typeof clearTimeout },
+ *   now?: () => number,
+ *   debounceMs?: number,
+ *   backoffMs?: number[],
+ *   stableMs?: number,
+ *   killTimeoutMs?: number,
+ * }} opts
+ */
+export function createSupervisor({
+  spawnChild,
+  restartOnChange,
+  log = () => {},
+  timers = globalThis,
+  now = Date.now,
+  debounceMs = RESTART_DEBOUNCE_MS,
+  backoffMs = CRASH_BACKOFF_MS,
+  stableMs = STABLE_MS,
+  killTimeoutMs = KILL_TIMEOUT_MS,
+}) {
+  /** @type {ChildLike | null} */
+  let child = null;
+  let startedAt = 0;
+  let restarting = false;
+  let stopping = false;
+  let crashes = 0;
+  /** @type {string | null} */
+  let pendingPath = null;
+  /** @type {any} */ let debounceTimer = null;
+  /** @type {any} */ let backoffTimer = null;
+  /** @type {any} */ let killTimer = null;
+  /** @type {Array<() => void>} */
+  const stopWaiters = [];
+
+  const clear = (t) => { if (t !== null) timers.clearTimeout(t); return null; };
+
+  const launch = () => {
+    backoffTimer = clear(backoffTimer);
+    if (stopping || child) return;
+    const c = spawnChild();
+    child = c;
+    startedAt = now();
+    c.once('exit', (code, signal) => onExit(c, code, signal));
+  };
+
+  const terminate = (c) => {
+    try { c.kill('SIGTERM'); } catch {}
+    killTimer = clear(killTimer);
+    killTimer = timers.setTimeout(() => {
+      killTimer = null;
+      if (child === c) { try { c.kill('SIGKILL'); } catch {} }
+    }, killTimeoutMs);
+  };
+
+  const onExit = (c, code, signal) => {
+    if (child !== c) return;
+    child = null;
+    killTimer = clear(killTimer);
+    if (stopping) {
+      for (const w of stopWaiters.splice(0)) w();
+      return;
+    }
+    if (restarting) {
+      // The restart we asked for: start the replacement right away.
+      restarting = false;
+      crashes = 0;
+      launch();
+      return;
+    }
+    // Exited on its own: a crash, a fatal boot error, or an outside kill.
+    if (now() - startedAt >= stableMs) crashes = 0;
+    const delay = backoffMs[Math.min(crashes, backoffMs.length - 1)];
+    crashes++;
+    const why = signal ? `signal ${signal}` : `code ${code}`;
+    log(`dev server exited (${why}); restarting in ${delay < 1000 ? `${delay}ms` : `${delay / 1000}s`}, or on the next file change`);
+    backoffTimer = timers.setTimeout(launch, delay);
+  };
+
+  const flush = () => {
+    debounceTimer = null;
+    const path = pendingPath;
+    pendingPath = null;
+    if (stopping) return;
+    if (!child) {
+      // Not running (crashed, or waiting out a backoff): a change is the cue.
+      if (path) log(`${path} changed, starting the dev server`);
+      launch();
+      return;
+    }
+    if (!restartOnChange || restarting) return;
+    restarting = true;
+    if (path) log(`${path} changed, restarting the dev server`);
+    terminate(child);
+  };
+
+  return {
+    start: launch,
+    /** @param {string} path */
+    change(path) {
+      if (stopping) return;
+      if (pendingPath === null) pendingPath = path;
+      debounceTimer = clear(debounceTimer);
+      debounceTimer = timers.setTimeout(flush, debounceMs);
+    },
+    /** @returns {Promise<void>} */
+    stop() {
+      stopping = true;
+      debounceTimer = clear(debounceTimer);
+      backoffTimer = clear(backoffTimer);
+      if (!child) return Promise.resolve();
+      const done = new Promise((r) => stopWaiters.push(() => r(undefined)));
+      terminate(child);
+      return done;
+    },
+    get running() { return child !== null; },
+  };
+}
+
+/**
+ * Run the dev server under the supervisor until a signal stops it.
+ *
+ * @param {{
+ *   cwd: string,
+ *   plan: { args: string[], restartOnChange: boolean, watchDirs: string[], watchFiles: string[] },
+ *   env: NodeJS.ProcessEnv,
+ *   onExit: (code: number) => void,
+ * }} opts
+ */
+export function superviseDevServer({ cwd, plan, env, onExit }) {
+  const log = (line) => console.log(`[webjs] ${line}`);
+  // A watcher error here is NOT logged: the server child watches the whole app
+  // tree (a superset of these paths) and prints one warning per unwatchable
+  // path itself, so logging it here too would print every warning twice. The
+  // watcher keeps running either way.
+  const ignoreWatchError = () => {};
+
+  const sup = createSupervisor({
+    restartOnChange: plan.restartOnChange,
+    log,
+    spawnChild: () => {
+      const c = spawn(process.execPath, plan.args, {
+        // The IPC channel lets the child notice this process is gone and exit,
+        // so a killed supervisor never leaves an orphan holding the port.
+        stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+        cwd,
+        env,
+      });
+      // A failed spawn emits 'error' and may never emit 'exit'; report it as
+      // an exit so the backoff retries it (a repeated exit is ignored).
+      c.on('error', (err) => {
+        console.error(`[webjs] could not start the dev server: ${err.message}`);
+        c.emit('exit', 1, null);
+      });
+      return c;
+    },
+  });
+
+  const outputs = readRegenerateOutputs(cwd);
+  const closeWatch = watchRestartPaths(cwd, {
+    dirs: plan.watchDirs,
+    files: plan.watchFiles,
+    ignore: (rel) => shouldIgnoreRestartPath(rel) || outputs.has(rel.replace(/\\/g, '/')),
+    onChange: (rel) => sup.change(rel),
+    onError: ignoreWatchError,
+  });
+
+  let exiting = false;
+  const shutdown = (code) => {
+    if (exiting) return;
+    exiting = true;
+    closeWatch();
+    sup.stop().then(() => onExit(code));
+  };
+  process.on('SIGINT', () => shutdown(0));
+  process.on('SIGTERM', () => shutdown(0));
+  process.on('SIGHUP', () => shutdown(0));
+  // Last resort: a watcher error that escaped every listener (a runtime that
+  // emits it somewhere else) is never fatal, and the server child reports the
+  // same path itself. Anything else is a real
+  // supervisor bug, so it is reported and the process exits non-zero after
+  // stopping the child.
+  process.on('uncaughtException', (err) => {
+    if (isWatchError(err)) return;
+    console.error(err && err.stack ? err.stack : err);
+    shutdown(1);
+  });
+
+  sup.start();
+  return sup;
+}