@webjsdev/server 0.8.30 → 0.8.31

package/package.json

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

package/src/asset-hash.js

@@ -39,9 +39,9 @@
 
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { extname, join, resolve, sep } from 'node:path';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { redactStringsAndTemplates } from './js-scan.js';
-import { resolveImport } from './module-graph.js';
+import { resolveImport, expandImportAlias } from './module-graph.js';
 
 /**
  * Length of the emitted hex hash. 12 hex chars (48 bits) is plenty to
@@ -306,6 +306,24 @@ const JS_SPEC_EXTS = new Set(['.js', '.mjs', '.jsx', '.cjs']);
  * @param {string} abs   the resolved absolute file path
  * @returns {string}
  */
+/**
+ * A base-path-safe relative specifier from the importing module to a resolved
+ * target file, used to rewrite a `#`-alias import in served source (#555). The
+ * browser resolves a relative specifier against the importer's own URL (already
+ * base-path-prefixed), so the result needs no importmap and no basePath fix-up,
+ * and it carries the `?v` the caller appends. Uses the resolved file's actual
+ * extension (so no `normalizeSpecToResolved` pass is needed).
+ *
+ * @param {string} importerAbs  absolute path of the module being served
+ * @param {string} abs          resolved absolute path of the import target
+ * @returns {string}
+ */
+function relativeSpecifier(importerAbs, abs) {
+  let rel = relative(dirname(importerAbs), abs).split(sep).join('/');
+  if (!rel.startsWith('.')) rel = './' + rel;
+  return rel;
+}
+
 function normalizeSpecToResolved(spec, abs) {
   const absExt = extname(abs);
   if (!absExt) return spec;
@@ -391,9 +409,15 @@ export function versionModuleImports(source, importerAbs) {
       // inside a string / template / comment and is not a real import edge.
       if (masked[/** @type {number} */ (m.index)] === ' ') continue;
       const spec = m[2];
-      // Only `./` `../` relative specifiers (base-path-correct, the app pattern).
-      // Bare -> importmap target; `/`-absolute -> pre-existing basePath gap.
-      if (spec[0] !== '.') continue;
+      const isRelative = spec[0] === '.';
+      // A `#`-style subpath alias (#555) is rewritten to a base-path-safe
+      // RELATIVE specifier below (so it carries `?v` and matches the preload,
+      // exactly like a relative import). Only `./`/`../` relatives and
+      // app-imports aliases qualify: a bare specifier is importmap-resolved and
+      // versioned at its target; a `/`-root-absolute specifier would miss the
+      // basePath prefix.
+      const isAlias = !isRelative && expandImportAlias(spec, _appDir) !== null;
+      if (!isRelative && !isAlias) continue;
       if (spec.includes('?')) continue;
       const abs = resolveImport(spec, importerAbs, _appDir);
       if (!abs || SERVER_FILE_RE.test(abs)) continue;
@@ -402,9 +426,14 @@ export function versionModuleImports(source, importerAbs) {
       if (!hash) continue;
       // `/d` flag: indices[2] is [start, end] of the specifier CONTENT (no
       // quotes). Replace it with the resolved-extension form + `?v` so the
-      // fetched URL is byte-identical to the preload href.
+      // fetched URL is byte-identical to the preload href. An alias is emitted
+      // as a relative specifier to the resolved file (the browser resolves it
+      // against the importer's already-prefixed URL, so it stays base-path-safe
+      // without the importmap, and the `?v` collapses fetch + preload to one
+      // immutable cache key).
       const [start, end] = /** @type {[number, number]} */ (m.indices[2]);
-      edits.push({ start, end, text: `${normalizeSpecToResolved(spec, abs)}?v=${hash}` });
+      const versioned = isAlias ? relativeSpecifier(importerAbs, abs) : normalizeSpecToResolved(spec, abs);
+      edits.push({ start, end, text: `${versioned}?v=${hash}` });
     }
   }
   if (edits.length === 0) return source;

package/src/dev.js

@@ -1,6 +1,6 @@
 import { createServer as createHttp1Server } from 'node:http';
 import { stat, readFile, watch as fsWatch } from 'node:fs/promises';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, extname, resolve, dirname, relative, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -45,7 +45,7 @@ import {
   varyWithAcceptEncoding,
 } from './listener-core.js';
 import { scanBareImports, resolveVendorImports, serveDownloadedBundle, clearVendorCache, hasVendorPin, readPinFile, prunePinToReachable } from './vendor.js';
-import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport } from './module-graph.js';
+import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport, appImportsMap } from './module-graph.js';
 import { primeComponentRegistry, findOrphanComponents, scanComponents } from './component-scanner.js';
 import { analyzeElision, elideImportsFromSource } from './component-elision.js';
 
