@webjsdev/server 0.9.0 → 0.10.0

package/src/dev-reload-worker.js

@@ -67,13 +67,13 @@ export const RELOAD_MAX_HOLD_MS = 5000;
  * component edit is a component edit, and morphing it would leave the old
  * component class running against fresh markup.
  */
-export const VERDICT_STRENGTH = ['reload', 'shell', 'page'];
+export const VERDICT_STRENGTH = ['reload', 'shell', 'page', 'component', 'css'];
 
 /**
  * Resolve an SSE `reload` frame's `data` to a verdict name.
  *
  * ANY failure resolves to `reload`: an absent payload, malformed JSON, a
- * non-object, a `v` outside the three literals, or the legacy bare `data: now`.
+ * non-object, a `v` outside the known names, or the legacy bare `data: now`.
  * That is what makes the wire-format change safe in both directions between a
  * long-running browser tab and a restarted server, since the worst a skew can
  * produce is the full reload that was the behaviour before this existed.
@@ -89,6 +89,32 @@ export function parseVerdict(data) {
   return 'reload';
 }
 
+/**
+ * Resolve an SSE `reload` frame's `data` to the whole verdict the relay posts
+ * to a tab (#1689): `{ v, by, why, modules, css }`, every field always present
+ * so a tab never has to guess. The same fail-safe as `parseVerdict`: anything
+ * it cannot read is `{ v: 'reload', why: 'unreadable-frame' }`, and a field of
+ * the wrong type falls back to its empty value rather than failing the frame.
+ *
+ * @param {string} data
+ * @returns {{ v: string, by: string, why: string, modules: string[], css: boolean }}
+ */
+export function parseReloadFrame(data) {
+  try {
+    const o = JSON.parse(data);
+    if (o && typeof o === 'object' && VERDICT_STRENGTH.indexOf(o.v) !== -1) {
+      return {
+        v: o.v,
+        by: typeof o.by === 'string' ? o.by : '',
+        why: typeof o.why === 'string' ? o.why : '',
+        modules: Array.isArray(o.modules) ? o.modules.filter((m) => typeof m === 'string') : [],
+        css: o.css === true,
+      };
+    }
+  } catch (_) { /* fall through to the fail-safe */ }
+  return { v: 'reload', by: '', why: 'unreadable-frame', modules: [], css: false };
+}
+
 /** First reconnect wait after the stream drops (#1507), doubled per failure. */
 export const RECONNECT_BASE_MS = 300;
 /** The longest wait between reconnect attempts (#1507). */
@@ -209,8 +235,13 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
   /** @type {any} */ let quietTimer = null;
   /** @type {any} */ let capTimer = null;
 
-  /** @type {string} the strongest verdict seen in the CURRENT batch (#1398) */
-  let batchVerdict = 'page';
+  /**
+   * The CURRENT batch's merged verdict (#1398, #1689): the strongest `v` with
+   * its `by` / `why`, the union of every `modules` list and whether any frame
+   * set `css`. Null between batches.
+   * @type {{ v: string, by: string, why: string, modules: Set<string>, css: boolean } | null}
+   */
+  let batch = null;
   /** Whether the batch reloads every tab, or only the stale ones in `batchPorts` (#1516). */
   let batchAll = false;
   /** @type {Set<any>} tabs whose page fell behind, reloaded on their own */
@@ -221,9 +252,9 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
   function emitReload() {
     if (quietTimer !== null) { timers.clearTimeout(quietTimer); quietTimer = null; }
     if (capTimer !== null) { timers.clearTimeout(capTimer); capTimer = null; }
-    const v = batchVerdict;
-    batchVerdict = 'page';   // a fresh batch starts at the weakest verdict
-    const msg = { type: 'reload', verdict: v };
+    const b = batch || { v: 'reload', by: '', why: 'no-verdict', modules: new Set(), css: false };
+    batch = null;   // a fresh batch starts from nothing
+    const msg = { type: 'reload', verdict: { v: b.v, by: b.by, why: b.why, modules: Array.from(b.modules).sort(), css: b.css } };
     const targets = batchAll ? Array.from(ports.keys()) : Array.from(batchPorts).filter((p) => ports.has(p));
     batchAll = false;
     batchPorts.clear();
@@ -236,6 +267,9 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
     }
   }
 
