@webjsdev/server 0.8.90 → 0.9.0

package/src/dev/server.js

@@ -18,6 +18,7 @@ import { stripBasePath } from '../base-path.js';
 import { basePath } from '../importmap.js';
 import { attachWebSocket } from '../websocket.js';
 import { toWebRequest, sendWebResponse } from './helpers.js';
+import { earlyHintLinks } from '../ssr/shipped-modules.js';
 import { isAddrInUse, portInUseError, reusePortRequested } from '../port-in-use.js';
 
 /** This copy of `@webjsdev/server`'s version, so a hot re-run can tell the framework itself changed. */
@@ -58,14 +59,21 @@ function debounce(fn, ms) {
  * (drizzle-kit output) churn during db:migrate. The `db/dev.db` branch is
  * prefix-only (no trailing separator) so the `-journal` / `-wal` sidecars match
  * too, while staying anchored to `db/dev.db` so a SOURCE file like
- * `db/schema.server.ts` still triggers a reload. The others stay
+ * `db/schema.server.ts` still triggers a reload. Beyond that, under the app's
+ * root `db/` only JS / TS source counts (#1664): a database file anywhere
+ * below it, whatever its name or sidecar (a `DATABASE_URL` pointing at
+ * `db/data/app.db`, libSQL's `-info` / `-client_wal_index` files), changes on
+ * every write and is skipped. Rails' reloader takes the same approach,
+ * watching a directory for source extensions only, rather than listing data
+ * files. The CLI's `shouldIgnoreRestartPath` carries the same pattern, and a
+ * test asserts the two agree over a corpus. The others stay
  * separator-anchored so an unrelated name like `node_modules.bak/foo` does not.
  *
  * @param {string} filename relative path from an fs.watch `event.filename`
  * @returns {boolean} true when the change should be ignored
  */
 export function shouldIgnoreWatchPath(filename) {
-  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(filename || '');
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)|^db[\\/](?!.*\.[cm]?[jt]s$)/.test(filename || '');
 }
 
 /**
@@ -149,7 +157,10 @@ async function startNodeListener(ctx) {
       // 103 Early Hints: before running SSR, send preload hints for the
       // page's module URLs so the browser can begin fetching them while
       // the server is still computing the body. Skipped in dev (file churn
-      // would send stale URLs after rebuilds) and for non-GET/HEAD.
+      // would send stale URLs after rebuilds) and for non-GET/HEAD. Plain
+      // preloads, never modulepreload: a module hint arrives before the
+      // page's import map, and Firefox then refuses the map (see
+      // earlyHintLinks in ../ssr/shipped-modules.js).
       if (
         !dev &&
         (req.method === 'GET' || req.method === 'HEAD') &&
@@ -159,7 +170,7 @@ async function startNodeListener(ctx) {
         if (match && match.moduleUrls.length) {
           try {
             res.writeEarlyHints({
-              link: match.moduleUrls.map((u) => `<${u}>; rel=modulepreload`),
+              link: earlyHintLinks(match.moduleUrls),
             });
           } catch (e) {
             logger.warn('writeEarlyHints failed', { err: String(e) });
@@ -368,6 +379,8 @@ export async function startServer(opts) {
           if (app.isRegenerateOutput(filename)) return;
           pendingVerdict = strongerVerdict(pendingVerdict, app.classifyWatchPath(filename, root));
           if (hotKey && needsHotReset(filename, (f) => !app.needsRegistryReset(f, root))) pendingPoke = true;
+          // A status wait (#1664) holds until the rebuild this event schedules.
+          app.noteChange?.();
           rebuild();
         },
         onError: onWatchError,

package/src/dev/vendor-retry.js

@@ -39,23 +39,21 @@ export function createRetryBackoff(opts = {}) {
   const now = opts.now ?? Date.now;
   let windowMs = 0;
   let notBefore = 0;
+  // Closures over the state, not methods reading `this`, so a handle can be
+  // destructured or passed as a callback (`onRebuild(backoff.reset)`).
+  const succeeded = () => {
+    windowMs = 0;
+    notBefore = 0;
+  };
   return {
-    allow() {
-      return windowMs === 0 || now() >= notBefore;
-    },
-    failed() {
+    allow: () => windowMs === 0 || now() >= notBefore,
+    failed: () => {
       windowMs = windowMs === 0 ? initialMs : Math.min(maxMs, windowMs * 2);
       notBefore = now() + windowMs;
     },
-    succeeded() {
-      windowMs = 0;
-      notBefore = 0;
-    },
-    reset() {
-      this.succeeded();
-    },
-    windowMs() {
-      return windowMs;
-    },
+    succeeded,
+    // A rebuild forgets the same thing a success does.
+    reset: succeeded,
+    windowMs: () => windowMs,
   };
 }

package/src/dev-regenerate.js

@@ -1,22 +1,18 @@
 /**
- * On-request regeneration of a stale build output in dev (#967).
+ * Build outputs that rebuild themselves when stale (#967), and the record of
+ * what each one was built from (#1672).
  *
  * A UI scaffold compiles a STATIC `public/tailwind.css` (#947) so the app is
  * fully styled with JavaScript OFF (progressive enhancement, invariant 1). In
- * prod that static file is built once by `start.before`. In DEV the classic
- * shape was a long-lived `tailwindcss --watch` in `dev.parallel`, but a watch
- * that dies mid-session, lags, or never starts (an app-dir relocation, a killed
- * child) then serves STALE or MISSING CSS with no error: a newly added utility
- * class has no backing rule, so the app renders unstyled locally while prod is
- * fine, a confusing, hard-to-attribute regression.
+ * DEV the classic shape was a long-lived `tailwindcss --watch` in
+ * `dev.parallel`, but a watch that dies mid-session, lags, or never starts then
+ * serves STALE or MISSING CSS with no error: a newly added utility class has no
+ * backing rule, so the app renders unstyled locally while prod is fine.
  *
  * This module removes that foot-gun by regenerating the output ON REQUEST when
- * it is stale, instead of relying on a live watch. It is deliberately GENERIC
- * and styling-agnostic: it runs whatever command the app declares, keyed by the
- * output path, so the framework stays BYO-styling (the Tailwind knowledge lives
- * in the scaffold's `package.json` config, not here). It is DEV-ONLY; prod keeps
- * the static build, so dev and prod resolve classes through the exact SAME
- * command (`tailwindcss -i input.css -o tailwind.css`) and cannot diverge.
+ * it is stale. It is deliberately GENERIC and styling-agnostic: it runs whatever
+ * command the app declares, keyed by the output path, so the framework stays
+ * BYO-styling (the Tailwind knowledge lives in the app's `package.json`).
  *
  * Declared as `webjs.dev.regenerate` in the app's `package.json`:
  *   "webjs": { "dev": { "regenerate": [
@@ -25,20 +21,44 @@
  *       "inputs": ["app", "components", "modules", "lib", "public/input.css"] }
  *   ] } }
  *
- * When `/public/tailwind.css` is requested and the newest mtime under any of
- * `inputs` is newer than the output (or the output is missing), `command` is run
- * to completion BEFORE the file is served, so the response is always fresh.
- * Concurrent requests coalesce onto one in-flight compile.
+ * FRESHNESS IS A RECORD, NOT AN MTIME ORDERING (#1672). Every build this module
+ * runs records, in `.webjs/regenerate.json`, the command it ran, a fingerprint
+ * of its inputs taken BEFORE the command started, and a fingerprint of the
+ * output it produced. An output is fresh exactly when all three still match.
+ * This is the shape of Ninja's `.ninja_log` (which records per output the
+ * command hash and the mtime it was built against, so a `restat` output a rule
+ * left untouched is not rebuilt) and of Vite's dep optimizer
+ * (`node_modules/.vite/deps/_metadata.json`, a lockfile and config hash compared
+ * on startup). Comparing mtimes instead, as Make does, fails three ways that all
+ * bit here: a compiler that skips writing unchanged bytes (the Tailwind CLI)
+ * leaves the output older than its inputs forever, an input dated in the future
+ * hides every later edit, and a deleted input is invisible. Equality of a
+ * recorded fingerprint has none of those failure modes.
+ *
+ * The same rules run outside the dev server through `webjs regenerate` (the
+ * CLI), which an app puts in `dev.before` / `start.before` in place of a raw
+ * compile, so every build path writes the one record and `webjs doctor` reads
+ * it. A build by hand (`npm run css:build`) writes no record, so the output
+ * reads as unrecorded and is rebuilt once on its next request.
  */
 
 import { spawn as nodeSpawn } from 'node:child_process';
-import { readFile, stat, readdir } from 'node:fs/promises';
-import { delimiter, dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { delimiter, dirname, join, relative, sep } from 'node:path';
 
 /**
  * @typedef {{ output: string, command: string, inputs: string[] }} RegenerateRule
+ * @typedef {{ command: string, inputs: string, output: string }} RegenerateRecord
+ * @typedef {{ version: 1, outputs: Record<string, RegenerateRecord> }} RegenerateManifest
+ * @typedef {'fresh' | 'stale' | 'missing' | 'unrecorded'} RegenerateState
+ * @typedef {{ ok: true } | { ok: false, reason: 'failed' | 'no-output' }} BuildResult
+ * @typedef {{ spawn?: typeof nodeSpawn, warn?: (msg: string) => void }} BuildOptions
  */
 
+/** The record of every build, relative to the app root. */
+export const REGENERATE_MANIFEST = '.webjs/regenerate.json';
+
 /**
  * Read + normalize the `webjs.dev.regenerate` rules from an app's
  * `package.json`. Defensive: a missing/malformed block yields `[]` (a plain app
@@ -69,54 +89,175 @@ export async function readRegenerateRules(appDir, read) {
     }));
 }
 
-// Directories never worth walking for a source-freshness check: build output,
+// Directories never worth walking for a source fingerprint: build output,
 // dependencies, VCS + framework caches. Skipping them keeps the walk cheap and
 // avoids treating a dependency's mtime as an app-source edit.
 const IGNORE_DIRS = new Set(['node_modules', '.git', '.webjs', 'dist', '.next', 'coverage']);
 
 /**
- * Newest mtime (ms) of any FILE under a path: the file's own mtime, or the max
- * over the files in a directory tree (skipping IGNORE_DIRS and dotfiles). A
- * missing path is 0, so it never makes the output look stale.
- *
- * Directory-node mtimes are deliberately NOT counted: a directory's mtime bumps
- * on a file add/remove but NOT on a content edit, so a content edit (the case
- * that matters, a new utility class in an existing file) is only visible through
- * the FILE mtime. Counting a new file's own mtime still catches an addition;
- * only a pure deletion is missed, which is harmless (stale rules self-heal on
- * the next real edit) and keeps the freshness check deterministic (a directory
- * mtime is a moving target that made the comparison flaky across runtimes).
- * Pure I/O, no throw.
+ * Append one line per FILE under `abs` to `lines`: its appDir-relative path,
+ * size and mtime. A missing path contributes a `missing` line, so creating it
+ * later changes the fingerprint. Skips IGNORE_DIRS, dotfiles and symlinks (a
+ * symlink can cycle into unbounded recursion or escape into node_modules).
+ * Directory-node mtimes are not counted: an addition or a deletion already
+ * shows as a line appearing or disappearing. Pure I/O, no throw.
  *
+ * @param {string} appDir
  * @param {string} abs
- * @returns {Promise<number>}
+ * @param {string[]} lines
+ * @returns {Promise<void>}
  */
-async function maxMtimeMs(abs) {
+async function collectFiles(appDir, abs, lines) {
+  const rel = relative(appDir, abs).split(sep).join('/');
   let st;
   try {
     st = await stat(abs);
   } catch {
-    return 0;
+    lines.push(`${rel}\0missing`);
+    return;
+  }
+  if (!st.isDirectory()) {
+    lines.push(`${rel}\0${st.size}\0${st.mtimeMs}`);
+    return;
   }
-  if (!st.isDirectory()) return st.mtimeMs;
-  let newest = 0;
   let entries;
   try {
     entries = await readdir(abs, { withFileTypes: true });
   } catch {
-    return newest;
+    return;
   }
   for (const e of entries) {
     if (e.name.startsWith('.') || IGNORE_DIRS.has(e.name)) continue;
-    // Skip symlinks entirely: following one can cycle (a link back to an
-    // ancestor) into unbounded recursion, or escape into node_modules via a
-    // renamed link. A symlinked source file is rare in an app tree; not
-    // counting its mtime is a safe tradeoff for a walk that cannot hang.
     if (e.isSymbolicLink()) continue;
-    const m = await maxMtimeMs(join(abs, e.name));
-    if (m > newest) newest = m;
+    await collectFiles(appDir, join(abs, e.name), lines);
+  }
+}
+
+/**
+ * A fingerprint of every file under a rule's `inputs`: a hash over each file's
+ * path, size and mtime, so an edit, an addition, a deletion and a rename all
+ * change it. Compared for EQUALITY, never ordering, so a file dated in the
+ * future is just another value and later edits still change the result.
+ *
+ * The rule's own `output` is left out even when an input directory contains it
+ * (`inputs: ["public"]` around `public/tailwind.css`): every build rewrites the
+ * output, so counting it would make each build invalidate itself.
+ *
+ * A command must not rewrite files under its own `inputs` with unchanged
+ * bytes, for the same reason: a prepare step inside the command (a copy into
+ * an input directory) has to compare before writing. One that writes a file
+ * whose content did change costs a single extra rebuild, which then settles.
+ *
+ * @param {string} appDir
+ * @param {RegenerateRule} rule
+ * @returns {Promise<string>}
+ */
+export async function inputFingerprint(appDir, rule) {
+  /** @type {string[]} */
+  const lines = [];
+  for (const inp of rule.inputs) await collectFiles(appDir, join(appDir, inp), lines);
+  const self = rule.output + '\0';
+  const own = lines.filter((l) => !l.startsWith(self)).sort();
+  return createHash('sha256').update(own.join('\n')).digest('hex');
+}
+
+/**
+ * The output's size and mtime, read right after a build and compared on every
+ * check, so a hand edit, a delete, or a different build replacing the file all
+ * read as stale. `null` when the output does not exist.
+ *
+ * @param {string} abs
+ * @returns {Promise<string | null>}
+ */
+async function outputFingerprint(abs) {
+  try {
+    const st = await stat(abs);
+    return st.isFile() ? `${st.size}:${st.mtimeMs}` : null;
+  } catch {
+    return null;
   }
-  return newest;
+}
+
+/**
+ * Read the build record. A missing, malformed, or other-version file reads as
+ * empty, which makes every output unrecorded and rebuilds it once: the safe
+ * direction.
+ *
+ * @param {string} appDir
+ * @returns {Promise<RegenerateManifest>}
+ */
+export async function readRegenerateManifest(appDir) {
+  try {
+    const m = JSON.parse(await readFile(join(appDir, REGENERATE_MANIFEST), 'utf8'));
+    if (m && m.version === 1 && m.outputs && typeof m.outputs === 'object') return m;
+  } catch {
+    // fall through
+  }
+  return { version: 1, outputs: {} };
+}
+
+// Writes to one manifest, chained per path. Parallel requests for different
+// outputs (the website's /ui page links nine stylesheets) each record a build;
+// unserialized, those read-modify-writes would drop each other's entries. A
+// dev server and a concurrent `webjs regenerate` are separate processes and can
+// still lose one entry, which costs one extra rebuild: the safe direction.
+/** @type {Map<string, Promise<void>>} */
+const manifestWrites = new Map();
+let tmpCounter = 0;
+
+/**
+ * Record one build, read-modify-write, written to a temp file and renamed so a
+ * reader never sees a half-written manifest. Never throws: a read-only
+ * filesystem (a locked-down prod image) must still serve, it only loses the
+ * record and rebuilds again.
+ *
+ * @param {string} appDir
+ * @param {string} output
+ * @param {RegenerateRecord} record
+ * @param {(msg: string) => void} warn
+ * @returns {Promise<void>}
+ */
+function recordBuild(appDir, output, record, warn) {
+  const path = join(appDir, REGENERATE_MANIFEST);
+  const prev = manifestWrites.get(path) || Promise.resolve();
+  const next = prev.then(async () => {
+    try {
+      const manifest = await readRegenerateManifest(appDir);
+      manifest.outputs[output] = record;
+      await mkdir(dirname(path), { recursive: true });
+      const tmp = `${path}.${process.pid}.${++tmpCounter}.tmp`;
+      await writeFile(tmp, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+      await rename(tmp, path);
+    } catch (err) {
+      warn(`[webjs] regenerate: could not record the build of ${output} in ${REGENERATE_MANIFEST} (${/** @type {Error} */ (err).message}); it will be rebuilt on its next request.`);
+    }
+  });
+  manifestWrites.set(path, next);
+  return next.finally(() => {
+    if (manifestWrites.get(path) === next) manifestWrites.delete(path);
+  });
+}
+
+/**
+ * Whether a rule's output is fresh against the record. Cheapest test first: a
+ * missing output or a missing record needs no input walk at all, and neither
+ * does a changed command or an output something else rewrote. Only a record
+ * that matches on all of those walks the inputs.
+ *
+ * @param {string} appDir
+ * @param {RegenerateRule} rule
+ * @param {RegenerateManifest} [manifest]
+ * @returns {Promise<{ state: RegenerateState, inputs?: string }>} `inputs` is the
+ *   fingerprint when the check computed it, so a build can record it unwalked.
+ */
+export async function regenerateState(appDir, rule, manifest) {
+  const out = await outputFingerprint(join(appDir, rule.output));
+  if (out === null) return { state: 'missing' };
+  const record = (manifest || await readRegenerateManifest(appDir)).outputs[rule.output];
+  if (!record) return { state: 'unrecorded' };
+  if (record.command !== rule.command || record.output !== out) return { state: 'stale' };
+  const inputs = await inputFingerprint(appDir, rule);
+  return { state: record.inputs === inputs ? 'fresh' : 'stale', inputs };
 }
 
 /**
@@ -140,38 +281,108 @@ function envWithLocalBin(cwd) {
 }
 
 /**
- * Run a regenerate command to completion. Never rejects (a compile failure is
- * logged by the tool's own inherited stderr; the caller then serves whatever is
- * on disk, degrading to the previous behaviour rather than 500ing the request).
+ * Run a regenerate command to completion and resolve its exit code: `null` for
+ * a spawn error or a child killed by a signal, so an interrupted compile is
+ * never recorded. Never rejects: a compile failure is logged by the tool's own
+ * inherited stderr.
  *
  * @param {string} command
  * @param {string} cwd
  * @param {typeof nodeSpawn} spawn
- * @returns {Promise<void>}
+ * @returns {Promise<number | null>}
  */
 function runCommand(command, cwd, spawn) {
   return new Promise((resolve) => {
     const child = spawn(command, { shell: true, stdio: 'inherit', cwd, env: envWithLocalBin(cwd) });
-    child.on('exit', () => resolve());
-    child.on('error', () => resolve());
+    // A Promise settles once, so whichever of these fires second is ignored.
+    child.on('exit', (code) => resolve(typeof code === 'number' ? code : null));
+    child.on('error', () => resolve(null));
   });
 }
 
-// In-flight compiles, keyed by appDir + output, so concurrent requests for the
+/**
+ * Move a file, falling back to copy + delete across filesystems (`.webjs` may
+ * be a link onto another volume). Resolves false when there is nothing to move.
+ *
+ * @param {string} from
+ * @param {string} to
+ * @returns {Promise<boolean>}
+ */
+async function moveFile(from, to) {
+  try {
+    await rename(from, to);
+    return true;
+  } catch (err) {
+    if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return false;
+    await copyFile(from, to);
+    await unlink(from);
+    return true;
+  }
+}
+
+/**
+ * Run a rule's command and record what it built.
+ *
+ * The output is moved aside into `.webjs/regenerate/` first, so the command has
+ * to WRITE it: a compiler that skips an unchanged write (the Tailwind CLI reads
+ * the existing file and returns early) writes a missing one. That makes the
+ * outcome decisive. Exit 0 with the output present is recorded. Exit 0 with no
+ * output means the rule's `output` is not the path its command writes, so the
+ * previous output is restored, nothing is recorded, and a warning names the
+ * rule, which repeats on every request until the rule is fixed. A failed or
+ * interrupted command restores the previous output (a last good stylesheet
+ * beats a partial one) and records nothing, so the next request retries.
+ *
+ * @param {string} appDir
+ * @param {RegenerateRule} rule
+ * @param {BuildOptions & { inputs?: string }} [opts] `inputs`: a fingerprint
+ *   already taken by `regenerateState`, so the build does not walk twice
+ * @returns {Promise<BuildResult>}
+ */
+export async function buildRegenerateOutput(appDir, rule, opts = {}) {
+  const spawn = opts.spawn || nodeSpawn;
+  const warn = opts.warn || ((m) => console.warn(m));
+  // The snapshot is taken BEFORE the command runs, so a file saved during the
+  // compile no longer matches the record and the next check rebuilds.
+  const inputs = opts.inputs ?? await inputFingerprint(appDir, rule);
+  const outAbs = join(appDir, rule.output);
+  const backupDir = join(appDir, '.webjs', 'regenerate');
+  const backup = join(backupDir, encodeURIComponent(rule.output));
+  await mkdir(backupDir, { recursive: true });
+  await rm(backup, { force: true }); // a leftover from an interrupted process
+  const hadOutput = await moveFile(outAbs, backup);
+
+  const code = await runCommand(rule.command, appDir, spawn);
+  const output = code === 0 ? await outputFingerprint(outAbs) : null;
+  if (output !== null) {
+    await rm(backup, { force: true });
+    await recordBuild(appDir, rule.output, { command: rule.command, inputs, output }, warn);
+    return { ok: true };
+  }
+  if (hadOutput) await moveFile(backup, outAbs);
+  if (code === 0) {
+    warn(`[webjs] regenerate: \`${rule.command}\` exited 0 but did not write ${rule.output}. Check that the rule's "output" is the path its command writes.`);
+    return { ok: false, reason: 'no-output' };
+  }
+  return { ok: false, reason: 'failed' };
+}
+
+// In-flight builds, keyed by appDir + output, so concurrent requests for the
 // same stale output share ONE compile instead of racing N of them. Module-scope
 // (not per-handler): the filesystem is the shared resource being guarded.
 const inFlight = new Map();
 
 /**
- * If a regenerate rule matches `relPath` and its output is stale (older than the
- * newest input, or missing), run the rule's command to completion before
- * returning, so the caller serves a fresh file. A no-op when no rule matches or
- * the output is already fresh. Concurrent calls for the same output coalesce.
+ * If a regenerate rule matches `relPath` and its output is not fresh against
+ * the record, build it before returning, so the caller serves a fresh file. A
+ * no-op when no rule matches or the output is fresh. Concurrent calls for the
+ * same output coalesce. Never rejects: a failed build leaves the previous
+ * output on disk to be served.
  *
  * @param {string} appDir
  * @param {string} relPath  appDir-relative served path, no leading slash (e.g. `public/tailwind.css`)
  * @param {RegenerateRule[]} rules
- * @param {{ spawn?: typeof nodeSpawn }} [opts] injectable spawn for tests
+ * @param {BuildOptions} [opts] injectable spawn and warning sink for tests
  * @returns {Promise<void>}
  */
 export async function maybeRegenerate(appDir, relPath, rules, opts = {}) {
@@ -181,25 +392,13 @@ export async function maybeRegenerate(appDir, relPath, rules, opts = {}) {
   const pending = inFlight.get(key);
   if (pending) return pending;
 
-  const spawn = opts.spawn || nodeSpawn;
   const run = (async () => {
-    const outAbs = join(appDir, rule.output);
-    let outMtime = 0;
-    try {
-      outMtime = (await stat(outAbs)).mtimeMs;
-    } catch {
-      outMtime = 0; // missing output: always stale
-    }
-    if (outMtime !== 0) {
-      let newestSrc = 0;
-      for (const inp of rule.inputs) {
-        const m = await maxMtimeMs(join(appDir, inp));
-        if (m > newestSrc) newestSrc = m;
-      }
-      if (newestSrc <= outMtime) return; // fresh, nothing to do
-    }
-    await runCommand(rule.command, appDir, spawn);
-  })();
+    const { state, inputs } = await regenerateState(appDir, rule);
+    if (state === 'fresh') return;
+    await buildRegenerateOutput(appDir, rule, { ...opts, inputs });
+  })().catch((err) => {
+    (opts.warn || console.warn)(`[webjs] regenerate: building ${rule.output} failed (${err && err.message}); serving what is on disk.`);
+  });
   inFlight.set(key, run);
   try {
     await run;
@@ -208,13 +407,58 @@ export async function maybeRegenerate(appDir, relPath, rules, opts = {}) {
   }
 }
 
+/**
+ * Build every rule whose output is not fresh, one at a time, and report each.
+ * The engine behind `webjs regenerate`, which an app runs in `dev.before` /
+ * `start.before` (or a CI step) so a build outside the dev server records its
+ * freshness the same way a dev request does. `force` rebuilds every rule.
+ *
+ * @param {string} appDir
+ * @param {{ force?: boolean, rules?: RegenerateRule[] } & BuildOptions} [opts]
+ * @returns {Promise<Array<{ output: string, state: RegenerateState, built: boolean } & ({ ok: true } | { ok: false, reason: 'failed' | 'no-output' })>>}
+ */
+export async function regenerateOutputs(appDir, opts = {}) {
+  const rules = opts.rules || await readRegenerateRules(appDir);
+  const results = [];
+  for (const rule of rules) {
+    const { state, inputs } = await regenerateState(appDir, rule);
+    if (state === 'fresh' && !opts.force) {
+      results.push({ output: rule.output, state, built: false, ok: /** @type {const} */ (true) });
+      continue;
+    }
+    const r = await buildRegenerateOutput(appDir, rule, { ...opts, inputs });
+    results.push({ output: rule.output, state, built: true, ...r });
+  }
+  return results;
+}
+
+/**
+ * Every rule's state against the record, without building anything. What
+ * `webjs doctor` reads, so the doctor and the dev server share one definition
+ * of fresh.
+ *
+ * @param {string} appDir
+ * @returns {Promise<Array<{ output: string, command: string, state: RegenerateState }>>}
+ */
+export async function regenerateStatus(appDir) {
+  const rules = await readRegenerateRules(appDir);
+  const manifest = await readRegenerateManifest(appDir);
+  const out = [];
+  for (const rule of rules) {
+    const { state } = await regenerateState(appDir, rule, manifest);
+    out.push({ output: rule.output, command: rule.command, state });
+  }
+  return out;
+}
+
 /**
  * Whether a dev-watcher filename is a regenerate OUTPUT (#967). A regenerate
  * output is a build product the dev server itself writes on request, so a write
  * to it must NOT trigger a rebuild + SSE reload: that would spuriously reload
  * the page mid-navigation (breaking a soft-nav / streaming interaction) and,
  * worse, could reload -> refetch -> recompile -> reload. Same rationale as the
- * `db/dev.db` carve-out in `shouldIgnoreWatchPath`. `fs.watch` reports a path
+ * `db/dev.db` carve-out in `shouldIgnoreWatchPath`, which also skips `.webjs/`,
+ * where the record and the moved-aside output live. `fs.watch` reports a path
  * relative to the watched root with OS separators, so it is normalized to `/`
  * before matching the rule's already-normalized `output`.
  *