@webjsdev/cli 0.10.13 → 0.10.14

package/README.md

@@ -42,10 +42,12 @@ webjs create <name>            # scaffold a full-stack app (default)
 webjs create <name> --template api   # backend-only API app
 webjs create <name> --template saas  # auth + dashboard + Prisma User model
 
-webjs dev                      # dev server with live reload
+webjs dev                      # dev server with live reload (prefer `npm run dev`, which runs the predev prisma generate hook)
 webjs start                    # production server (no build step, serves source directly)
-webjs check                    # validate project conventions
+webjs check                    # validate source-code conventions (CI gate)
+webjs doctor                   # verify the project/toolchain setup (local onboarding, not CI)
 webjs test                     # run server + browser tests
+webjs vendor pin [--download]  # pin client deps to a committable importmap (offline/reproducible)
 webjs db <prisma-subcommand>   # prisma passthrough (saas template)
 
 webjs ui init                  # initialise @webjsdev/ui in this project

package/bin/webjs.js

@@ -3,6 +3,7 @@ import { resolve, join, dirname } from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
+import { loadAppEnv, resolvePort } from '../lib/port.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
@@ -43,7 +44,7 @@ const USAGE = `webjs commands:
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check [--json]                            Run correctness checks on the app (--json emits structured violations)
   webjs mcp                                       Start the read-only MCP server (routes / actions / components / check)
-  webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, @webjsdev versions, git hook)
+  webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook)
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs typecheck [tsc args...]                   Type-check the app with the project's tsc --noEmit (non-zero on errors)
   webjs create <name> [--template full-stack|api|saas] [--no-install]  Scaffold a new webjs app
@@ -85,11 +86,24 @@ async function main() {
       // If we're already inside the --watch child, start the server directly.
       if (process.env.__WEBJS_DEV_CHILD === '1') {
         const { startServer } = await import('@webjsdev/server');
-        const port = Number(flag(rest, '--port', process.env.PORT || 8080));
+        // Load `.env` BEFORE resolving the port so a `PORT` set there is in
+        // process.env at resolution time (#447). The server loads `.env`
+        // too, but that runs too late to affect the port the CLI computes.
+        loadAppEnv(process.cwd());
+        const port = resolvePort(flag(rest, '--port'));
         await startServer({ appDir: process.cwd(), port, dev: true });
         break;
       }
 
+      // A bare `webjs dev` (not `npm run dev`) skips the `predev` hook, so a
+      // Prisma app boots against an ungenerated client and crashes with no
+      // hint (#452). Detect that here, in the PARENT only, so the message
+      // prints once rather than on every watch restart. Scoped to Prisma apps;
+      // a non-Prisma app sees nothing. A hint, not an auto-run.
+      const { prismaDevHint } = await import('../lib/prisma-preflight.js');
+      const hint = prismaDevHint(process.cwd());
+      if (hint) console.error(hint);
+
       // Otherwise, spawn ourselves as a child with node --watch.
       // This restarts the process on file changes, guaranteeing a fresh
       // Node ESM module cache. Without this, edits to transitively-imported
@@ -125,7 +139,10 @@ async function main() {
     }
     case 'start': {
       const { startServer } = await import('@webjsdev/server');
-      const port = Number(flag(rest, '--port', process.env.PORT || 8080));
+      // Load `.env` BEFORE resolving the port so a `PORT` set there wins over
+      // the 8080 default (#447), same as for `dev`.
+      loadAppEnv(process.cwd());
+      const port = resolvePort(flag(rest, '--port'));
       await startServer({ appDir: process.cwd(), port, dev: false });
       break;
     }
@@ -417,7 +434,7 @@ Full docs: https://docs.webjs.com`);
       const sub = rest[0];
       const args = rest.slice(1);
       const appDir = process.cwd();
-      const { pinAll, unpinPackage, listPinned, auditPinned, findOutdated, updatePinned, readPinFile, SUPPORTED_PROVIDERS } = await import('@webjsdev/server');
+      const { pinAll, unpinPackage, listPinned, auditPinned, findOutdated, updatePinned, readPinFile, ensureVendorCommittable, SUPPORTED_PROVIDERS } = await import('@webjsdev/server');
 
       // Parse `--from <provider>` once at the top so subcommands share it.
       // Mirrors importmap-rails's `bin/importmap pin foo --from jsdelivr`.
@@ -498,6 +515,30 @@ Full docs: https://docs.webjs.com`);
           (downloaded ? ` + ${downloaded} bundle${downloaded === 1 ? '' : 's'}` : '') + '.';
         const pruneMsg = pruned.length ? ` Pruned ${pruned.length} orphan${pruned.length === 1 ? '' : 's'}.` : '';
         console.log(pinMsg + pruneMsg);