+  /** The reload a tab gets when its page is behind the server (#1516). */
+  const PAGE_BEHIND = { v: 'reload', by: '', why: 'page-behind' };
+
   /** Strength rank; an unrecognised name ranks strongest, so it can only ever
    * over-reload. @param {string} v */
   function rank(v) {
@@ -244,12 +278,27 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
   }
 
   /**
-   * @param {string} verdict
+   * Fold one signal into the batch: the strongest `v` wins with its `by` /
+   * `why` (the earlier one on a tie), `modules` unions and `css` ORs, the same
+   * rule as `mergeVerdicts` on the server.
+   * @param {{ v: string, by?: string, why?: string, modules?: string[], css?: boolean }} verdict
+   */
+  function mergeIntoBatch(verdict) {
+    const v = VERDICT_STRENGTH[rank(verdict.v)];
+    if (batch === null) batch = { v, by: verdict.by || '', why: verdict.why || '', modules: new Set(), css: false };
+    else if (rank(v) < rank(batch.v)) { batch.v = v; batch.by = verdict.by || ''; batch.why = verdict.why || ''; }
+    if (verdict.modules) for (const m of verdict.modules) batch.modules.add(m);
+    if (verdict.css) batch.css = true;
+  }
+
+  /**
+   * @param {{ v: string, by?: string, why?: string, modules?: string[], css?: boolean }} verdict
    * @param {any} [port]  reload only this tab (its page fell behind); omitted, every tab
+   * @param {boolean} [inPlace]  the signal came from a server that reloads in place
    */
   function requestReload(verdict, port, inPlace) {
     if (port === undefined) batchAll = true; else batchPorts.add(port);
-    if (rank(verdict) < rank(batchVerdict)) batchVerdict = VERDICT_STRENGTH[rank(verdict)];
+    mergeIntoBatch(verdict);
     // One restart signal anywhere in the batch keeps the long window (#1575).
     if (!inPlace) batchRestart = true;
     if (quietTimer !== null) timers.clearTimeout(quietTimer);
@@ -278,7 +327,7 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
   // Reload every tab whose page is behind what the server reports now (#1516).
   function checkPages() {
     for (const [p, page] of pages) {
-      if (pageIsStale(page, lastBoot, lastSeq)) requestReload('reload', p);
+      if (pageIsStale(page, lastBoot, lastSeq)) requestReload(PAGE_BEHIND, p);
     }
   }
 
@@ -297,7 +346,7 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
       touch();
       const h = parseHello(e.data);
       if (lastBoot !== null && (h.boot !== lastBoot || (h.seq !== null && lastSeq !== null && h.seq !== lastSeq))) {
-        requestReload('reload');
+        requestReload({ v: 'reload', by: '', why: h.boot !== lastBoot ? 'server-restarted' : 'missed-update' });
       }
       lastBoot = h.boot;
       lastSeq = h.seq;
@@ -308,7 +357,7 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
       lastError = null;
       const n = reloadSeq(e.data);
       if (n !== null) lastSeq = n;
-      requestReload(parseVerdict(e.data), undefined, frameInPlace(e.data));
+      requestReload(parseReloadFrame(e.data), undefined, frameInPlace(e.data));
     });
     es.addEventListener('webjs-error', (e) => { lastError = e.data; fanout({ type: 'webjs-error', data: e.data }); });
     // The stream dropped (a restarting server, a network blip, a host that
@@ -348,7 +397,7 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
         // out reload catches up, and again on every hello.
         if (typeof d.boot === 'string') {
           pages.set(port, { boot: d.boot, seq: typeof d.seq === 'number' ? d.seq : null });
-          if (pageIsStale(pages.get(port), lastBoot, lastSeq)) requestReload('reload', port);
+          if (pageIsStale(pages.get(port), lastBoot, lastSeq)) requestReload(PAGE_BEHIND, port);
         }
         return;
       }

package/src/dev-secret.js

