@webjsdev/server 0.8.29 → 0.8.31

package/package.json

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

package/src/actions.js

@@ -150,7 +150,7 @@ async function rpcResponse(payload, init = {}) {
  * module (the hash index is all the analysis needs; a module is imported on
  * demand by `invokeAction` / `serveActionStub`), so it is safe for a read-only
  * introspection caller (the MCP `list_actions` tool, #262) with no top-level
- * side effects (Prisma init, DB connect).
+ * side effects (DB driver init, DB connect).
  *
  * @param {string} appDir
  * @param {boolean} dev
@@ -181,7 +181,7 @@ export async function buildActionIndex(appDir, dev) {
     // Pure-RPC actions are NOT executed at boot: invokeAction and
     // serveActionStub import the module on demand (first RPC call / first stub
     // fetch), so the hash index above is all the analysis needs. Eagerly
-    // running every server module (and its transitive Prisma init, DB
+    // running every server module (and its transitive DB driver init, DB
     // connects, etc.) would be wasted work.
   }
 

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/cache-fn.js

@@ -8,7 +8,7 @@
  * import { cache } from '@webjsdev/server';
  *
  * export const listPosts = cache(
- *   async () => prisma.post.findMany({ orderBy: { createdAt: 'desc' } }),
+ *   async () => db.query.posts.findMany({ orderBy: { createdAt: 'desc' } }),
  *   { key: 'posts', ttl: 60 }
  * );
  *
@@ -107,7 +107,7 @@ export function cache(fn, opts) {
    *
    * ```js
    * export async function createPost(input) {
-   *   await prisma.post.create({ data: input });
+   *   await db.insert(posts).values(input);
    *   await listPosts.invalidate();
    * }
    * ```

package/src/cache-tags.js

@@ -104,7 +104,7 @@ export async function addKeyToTags(tags, cacheKey, ttlMs) {
  * 'use server';
  * import { revalidateTag } from '@webjsdev/server';
  * export async function createComment(input) {
- *   await prisma.comment.create({ data: input });
+ *   await db.insert(comments).values(input);
  *   await revalidateTag('post:' + input.postId); // postById(postId) recomputes
  *   return { success: true };
  * }

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
@@ -1353,16 +1363,18 @@ export async function createRequestHandler(opts) {
  * artefact dir (the #258 routes.d.ts and the vendor pin) that the dev server
  * itself writes on startup and on every rebuild, so without this skip the
  * write fires a watch event, triggers a rebuild, re-writes the file, and loops
- * forever. `prisma/dev*` / `prisma/migrations` churn during db:migrate. The
- * prisma branch is prefix-only (no trailing separator) so the SQLite sidecars
- * `prisma/dev.db` / `prisma/dev.db-journal` match too; the others stay
+ * forever. `db/dev.db*` (the SQLite file + sidecars) and `db/migrations`
+ * (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
  * 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)(?:[\\/]|$)|(?:^|[\\/])prisma[\\/](?:dev|migrations)/.test(filename || '');
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(filename || '');
 }
 
 /**
@@ -1414,7 +1426,7 @@ export async function startServer(opts) {
     //
     // fs.watch returns relative paths in event.filename. `shouldIgnoreWatchPath`
     // (module-level, exported for tests) skips node_modules, .git, .webjs/, and
-    // prisma's dev artefacts so a file the dev server itself writes never loops.
+    // the SQLite dev DB (db/dev.db) + db/migrations so a file the dev server itself writes never loops.
     const rebuild = debounce(() => app.rebuild(), 80);
     watcherAbort = new AbortController();
     (async () => {
@@ -2359,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/env-schema.js

@@ -3,7 +3,7 @@
  *
  * webjs auto-loads `<appDir>/.env` into `process.env` at boot, but does no
  * validation, so a missing or misconfigured required var (DATABASE_URL,
- * AUTH_SECRET, ...) fails late and cryptically (a Prisma connect error
+ * AUTH_SECRET, ...) fails late and cryptically (a database connect error
  * mid-request, an undefined secret signing a token). This module adds an
  * optional boot-time validation hook that fails fast with one clear message
  * listing EVERY missing or invalid var at once, before the app serves a

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/json.js

@@ -9,7 +9,7 @@ import { readTextBounded, BodyLimitError, DEFAULT_MAX_BODY_BYTES } from './body-
  *   // GET /api/posts
  *   import { json } from '@webjsdev/server';
  *   export async function GET() {
- *     return json(await listPosts());   // plain Prisma rows with Date columns
+ *     return json(await listPosts());   // plain Drizzle rows with Date columns
  *   }
  *
  * The helper reads the in-flight Request from the AsyncLocalStorage

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 {

package/src/vendor.js

@@ -409,7 +409,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, @prisma/client) the browser never fetches
+      // @webjsdev/server, better-sqlite3) 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

@@ -2,8 +2,8 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://webjs.dev/schemas/webjs-config.schema.json",
   "title": "webjs config block",
-  "description": "Schema for the `webjs` object in a webjs app's package.json. Each key maps to a documented server reader. An unknown key is flagged (additionalProperties is false) so a typo no longer silently falls back to the default.",
-  "$comment": "Single source of truth lives in THREE co-located places that must stay in lockstep: this schema, the TS type at packages/core/src/webjs-config.d.ts, and the server reader functions (readElideEnabled in dev.js, readSeedEnabled in dev.js, compileHeaderRules in headers.js, compileRedirectRules / readTrailingSlashPolicy in redirects.js, readBasePath in base-path.js, readCspConfig in csp.js, readBodyLimits / computeServerTimeouts in body-limit.js). Adding a webjs.* key means updating all three. See packages/server/AGENTS.md for the one documented procedure.",
+  "description": "Schema for the `webjs` object in a webjs app's package.json. Each key maps to a documented reader (a server reader, or for `dev`/`start` the CLI's readAppTasks). An unknown key is flagged (additionalProperties is false) so a typo no longer silently falls back to the default.",
+  "$comment": "Single source of truth lives in THREE co-located places that must stay in lockstep: this schema, the TS type at packages/core/src/webjs-config.d.ts, and the reader functions (readElideEnabled in dev.js, readSeedEnabled in dev.js, compileHeaderRules in headers.js, compileRedirectRules / readTrailingSlashPolicy in redirects.js, readBasePath in base-path.js, readCspConfig in csp.js, readBodyLimits / computeServerTimeouts in body-limit.js, and the CLI's readAppTasks in packages/cli/lib/app-tasks.js for dev/start, #550). Adding a webjs.* key means updating all three. See packages/server/AGENTS.md for the one documented procedure.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -147,6 +147,35 @@
       "type": "integer",
       "minimum": 0,
       "default": 5000
+    },
+    "dev": {
+      "description": "Dev task orchestration (#550). Read by the CLI (readAppTasks in packages/cli/lib/app-tasks.js), NOT the server. webjs dev runs `before` (one-shot, e.g. webjs db migrate) to completion, then `parallel` (long-lived watchers, e.g. tailwindcss --watch) alongside the server. Replaces the old predev hook + concurrently watchers.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "before": {
+          "description": "One-shot commands run sequentially to completion before the dev server boots. A non-zero exit aborts the boot.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "parallel": {
+          "description": "Long-lived commands run as child processes alongside the dev server, torn down on exit so a watcher cannot leak past it.",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "start": {
+      "description": "Start task orchestration (#550). Read by the CLI (readAppTasks in packages/cli/lib/app-tasks.js), NOT the server. webjs start runs `before` (one-shot, e.g. webjs db migrate) to completion before serving. Replaces the old prestart hook.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "before": {
+          "description": "One-shot commands run sequentially to completion before the prod server boots. A non-zero exit aborts the boot.",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
     }
   }
 }