+
+        // Make the pins committable. Vendoring is opt-in, so the pins the
+        // user just wrote are meant for source control; a `.gitignore`
+        // that excludes `.webjs/` would silently swallow them. Fresh
+        // scaffolds already carry the `!.webjs/vendor/` exception, so for
+        // them this is a no-op. If the output IS ignored, self-heal the
+        // app's own `.gitignore`; if there is no `.gitignore` to patch (the
+        // ignore comes from a parent repo or `.git/info/exclude`), print a
+        // notice so the pins do not vanish from `git status` unexplained.
+        const committable = await ensureVendorCommittable(appDir);
+        if (committable.patched) {
+          console.log(
+            `Added the \`.webjs/vendor/\` exception to .gitignore so these pins commit. ` +
+            `Run \`git add .gitignore .webjs/vendor\`.`,
+          );
+        } else if (committable.ignored) {
+          console.warn(
+            `[webjs] .webjs/vendor/importmap.json is gitignored, so these pins will NOT ` +
+            `commit. The ignore is not in this app's .gitignore (a parent repo's .gitignore ` +
+            `or .git/info/exclude). Un-ignore it by adding \`!**/.webjs/vendor/\` and ` +
+            `\`!**/.webjs/vendor/**\` where the \`.webjs\` exclusion lives, then ` +
+            `\`git add .webjs/vendor\`. Verify with \`git check-ignore -q .webjs/vendor/importmap.json\`.`,
+          );
+        }
         break;
       }
 

package/lib/doctor.js

@@ -326,6 +326,84 @@ async function checkVendorPin(appDir, opts) {
   };
 }
 