@@ -0,0 +1,73 @@
+/**
+ * A signing secret for development and tests when the app sets none (#1686),
+ * the way Rails keeps `tmp/local_secret.txt` and NextAuth v4 fell back to a
+ * generated secret outside production. `.env` is gitignored, so a fresh clone
+ * or a git worktree had no `AUTH_SECRET` / `SESSION_SECRET` and every page
+ * behind `session()` or `createAuth()` answered 500 until someone wrote one.
+ *
+ * The secret is generated once and kept in `.webjs/dev-secret` under the
+ * current directory (the app root for `webjs dev` and `webjs test`), which the
+ * scaffold's `.gitignore` already excludes, so sessions survive a restart.
+ *
+ * It is OPT-IN, and `NODE_ENV` alone decides ({@link devSecretApplies}): only
+ * `NODE_ENV=development` or `NODE_ENV=test` gets one (`webjs dev` and
+ * `webjs test` set them when unset). A process a test spawns inherits
+ * `NODE_ENV=test`, as under Jest, so it gets one too unless the test sets
+ * `NODE_ENV=production` on it.
+ * Anything else, a production `NODE_ENV` or none at all (an embedded host, a
+ * container running `node server.js`), gets undefined and the caller throws,
+ * so a production cookie is never signed with a key from disk because an env
+ * var was missing. It is read per call, never latched for the process, so a
+ * development handler created earlier in the same process opts nothing in.
+ *
+ * @module
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+
+const warned = new Set();
+
+/**
+ * Whether this process may use the generated development secret, decided
+ * from `NODE_ENV` alone on every call: `development` or `test`.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {boolean}
+ */
+export function devSecretApplies(env = process.env) {
+  return env.NODE_ENV === 'development' || env.NODE_ENV === 'test';
+}
+
+/**
+ * The development secret, created on first use, or undefined unless this is a
+ * development or test process.
+ * @param {string} name the variable the app left unset, named in the warning
+ * @param {{ dir?: string, env?: Record<string, string | undefined>, warn?: (msg: string) => void }} [opts]
+ * @returns {string | undefined}
+ */
+export function devSecret(name, opts = {}) {
+  const env = opts.env || process.env;
+  if (!devSecretApplies(env)) return undefined;
+  const file = join(opts.dir || process.cwd(), '.webjs', 'dev-secret');
+  let secret = '';
+  try {
+    if (existsSync(file)) secret = readFileSync(file, 'utf8').trim();
+  } catch {}
+  if (!secret) {
+    secret = randomBytes(32).toString('hex');
+    try {
+      mkdirSync(join(file, '..'), { recursive: true });
+      writeFileSync(file, secret + '\n', { mode: 0o600 });
+    } catch {
+      // A read-only directory still gets a secret, just one per process.
+    }
+  }
+  if (!warned.has(name)) {
+    warned.add(name);
+    (opts.warn || ((m) => console.warn(m)))(
+      `[webjs] ${name} is not set, so a generated development secret in .webjs/dev-secret signs the cookie. `
+      + `Set ${name} in .env for production, where it is required.`,
+    );
+  }
+  return secret;
+}

package/src/dev-source-locations-hook.js

@@ -28,6 +28,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { relative, isAbsolute } from 'node:path';
 import { serverRuntime } from './listener-core.js';
+import { rewriteAppSource } from './dev/bun-app-source.js';
 import {
   annotateSourceLocations,
   isSourceLocationCandidate,
@@ -128,7 +129,9 @@ export function registerSourceLocationHook(appDir) {
           try {
             contents = transformForSsr(abs, src) ?? src;
           } catch { /* fail open: the raw module */ }
-          return { contents, loader };
+          // The same alias rewrite and module versions the app-source plugin
+          // applies (#1689), which this plugin wins over while it is on.
+          return { contents: rewriteAppSource(contents, abs), loader };
         });
       },
     });

package/src/dev-source-locations.js

@@ -141,14 +141,33 @@ export function annotateSourceLocations(source, file) {
   }
 }
 
+/**
+ * The static strings of every `html` template in `src`, with the 1-based line
+ * each template starts on, for a check rule that inspects template markup
+ * (`no-jsx-attributes`). The strings are the raw source text between holes.
+ * Returns [] when the source cannot be lexed.
+ *
+ * @param {string} src
+ * @returns {{ strings: string[], line: number }[]}
+ */
+export function htmlTemplateStrings(src) {
+  if (typeof src !== 'string' || !src.includes('html')) return [];
+  /** @type {{ strings: string[], line: number }[]} */
+  const templates = [];
+  try { collectInserts(src, '', templates); } catch { return []; }
+  return templates;
+}
+
 /**
  * Lex `src` and return `[offset, text]` insertions, in ascending order.
  *
  * @param {string} src
  * @param {string} file
+ * @param {{ strings: string[], line: number }[]} [templates] when given,
+ *   each `html` template's static strings are collected here
  * @returns {Array<[number, string]>}
  */
