@webjsdev/server 0.8.34 → 0.8.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.34",
+  "version": "0.8.36",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/action-seed-bun.js

@@ -26,39 +26,73 @@
  * same module Bun would have loaded.
  */
 
+/** Bun's global install cache + node_modules: a dep, never an app file to rewrite. */
+const DEP_PATH_RE = /[\\/](?:node_modules|install[\\/]cache|\.bun)[\\/]/;
+
 /**
- * Install the `Bun.plugin` seed `onLoad`. Idempotency is the caller's
- * responsibility (`registerSeedHooks` guards on `_registered`).
+ * Install the webjs `Bun.plugin` `onLoad`. It carries two independent transforms
+ * on ONE handler (Bun `onLoad` is first-match-wins, so a second overlapping
+ * plugin would starve one of them):
+ *
+ *   - **Pin rewrite (#685)**, when `pinTransform` is supplied: rewrite bare
+ *     specifiers of declared deps to inline-versioned ones so Bun zero-install
+ *     fetches the pinned version, not latest. Applies to APP files only (a dep
+ *     in `node_modules` / the global cache is returned raw). This broadens the
+ *     filter to all JS/TS; without it the filter stays the cheap `*.server.*`
+ *     pre-screen.
+ *   - **Seed facade (#472)**, when `seedEnabled`: facet a `'use server'`
+ *     candidate into the SSR action-result seed facade, built from the
+ *     (already pin-rewritten) source.
+ *
+ * Idempotency is the caller's responsibility (`registerSeedHooks` guards on
+ * `_registered`).
  *
  * @param {{
  *   isSeedCandidate: (specifier: string) => boolean,
  *   buildSeedFacade: (origSpec: string, absPath: string, src: string) => (string | null),
  *   serverFileRe: RegExp,
+ *   seedEnabled?: boolean,
+ *   pinTransform?: ((src: string, loader: 'ts' | 'js') => string) | null,
  * }} helpers
  */