+/**
+ * CHECK: the `.gitignore` does not swallow the committed vendor pin. The pattern
+ * for `.webjs/vendor/` is subtle: a bare `.webjs/` line excludes the directory
+ * entirely and git cannot re-include children of an excluded parent, so a
+ * `!.webjs/vendor/` exception silently does nothing and `webjs vendor pin`
+ * output never gets committed. The correct pattern is the depth-robust
+ * contents-glob form (see the fix text below / VENDOR_GITIGNORE_LINES in
+ * vendor.js): a globstar-prefixed `.webjs/*` plus the matching vendor
+ * negations, which ignores transient `.webjs` output at any depth while
+ * keeping the committed vendor pin tracked.
+ *
+ * This was a `webjs check` rule, but inspecting `.gitignore` is a project-config
+ * concern (like `tsconfig-erasable`), not source-code correctness, and vendoring
+ * is optional, so a doctor WARN fits the domain and severity better than a CI
+ * hard-fail (#461). It lives next to `vendor-pin` (same family).
+ *
+ * PASS/skip when the dir is not a git repo or has no `.gitignore` (the user has
+ * not opted into version control yet). Probes two representative paths via
+ * `git check-ignore` with the inherited GIT_* env stripped so `cwd` is the sole
+ * authority on which repo + .gitignore stack is consulted (a pre-commit hook
+ * from a linked worktree exports GIT_WORK_TREE, which would otherwise override
+ * cwd-based discovery).
+ *
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkVendorGitignore(appDir) {
+  const hasGit = existsSync(join(appDir, '.git'));
+  const hasGitignore = existsSync(join(appDir, '.gitignore'));
+  if (!hasGit || !hasGitignore) {
+    return {
+      name: 'vendor-gitignore',
+      status: 'pass',
+      message: 'Not a git checkout with a .gitignore; nothing to verify.',
+    };
+  }
+  const { spawnSync } = await import('node:child_process');
+  const {
+    GIT_DIR: _gd, GIT_WORK_TREE: _gwt, GIT_INDEX_FILE: _gif, GIT_PREFIX: _gp,
+    ...gitEnv
+  } = process.env;
+  // Check two representative paths: the pin manifest AND a sample downloaded
+  // bundle. A `.gitignore` that allows the manifest but blocks bundles (e.g.
+  // `*.js` higher up) would still break `webjs vendor pin --download`.
+  // `git check-ignore -q` exits 0 when the path is ignored, 1 when not.
+  const probes = [
+    '.webjs/vendor/importmap.json',
+    '.webjs/vendor/sample-pkg@1.0.0.js',
+  ];
+  for (const probe of probes) {
+    const result = spawnSync('git', ['check-ignore', '-q', probe], {
+      cwd: appDir,
+      stdio: 'pipe',
+      env: gitEnv,
+    });
+    if (result.status === 0) {
+      return {
+        name: 'vendor-gitignore',
+        status: 'warn',
+        message:
+          `${probe} is gitignored, but \`webjs vendor pin\` writes files under .webjs/vendor/ that MUST be committed for a production deploy to use the pin (instead of calling api.jspm.io on every cold start). The most common cause: a \`.webjs/\` line that excludes the parent directory before the \`!.webjs/vendor/\` exception can take effect (git semantics: a parent exclusion blocks child negations). A second cause is a broader rule (e.g. \`*.js\` at root) hiding bundle files added by \`webjs vendor pin --download\`.`,
+        fix:
+          'Replace `.webjs/` in your .gitignore with this three-line pattern:\n' +
+          '  **/.webjs/*\n' +
+          '  !**/.webjs/vendor/\n' +
+          '  !**/.webjs/vendor/**\n' +
+          'The `**/` prefix ignores `.webjs/` at any depth (so a nested / monorepo app does not leak its generated `.webjs/routes.d.ts`) while still re-including the committed vendor pin. ' +
+          'Verify with `git check-ignore -q .webjs/vendor/importmap.json` (exit 1 means correctly un-ignored).',
+      };
+    }
+  }
+  return {
+    name: 'vendor-gitignore',
+    status: 'pass',
+    message: 'The .gitignore keeps .webjs/vendor/ committable.',
+  };
+}
+
 /**
  * Compare an installed version against a semver range PRAGMATICALLY (no semver
  * dependency). Supports the common scaffold shapes: `latest` / `*` / `workspace:*`
@@ -367,6 +445,200 @@ function satisfiesRange(installed, range) {
   return null;
 }
 
+/**
+ * Read the declared dependency ranges of an INSTALLED package from
+ * `node_modules/<pkg>/package.json`, for the importmap-coherence check. This
+ * is the "already-resolved metadata, no network" path the issue calls for: the
+ * package is on disk (it was installed for the importmap to pin it), so its
+ * manifest is a local read. Returns null on any failure (not installed,
+ * unreadable, unparseable), which the coherence check treats as "could not
+ * verify" rather than a conflict.
+ *
+ * @param {string} appDir
+ * @returns {(pkg: string) => Promise<{ dependencies?: Record<string,string>, peerDependencies?: Record<string,string> } | null>}
+ */
+function makeInstalledManifestReader(appDir) {
+  return async (pkg) => {
+    const manifestPath = join(appDir, 'node_modules', pkg, 'package.json');
+    if (!existsSync(manifestPath)) return null;
+    try {
+      const parsed = JSON.parse(await readFile(manifestPath, 'utf8'));
+      return {
+        dependencies: parsed.dependencies || {},
+        peerDependencies: parsed.peerDependencies || {},
+      };
+    } catch {
+      return null;
+    }
+  };
+}
+
+/**
+ * Format a coherence conflict list into a single human-readable warning line
+ * naming each conflicting pair, the required range, and the pinned version.
+ * @param {Array<{ pkg: string, version: string, dependsOn: string, kind: string, requiredRange: string, pinnedVersion: string }>} conflicts
+ * @returns {string}
+ */
+function formatConflicts(conflicts) {
+  return conflicts
+    .map(
+      (c) =>
+        `${c.pkg}@${c.version} needs ${c.dependsOn} ${c.kind === 'peerDependency' ? '(peer) ' : ''}${c.requiredRange} but the importmap pins ${c.dependsOn}@${c.pinnedVersion}`,
+    )
+    .join('; ');
+}
+
+/**
+ * CHECK 7, importmap coherence (issue #450). Defense-in-depth that catches an
+ * INCOHERENT client dependency graph in the produced importmap, regardless of
+ * how the incoherence arose (a hand-edited pin file, a partial vendor pin, or
+ * the #446 resolution skew). For each resolved package, it checks that the
+ * version actually pinned for every OTHER resolved package it depends on
+ * satisfies the declared range; a miss warns naming both packages, the range,
+ * and the pinned version.
+ *
+ * Runs the SAME check over BOTH inputs and produces the same verdict for the
+ * same dep set (the parity invariant): the live importmap (resolved the way the
+ * server resolves it at runtime) AND the vendored `.webjs/vendor/importmap.json`.
+ * A vendored importmap is a freeze of the runtime-resolved graph, so a coherent
+ * runtime graph that gets vendored stays coherent.
+ *
+ * WARN-only and BEST-EFFORT: it never hard-fails (a runtime incoherence is the
+ * app's concern, not a broken toolchain), and it degrades to a soft
+ * "could not verify" whenever metadata or a live resolve is unavailable rather
+ * than failing closed. Dependency metadata is read from the already-installed
+ * `node_modules` manifests, no network call of its own; the only network touch
+ * is the live importmap resolve, which is wrapped so any failure degrades.
+ *
+ * The vendor functions + manifest reader are injectable via `opts.coherence`
+ * so a test can drive every branch without a network call.
+ *
+ * @param {string} appDir
+ * @param {{ coherence?: {
+ *   liveImports?: () => Promise<Record<string,string> | null>,
+ *   vendoredImports?: () => Promise<Record<string,string> | null>,
+ *   getManifest?: (pkg: string, version: string) => Promise<any>,
+ *   check?: (imports: Record<string,string>, o: { getManifest: any }) => Promise<{ conflicts: any[], unverified: any[], checked: number }>,
+ * } }} opts
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkImportmapCoherence(appDir, opts) {
+  let inj = opts.coherence;
+  // Resolve the real vendor toolchain unless a test injected stubs. Both the
+  // importmap sources and the coherence-check function come from
+  // @webjsdev/server, so a missing install degrades to a WARN, never a throw.
+  if (!inj || !inj.check || !inj.liveImports || !inj.vendoredImports || !inj.getManifest) {
+    let mod;
+    try {
+      mod = await import('@webjsdev/server');
+    } catch {
+      return {
+        name: 'importmap-coherence',
+        status: 'warn',
+        message: 'Could not load the vendor toolchain to check importmap coherence.',
+        fix: 'Run `npm install` so @webjsdev/server is available, then re-run `webjs doctor`.',
+      };
+    }
+    const real = {
+      check: mod.checkImportmapCoherence,
+      // Hoist-aware manifest read from the already-installed node_modules (no
+      // network of its own), so a monorepo-hoisted dep still resolves. Falls
+      // back to the local app/node_modules read if the server build predates
+      // getPackageManifest.
+      getManifest: typeof mod.getPackageManifest === 'function'
+        ? (pkg) => mod.getPackageManifest(pkg, appDir)
+        : makeInstalledManifestReader(appDir),
+      // Live importmap: resolve vendor imports the way the server does on the
+      // first request (prefers the pin file, else a live jspm.io resolve).
+      liveImports: async () => {
+        try {
+          const resolved = await mod.resolveVendorImports(appDir, () => mod.scanBareImports(appDir));
+          return resolved && resolved.imports ? resolved.imports : {};
+        } catch {
+          return null;
+        }
+      },
+      // Vendored importmap: the committed pin file, no network.
+      vendoredImports: async () => {
+        try {
+          const pin = await mod.readPinFile(appDir);
+          return pin && pin.imports ? pin.imports : null;
+        } catch {
+          return null;
+        }
+      },
+    };
+    inj = { ...real, ...(inj || {}) };
+  }
+
+  // Gather both importmaps. Either may be absent (no pin file, or a live
+  // resolve that failed / found no vendor imports); the check runs over
+  // whichever exist, identically.
+  let live = null;
+  let vendored = null;
+  try { live = await inj.liveImports(); } catch { live = null; }
+  try { vendored = await inj.vendoredImports(); } catch { vendored = null; }
+
+  const liveHas = live && Object.keys(live).length > 0;
+  const vendoredHas = vendored && Object.keys(vendored).length > 0;
+  if (!liveHas && !vendoredHas) {
+    return {
+      name: 'importmap-coherence',
+      status: 'pass',
+      message: 'No vendor importmap to check (the app imports no npm packages on the client).',
+    };
+  }
+
+  // Run the IDENTICAL check over each available importmap. The function is
+  // pure in (imports, getManifest), so the same pinned dep set produces the
+  // same verdict whichever input it came from (the runtime-vs-vendored parity
+  // invariant). Aggregate the conflicts; dedupe identical ones so a package
+  // pinned the same way in both maps is reported once.
+  /** @type {Map<string, any>} */
+  const conflictsByKey = new Map();
+  let anyChecked = 0;
+  let anyUnverified = 0;
+  for (const imports of [liveHas ? live : null, vendoredHas ? vendored : null]) {
+    if (!imports) continue;
+    let report;
+    try {
+      report = await inj.check(imports, { getManifest: inj.getManifest });
+    } catch {
+      // A check that threw is a "could not verify", never a doctor crash.
+      anyUnverified++;
+      continue;
+    }
+    anyChecked += report.checked || 0;
+    anyUnverified += (report.unverified || []).length;
+    for (const c of report.conflicts || []) {
+      conflictsByKey.set(`${c.pkg}@${c.version}->${c.dependsOn}@${c.pinnedVersion}`, c);
+    }
+  }
+
+  const conflicts = [...conflictsByKey.values()];
+  if (conflicts.length > 0) {
+    return {
+      name: 'importmap-coherence',
+      status: 'warn',
+      message: `Incoherent client dependency graph in the importmap: ${formatConflicts(conflicts)}.`,
+      fix: 'Align the pinned versions: re-run `webjs vendor pin` to re-resolve a coherent set, or bump the lagging package in package.json and reinstall so the importmap pins a version satisfying every dependent.',
+    };
+  }
+  if (anyChecked === 0 && anyUnverified > 0) {
+    return {
+      name: 'importmap-coherence',
+      status: 'warn',
+      message: 'Could not verify importmap coherence (dependency metadata for the pinned packages was unavailable).',
+      fix: 'Run `npm install` so the pinned packages are present in node_modules, then re-run `webjs doctor`.',
+    };
+  }
+  return {
+    name: 'importmap-coherence',
+    status: 'pass',
+    message: 'The importmap dependency graph is coherent (every pinned package satisfies its dependents\' declared ranges).',
+  };
+}
+
 /**
  * CHECK 5, @webjsdev/* version coherence. WARN-level only (a version drift is
  * not a crash). Reads the app package.json `@webjsdev/*` ranges across
@@ -518,6 +790,9 @@ function checkGitHook(appDir) {
  *     required major (defaults to THIS module's package);
  *   - `vendor`: inject the `{ hasVendorPin, findOutdated }` pair so the pin check
  *     runs against a stub instead of a real network call.
+ *   - `coherence`: inject `{ liveImports, vendoredImports, getManifest, check }`
+ *     so the importmap-coherence check runs against stub importmaps + metadata
+ *     instead of a real live resolve / node_modules read.
  * @returns {Promise<DoctorResult[]>}
  */
 export async function runDoctorChecks(appDir, opts = {}) {
@@ -527,7 +802,9 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkTsconfig(appDir),
     checkEnv(appDir),
     checkVendorPin(appDir, opts),
+    checkVendorGitignore(appDir),
     checkWebjsVersions(appDir),
+    checkImportmapCoherence(appDir, opts),
     Promise.resolve(checkGitHook(appDir)),
   ]);
   return results;