@@ -85,7 +85,7 @@ function resolveRequestId(req) {
 function shouldAccessLog(pathname) {
   return !pathname.startsWith('/__webjs/');
 }
-import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath } from './importmap.js';
+import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath, setImportAliasEntries, importAliasBrowserEntries } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
@@ -493,6 +493,16 @@ export async function createRequestHandler(opts) {
     existsSync(join(distDir, 'webjs-core-browser.js'));
   await setCoreInstall(coreDir, distComplete);
 
+  // Path-alias imports (#555). Emit the browser importmap scopes for the app's
+  // `package.json "imports"` aliases, derived from the SAME map the server
+  // resolver (`expandImportAlias`) reads, so SSR and the browser agree. The
+  // scaffold ships the single catch-all `"#*": "./*"` (one key, zero
+  // maintenance, Bun-safe), which expands to one browser prefix scope per
+  // top-level dir (`#lib/` -> `/lib/`, ...); the dir scan is here so a new
+  // folder is picked up on boot. An app with no `"imports"` block yields {}
+  // (a no-op, byte-identical to before this feature).
+  await setImportAliasEntries(importAliasBrowserEntries(appImportsMap(appDir), appTopLevelDirs(appDir)));
+
   // Content-hash asset URLs for immutable caching (issue #243). Bind the
   // asset-hash module to the app + core roots and enable fingerprinting in
   // PROD only. In dev `withAssetHash` stays a pure no-op (never enabled), so
@@ -2361,6 +2371,26 @@ function computeBrowserBoundFiles(routeTable, moduleGraph, components, appDir) {
   return reachableFromEntries(moduleGraph, [...entries], appDir);
 }
 
+/**
+ * List the app's top-level source directory names, for expanding a `#*`
+ * catch-all import alias into one browser importmap prefix scope per dir (#555).
+ * Excludes infra dirs that are never imported via `#` (node_modules, dotfiles,
+ * the build/vendor caches). A new top-level folder is picked up on the next boot
+ * (dev restarts on changes), so the alias stays zero-maintenance.
+ * @param {string} appDir
+ * @returns {string[]}
+ */
+function appTopLevelDirs(appDir) {
+  const SKIP = new Set(['node_modules', 'dist', 'public']);
+  try {
+    return readdirSync(appDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !SKIP.has(e.name))
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Find the absolute directory of the `@webjsdev/core` package, regardless of
  * whether we're running from the monorepo or an installed copy.

package/src/importmap.js

@@ -28,6 +28,17 @@ function escapeAttr(s) {
 /** @type {Record<string, string>} */
 let _extraEntries = {};
 
+/**
+ * Browser importmap entries for the app's `package.json "imports"` subpath
+ * aliases (#555), e.g. `{ "#lib/": "/lib/" }` for `"#lib/*": "./lib/*"`. Kept in lockstep
+ * with the server-side resolver (`module-graph.js`'s `expandImportAlias`):
+ * BOTH are derived from the one `"imports"` map, so an alias that resolves in
+ * SSR never 404s in the browser (the #158/#159 preload-mismatch class). Set at
+ * boot by `dev.js` via `setImportAliasEntries`.
+ * @type {Record<string, string>}
+ */
+let _aliasEntries = {};
+
 /**
  * The normalized `webjs.basePath` for a sub-path deployment (issue #256),
  * `''` (the default) for a root mount. When non-empty, every same-origin
@@ -67,6 +78,65 @@ export function basePath() {
   return _basePath;
 }
 
+/**
+ * Derive the BROWSER importmap entries for an app's `package.json "imports"`
+ * subpath-alias map (#555). The scaffold ships a single root catch-all key
+ * `"#*": "./*"` (one key, zero maintenance: a new top-level folder is aliased
+ * with no config change, and `#*` resolves natively on Node AND Bun, unlike a
+ * `#/`-prefixed key which Bun rejects). A browser importmap needs a
+ * trailing-slash PREFIX key to match, and a bare `#` is not one, so a catch-all
+ * is expanded into one prefix scope PER top-level directory (`topLevelDirs`):
+ * `#lib/` -> `/lib/`, `#components/` -> `/components/`, etc. The dirs are scanned
+ * by the caller (dev.js) so this stays pure; a new folder produces a new scope
+ * on the next boot. A non-catch-all key is mapped directly: a per-dir wildcard
+ * `"#lib/*": "./lib/*"` becomes `"#lib/": "/lib/"`, an exact `"#db": "./x.ts"`
+ * becomes `"#db": "/x.ts"`. The leading `./` becomes a root-absolute `/` and the
+ * `*` is dropped (the trailing slash carries the prefix match). A non-default
+ * base (`"#*": "./src/*"`) folds into the emitted URL. Only string targets are
+ * mappable (a conditional-export object is skipped). Derived from the SAME map
+ * the server resolver reads, so SSR and the browser agree.
+ *
+ * @param {Record<string, unknown> | null | undefined} importsMap
+ * @param {string[]} [topLevelDirs]  app top-level dir names, for expanding a `#*` catch-all
+ * @returns {Record<string, string>}
+ */
+export function importAliasBrowserEntries(importsMap, topLevelDirs = []) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  if (!importsMap || typeof importsMap !== 'object') return out;
+  for (const [key, value] of Object.entries(importsMap)) {
+    if (typeof value !== 'string') continue;
+    if (!value.startsWith('./')) continue; // only app-root-relative targets map to a URL
+    const star = key.indexOf('*');
+    if (star !== -1 && key.slice(0, star) === '#') {
+      // Root catch-all `#*` -> `./<base>*`: expand to a prefix scope per dir.
+      // base is the part of the value between `.` and `*` (`'' ` for `./*`,
+      // `/src/` for `./src/*`), so `#<dir>/` -> `/<base><dir>/`.
+      const base = value.slice(1, value.lastIndexOf('*')); // './*' -> '/', './src/*' -> '/src/'
+      for (const dir of topLevelDirs) out[`#${dir}/`] = `${base}${dir}/`;
+      continue;
+    }
+    // Per-dir wildcard or exact key: map directly.
+    out[key.replace('*', '')] = value.replace(/^\./, '').replace('*', '');
+  }
+  return out;
+}
+
+/**
+ * Bind the browser importmap to the app's `package.json "imports"` aliases
+ * (#555). Called once at boot by `dev.js`, derived from the SAME `"imports"`
+ * map the server resolver reads, so SSR and the browser agree. The hash is
+ * recomputed eagerly (like `setBasePath` / `setCoreInstall`) so
+ * `importMapHash()` stays synchronous on the per-request path.
+ *
+ * @param {Record<string, string>} entries  browser entries from `importAliasBrowserEntries`
+ * @returns {Promise<void>}
+ */
+export async function setImportAliasEntries(entries) {
+  _aliasEntries = entries && typeof entries === 'object' ? entries : {};
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap({ fingerprint: false })));
+}
+
 /**
  * SRI integrity hashes keyed by FINAL URL (post-importmap-rewrite).
  * Populated only when a pin file with `integrity` is present;
@@ -338,6 +408,7 @@ export function buildImportMap(opts = {}) {
   const merged = {
     ..._coreEntries,
     ..._extraEntries,
+    ..._aliasEntries,
   };
   // Sort keys so logically-identical importmaps serialize byte-for-byte
   // identically. The client router compares textContent to detect

package/src/module-graph.js

@@ -12,10 +12,71 @@
  */
 
 import { readFile, readdir, stat } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve, dirname, extname, sep } from 'node:path';
 import { redactStringsAndTemplates } from './js-scan.js';
 
