@webjsdev/server 0.8.63 → 0.8.65

package/src/component-elision.js

@@ -45,6 +45,7 @@ import {
   redactToPlaceholders,
 } from './js-scan.js';
 import { transitiveDeps, expandImportAlias } from './module-graph.js';
+import { ensureStripper } from './ts-strip.js';
 
 /**
  * Named imports from a `@webjsdev/core` specifier that imply the
@@ -244,7 +245,7 @@ const CLIENT_ROUTER_SUBPATH_RE = /['"]@webjsdev\/core\/client-router['"]/;
  * REACTIVE_IMPORTS: a router function the barrel re-exports but this list omits
  * is not recognized as client work, so a component using it is wrongly elided.
  */
-export const CLIENT_ROUTER_IMPORTS = ['navigate', 'enableClientRouter', 'disableClientRouter', 'revalidate', 'loadFrame'];
+export const CLIENT_ROUTER_IMPORTS = ['navigate', 'enableClientRouter', 'disableClientRouter', 'revalidate', 'refreshPage', 'loadFrame'];
 
 /** Identifiers that only exist in a browser; their presence means client work. */
 const CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|sessionStorage|customElements|matchMedia|addEventListener)\b/;
@@ -267,6 +268,23 @@ const INSTANCEOF_RE = /\binstanceof\s+([A-Z][A-Za-z0-9_$]*)/g;
  * `customElements.define(...)` legitimately uses it and must not force ship). */
 const COMPONENT_CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|sessionStorage|matchMedia|addEventListener)\b/;
 
+/**
+ * Constructors that produce inert DATA with no side effect, so a module-scope
+ * `export const X = new Set([...])` (a lookup table, a compiled RegExp, a
+ * parsed URL) is not client work and must not pin an importing page/layout
+ * (#623). Any constructor NOT in this set (`new WebSocket()`, `new Worker()`,
+ * `new EventSource()`, `new Audio()`) IS a side effect and still ships.
+ */
+const PURE_DATA_CONSTRUCTORS = new Set([
+  'Set', 'Map', 'WeakSet', 'WeakMap', 'Date', 'RegExp', 'Array', 'Object',
+  'Number', 'String', 'Boolean', 'BigInt', 'Symbol',
+  'Error', 'TypeError', 'RangeError', 'SyntaxError',
+  'URL', 'URLSearchParams', 'ArrayBuffer', 'DataView',
+  'Int8Array', 'Uint8Array', 'Uint8ClampedArray', 'Int16Array', 'Uint16Array',
+  'Int32Array', 'Uint32Array', 'Float32Array', 'Float64Array',
+  'BigInt64Array', 'BigUint64Array',
+]);
+
 /**
  * Module-scope client work, detected by an ALLOWLIST of safe top-level forms
  * rather than a denylist of browser globals. A module that runs ANY code when
@@ -285,13 +303,22 @@ const COMPONENT_CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|
  *
  * Scans the redacted copy (strings / templates / comments blanked, regex
  * literals and nested `${...}` interpolation tracked by the lexer) so template
- * prose and JSDoc / TS type annotations cannot trip it; quoted-string bodies,
- * which redaction keeps verbatim for other rules, are blanked here too so a
- * string like `"foo()"` or `"{"` is not read as a call and cannot unbalance
- * the brace scan. The unbalanced-brace and unterminated-string fallbacks below
- * are defense in depth: with the lexer tracking regex literals, neither should
- * trigger on valid code, but if either does the module ships rather than risk
- * hiding client work.
+ * prose and JSDoc cannot trip it; quoted-string bodies, which redaction keeps
+ * verbatim for other rules, are blanked here too so a string like `"foo()"` or
+ * `"{"` is not read as a call and cannot unbalance the brace scan. The
+ * unbalanced-brace and unterminated-string fallbacks below are defense in
+ * depth: with the lexer tracking regex literals, neither should trigger on
+ * valid code, but if either does the module ships rather than risk hiding
+ * client work.
+ *
+ * PASS TYPE-ERASED SOURCE for a TypeScript module. Redaction blanks comments
+ * and literals, NOT type syntax, and TS annotations are call-shaped often
+ * enough to matter: `readonly (readonly [number, number, number])[]` is an
+ * identifier immediately followed by `(`, so a module holding nothing but a
+ * typed data literal reads as running code at module scope (#1423). The
+ * analyser erases types before it calls this (`eraseTypesForScan`), so the
+ * request path is covered; a DIRECT caller handing it `.ts` source as authored
+ * is opting into that false positive.
  *
  * Over-detection is safe (a top-level arrow whose body calls something, or a
  * pure top-level helper call, only ships). The accepted residual misses, all
@@ -299,25 +326,10 @@ const COMPONENT_CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|
  * top-level object / array initializer or a destructuring default, and a
  * side-effecting tagged-template hole evaluated at module scope.
  *
- * @param {string} src raw module source
- */
-/**
- * Constructors that produce inert DATA with no side effect, so a module-scope
- * `export const X = new Set([...])` (a lookup table, a compiled RegExp, a
- * parsed URL) is not client work and must not pin an importing page/layout
- * (#623). Any constructor NOT in this set (`new WebSocket()`, `new Worker()`,
- * `new EventSource()`, `new Audio()`) IS a side effect and still ships.
+ * @param {string} src module source, type-erased if it came from a TypeScript file
+ * @param {string[]} [literals] the redaction's literal bodies, when already computed
+ * @returns {boolean}
  */