-function collectInserts(src, file) {
+function collectInserts(src, file, templates) {
   /** @type {Array<[number, string]>} */
   const inserts = [];
   const n = src.length;
@@ -184,13 +203,19 @@ function collectInserts(src, file) {
       const c = src[i];
       if (c === '\\') {
         // An escape is static text the html machine sees as an opaque char.
+        if (html && html.record) html.record.strings[html.record.strings.length - 1] += src.slice(i, i + 2);
         if (html) html.feed(src, i, line);
         if (src[i + 1] === '\n') line++;
         i += 2;
         continue;
       }
       if (c === '`') { i++; return 'end'; }
-      if (c === '$' && src[i + 1] === '{') { i += 2; return 'hole'; }
+      if (c === '$' && src[i + 1] === '{') {
+        i += 2;
+        if (html && html.record) html.record.strings.push('');
+        return 'hole';
+      }
+      if (html && html.record) html.record.strings[html.record.strings.length - 1] += c;
       if (html) {
         const ins = html.feed(src, i, line);
         if (ins !== -1) inserts.push([ins, ` data-webjs-src="${file}:${line}"`]);
@@ -208,6 +233,10 @@ function collectInserts(src, file) {
   const enterTemplate = (isHtml) => {
     i++; // the backtick
     const html = isHtml ? new HtmlState() : null;
+    if (html && templates) {
+      html.record = { strings: [''], line };
+      templates.push(html.record);
+    }
     const r = scanTemplateText(html);
     if (r === 'hole') { stack.push({ kind: 'tpl', html }); prev = 'punct'; }
     else prev = 'str';
@@ -320,6 +349,8 @@ function collectInserts(src, file) {
  */
 class HtmlState {
   constructor() {
+    /** @type {{ strings: string[], line: number } | null} the template's static strings, when collected */
+    this.record = null;
     /** @type {'text' | 'tag' | 'dq' | 'sq' | 'comment' | 'raw'} */
     this.mode = 'text';
     /** Tag name of the tag being read (lowercased), '' for a close / bang tag. */

package/src/dev.js

@@ -4,7 +4,6 @@
  */
 
 export {
-  readElideEnabled,
   readSeedEnabled,
   readClientRouterEnabled,
   readHeaderRules,

package/src/env-files.js

@@ -0,0 +1,124 @@
+/**
+ * Load an app's `.env` files the way Next.js does, so a Next project's
+ * `.env.local` / `.env.development` / `.env.production` keep working.
+ *
+ * Order, highest precedence first (Next's `@next/env`):
+ *   1. the real environment (`process.env`, never overwritten)
+ *   2. `.env.$mode.local`
+ *   3. `.env.local` (skipped when mode is `test`, so tests are reproducible)
+ *   4. `.env.$mode`
+ *   5. `.env`
+ * where `$mode` is `development` under `webjs dev`, `production` under
+ * `webjs start`, and `test` when `NODE_ENV=test`.
+ *
+ * Files are read with `readFileSync` + `util.parseEnv`, so loading behaves the
+ * same on Node and Bun (`process.loadEnvFile`, which this replaces, does not
+ * exist on Bun, so a Bun app never saw its `.env`). A key is assigned only
+ * when still unset, which yields the precedence above.
+ *
+ * Values are expanded the way `@next/env` does with dotenv-expand: `$NAME`,
+ * `${NAME}` and `${NAME:-default}` (also `${NAME-default}`) resolve against the
+ * real environment and the files already loaded, then the same file's keys,
+ * else empty (or the default); `\$` is a literal dollar, and a single-quoted
+ * value is left as written.
+ *
+ * The CLI keeps a byte-identical copy (`packages/cli/lib/env-files.js`) because
+ * it must load env before the server package is imported (the port, the
+ * `webjs.*` tasks); `test/cli/env-files-parity.test.mjs` keeps them in step.
+ *
+ * @module env-files
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseEnv } from 'node:util';
+
+/**
+ * @param {string} mode `development` | `production` | `test`
+ * @returns {string[]} file names, highest precedence first
+ */
+export function envFileOrder(mode) {
+  return [`.env.${mode}.local`, ...(mode === 'test' ? [] : ['.env.local']), `.env.${mode}`, '.env'];
+}
+
+/**
+ * The env mode for a server run: `test` when NODE_ENV says so, else the run's
+ * own mode.
+ * @param {boolean} dev
+ * @returns {'development' | 'production' | 'test'}
+ */
+export function envMode(dev) {
+  if (process.env.NODE_ENV === 'test') return 'test';
+  return dev ? 'development' : 'production';
+}
+
+/**
+ * Load the app's env files into `process.env` (unset keys only).
+ * @param {string} appDir
+ * @param {string} mode
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]} the files that were found and read
+ */
+export function loadEnvFiles(appDir, mode, env = process.env) {
+  /** @type {string[]} */
+  const loaded = [];
+  for (const name of envFileOrder(mode)) {
+    let text;
+    try { text = readFileSync(join(appDir, name), 'utf8'); } catch { continue; }
+    let parsed;
+    try { parsed = parseEnv(text); } catch { continue; }
+    const literal = singleQuotedKeys(text);
+    /** @type {Record<string, string>} */
+    const done = {};
+    /** @type {Set<string>} */
+    const active = new Set();
+    /** @param {string} key @returns {string | undefined} undefined when unset */
+    const resolve = (key) => {
+      // Own keys only: ${toString} or $constructor names a variable, never an
+      // Object.prototype member, which would be a function here.
+      if (Object.hasOwn(env, key) && env[key] !== undefined) return env[key];
+      if (!Object.hasOwn(parsed, key)) return undefined;
+      if (Object.hasOwn(done, key)) return done[key];
+      if (active.has(key)) return ''; // a cycle expands to empty rather than looping
+      active.add(key);
+      const out = literal.has(key) ? parsed[key] : expandValue(parsed[key], resolve);
+      active.delete(key);
+      return (done[key] = out);
+    };
+    for (const k of Object.keys(parsed)) {
+      if (env[k] === undefined) env[k] = literal.has(k) ? parsed[k] : expandValue(parsed[k], resolve);
+    }
+    loaded.push(name);
+  }
+  return loaded;
+}
+
+/**
+ * Expand `$NAME`, `${NAME}`, `${NAME:-default}` and `${NAME-default}` in one
+ * value, with `\$` as a literal dollar (dotenv-expand's syntax). `:-` uses the
+ * default when NAME is unset or empty, `-` only when it is unset.
+ * @param {string} value
+ * @param {(key: string) => string | undefined} lookup undefined when unset
+ * @returns {string}
+ */
+export function expandValue(value, lookup) {
+  return value.replace(/\\\$|\$\{([A-Za-z_][A-Za-z0-9_]*)(?:(:?-)([^}]*))?\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (m, braced, op, fallback, bare) => {
+    if (m === '\\$') return '$';
+    const v = lookup(braced || bare);
+    if (op === ':-') return v === undefined || v === '' ? fallback : v;
+    if (op === '-') return v === undefined ? fallback : v;
+    return v ?? '';
+  });
+}
+
+/**
+ * The keys whose value is single-quoted in the file text, which dotenv-expand
+ * leaves unexpanded (`util.parseEnv` strips the quotes, so read them here).
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+function singleQuotedKeys(text) {
+  /** @type {Set<string>} */
+  const keys = new Set();
+  for (const m of text.matchAll(/^[ \t]*(?:export[ \t]+)?([A-Za-z_][A-Za-z0-9_.-]*)[ \t]*=[ \t]*'/gm)) keys.add(m[1]);
+  return keys;
+}

package/src/file-storage.js

@@ -28,7 +28,7 @@
  *     a limit; it only stays streaming.
  *   - **Traversal-safe keys.** Every key is resolved to an absolute path under
  *     `dir` and rejected if it escapes, using the same `resolve` +
- *     `startsWith(dir + sep)` containment guard the `/public/*` serve path uses
+ *     `startsWith(dir + sep)` containment guard the `public/` serve path uses
  *     in dev.js. A key with `..`, an absolute path, a leading slash, a NUL, or a
  *     backslash is rejected BEFORE any fs operation.
  *   - **S3-pluggability.** The interface operates on web-standard objects only
@@ -117,7 +117,7 @@ const SAFE_EXTENSIONS = new Set([
 /**
  * Validate a storage key and reject anything that could escape the root or is
  * otherwise unsafe. Throws on a bad key BEFORE any filesystem operation; this is
- * the security-critical seam. Mirrors the `/public/*` containment guard
+ * the security-critical seam. Mirrors the `public/` containment guard
  * (`resolve` + `startsWith(root + sep)`) in dev.js.
  *
  * Rejected: an empty / non-string key, a key with a NUL byte, an absolute path,