-export function installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe }) {
+export function installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe, seedEnabled = true, pinTransform = null }) {
+  // Pinning needs to see every app module's imports, so broaden the filter when
+  // it is active; otherwise keep the narrow `*.server.*` seed pre-screen.
+  const filter = pinTransform ? /\.m?[jt]s(\?|$)/ : serverFileRe;
   Bun.plugin({
-    name: 'webjs-action-seed',
+    name: 'webjs-onload',
     setup(build) {
-      // The filter is a cheap path pre-screen (`*.server.*`, optional query).
-      build.onLoad({ filter: serverFileRe }, async (args) => {
+      build.onLoad({ filter }, async (args) => {
         const absPath = args.path.split('?')[0];
         // `.ts` / `.mts` strip via the `ts` loader; `.js` / `.mjs` via `js`.
         const loader = /\.m?ts$/.test(absPath) ? 'ts' : 'js';
+        // A dependency (node_modules or Bun's global cache): never rewrite it
+        // (the app's package.json does not pin transitive deps; they follow from
+        // the pinned direct deps' own manifests). Return the raw source unchanged.
+        if (pinTransform && DEP_PATH_RE.test(absPath)) {
+          return { contents: await Bun.file(absPath).text(), loader };
+        }
         // Read the real source. A genuine read failure (missing file) propagates,
         // which Bun reports as a load error exactly as it would without the plugin.
-        const src = await Bun.file(absPath).text();
+        let src = await Bun.file(absPath).text();
+        // Pin rewrite. For a NON-`.server` module this is where its specifiers get
+        // pinned. A `.server` candidate's REAL module is pinned on its
+        // `?webjs-seed-orig` passthrough load (which re-enters this onLoad); the
+        // facade itself only reads export names, unaffected by the rewrite.
+        if (pinTransform) {
+          try { src = pinTransform(src, loader); } catch { /* fail-open: raw source */ }
+        }
         try {
           // Facet only a `'use server'` candidate (not the `?webjs-seed-orig`
           // passthrough); a non-candidate or a passthrough falls through to the
-          // raw source below.
-          if (isSeedCandidate(args.path)) {
+          // (possibly pin-rewritten) source below.
+          if (seedEnabled && isSeedCandidate(args.path)) {
             const source = buildSeedFacade(args.path, absPath, src);
             if (source != null) return { contents: source, loader: 'js' };
           }
         } catch {
-          // Fail-open: any faceting error serves the raw source (no seeding for
-          // this module), the Bun analog of the Node hook's `nextLoad` fallback.
+          // Fail-open: any faceting error serves the source (no seeding for this
+          // module), the Bun analog of the Node hook's `nextLoad` fallback.
         }
         return { contents: src, loader };
       });

package/src/action-seed.js

@@ -51,11 +51,13 @@
 import * as nodeModule from 'node:module';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { stringify } from '@webjsdev/core';
 import { hashFile } from './actions.js';
 import { isStreamable } from './action-stream.js';
 import { serverRuntime } from './listener-core.js';
+import { resolveDepVersions, rewriteDepSpecifiers } from './bun-pin-rewrite.js';
 
 /** Ambient per-render seed collector. `Map<key, value>` or undefined. */
 const als = new AsyncLocalStorage();
@@ -296,27 +298,66 @@ function seedLoadHook(url, context, nextLoad) {
 }
 
 /**
- * Install the seed load hook (idempotent). Called once at boot from `dev.js`
- * when seeding is enabled, BEFORE any action module is imported (a module loaded
- * before the hook would already be cached unwrapped). The install mechanism is
- * chosen by `serverRuntime()` (#529): Node's synchronous `module.registerHooks`,
- * or a `Bun.plugin` `onLoad` on Bun. A no-op on a second call. Async because the
- * Bun path dynamically imports `action-seed-bun.js` (so the `Bun.*` global is
- * never referenced on Node); the Node path resolves synchronously.
+ * Build the per-file pin transform for Bun (#685): read the app's declared dep
+ * versions (package.json, with `bun.lock` exact pins preferred) and return a
+ * function that rewrites a module's bare dep specifiers to inline-versioned ones
+ * so Bun zero-install fetches the pinned version, not latest. Returns null when
+ * there is nothing to pin (no package.json, or no declared deps). Bun-only: it
+ * references `Bun.Transpiler`, so it is invoked only on the Bun branch.
+ * @param {string} appDir
+ * @returns {((src: string, loader: 'ts' | 'js') => string) | null}
+ */
+function buildBunPinTransform(appDir) {
+  let pkgText;
+  try { pkgText = readFileSync(join(appDir, 'package.json'), 'utf8'); } catch { return null; }
+  let lockText = null;
+  try { lockText = readFileSync(join(appDir, 'bun.lock'), 'utf8'); } catch { /* optional */ }
+  const versions = resolveDepVersions(pkgText, lockText);
+  if (Object.keys(versions).length === 0) return null;
+  return (src, loader) => {
+    const imports = new Bun.Transpiler({ loader }).scanImports(src);
+    return rewriteDepSpecifiers(src, imports, versions);
+  };
+}
+
+/**
+ * Install the boot-time load hook(s) (idempotent). Called once from `dev.js`,
+ * BEFORE any app module is imported (a module loaded before the hook would
+ * already be cached untransformed). Two concerns ride here:
+ *
+ *   - **Seeding (#472)** when `seedEnabled`: facet `'use server'` modules into
+ *     the SSR action-result seed facade. Node uses `module.registerHooks`; Bun a
+ *     `Bun.plugin` `onLoad`.
+ *   - **Pinning (#685)** when `pinEnabled` (Bun only): rewrite bare dep
+ *     specifiers to the package.json/bun.lock version so zero-install fetches the
+ *     pinned version, not latest. Independent of seeding, so the Bun plugin is
+ *     installed when EITHER is on (they share the one first-match-wins onLoad).
+ *
+ * No-op on a second call. Async because the Bun path dynamically imports
+ * `action-seed-bun.js` (so the `Bun.*` global is never referenced on Node).
+ *
+ * @param {{ appDir?: string | null, seedEnabled?: boolean, pinEnabled?: boolean }} [opts]
  * @returns {Promise<void>}
  */
-export async function registerSeedHooks() {
+export async function registerSeedHooks({ appDir = null, seedEnabled = true, pinEnabled = false } = {}) {
   if (_registered) return;
   _registered = true;
 
   if (serverRuntime() === 'bun') {
-    // Bun has no module.registerHooks; install the same facade via Bun.plugin.
+    // Bun has no module.registerHooks; install the facade + pin rewrite via one
+    // Bun.plugin onLoad (first-match-wins, so the two transforms must share it).
     const { installBunSeedPlugin } = await import('./action-seed-bun.js');
-    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE });
-    _enabled = true;
+    const pinTransform = (pinEnabled && appDir) ? buildBunPinTransform(appDir) : null;
+    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE, seedEnabled, pinTransform });
+    if (seedEnabled) _enabled = true;
     return;
   }
 
+  // Node: seeding only (Bun-specific inline-version pinning does not apply; the
+  // Node zero-install resolve-hook is #669's separate concern). Nothing to
+  // install when seeding is off.
+  if (!seedEnabled) return;
+
   // A runtime that is neither Node-with-registerHooks nor Bun: seeding stays
   // OFF (fail-open). `seedingEnabled()` is false, ssr.js emits no seed block,
   // and the client RPC stub falls back to a normal fetch. Never wrong data.

package/src/bun-pin-rewrite.js

@@ -0,0 +1,152 @@
+/**
+ * Pin Bun zero-install dependency versions by rewriting bare import specifiers
+ * to inline-versioned ones (#685).
+ *
+ * Under Bun zero-install (`bun run dev` / `start` via the `webjs-bun.mjs`
+ * bootstrap, no `node_modules`), Bun's auto-install fetches `latest` for a bare
+ * `import 'zod'`, ignoring package.json and `bun.lock` (#684). But Bun honors an
+ * INLINE version in the specifier (`import 'zod@1.0.0'`), and that survives the
+ * `onResolve` bypass because it is part of the specifier the loader receives. So
+ * an `onLoad` transform that rewrites `import 'zod'` to `import 'zod@<pinned>'`
+ * (the version from package.json / `bun.lock`) makes auto-install fetch the
+ * pinned version. This module is the runtime-neutral, unit-testable core; the
+ * Bun `onLoad` glue (which supplies `Bun.Transpiler().scanImports` and the
+ * resolved dep versions) lives in the Bun-side plugin.
+ *
+ * The specifier set comes from `Bun.Transpiler.scanImports`, which is
+ * AST-accurate (a plain string that merely looks like a specifier is NOT
+ * listed), so we never rewrite a non-import string. The in-source replacement is
+ * additionally anchored on the `from` / `import` / `require` keyword so an
+ * identical non-import string literal elsewhere is left alone.
+ */
+
+/**
+ * Resolve the version to pin each DECLARED dependency to: the exact version from
+ * `bun.lock` when present (precise), else the package.json range/value as-is
+ * (Bun resolves a range in an inline specifier). Only declared deps are
+ * returned, so the rewrite never pins a transitive dep through an app import
+ * (those follow from the pinned direct deps' own manifests).
+ *
+ * Runtime-neutral: takes the two file contents (the Bun glue reads them via
+ * `Bun.file`), so this stays unit-testable on Node.
+ *
+ * @param {string} pkgJsonText  package.json contents
+ * @param {string | null} [bunLockText]  bun.lock contents, when present
+ * @returns {Record<string, string>}  package name -> version
+ */
+export function resolveDepVersions(pkgJsonText, bunLockText) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  let pkg;
+  try { pkg = JSON.parse(pkgJsonText); } catch { return out; }
+  const declared = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  // bun.lock pins each package as `"name": ["name@<exact>", ...]`. Extract the
+  // exact version for each DECLARED dep, anchored on its name so a substring
+  // match cannot cross to another package. This is the precise source.
+  /** @type {Record<string, string>} */
+  const lockExact = {};
+  if (bunLockText) {
+    for (const name of Object.keys(declared)) {
+      const esc = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const m = bunLockText.match(new RegExp('"' + esc + '"\\s*:\\s*\\[\\s*"' + esc + '@([^"]+)"'));
+      if (m && isExactVersion(m[1])) lockExact[name] = m[1];
+    }
+  }
+
+  for (const [name, range] of Object.entries(declared)) {
+    // ONLY an EXACT version can be an inline specifier: Bun zero-install
+    // auto-install resolves `name@1.2.3` but ENOENTs on a range or dist-tag
+    // (`name@^1.2`, `name@latest`) and on a protocol range (`workspace:`,
+    // `file:`, ...). So pin to the bun.lock exact when present, else an exact
+    // package.json pin; a range without a lock is left BARE (it resolves to
+    // latest, exactly as before this feature, never to a broken specifier).
+    if (lockExact[name]) out[name] = lockExact[name];
+    else if (isExactVersion(range)) out[name] = range;
+  }
+  return out;
+}
+
+/**
+ * Whether a version string is an EXACT semver (the only form valid as a Bun
+ * inline specifier): `1.2.3`, with an optional prerelease / build suffix
+ * (`1.2.3-rc.1`, `1.2.3+build`). Rejects any range operator (`^ ~ > < = * x | -`
+ * space), a dist-tag (`latest`), and a protocol range (`workspace:` etc.).
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+function isExactVersion(v) {
+  return typeof v === 'string' && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(v);
+}
+
+/**
+ * The npm package name a specifier belongs to: `@scope/name[/sub]` or
+ * `name[/sub]`. Returns null for a bare scope with no name.
+ * @param {string} p
+ * @returns {string | null}
+ */
+export function packageNameOf(p) {
+  if (p.startsWith('@')) {
+    const parts = p.split('/');
+    return parts.length >= 2 && parts[0] && parts[1] ? parts[0] + '/' + parts[1] : null;
+  }
+  return p.split('/')[0] || null;
+}
+
+/**
+ * Whether a specifier should be left untouched: relative, the `#` app alias, a
+ * protocol/builtin (`node:`, `bun:`, `http:`...), or already version-pinned.
+ * @param {string} p
+ * @param {string} name
+ * @returns {boolean}
+ */
+function skipSpecifier(p, name) {
+  if (!p || p[0] === '.' || p[0] === '#') return true;
+  // A protocol/builtin has a colon before any slash (node:fs, bun:sqlite, http:).
+  // A scope `@scope/x` has no leading colon, so it is not caught here.
+  const firstSlash = p.indexOf('/');
+  const head = firstSlash === -1 ? p : p.slice(0, firstSlash);
+  if (head.includes(':')) return true;
+  // Already versioned: the name is immediately followed by `@<something>`.
+  if (p.slice(name.length).startsWith('@')) return true;
+  return false;
+}
+
+/**
+ * Rewrite bare specifiers of DECLARED deps to `name@version` (keeping any
+ * subpath). `name` -> `name@v`, `name/sub` -> `name@v/sub`,
+ * `@scope/name/sub` -> `@scope/name@v/sub`.
+ *
+ * @param {string} src  module source
+ * @param {Array<{ kind: string, path: string }>} imports  Bun.Transpiler.scanImports output
+ * @param {Record<string, string>} depVersions  package name -> version (exact preferred, e.g. from bun.lock)
+ * @returns {string} the rewritten source (unchanged when nothing matched)
+ */
+export function rewriteDepSpecifiers(src, imports, depVersions) {
+  /** @type {Map<string, string>} specifier -> versioned specifier */
+  const remap = new Map();
+  for (const imp of imports) {
+    const p = imp && imp.path;
+    if (!p || remap.has(p)) continue;
+    const name = packageNameOf(p);
+    if (!name || skipSpecifier(p, name)) continue;
+    const ver = depVersions[name];
+    if (!ver) continue;
+    remap.set(p, name + '@' + ver + p.slice(name.length));
+  }
+  if (remap.size === 0) return src;
+
+  let out = src;
+  for (const [from, to] of remap) {
+    const q = from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Anchor on the import/export/require form so an identical non-import
+    // string literal is not touched: `from 'x'`, `import 'x'`, `import('x')`,
+    // `require('x')`. The optional `(` covers dynamic import / require. The
+    // leading `(^|[^\w.$])` boundary keeps a method call (`db.select().from('x')`,
+    // a `.import(...)` member) or a keyword-suffixed identifier (`xfrom 'x'`)
+    // from matching, which an unanchored keyword would wrongly rewrite.
+    const re = new RegExp("(^|[^\\w.$])((?:from|import|require)\\s*\\(?\\s*)(['\"])" + q + "\\3", 'g');
+    out = out.replace(re, (_m, pre, lead, quote) => pre + lead + quote + to + quote);
+  }
+  return out;
+}

package/src/check.js

@@ -77,12 +77,12 @@ export const RULES = [
   {
     name: 'no-static-properties',
     description:
-      'Reactive properties must be declared via the `extends WebComponent({ … })` factory, never a hand-written `static properties = { … }` field in the class body. The factory types each field for you (no `declare` needed) and the runtime throws on a direct `static properties`. Migrate `class X extends WebComponent { static properties = { count: { type: Number } } }` to `class X extends WebComponent({ count: Number })`; use the `prop()` helper for options (`prop(Number, { reflect: true })`) and set defaults via the `default` option or in the constructor.',
+      'Reactive properties must be declared via the `extends WebComponent({ … })` factory, never a hand-written `static properties = { … }` field in the class body. The factory types each field for you (no `declare` needed) and the runtime throws on a direct `static properties`. Migrate `class X extends WebComponent { static properties = { count: { type: Number } } }` to `class X extends WebComponent({ count: Number })`; use the `prop()` helper for options (`prop(Number, { reflect: true })`) and set defaults in the constructor after super().',
   },
   {
     name: 'reactive-props-no-class-field',
     description:
-      'A reactive property declared via the `extends WebComponent({ … })` factory must NOT also have a plain class-field initializer (`count = 0` or `count: number = 0`) in the class body. Under modern class-field semantics that initializer runs Object.defineProperty *after* super(), clobbering the framework\'s reactive accessor and silently breaking re-renders. Set the default via the `default` property option (`prop(Number, { default: 0 })`) or by assigning in the constructor after super().',
+      'A reactive property declared via the `extends WebComponent({ … })` factory must NOT also have a plain class-field initializer (`count = 0` or `count: number = 0`) in the class body. Under modern class-field semantics that initializer runs Object.defineProperty *after* super(), clobbering the framework\'s reactive accessor and silently breaking re-renders. Set the default by assigning in the constructor after super().',
   },
   {
     name: 'array-prop-uses-array-type',
@@ -451,7 +451,7 @@ export async function checkConventions(appDir) {
           file: rel,
           message:
             '`static properties = { … }` is no longer supported; declare reactive properties via the `extends WebComponent({ … })` factory instead.',
-          fix: 'Move the properties into the factory call: `class X extends WebComponent({ count: Number })`. Use `prop(Number, { reflect: true })` for options and set defaults via the `default` option or the constructor. Delete the `static properties` block and any `declare` fields for those props.',
+          fix: 'Move the properties into the factory call: `class X extends WebComponent({ count: Number })`. Use `prop(Number, { reflect: true })` for options and set defaults in the constructor after super(). Delete the `static properties` block and any `declare` fields for those props.',
         });
       }
     }
@@ -471,7 +471,7 @@ export async function checkConventions(appDir) {
             rule: 'reactive-props-no-class-field',
             file: rel,
             message: `Reactive prop \`${bad}\` uses a class-field initializer; this clobbers the framework's reactive accessor under modern class-field semantics.`,
-            fix: `Remove the class-field initializer and set the default via the \`default\` option (\`prop(<Type>, { default: <value> })\`) or by assigning \`this.${bad} = <value>\` inside \`constructor()\` after \`super()\`.`,
+            fix: `Remove the class-field initializer and set the default by assigning \`this.${bad} = <value>\` inside \`constructor()\` after \`super()\`.`,
           });
         }
       }