package/lib/port.js

@@ -0,0 +1,60 @@
+/**
+ * Port resolution for `webjs dev` / `webjs start` (issue #447).
+ *
+ * The bug this fixes: the CLI read `process.env.PORT || 8080` BEFORE the
+ * server's bootstrap ran `process.loadEnvFile('.env')`, so a `PORT` set in
+ * the project's `.env` never reached the port comparison and the server
+ * always came up on 8080. Every OTHER `.env` var worked, because the server
+ * loads `.env` early enough for everything IT reads; only the port, computed
+ * one layer up in the CLI, missed the load.
+ *
+ * The fix loads `.env` into `process.env` here, in the CLI, before the port
+ * is computed. Both functions live in this module so `dev` and `start` share
+ * one implementation and the logic is unit-testable without spawning a
+ * server.
+ */
+import { join } from 'node:path';
+
+/**
+ * Load `<appDir>/.env` into `process.env`, guarded exactly like the server's
+ * own `loadAppEnv` (`packages/server/src/dev.js`): only on a Node with the
+ * built-in `process.loadEnvFile`, and swallowing a missing or malformed file.
+ *
+ * Node's `loadEnvFile` does NOT override a var already present in
+ * `process.env`, so a real shell-exported `PORT=NNNN npm run dev` still wins
+ * over the file. That "shell beats file" precedence is intentional and
+ * matches what the server does after its own load.
+ *
+ * @param {string} appDir
+ */
+export function loadAppEnv(appDir) {
+  try {
+    if (typeof process.loadEnvFile === 'function') {
+      process.loadEnvFile(join(appDir, '.env'));
+    }
+  } catch {
+    // No .env, malformed file, or a Node without loadEnvFile. Fall through
+    // silently: the app may not need any env vars, or they may be set via
+    // the shell.
+  }
+}
+
+/**
+ * Resolve the server port with precedence `--port` flag > `PORT` (shell env
+ * or `.env`, whichever landed in `process.env`) > 8080.
+ *
+ * Kept pure (no `.env` loading, no `process.env` mutation) so it is trivially
+ * testable: the caller loads `.env` first via `loadAppEnv`, then passes the
+ * resulting `process.env` in. A non-numeric or empty `--port` / `PORT`
+ * surfaces as `NaN`, same as the previous inline `Number(...)`, so behaviour
+ * for bad input is unchanged.
+ *
+ * @param {string | undefined} portFlag  The `--port` value, or undefined.
+ * @param {NodeJS.ProcessEnv} [env]      Defaults to `process.env`.
+ * @returns {number}
+ */
+export function resolvePort(portFlag, env = process.env) {
+  if (portFlag !== undefined) return Number(portFlag);
+  if (env.PORT) return Number(env.PORT);
+  return 8080;
+}