+/**
+ * Per-appDir cache of the parsed `package.json "imports"` subpath-alias map
+ * (#555). `null` means "no imports block" (the common case for an app that
+ * does not use the `#` alias). Read once per appDir; cleared with the parse
+ * cache on rebuild.
+ * @type {Map<string, Record<string,string> | null>}
+ */
+const IMPORTS_CACHE = new Map();
+
+/**
+ * Read an app's `package.json "imports"` subpath-import map (Node's native
+ * import-alias mechanism). Cached per appDir.
+ * @param {string} appDir
+ * @returns {Record<string,string> | null}
+ */
+export function appImportsMap(appDir) {
+  if (IMPORTS_CACHE.has(appDir)) return IMPORTS_CACHE.get(appDir) ?? null;
+  let map = null;
+  try {
+    const pkg = JSON.parse(readFileSync(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && typeof pkg.imports === 'object' && pkg.imports) map = pkg.imports;
+  } catch { /* no package.json / unparseable: no aliases */ }
+  IMPORTS_CACHE.set(appDir, map);
+  return map;
+}
+
+/**
+ * Expand a `package.json "imports"` subpath alias (e.g. `#lib/db.server.ts`
+ * with the scaffold's catch-all `"#*": "./*"`) to its real APP-RELATIVE target
+ * string (`./lib/db.server.ts`).
+ * The security-critical seam (#555): the graph walker, auth gate, elision, and
+ * `no-server-import-in-browser-module` all route through `resolveImport`, so
+ * expanding the alias here (to the real path) is what stops an alias from
+ * laundering a `.server.ts` past those checks. Driven off the actual `"imports"`
+ * map so a non-default base (`"#lib/*": "./src/lib/*"`) is honored; never
+ * hardcodes `./`. Supports one trailing `*` wildcard per key (Node's rule) plus
+ * exact keys. (A `#/`-prefixed key is avoided in the scaffold because Bun's
+ * native resolver rejects it; the expansion here is key-shape-agnostic.)
+ * @param {string} spec  the import specifier, e.g. `'#lib/db.server.ts'`
+ * @param {string} appDir
+ * @returns {string | null}  the app-relative target (e.g. `'./lib/db.server.ts'`), or null if no alias matches
+ */
+export function expandImportAlias(spec, appDir) {
+  const map = appImportsMap(appDir);
+  if (!map) return null;
+  for (const [key, value] of Object.entries(map)) {
+    if (typeof value !== 'string') continue; // conditional-export objects are not graph-resolvable
+    const star = key.indexOf('*');
+    if (star === -1) {
+      if (spec === key) return value;
+      continue;
+    }
+    const prefix = key.slice(0, star);
+    const suffix = key.slice(star + 1);
+    if (!spec.startsWith(prefix) || !spec.endsWith(suffix)) continue;
+    const middle = spec.slice(prefix.length, spec.length - suffix.length);
+    return value.replace('*', middle);
+  }
+  return null;
+}
+
 /** @type {RegExp} match static `import … from '…'` and `import '…'` */
 const IMPORT_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/g;
 
@@ -52,6 +113,9 @@ const EXPORT_FROM_RE = /\bexport\b[^'";]+?\sfrom\s+['"]([^'"]+)['"]/g;
  * @returns {Promise<ModuleGraph>}
  */
 export async function buildModuleGraph(appDir) {
+  // Re-read the app's `package.json "imports"` each build so an edit to the
+  // alias map (#555) is picked up on rebuild.
+  IMPORTS_CACHE.delete(appDir);
   /** @type {ModuleGraph} */
   const graph = new Map();
   /** @type {Set<string>} every file walked this build (graph holds only files
@@ -286,8 +350,11 @@ async function parseFile(file, appDir, graph, seen) {
       // and is not a real import edge.
       if (masked[m.index] === ' ') continue;
       const spec = m[1];
-      // Only resolve relative imports within the project.
-      if (!spec.startsWith('.') && !spec.startsWith('/')) continue;
+      // Only resolve relative imports + `#`-style subpath aliases (#555)
+      // within the project. A bare npm specifier (dayjs) has no alias match
+      // and is skipped; an aliased `#lib/x.server.ts` IS followed so the
+      // graph / auth gate / elision see the real path through the alias.
+      if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) continue;
       const resolved = resolveImport(spec, file, appDir);
       if (resolved) deps.add(resolved);
     }
@@ -308,7 +375,13 @@ async function parseFile(file, appDir, graph, seen) {
 export function resolveImport(spec, fromFile, appDir) {
   const base = dirname(fromFile);
   let target;
-  if (spec.startsWith('/')) {
+  const aliased = expandImportAlias(spec, appDir);
+  if (aliased) {
+    // `#`-style subpath alias (#555): the app-relative target is resolved
+    // against the app root, then run through the same extension fallback below
+    // so the boundary / elision / preload all see the real on-disk path.
+    target = resolve(appDir, aliased);
+  } else if (spec.startsWith('/')) {
     // Absolute from app root (how browser sees it)
     target = join(appDir, spec);
   } else {