package/src/dev.js

@@ -268,6 +268,32 @@ export async function readSeedEnabled(appDir) {
   return true;
 }
 
+/**
+ * Read the Bun zero-install version-pinning switch (#685). The `WEBJS_PIN` env
+ * override wins (same grammar as `WEBJS_SEED`), otherwise
+ * `{ "webjs": { "pin": false } }` disables it. Default ON (opt-out). Consulted
+ * only on Bun: the rewrite injects inline-version specifiers that Bun's
+ * auto-install honors so zero-install fetches the pinned version, not latest
+ * (#684). Node zero-install pinning is #669's separate concern.
+ * @param {string} appDir
+ * @returns {Promise<boolean>}
+ */
+export async function readPinEnabled(appDir) {
+  const raw = process.env.WEBJS_PIN;
+  if (raw != null && raw !== '') {
+    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;
+  }
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && pkg.webjs && pkg.webjs.pin === 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
@@ -568,7 +594,11 @@ export async function createRequestHandler(opts) {
   // Read once (not per-rebuild): the hook is global and cannot be cleanly
   // un-installed, so toggling needs a restart. Disabled -> no hook, no ambient
   // collector wrap in ssr.js, and module loading stays byte-identical.
-  if (await readSeedEnabled(appDir)) await registerSeedHooks();
+  // Pinning (#685) is Bun-only and independent of seeding, so install the hook
+  // when EITHER is on (on Bun they share one onLoad).
+  const seedEnabled = await readSeedEnabled(appDir);
+  const pinEnabled = serverRuntime() === 'bun' && await readPinEnabled(appDir);
+  if (seedEnabled || pinEnabled) await registerSeedHooks({ appDir, seedEnabled, pinEnabled });
 
   // When an app commits a vendor pin (.webjs/vendor/importmap.json) it carries a
   // deterministic vendor map that is cheap to read (one file, no analysis, no

package/src/vendor.js

@@ -412,7 +412,7 @@ async function jspmCall(installs, provider) {
       // A 5xx/429 is a transient jspm problem worth retrying. A 401/4xx
       // means at least one install is genuinely unresolvable (jspm uses
       // 401 for that): a private / workspace / server-only package (e.g.
-      // @webjsdev/server, better-sqlite3) the browser never fetches
+      // @webjsdev/server, pg) the browser never fetches
       // anyway. Permanent failures must NOT block readiness.
       const transient = response.status >= 500 || response.status === 429;
       return { ok: false, imports: {}, transient };

package/webjs-config.schema.json

@@ -17,6 +17,11 @@
       "type": "boolean",
       "default": true
     },
+    "pin": {
+      "description": "Bun zero-install dependency version-pinning switch (#685). Default true, Bun only. When on, an onLoad transform rewrites a declared dep's bare import specifier to its package.json / bun.lock version so Bun auto-install fetches the pinned version instead of latest (#684). Set to false to leave specifiers bare (zero-install resolves to latest). Read by readPinEnabled in dev.js; the WEBJS_PIN env override wins over this. No effect on Node.",
+      "type": "boolean",
+      "default": true
+    },
     "clientRouter": {
       "description": "Client-router switch (#629). Default true: the client router auto-enables in the browser whenever @webjsdev/core loads, so any page with a component gets SPA-style navigation with no import. Set to false to opt the whole app out (pure MPA, full-page navigation). Read by readClientRouterEnabled in dev.js.",
       "type": "boolean",