-const PURE_DATA_CONSTRUCTORS = new Set([
-  'Set', 'Map', 'WeakSet', 'WeakMap', 'Date', 'RegExp', 'Array', 'Object',
-  'Number', 'String', 'Boolean', 'BigInt', 'Symbol',
-  'Error', 'TypeError', 'RangeError', 'SyntaxError',
-  'URL', 'URLSearchParams', 'ArrayBuffer', 'DataView',
-  'Int8Array', 'Uint8Array', 'Uint8ClampedArray', 'Int16Array', 'Uint16Array',
-  'Int32Array', 'Uint32Array', 'Float32Array', 'Float64Array',
-  'BigInt64Array', 'BigUint64Array',
-]);
-
 export function hasModuleScopeSideEffect(src, literals) {
   let redacted = src;
   if (!literals) {
@@ -871,6 +883,131 @@ export function extractRenderedTags(src) {
   return tags;
 }
 
+/**
+ * The extensions that can carry TypeScript type syntax INTO this analysis.
+ *
+ * Derive it from what actually reaches `allFiles`, which is seeded from three
+ * places with three different filters: the component set from `scanComponents`
+ * (`/\.m?[jt]sx?$/`), the route modules from the router (`js|mjs|ts|mts`), and
+ * the module graph from its walker (`/\.(js|ts|mjs|mts)$/`). The COMPONENT set
+ * is the widest and it does not pass through the other two, so a `.tsx`
+ * component arrives here whatever the walker and the router admit. Hence
+ * `.tsx`, even though nothing in WebJs serves one: leaving it out is how the
+ * #1423 false positive comes back for exactly the file class no other filter
+ * would have let through. `.cts` is absent because no filter admits it.
+ *
+ * The rule to hold, if any of those three filters moves: this set is every
+ * TypeScript-carrying extension in their UNION. Narrowing it to the servable
+ * set instead is a change that looks tighter and silently un-erases files.
+ */
+const TS_SOURCE_RE = /\.m?tsx?$/;
+
+/**
+ * Per-file memo of {@link eraseTypesForScan}, holding the source it was derived
+ * from so a hit is proven rather than assumed. One entry per file, so it is
+ * bounded by the app's file count and needs no eviction policy; a deleted file
+ * leaves one dead entry until the process ends, which is cheaper than tracking
+ * liveness for it.
+ *
+ * @type {Map<string, { src: string, out: string }>}
+ */
+const STRIP_CACHE = new Map();
+
+/**
+ * Return `src` with its TYPE syntax erased, so every scan below reads the code
+ * that actually RUNS rather than the code as authored (#1423).
+ *
+ * The scans are lexical heuristics, and TypeScript annotations are syntax the
+ * heuristics were never designed for: `readonly (readonly [number, number,
+ * number])[]` is an identifier immediately followed by `(`, which the
+ * top-level-call matcher in `hasModuleScopeSideEffect` reads as a call, so a
+ * module holding nothing but a typed data literal was classified as running
+ * code at module scope and pinned every route module that imported it. Type
+ * syntax is erased before anything runs, so it can never be a runtime signal,
+ * and the only sound reading of it is none at all.
+ *
+ * This uses the framework's own stripper rather than a lexical annotation
+ * matcher: it is the same erasure the browser is served, so the analyser and
+ * the runtime agree by construction, where a hand-rolled matcher would meet
+ * generics, `as`, `satisfies`, and conditional types and get some of them
+ * wrong. It is position-preserving whitespace replacement, so every offset,
+ * line, and column the other scans depend on is unchanged.
+ *
+ * A non-TypeScript file is returned untouched (there is nothing to erase, and
+ * running a TS parser over one buys only new ways to fail). A PER-FILE strip
+ * failure also returns the source untouched, which is the pre-#1423 behaviour
+ * and therefore the conservative direction: the scans then over-detect at
+ * worst. Two things take that path, both silent because both are one file's
+ * problem. A non-erasable module, which invariant 10 forbids and `webjs check`
+ * catches at edit time, so it is a broken app rather than a supported one. And
+ * a `.tsx` holding real JSX, which the stripper parses as non-JSX TypeScript
+ * and rejects, so a JSX component is scanned as authored while a `.tsx` that is
+ * only TypeScript is erased normally.
+ *
+ * A missing stripper BACKEND is the failure that does not stay silent, and it
+ * is why the backend is resolved once by the caller rather than per file. It
+ * means no TypeScript in the app can be erased (a runtime with neither the
+ * built-in nor `amaro`), so every module is scanned as authored and the #1423
+ * verdict comes back app-wide. Swallowing that alongside a syntax rejection
+ * would make an app-wide regression indistinguishable from one broken file, so
+ * `resolveScanStripper` warns once and this returns the source untouched.
+ *
+ * Results are memoized per file and validated against the exact source, since
+ * this runs on every dev rebuild and stripping costs roughly 50x the read it
+ * sits beside. Validating on content rather than mtime means a same-mtime
+ * rewrite cannot serve a stale strip.
+ *
+ * @param {import('./ts-strip.js').Stripper | null} stripper resolved once per run, null when unavailable
+ * @param {string} file absolute path, the cache key and the extension source
+ * @param {string} src
+ * @returns {string}
+ */
+function eraseTypesForScan(stripper, file, src) {
+  if (!stripper || !TS_SOURCE_RE.test(file)) return src;
+  const hit = STRIP_CACHE.get(file);
+  if (hit && hit.src === src) return hit.out;
+  let out;
+  try {
+    out = stripper.fn(src);
+  } catch {
+    out = src;
+  }
+  STRIP_CACHE.set(file, { src, out });
+  return out;
+}
+
+/** Whether {@link resolveScanStripper} has already reported a missing backend. */
+let warnedNoStripper = false;
+
+/**
+ * Resolve the TypeScript stripper backend once for a whole analysis run, or
+ * `null` when this runtime has none.
+ *
+ * `analyzeElision` runs outside the dev request handler too (`webjs check`,
+ * `webjs elision`), and `ensureStripper` is called on the dev path only, so
+ * this is where the no-backend case surfaces for the other entry points. It
+ * warns once per process rather than per file: the condition is a property of
+ * the runtime, so repeating it once per module would bury it.
+ *
+ * @returns {Promise<import('./ts-strip.js').Stripper | null>}
+ */
+async function resolveScanStripper() {
+  try {
+    return await ensureStripper();
+  } catch (e) {
+    if (!warnedNoStripper) {
+      warnedNoStripper = true;
+      console.warn(
+        '[webjs] elision analysis could not resolve a TypeScript stripper, so type syntax ' +
+        'is not erased before the scans read a module. A type annotation can then read as ' +
+        'module-scope work, which ships modules that would otherwise be elided. Underlying: ' +
+        (e && e.message ? e.message : String(e)),
+      );
+    }
+    return null;
+  }
+}
+
 /**
  * Compute the set of component FILES whose browser download can be
  * elided. A file is elidable only when every component it defines is
@@ -978,6 +1115,11 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     for (const v of vs) if (!appDir || v.startsWith(appDir)) allFiles.add(v);
   }
 
+  // Resolve the stripper ONCE for the run: the backend is a property of the
+  // runtime, not of a file, and the no-backend case must be reported rather
+  // than swallowed per module (see `eraseTypesForScan`).
+  const scanStripper = await resolveScanStripper();
+
   for (const file of allFiles) {
     if (SERVER_FILE_RE.test(file)) { serverFiles.add(file); continue; }
     let src;
@@ -989,6 +1131,11 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
       continue;
     }
     if (typeof src !== 'string') continue;
+    // Erase type syntax first, so every scan below reads the code that RUNS
+    // (#1423). This is the single point where the analyser reads a file, so
+    // doing it here covers the module-scope, template, import, and component
+    // scans at once.
+    src = eraseTypesForScan(scanStripper, file, src);
     // Mask comments once for every signal scan below (#179): a `<tag>`, an
     // `@event`, a browser global, an `import`, or a `whenDefined` written in a
     // comment must not register as a real signal. String and template content

package/src/dev/config.js

@@ -0,0 +1,338 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { compileHeaderRules } from '../headers.js';
+import { compileRedirectRules, readTrailingSlashPolicy } from '../redirects.js';
+import { readBasePath } from '../base-path.js';
+import { validateAppWebjsConfig } from '../webjs-config-validate.js';
+import { readAllowedOrigins } from '../csrf.js';
+import { readCspConfig } from '../csp.js';
+import { readBodyLimits, computeServerTimeouts } from '../body-limit.js';
+
+/**
+ * Read the `WEBJS_ELIDE` environment override, if set.
+ * `0` / `false` / `off` / `no` (case-insensitive) force elision OFF;
+ * `1` / `true` / `on` / `yes` force it ON. Any other value, or an unset
+ * variable, returns `undefined` so the caller falls through to the
+ * `package.json` switch. The env override is the deploy-time / ops escape
+ * hatch: force-disable elision to rule it out while debugging a wrong-strip
+ * without editing committed code, or force-enable it regardless of an
+ * app's `package.json`. It is also the seam the differential elision test
+ * uses to render the same app on and off in one process.
+ * @returns {boolean | undefined}
+ */
+function elideEnvOverride() {
+  const raw = process.env.WEBJS_ELIDE;
+  if (raw == null || raw === '') return undefined;
+  const v = String(raw).trim().toLowerCase();
+  if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
+  if (v === '1' || v === 'true' || v === 'on' || v === 'yes') return true;
+  return undefined;
+}
+
+/**
+ * Read the project-level elision switch.
+ * Precedence: the `WEBJS_ELIDE` env override wins when set, otherwise the
+ * `package.json` `{ "webjs": { "elide": false } }` switch disables
+ * display-only and inert-route elision app-wide (everything ships, like
+ * before the feature existed). Any other value, or an absent key, leaves
+ * elision enabled (the default). Re-read on every rebuild so toggling
+ * either control takes effect without a server restart.
+ * @param {string} appDir
+ * @returns {Promise<boolean>}
+ */
+export async function readElideEnabled(appDir) {
+  const override = elideEnvOverride();
+  if (override !== undefined) return override;
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && pkg.webjs && pkg.webjs.elide === false) return false;
+  } catch {
+    // No package.json, malformed JSON, or unreadable. Keep the default.
+  }
+  return true;
+}
+
+/**
+ * Read the `WEBJS_SEED` environment override, if set. Same grammar as
+ * `WEBJS_ELIDE`: `0`/`false`/`off`/`no` force seeding OFF, `1`/`true`/`on`/`yes`
+ * force it ON, anything else (or unset) falls through to the package.json
+ * switch. The deploy-time / ops escape hatch and the seam tests use to render
+ * an app with seeding on and off in one process.
+ * @returns {boolean | undefined}
+ */
+function seedEnvOverride() {
+  const raw = process.env.WEBJS_SEED;
+  if (raw == null || raw === '') return undefined;
+  const v = String(raw).trim().toLowerCase();
+  if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
+  if (v === '1' || v === 'true' || v === 'on' || v === 'yes') return true;
+  return undefined;
+}
+
+/**
+ * Read the project-level SSR action-seeding switch (#472). Precedence: the
+ * `WEBJS_SEED` env override wins when set, otherwise the package.json
+ * `{ "webjs": { "seed": false } }` switch disables it (the client re-fetches on
+ * hydration as it did before the feature). Default ON (opt-out), mirroring
+ * elision: any value other than the literal `false` keeps seeding enabled.
+ *
+ * Seeding installs a process-global `module.registerHooks` load hook, so unlike
+ * elision it is read ONCE at boot (not re-read per rebuild): toggling it needs a
+ * restart, like a deploy.
+ * @param {string} appDir
+ * @returns {Promise<boolean>}
+ */
+export async function readSeedEnabled(appDir) {
+  const override = seedEnvOverride();
+  if (override !== undefined) return override;
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && pkg.webjs && pkg.webjs.seed === false) return false;
+  } catch {
+    // No package.json, malformed JSON, or unreadable. Keep the default.
+  }
+  return true;
+}
+
+/**
+ * Read the client-router switch (`webjs.clientRouter`) from the app's
+ * package.json (#629). Default `true`: the client router auto-enables in the
+ * browser whenever `@webjsdev/core` loads (the automatic-navigation thesis).
+ * `{ "webjs": { "clientRouter": false } }` opts the WHOLE app out (pure MPA,
+ * full-page navigation), which the render path signals to the browser so the
+ * core bundle's module-end auto-enable is skipped. Any other value, or an
+ * absent key, keeps the router on. Re-read on every rebuild (alongside elide)
+ * so toggling it takes effect without a server restart.
+ * @param {string} appDir
+ * @returns {Promise<boolean>}
+ */
+export async function readClientRouterEnabled(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && pkg.webjs && pkg.webjs.clientRouter === false) return false;
+  } catch {
+    // No package.json, malformed JSON, or unreadable. Keep the default.
+  }
+  return true;
+}
+
+/**
+ * Read the per-path response-header config (`webjs.headers`) from the
+ * app's package.json and compile it to URLPattern rules. A missing,
+ * malformed, or unreadable config yields an empty rule set (the secure
+ * defaults still apply), never a throw.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof compileHeaderRules>>}
+ */
+export async function readHeaderRules(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return compileHeaderRules(pkg);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read the declarative redirect config (`webjs.redirects`) from the app's
+ * package.json and compile it to URLPattern rules (issue #254). A missing,
+ * malformed, or unreadable config yields an empty rule set (no redirects),
+ * never a throw. Patterns are compiled ONCE here at boot, not per request.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof compileRedirectRules>>}
+ */
+export async function readRedirectRules(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return compileRedirectRules(pkg);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read the trailing-slash policy (`webjs.trailingSlash`) from the app's
+ * package.json (issue #255). A missing, malformed, or unreadable config
+ * yields `'ignore'` (no canonicalization), never a throw, so an
+ * unconfigured app is unchanged.
+ *
+ * @param {string} appDir
+ * @returns {Promise<'never' | 'always' | 'ignore'>}
+ */
+export async function readTrailingSlashFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readTrailingSlashPolicy(pkg);
+  } catch {
+    return 'ignore';
+  }
+}
+
+/**
+ * Read the sub-path base path (`webjs.basePath`) from the app's
+ * package.json (issue #256). A missing, malformed, or unreadable config
+ * yields `''` (root mount), never a throw, so an unconfigured app is
+ * byte-identical to before this feature. Normalized to `''` or
+ * `/segment[/segment...]` by `readBasePath`.
+ *
+ * @param {string} appDir
+ * @returns {Promise<string>}
+ */
+export async function readBasePathFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readBasePath(pkg);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Read the app package.json and warn once about anything wrong with its `webjs`
+ * block (#1300). One aggregated warning, listing every problem, so a config with
+ * three typos does not produce three log lines.
+ *
+ * Never throws and never exits. See `webjs-config-validate.js` for why warning
+ * is the ruling and why this does not replace the CLI's `doctor.gate` check.
+ *
+ * @param {string} appDir
+ * @param {{ warn?: (...args: any[]) => void }} logger
+ * @returns {Promise<void>}
+ */
+export async function warnOnInvalidWebjsConfig(appDir, logger) {
+  let problems;
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    problems = validateAppWebjsConfig(pkg);
+  } catch {
+    return;
+  }
+  if (!problems.length) return;
+  logger?.warn?.(
+    `[webjs] the "webjs" block in package.json has ${problems.length} problem(s), ` +
+      `each ignored at its default: ${problems.join('; ')}. ` +
+      `See https://webjs.dev/docs/configuration`,
+  );
+}
+
+/**
+ * Read the cross-origin allowlist (`webjs.allowedOrigins`) from the app's
+ * package.json. These hosts / origins are accepted by the action CSRF check
+ * even when cross-site (reverse-proxy / multi-domain setups). A missing or
+ * unreadable config yields `[]`.
+ *
+ * @param {string} appDir
+ * @returns {Promise<string[]>}
+ */
+export async function readAllowedOriginsFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readAllowedOrigins(pkg);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read the CSP config (`webjs.csp`) from the app's package.json and
+ * normalize it (issue #233). A missing, malformed, or unreadable config
+ * yields a disabled config (no nonce minted, no CSP header), never a
+ * throw: a broken security knob must fail closed, not take the app down.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof readCspConfig>>}
+ */
+export async function readCspConfigFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readCspConfig(pkg);
+  } catch {
+    return readCspConfig(undefined);
+  }
+}
+
+/**
+ * Resolve the request body-size limits (issue #237) from the app's package.json
+ * `webjs.maxBodyBytes` / `webjs.maxMultipartBytes` plus the env overrides
+ * (`WEBJS_MAX_BODY_BYTES` / `WEBJS_MAX_MULTIPART_BYTES`). A missing or
+ * unreadable package.json falls through to the secure defaults (env still wins),
+ * never a throw.
+ *
+ * @param {string} appDir
+ * @returns {Promise<{ json: number, multipart: number }>}
+ */
+export async function readBodyLimitsFromApp(appDir) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    pkg = undefined;
+  }
+  return readBodyLimits(pkg);
+}
+
+/**
+ * Extra dev watch roots from the app's package.json `webjs.dev.watch` (#894).
+ * These are directories the app READS from but that live OUTSIDE its appDir, so
+ * the recursive `fs.watch(appDir)` never sees them (e.g. the website renders
+ * posts from a repo-root `blog/` dir, a sibling of the app, so editing a post
+ * would not live-reload). Each entry is resolved relative to the appDir and MAY
+ * escape it (`"../blog"`); a change under one runs the same rebuild + reload as
+ * an in-tree edit. Opt-in: a missing/empty config yields `[]`, so a plain app
+ * watches only its appDir, unchanged.
+ *
+ * Returns absolute, de-duped paths, skipping any that overlap the appDir (the
+ * appDir is already watched recursively, so an ancestor or descendant root
+ * would just double-fire the rebuild). Existence is NOT checked here (the caller
+ * filters missing paths so it can log them); the reader stays a pure
+ * package.json read, matching the other `readXFromApp` helpers.
+ *
+ * @param {string} appDir
+ * @returns {Promise<string[]>}
+ */
+export async function readDevWatchPathsFromApp(appDir) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    return [];
+  }
+  const raw = pkg && pkg.webjs && pkg.webjs.dev && pkg.webjs.dev.watch;
+  if (!Array.isArray(raw)) return [];
+  /** @type {string[]} */
+  const out = [];
+  const seen = new Set();
+  for (const entry of raw) {
+    if (typeof entry !== 'string' || !entry.trim()) continue;
+    const abs = resolve(appDir, entry);
+    // Skip the appDir itself and any ancestor/descendant overlap: the appDir is
+    // already watched recursively, so an overlapping extra root double-fires.
+    if (abs === appDir || appDir.startsWith(abs + sep) || abs.startsWith(appDir + sep)) continue;
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * Resolve the node:http server timeouts (issue #237) from the app's
+ * package.json `webjs.requestTimeoutMs` / `webjs.headersTimeoutMs` /
+ * `webjs.keepAliveTimeoutMs` plus the env overrides. A missing or unreadable
+ * package.json falls through to the secure defaults (env still wins).
+ *
+ * @param {string} appDir
+ * @returns {Promise<{ requestTimeout: number, headersTimeout: number, keepAliveTimeout: number }>}
+ */
+export async function readServerTimeoutsFromApp(appDir) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    pkg = undefined;
+  }
+  return computeServerTimeouts(pkg);
+}
+