package/lib/prisma-preflight.js

@@ -0,0 +1,168 @@
+/**
+ * Prisma-client preflight for `webjs dev` (#452).
+ *
+ * The scaffold's `dev` npm script is `webjs dev`, and `npm run dev` runs the
+ * `predev` hook (`prisma generate`) FIRST. Invoking the `webjs dev` binary
+ * directly (easy to do, and tempting for an AI/CLI) skips `predev`, so the dev
+ * server boots against an ungenerated `@prisma/client` and crashes with a raw
+ * "did not initialize yet" error and no hint that the canonical command is
+ * `npm run dev`. This turns that crash into a one-line, actionable message.
+ *
+ * Scope is deliberately narrow: it only fires for an app that actually uses
+ * Prisma (a `prisma/schema.prisma` OR an `@prisma/client` dependency), and it
+ * only HINTS. It never auto-runs an arbitrary `predev` script and never shells
+ * out to `prisma generate` on its own, keeping the no-build promise intact.
+ *
+ * Detection (verified against a real Prisma 6 install): the GENERATED
+ * `.prisma/client` target is resolved through standard Node resolution from the
+ * app (so a hoisted monorepo, where the client lives at a PARENT `node_modules`,
+ * resolves correctly), then read. An ABSENT target, or a present-but-stub target
+ * (the ungenerated client whose `PrismaClient` constructor throws the init
+ * error), is "ungenerated". A real generated target older than the schema is
+ * "stale". We do NOT grep the static `@prisma/client` re-export shim: it is
+ * present in both states and never carries the init-error string itself.
+ */
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+
+/**
+ * Does this app use Prisma? True if a schema is checked in OR `@prisma/client`
+ * is a declared dependency. Either alone is enough; a non-Prisma app has
+ * neither and gets no warning.
+ *
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function usesPrisma(cwd) {
+  if (existsSync(join(cwd, 'prisma', 'schema.prisma'))) return true;
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return Boolean(deps && deps['@prisma/client']);
+  } catch {
+    return false;
+  }
+}
+
+// Marker the ungenerated `prisma-client-js` stub embeds in its generated target
+// (`node_modules/.prisma/client/index.js`). Verified against a real Prisma 6
+// install: after `npm i @prisma/client` but before `prisma generate`, the
+// generated `.prisma/client` entry IS present but its `PrismaClient` constructor
+// throws `@prisma/client did not initialize yet. Please run "prisma generate"`.
+// A real `prisma generate` replaces that stub with the generated client, which
+// does NOT contain this string. So the marker, read from the GENERATED target
+// (not the static `@prisma/client` shim), is the reliable ungenerated signal.
+const UNGENERATED_MARKER = 'did not initialize yet';
+
+/**
+ * Resolve the GENERATED Prisma client entry (`.prisma/client/index.js`) for an
+ * app, following standard Node resolution so a hoisted monorepo layout (the
+ * generated client at a PARENT `node_modules`, the app under `apps/<x>`) still
+ * resolves. Returns a discriminated result so the caller can tell the three
+ * cases apart:
+ *   - `{ kind: 'unresolved' }`        - `@prisma/client` itself is not resolvable.
+ *   - `{ kind: 'no-target' }`         - the package resolves but `.prisma/client`
+ *                                       does not (a custom `output`, ambiguous).
+ *   - `{ kind: 'target', path }`      - the generated target resolves.
+ *
+ * @param {string} cwd
+ * @returns {{ kind: 'unresolved' } | { kind: 'no-target' } | { kind: 'target', path: string }}
+ */
+function resolveGeneratedClient(cwd) {
+  let clientDir;
+  try {
+    // Resolve @prisma/client AS THE APP would (hoisting-aware), then locate its
+    // package dir. The shim itself loads `.prisma/client/default` relative to
+    // here, so resolving from this dir follows the same (possibly hoisted) path.
+    const appRequire = createRequire(join(cwd, 'noop.js'));
+    clientDir = dirname(appRequire.resolve('@prisma/client'));
+  } catch {
+    return { kind: 'unresolved' };
+  }
+  const shimRequire = createRequire(join(clientDir, 'noop.js'));
+  for (const entry of ['.prisma/client/index.js', '.prisma/client/default.js']) {
+    try {
+      return { kind: 'target', path: shimRequire.resolve(entry) };
+    } catch { /* try the next entry */ }
+  }
+  return { kind: 'no-target' };
+}
+
+/**
+ * Inspect the generated Prisma client state for a Prisma app.
+ *
+ * Returns one of:
+ *   - `{ status: 'ok' }`         - client generated and not older than the schema.
+ *   - `{ status: 'missing' }`    - schema/dep present but no generated client.
+ *   - `{ status: 'stale' }`      - client exists but the schema is newer than it.
+ *
+ * Detection resolves the GENERATED `.prisma/client` target through standard Node
+ * resolution (so hoisted monorepos are handled) and reads it: an absent target,
+ * or a present-but-stub target (the ungenerated `PrismaClient` that throws on
+ * construction), is `missing`. A real generated client that is older than the
+ * schema is `stale`. A custom-`output` generator whose target Node cannot
+ * resolve falls back to `ok` rather than nag a working app (false positives are
+ * worse than a missed hint here).
+ *
+ * @param {string} cwd
+ * @returns {{ status: 'ok' | 'missing' | 'stale' }}
+ */
+export function prismaClientState(cwd) {
+  const resolved = resolveGeneratedClient(cwd);
+
+  // @prisma/client not resolvable: the app declared the dep (usesPrisma gated
+  // us here) but it is not installed/generated. That is the boot-crash case.
+  if (resolved.kind === 'unresolved') return { status: 'missing' };
+
+  // The package resolves but the default `.prisma/client` target does not: a
+  // custom `output` whose location we cannot cheaply verify. Fall back to `ok`
+  // rather than nag a working app (false positives are worse than a missed hint).
+  if (resolved.kind === 'no-target') return { status: 'ok' };
+
+  const generatedIndex = resolved.path;
+
+  // The generated target exists. Is it still the ungenerated stub (its
+  // PrismaClient constructor throws the init error)?
+  try {
+    const body = readFileSync(generatedIndex, 'utf8');
+    if (body.includes(UNGENERATED_MARKER)) return { status: 'missing' };
+  } catch { /* unreadable: fall through to the stale check, then ok */ }
+
+  // Generated for real. Is it older than the schema (a stale client)?
+  const schema = join(cwd, 'prisma', 'schema.prisma');
+  try {
+    if (existsSync(schema)) {
+      const schemaMtime = statSync(schema).mtimeMs;
+      const clientMtime = statSync(generatedIndex).mtimeMs;
+      if (schemaMtime > clientMtime) return { status: 'stale' };
+    }
+  } catch { /* if we can't stat, treat as ok */ }
+
+  return { status: 'ok' };
+}
+
+/**
+ * Build the actionable hint for an ungenerated/stale client, or `null` when the
+ * app is fine or does not use Prisma. The caller prints it (a warning, not a
+ * hard exit) before booting the dev server.
+ *
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function prismaDevHint(cwd) {
+  if (!usesPrisma(cwd)) return null;
+  const { status } = prismaClientState(cwd);
+  if (status === 'ok') return null;
+
+  const reason =
+    status === 'stale'
+      ? 'Your Prisma client looks stale (the schema changed since it was generated).'
+      : 'Your Prisma client is not generated yet.';
+  return (
+    `webjs: ${reason}\n` +
+    `  The dev server will crash on an ungenerated client. Fix it with either:\n` +
+    `    npm run dev          # canonical: runs \`prisma generate\` (predev) first\n` +
+    `    webjs db generate    # just regenerate the client, then re-run\n`
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.13",
+  "version": "0.10.14",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/AGENTS.md

@@ -96,6 +96,52 @@ node_modules/@webjsdev/
 Reaching straight for the source is the fastest way to resolve "why
 doesn't X work?" with no documentation guesswork and no stale blog posts.
 
+## Use the webjs MCP server (introspection + framework knowledge)
+
+This project ships a **read-only Model Context Protocol server** that gives
+you (the AI agent) live, version-accurate facts about THIS app and the
+framework. Prefer it over guessing or recalling webjs from training data,
+which drifts. It mutates nothing.
+
+**It is already available, no install needed:** the webjs CLI (a project
+dependency) has it built in as `webjs mcp`. It is an MCP STDIO server (JSON-RPC
+over stdout), so you do not run it in a terminal and read its output. Your MCP
+host (Claude Code, Cursor, etc.) launches it and surfaces its tools, then you
+invoke those tools through the MCP protocol.
+
+Claude Code is pre-wired (see `.claude.json`). For another host, register the
+server by pointing it at the CLI (or the equivalent standalone package):
+
+```jsonc
+// Cursor: .cursor/mcp.json   (or your host's MCP config)
+{ "mcpServers": { "webjs": {
+  "command": "npx", "args": ["@webjsdev/cli", "mcp"]   // the built-in CLI route
+  // equivalent: "command": "npx", "args": ["@webjsdev/mcp"]
+} } }
+```
+
+What it serves:
+
+- **Introspection of this app** (read-only, no module load, no DB side
+  effects): `list_routes` (the route table), `list_actions` (server actions
+  with their `/__webjs/action/<hash>/<fn>` RPC endpoints), `list_components`
+  (registered custom-element tags), `check` (the structured `webjs check`
+  violations). Use these to learn the real route/action/component surface
+  before editing, instead of grepping or assuming.
+- **Framework knowledge**: an `init` primer (the read-first mental model +
+  invariants), a `docs` tool (retrieve a topic or search the `agent-docs`
+  corpus), MCP `resources` (the docs corpus + this AGENTS.md), recipe
+  `prompts` (guided page/route/action/component workflows), and a `source`
+  tool that reads the framework's OWN no-build source from
+  `node_modules/@webjsdev/*/src` (what actually runs).
+
+You have TWO complementary ways to understand the framework, use whichever
+helps (or both): (1) **grep the full framework source** under
+`node_modules/@webjsdev/*/src`, which is the real no-build code that runs (no
+sourcemaps, no guessing), and (2) **the MCP** for live app introspection plus
+the curated `init` / `docs` / `source` knowledge tools. Reach for either before
+guessing from training data or asking the user.
+
 ## Editor TS plugin: `@webjsdev/intellisense`
 
 This scaffold's `tsconfig.json` lists a single tsserver plugin. It is
@@ -474,9 +520,10 @@ Production then has no importmap.json and the server falls back to
 calling api.jspm.io on every cold start. The `**/` prefix matters too:
 it ignores `.webjs/` at any depth, so an app nested below its repo root
 (a monorepo package) does not leak its generated `.webjs/routes.d.ts`
-into `git status`. The `gitignore-vendor-not-ignored` lint rule
-(`webjs check`) verifies the pattern with `git check-ignore` and will
-fail CI if it regresses.
+into `git status`. The `vendor-gitignore` check (`webjs doctor`)
+verifies the pattern with `git check-ignore` and warns if it regresses
+(it is a project-config / setup concern, not a source-code-correctness
+CI gate).
 
 ## Imports
 

package/templates/CONVENTIONS.md

@@ -66,7 +66,10 @@ even if the user doesn't explicitly ask.**
 Run `npm run doctor` (which runs `webjs doctor`) once after cloning to assert
 the project is set up correctly: the Node major (the strip-types floor), the
 tsconfig `erasableSyntaxOnly` flag, `.env` drift vs `.env.example`, vendor-pin
-freshness, `@webjsdev/*` version coherence, and the git pre-commit hook. It
+freshness, the `.gitignore` keeping `.webjs/vendor/` committable
+(`vendor-gitignore`), importmap-coherence (the resolved client deps agree on a
+shared transitive version), `@webjsdev/*` version coherence, and the git
+pre-commit hook. It
 prints `[pass]` / `[warn]` / `[fail]` per check with an actionable fix line and
 exits non-zero only on a hard fail (a broken toolchain), so a green run means
 `npm run dev` will boot. It is a local onboarding/setup-verify tool, not a CI
@@ -348,7 +351,7 @@ variables control infrastructure (no config files needed):
 | `AUTH_SECRET` | Required for auth JWT signing (32+ random chars) |
 | `AUTH_GOOGLE_ID` | Google OAuth client ID (optional) |
 | `AUTH_GITHUB_ID` | GitHub OAuth client ID (optional) |
-| `PORT` | Server port (default: 8080) |
+| `PORT` | Server port. Precedence: `--port` flag > `PORT` (a real exported env var or a `PORT` in `.env`) > 8080. |
 | `WEBJS_PUBLIC_*` | Any env var starting with this prefix is exposed to the browser as `process.env.WEBJS_PUBLIC_X`. Components can read it directly. No build step, no transform. Use for API base URLs, Stripe publishable keys, analytics IDs, anything that is intended to be visible client-side. |
 
 **Server-only by default.** Any env var without the `WEBJS_PUBLIC_` prefix never reaches the browser. Reading `process.env.DATABASE_URL` from a component returns `undefined`, the same as a typo. The prefix is fail-closed: secrets cannot accidentally leak.