@webjsdev/cli 0.10.12 → 0.10.14

package/README.md

@@ -10,7 +10,7 @@ Installing this package gives you the `webjs` command.
 Install once, globally:
 
 ```sh
-npm i -g @webjsdev/cli
+npm i -g webjsdev
 ```
 
 Then scaffold a new app anywhere:
@@ -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;
     }
@@ -141,7 +158,7 @@ async function main() {
     }
     case 'ui': {
       // Delegate to @webjsdev/ui. Bundled as a hard dependency of
-      // @webjsdev/cli, so `npm install -g @webjsdev/cli` pulls it in
+      // @webjsdev/cli, so `npm install -g webjsdev` pulls it in
       // automatically, and `webjs ui add button` works out of the box
       // without an extra install in user projects.
       const { createRequire } = await import('node:module');
@@ -157,7 +174,7 @@ async function main() {
           entry = userReq.resolve('@webjsdev/ui/bin/webjsui.js');
         } catch {
           console.error('@webjsdev/ui could not be resolved.');
-          console.error('Reinstall the CLI:  npm install -g @webjsdev/cli');
+          console.error('Reinstall the CLI:  npm install -g webjsdev');
           process.exit(1);
         }
       }
@@ -275,7 +292,9 @@ async function main() {
       // identical to the MCP `check` tool. The non-zero exit on violations is
       // preserved (an agent gates on the exit code AND parses the report).
       if (rest.includes('--json')) {
-        const { projectCheck } = await import('../lib/check-json.js');
+        // The projector lives in @webjsdev/mcp (the MCP `check` tool's home),
+        // so `check --json` and the MCP tool stay byte-identical (#415).
+        const { projectCheck } = await import('@webjsdev/mcp/check-report');
         console.log(JSON.stringify(projectCheck(violations)));
         if (violations.length > 0) process.exit(1);
         break;
@@ -415,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`.
@@ -496,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;
       }
 
@@ -647,19 +690,23 @@ Full docs: https://docs.webjs.com`);
       process.exit(1);
     }
     case 'mcp': {
-      // Read-only MCP server (#262) over stdio. STDOUT is the JSON-RPC channel,
-      // so nothing here may write to stdout: the data functions are read-only
-      // and `runMcpServer` routes all diagnostics to stderr. The CLI version is
-      // advertised in the initialize handshake's serverInfo.
-      const { readFileSync } = await import('node:fs');
+      // Read-only MCP server (#262, #415) over stdio. STDOUT is the JSON-RPC
+      // channel, so nothing here may write to stdout: the data functions are
+      // read-only and `runMcpServer` routes all diagnostics to stderr. The
+      // implementation lives in the standalone `@webjsdev/mcp` package (also
+      // runnable directly as `npx @webjsdev/mcp`); `webjs mcp` delegates to it
+      // for back-compat. The version advertised in the initialize handshake is
+      // @webjsdev/mcp's own, resolved by its bin, so this passes none.
+      const { runMcpServer } = await import('@webjsdev/mcp');
+      const { createRequire } = await import('node:module');
+      const require = createRequire(import.meta.url);
       let version = '0.0.0';
       try {
-        const pkg = JSON.parse(
-          readFileSync(join(__dirname, '..', 'package.json'), 'utf8'),
-        );
-        version = pkg.version || version;
+        const { readFileSync } = await import('node:fs');
+        version = JSON.parse(
+          readFileSync(require.resolve('@webjsdev/mcp/package.json'), 'utf8'),
+        ).version || version;
       } catch {}
-      const { runMcpServer } = await import('../lib/mcp.js');
       await runMcpServer({
         stdin: process.stdin,
         stdout: process.stdout,

package/lib/create.js

@@ -308,6 +308,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // tsc --noEmit). Not needed at runtime (Node strips types in place), only
       // to type-check the app.
       typescript: '^5.6.0',
+      '@types/node': '^24.0.0',
       '@web/test-runner': '^0.20.0',
       '@web/test-runner-playwright': '^0.11.0',
       'playwright': '^1.59.0',
@@ -315,14 +316,19 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // assertNoA11yViolations() test helper from @webjsdev/core/testing.
       // Test-only: dynamically imported, never shipped to the app runtime.
       'axe-core': '^4.10.0',
-      // tsserver plugin for editor intelligence inside html`` templates.
-      // @webjsdev/ts-plugin bundles ts-lit-plugin internally, so just one
-      // plugin entry is needed in tsconfig (see below).
-      '@webjsdev/ts-plugin': 'latest',
-      // AI-first component library CLI, preinstalled so `webjs ui add button`
-      // works immediately after scaffold. Users can remove if they prefer
-      // to add it later.
-      '@webjsdev/ui': 'latest',
+      // tsserver plugin, wired into tsconfig below. Gives the language
+      // INTELLIGENCE (go-to-def, completions, diagnostics, hover inside html``
+      // templates) in any tsserver editor with NO editor plugin installed,
+      // because editors load tsconfig plugins from node_modules. The `webjs`
+      // VS Code extension and webjs.nvim ALSO bundle this plugin (so it works
+      // before `npm install` too, and adds template HIGHLIGHTING, which a
+      // tsserver plugin can't provide); tsserver dedupes by name, so loading
+      // it both ways is a no-op. Standalone, no Lit dependency. Editor-only.
+      '@webjsdev/intellisense': 'latest',
+      // NOTE: @webjsdev/ui is intentionally NOT pinned. The UI kit is
+      // shadcn-style copy-in: `webjs ui add <name>` copies component source
+      // into components/ui/ (they import @webjsdev/core, not the kit), and the
+      // CLI resolves @webjsdev/ui from its own install.
     },
   }, null, 2) + '\n');
 
@@ -332,6 +338,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       module: 'NodeNext',
       moduleResolution: 'NodeNext',
       lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+      types: ['node'],
       strict: true,
       noEmit: true,
       allowImportingTsExtensions: true,
@@ -347,17 +354,16 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // SYNTAX errors. Use a `const` object + union for enum-shaped
       // values; write fields + constructor assignments explicitly.
       erasableSyntaxOnly: true,
-      // @webjsdev/ts-plugin gives the editor:
-      //   • type-check + diagnostics inside html`` templates (via the
-      //     ts-lit-plugin it bundles internally)
-      //   • webjs-aware go-to-definition on custom-element tags
-      //   • "Unknown tag/attribute" suppression for elements registered
-      //     via Class.register('tag-name')
-      //   • attribute auto-complete sourced from `static properties`
-      //   • attribute-value type-check against `declare` annotations
-      // Editor-only. The framework runs without it.
+      // @webjsdev/intellisense (standalone, no Lit dependency) gives the editor,
+      // inside html`` templates:
+      //   • go-to-definition on custom-element tags, attributes, and CSS classes
+      //   • binding-aware completions (tag names, .prop / ?bool / plain attrs)
+      //   • diagnostics (value type-checks, unquoted-binding, expressionless .prop)
+      //   • hover showing the component class / declared member type
+      // Editor-only. The framework runs without it. For VS Code / Cursor /
+      // Windsurf, the `webjs` extension bundles this automatically.
       plugins: [
-        { name: '@webjsdev/ts-plugin' },
+        { name: '@webjsdev/intellisense' },
       ],
     },
     // `.webjs/routes.d.ts` is the OPT-IN generated route-types overlay (#258):

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;
+}