@webjsdev/cli 0.10.54 → 0.10.56

package/lib/api-gallery.js

@@ -69,9 +69,33 @@ export async function writeApiGallery(appDir) {
     "// Per-segment middleware: it sits beside this route, so it rate-limits ONLY",
     "// /api/features/rate-limit. rateLimit() is backed by the pluggable cache store",
     "// (in-memory by default; point it at Redis to share the window across nodes).",
+    "//",
+    "// `trustProxy: true` decides WHAT gets counted. Without it the bucket key is",
+    "// the socket peer, which is the visitor only when the browser connects to you",
+    "// directly. Behind a CDN or a platform router the peer is that proxy, so a",
+    "// proxy POOL hands out one bucket per proxy and multiplies your real limit by",
+    "// the pool size. With it the key is the forwarded client address instead.",
+    "//",
+    "// It has a precondition: the proxy in front MUST strip an inbound",
+    "// X-Forwarded-For before adding its own, or a client can forge the header and",
+    "// pick its own bucket. Serving with nothing in front? Drop the option, since",
+    "// then the socket peer IS the visitor. WEBJS_NO_TRUST_PROXY=1 outranks it either",
+    "// way. https://webjs.dev/docs/rate-limiting has the full threat model.",
+    "//",
+    "// Behind a CDN, add `clientIpHeader` to name the header carrying the visitor,",
+    "// e.g. `clientIpHeader: 'cf-connecting-ip'` behind Cloudflare. The default",
+    "// chain reads the leftmost X-Forwarded-For entry, which behind a CDN is the",
+    "// CDN's egress address; those are pinned per connection, so the limiter ends up",
+    "// handing out a bucket per connection and refusing nobody. It is left unset",
+    "// here because the right header depends on what you deploy behind.",
     "import { rateLimit } from '@webjsdev/server';",
     "",
-    "export default rateLimit({ window: '10s', max: 5, message: 'Slow down: five requests per ten seconds.' });",
+    "export default rateLimit({",
+    "  window: '10s',",
+    "  max: 5,",
+    "  trustProxy: true,",
+    "  message: 'Slow down: five requests per ten seconds.',",
+    "});",
     "",
   ].join('\n'));
   await writeFile(feat('rate-limit', 'route.ts'), [

package/lib/create.js

@@ -476,6 +476,41 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // @webjsdev/core, not the kit), and the
       // CLI resolves @webjsdev/ui from its own install.
     },
+    // Transitive-version floor for the browser test runner (#1418). Without
+    // this, `npm audit` in a freshly created app reports 5 high-severity
+    // advisories the moment scaffolding finishes, all of them one advisory
+    // (GHSA-jmr9-qjv8-65gv, an unvalidated symlink path traversal in
+    // extract-zip) reached through one chain:
+    //
+    //   @web/test-runner -> @web/test-runner-chrome -> puppeteer-core@24
+    //     -> @puppeteer/browsers@2.13.2 -> extract-zip@2.0.1
+    //
+    // extract-zip has NO patched version (the advisory covers `*`, and 2.0.1
+    // is the newest release), so an override on extract-zip itself cannot fix
+    // anything. The fix sits one level up: @puppeteer/browsers@3 dropped
+    // extract-zip entirely (it unpacks with modern-tar), and puppeteer-core@25
+    // depends on that 3 line. puppeteer-core@24.43.1 pins @puppeteer/browsers
+    // EXACTLY ("2.13.2", no caret), so npm cannot dedupe its way out and an
+    // explicit override is the only lever.
+    //
+    // Nothing in a scaffolded app executes this code. The runner is a
+    // devDependency, and web-test-runner.config.js launches browsers through
+    // playwrightLauncher, so the puppeteer chrome launcher is dead weight that
+    // @web/test-runner pulls in unconditionally via its own hard dependency on
+    // @web/test-runner-chrome (there is no supported install without it).
+    //
+    // Caret, not an exact pin: this is a security FLOOR, so a generated app
+    // should pick up later 25.x patches. That is the opposite of the
+    // drizzle-orm reasoning above, where the exact pin is deliberate because
+    // the scaffold source is written against one rc API.
+    //
+    // Do NOT "fix" this by taking @web/test-runner@1, which is what
+    // `npm audit fix --force` proposes: its @web/test-runner-chrome@1 still
+    // declares puppeteer-core ^24, so the same vulnerable chain resolves and
+    // the audit stays red after a breaking major.
+    overrides: {
+      'puppeteer-core': '^25.7.0',
+    },
     // Dev + start task orchestration (#550). `webjs dev` / `webjs start` read
     // `before` and run it in-process, so `npm run dev` / `start` (thin aliases
     // above) behave identically. Both apply pending migrations via `webjs db

package/lib/doctor/codes.js

@@ -0,0 +1,66 @@
+/**
+ * `status` is what the CHECK found and never depends on config. `severity` is
+ * the EFFECTIVE level the result contributes after the app's gate is applied,
+ * attached by `applyDoctorPolicy` (the checks never set it). `bestEffort` marks
+ * a result that reports "could not check" rather than a real finding, which is
+ * the one thing a gate can never escalate.
+ * @typedef {'pass' | 'warn' | 'fail'} DoctorStatus
+ * @typedef {'off' | 'warn' | 'error'} DoctorSeverity  a level a gate entry may DECLARE
+ * @typedef {'pass' | DoctorSeverity} DoctorLevel  the EFFECTIVE level of a result
+ * @typedef {{ name: string, code: string, status: DoctorStatus, message: string, fix?: string, bestEffort?: boolean, severity?: DoctorLevel }} DoctorResult
+ */
+
+/**
+ * The severity levels a `webjs.doctor.gate` entry may name, mirroring ESLint's
+ * three-level scale (its `off` / `warn` / `error`, which Next.js's
+ * `eslint-plugin-next` uses verbatim as a rule-id-keyed map). `off` is uniform:
+ * it silences ANY code, the two hard-fail checks included, exactly as ESLint
+ * lets any rule be turned off.
+ * @type {DoctorSeverity[]}
+ */
+export const DOCTOR_SEVERITIES = ['off', 'warn', 'error'];
+
+/**
+ * Stable machine-readable code per check (#975), so an agent consuming
+ * `webjs doctor --json` branches on the failure KIND, not the human message
+ * text (which is free to change). The `name` stays the display identity (some
+ * are kebab-case, two are prose); the `code` is the durable contract, a
+ * SCREAMING_SNAKE_CASE constant that never changes for a given check. Attached
+ * centrally in `runDoctorChecks` so every check function stays focused on its
+ * own logic. Mirrors Remix's `DoctorFindingCode` enum (its `doctor/types.ts`).
+ *
+ * Keyed by each check's `name`. A missing entry falls back to a name-derived
+ * code (see `codeForName`), but every shipped check is listed here explicitly
+ * and a drift test asserts each result carries one of these codes.
+ * @type {Record<string, string>}
+ */
+export const DOCTOR_CODES = {
+  'node-version': 'NODE_VERSION',
+  'tsconfig-erasable': 'TSCONFIG_ERASABLE',
+  'env-drift': 'ENV_DRIFT',
+  'vendor-pin': 'VENDOR_PIN',
+  'vendor-gitignore': 'VENDOR_GITIGNORE',
+  'webjs-versions': 'WEBJS_VERSIONS',
+  'framework-resolve': 'FRAMEWORK_RESOLVE',
+  'importmap-coherence': 'IMPORTMAP_COHERENCE',
+  'git-hook': 'GIT_HOOK',
+  'Page/layout elision (carrier hygiene)': 'ELISION_CARRIERS',
+  'Component elision (what the browser drops)': 'ELISION_COMPONENTS',
+  'Static build outputs (dev.regenerate freshness)': 'STATIC_ASSET_FRESHNESS',
+  'Asset urls (unmarked stylesheet links)': 'UNMARKED_ASSET_LINKS',
+};
+
+/**
+ * The stable code for a check name: the explicit `DOCTOR_CODES` entry, else a
+ * best-effort derivation (uppercased, non-alphanumerics collapsed to `_`) so a
+ * newly-added check that forgets its map entry still gets a non-empty code.
+ * @param {string} name
+ * @returns {string}
+ */
+export function codeForName(name) {
+  return DOCTOR_CODES[name] || name.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+
+/**
+ * @typedef {{ gate: Record<string, DoctorSeverity>, unknownCodes: string[], badSeverities: Array<{ code: string, value: unknown }>, malformed: Array<{ path: string, value: unknown }>, unknownKeys: string[] }} DoctorPolicy
+ */

package/lib/doctor/manifest.js

@@ -0,0 +1,161 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+/**
+ * Compare an installed version against a semver range PRAGMATICALLY (no semver
+ * dependency). Supports the common scaffold shapes: `latest` / `*` / `workspace:*`
+ * (any installed version satisfies), an exact `1.2.3`, and a caret `^1.2.3`
+ * (installed must be >= the floor AND share the same major, with major 0 also
+ * pinning the minor, matching npm caret semantics). An unrecognized range is
+ * treated as "cannot statically verify" (returns null), so the caller does not
+ * warn on a shape it does not understand.
+ * @param {string} installed
+ * @param {string} range
+ * @returns {boolean | null}
+ */
+export function satisfiesRange(installed, range) {
+  if (!installed) return null;
+  const r = String(range).trim();
+  if (r === 'latest' || r === '*' || r === '' || r.startsWith('workspace:')) return true;
+  const parse = (v) => {
+    const m = String(v).match(/(\d+)\.(\d+)\.(\d+)/);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  };
+  const inst = parse(installed);
+  if (!inst) return null;
+  if (/^\d+\.\d+\.\d+$/.test(r)) {
+    const exact = parse(r);
+    return exact ? inst[0] === exact[0] && inst[1] === exact[1] && inst[2] === exact[2] : null;
+  }
+  if (r.startsWith('^')) {
+    const floor = parse(r);
+    if (!floor) return null;
+    if (inst[0] !== floor[0]) return false;
+    // For 0.x, caret pins the minor too (^0.7.0 allows 0.7.x, not 0.8.0).
+    if (floor[0] === 0 && inst[1] !== floor[1]) return false;
+    const cmp =
+      inst[0] !== floor[0] ? inst[0] - floor[0] :
+      inst[1] !== floor[1] ? inst[1] - floor[1] :
+      inst[2] - floor[2];
+    return cmp >= 0;
+  }
+  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>}
+ */
+export 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}
+ */
+export 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('; ');
+}
+
+/**
+ * Read a dependency's INSTALLED version as resolved FROM `appDir`, or null when
+ * it does not resolve there at all.
+ *
+ * Node's own resolver is the ground truth here, not a directory read. The check
+ * this serves asks "would this app resolve this dependency at runtime, and at
+ * what version", and Node's resolution algorithm IS that question's definition,
+ * so anything re-implementing it can only be a worse approximation. Asking Node
+ * handles workspace hoisting (the bug this fixes: under npm workspaces the
+ * `@webjsdev/*` deps hoist to the ROOT node_modules, so an app subdirectory has
+ * no local copy and a per-app `node_modules/<dep>/package.json` read reported
+ * every declared dep missing on a healthy install), symlinked workspace links,
+ * nested non-hoisted trees, and `package.json` `imports`, for free and for ever.
+ *
+ * The direct `<dep>/package.json` resolve is attempted FIRST because a package
+ * may declare no main entry at all: `@webjsdev/cli` is bin-only (no `main`, no
+ * `exports`), so `require.resolve('@webjsdev/cli')` throws MODULE_NOT_FOUND.
+ * The ERR_PACKAGE_PATH_NOT_EXPORTED fallback exists because a package may lock
+ * its manifest out of its `exports` map: `@webjsdev/server` exports only `.`,
+ * `./check`, `./testing`, and `./webjs-config.schema.json`, so the direct
+ * manifest resolve is refused and the main entry plus a bounded walk up to the
+ * package root is the way in. Neither strategy alone resolves all four
+ * `@webjsdev/*` packages; both halves are required.
+ *
+ * Local rather than `getPackageVersion` from `@webjsdev/server` for two reasons.
+ * Doctor must stay usable when the framework does not resolve from the app dir
+ * at all, which is the #954 fresh-worktree case doctor exists to diagnose, so
+ * this check cannot import the server (the same argument `frameworkResolves`
+ * below already follows). And `getPackageVersion` resolves the main entry only,
+ * so it returns null for a bin-only package, which would leave `@webjsdev/cli`
+ * reported missing: the same false positive with more machinery.
+ *
+ * Pinned by the workspace, bin-only, and exports-locked fixtures in
+ * `test/cli/doctor.test.mjs`.
+ * @param {string} dep package name, e.g. `@webjsdev/server`
+ * @param {string} appDir directory to anchor resolution at
+ * @returns {Promise<string|null>} the installed version, or null when unresolvable
+ */
+export async function readInstalledVersion(dep, appDir) {
+  // The base file need not exist; createRequire only uses it to anchor the
+  // node_modules lookup at appDir.
+  const require = createRequire(join(appDir, '__webjs_resolve_probe__.js'));
+  let manifestPath = null;
+  try {
+    manifestPath = require.resolve(dep + '/package.json');
+  } catch (err) {
+    if (err?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') return null;
+    let entry;
+    try {
+      entry = require.resolve(dep);
+    } catch {
+      return null;
+    }
+    let dir = dirname(entry);
+    for (let i = 0; i < 12; i++) {
+      const candidate = join(dir, 'package.json');
+      if (existsSync(candidate)) {
+        manifestPath = candidate;
+        break;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    if (!manifestPath) return null;
+  }
+  try {
+    return JSON.parse(await readFile(manifestPath, 'utf8')).version || null;
+  } catch {
+    return null;
+  }
+}

package/lib/doctor/policy.js

@@ -0,0 +1,124 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DOCTOR_CODES, DOCTOR_SEVERITIES } from './codes.js';
+
+/**
+ * @typedef {import('./codes.js').DoctorSeverity} DoctorSeverity
+ * @typedef {import('./codes.js').DoctorLevel} DoctorLevel
+ * @typedef {import('./codes.js').DoctorResult} DoctorResult
+ * @typedef {{ gate: Record<string, DoctorSeverity>, unknownCodes: string[], badSeverities: Array<{ code: string, value: unknown }>, malformed: Array<{ path: string, value: unknown }>, unknownKeys: string[] }} DoctorPolicy
+ */
+
+/** A plain JSON object (not null, not an array), the only shape the gate accepts. */
+function isPlainObject(v) {
+  return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Read the app's per-check severity policy out of `package.json`
+ * `webjs.doctor.gate` (#1257). PURE: it reads one file and returns data, and
+ * the caller (the CLI) decides what to do about a problem.
+ *
+ * `gate` keeps only WELL-FORMED entries, so a caller can fold it over the
+ * results without re-validating. Everything rejected is reported separately:
+ * a key that is not a value of `DOCTOR_CODES` lands in `unknownCodes`, a value
+ * outside `DOCTOR_SEVERITIES` in `badSeverities`, a wrong SHAPE (a non-object
+ * `doctor` or `gate`) in `malformed`, and a misspelled sibling of `gate` such
+ * as `gates` in `unknownKeys`. All four are surfaced as a hard error by the
+ * CLI rather than skipped.
+ *
+ * The shape check matters as much as the per-entry one, and is the easier half
+ * to leave out. A gate that FAILS OPEN is the one outcome this mechanism cannot
+ * afford: `"gate": "error"` or a misspelled `"gates": {...}` would leave CI
+ * un-gated while the package.json looks gated, which is strictly worse than
+ * having no gate at all, since nobody goes looking. The JSON Schema catches
+ * these in an editor, but it is editor-only, so it can never be the enforcement.
+ *
+ * A missing package.json, a missing block, or unparseable JSON is an EMPTY
+ * policy with no problems: an app that declares nothing behaves exactly as it
+ * did before the gate existed. Unparseable JSON in particular is deliberately
+ * not an error here, since `checkWebjsVersions` already reports that condition
+ * and doctor must never crash on a broken app file.
+ *
+ * @param {string} appDir
+ * @returns {DoctorPolicy}
+ */
+export function readDoctorPolicy(appDir) {
+  /** @type {DoctorPolicy} */
+  const empty = { gate: {}, unknownCodes: [], badSeverities: [], malformed: [], unknownKeys: [] };
+  let raw;
+  try {
+    raw = readFileSync(join(appDir, 'package.json'), 'utf8');
+  } catch {
+    return empty;
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch {
+    return empty;
+  }
+  const doctor = pkg?.webjs?.doctor;
+  if (doctor === undefined) return empty;
+  if (!isPlainObject(doctor)) return { ...empty, malformed: [{ path: 'webjs.doctor', value: doctor }] };
+
+  /** @type {DoctorPolicy} */
+  const policy = { gate: {}, unknownCodes: [], badSeverities: [], malformed: [], unknownKeys: [] };
+  // A misspelled sibling (`gates`) would otherwise be dropped in silence, which
+  // is the fail-open case. `gate` is the only key this block accepts.
+  for (const key of Object.keys(doctor)) {
+    if (key !== 'gate') policy.unknownKeys.push(`webjs.doctor.${key}`);
+  }
+  const declared = doctor.gate;
+  if (declared !== undefined && !isPlainObject(declared)) {
+    policy.malformed.push({ path: 'webjs.doctor.gate', value: declared });
+  }
+  if (!isPlainObject(declared)) return policy;
+
+  const known = new Set(Object.values(DOCTOR_CODES));
+  for (const [code, value] of Object.entries(declared)) {
+    if (!known.has(code)) {
+      policy.unknownCodes.push(code);
+      continue;
+    }
+    if (typeof value !== 'string' || !DOCTOR_SEVERITIES.includes(/** @type {DoctorSeverity} */ (value))) {
+      policy.badSeverities.push({ code, value });
+      continue;
+    }
+    policy.gate[code] = /** @type {DoctorSeverity} */ (value);
+  }
+  return policy;
+}
+
+/**
+ * Fold a severity `gate` over check results, returning a NEW array whose
+ * results each carry the EFFECTIVE level they contribute (#1257). PURE: the
+ * input array and its results are never mutated.
+ *
+ * `severity` is the effective level, not the declared one, which is why a
+ * PASSING check reports `'pass'` even when its code is gated `error`. A rule
+ * that did not fire contributes nothing, the same way ESLint puts severity on a
+ * message rather than on a rule that stayed quiet. It also keeps the obvious
+ * one-liner honest: `results.some((r) => r.severity === 'error')` is exactly
+ * "something fatal was found", with no passing-check false positive.
+ *
+ * The gate's one hard limit is `bestEffort`: a result that could not check
+ * (a toolchain that would not load, a network that was unreachable) is CLAMPED
+ * to `warn` however loudly the gate declares its code. That is what lets this
+ * repo's required CI job run a check whose live resolve touches jspm without
+ * an outage there ever redding an unrelated pull request.
+ *
+ * @param {DoctorResult[]} results
+ * @param {Record<string, DoctorSeverity>} [gate]  well-formed entries only (see readDoctorPolicy)
+ * @returns {DoctorResult[]}
+ */
+export function applyDoctorPolicy(results, gate = {}) {
+  return results.map((r) => {
+    if (r.status === 'pass') return { ...r, severity: /** @type {DoctorLevel} */ ('pass') };
+    const declared = gate[r.code];
+    const fallback = r.status === 'fail' ? 'error' : 'warn';
+    let severity = /** @type {DoctorSeverity} */ (declared || fallback);
+    if (r.bestEffort && severity === 'error') severity = 'warn';
+    return { ...r, severity };
+  });
+}

package/lib/doctor/probes/elision.js

@@ -0,0 +1,111 @@
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * Advisory (#646): name why a page/layout SHIPS its module to the browser
+ * instead of being elided. A page/layout that is a pure carrier (import-only
+ * #605 / inert #179) stays out of the browser; one that ships whole is pinned
+ * by a specific client-effecting NON-component on a component-free path from it, #963 (a util touching
+ * a client global, a module-scope side effect, a bare side-effect import) or by
+ * its own client work. This turns that invisible #605/#179 regression into a
+ * named line. WARN only: a page legitimately MAY ship, and the analyser is
+ * biased toward shipping by design (server AGENTS invariant 7), so this is a
+ * "you may not have intended this" hint, never a hard fail.
+ * @param {Promise<any|null>} elisionPromise  the ONE shared report (#1308)
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkElisionCarriers(elisionPromise) {
+  const name = 'Page/layout elision (carrier hygiene)';
+  const report = await elisionPromise;
+  if (!report) {
+    // Analysis unavailable (no app, malformed, server import failed): no advice.
+    return { name, status: 'pass', message: 'not analysed (no routable app or analysis unavailable)' };
+  }
+  if (!report.analysed) {
+    return { name, status: 'pass', message: 'not analysed (no routable app, or elision is disabled)' };
+  }
+  // Paths and reasons arrive app-relative from `analyzeAppElision` (#1308).
+  const shipped = report.routeModules.filter((r) => r.verdict === 'shipped');
+  if (shipped.length === 0) {
+    return { name, status: 'pass', message: 'every page/layout is elided (a pure import-only or inert carrier)' };
+  }
+  // Name the FIRST client-effecting blocker (there may be more than one; the
+  // module stays shipped until every such blocker is moved out).
+  const lines = shipped.map(({ file, blocker, reason }) =>
+    blocker
+      ? `${file} ships whole. Its first client-effecting blocker is ${blocker}, which ${reason} and is not a component`
+      : `${file} ships whole because it ${reason}`,
+  );
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${shipped.length} page/layout module(s) ship to the browser instead of being elided:\n` +
+      lines.map((l) => `    ${l}`).join('\n'),
+    fix: 'Move the client work out of the page/layout closure (into a component, or a .server module reached through an action) so the carrier can be elided, or accept that it ships. See references/components.md in the skill.',
+  };
+}
+
+/**
+ * The OTHER direction of the elision verdict (#1308): which COMPONENT modules
+ * the browser never downloads. `checkElisionCarriers` above reports the benign
+ * over-ship direction; this one reports what was DROPPED, which is where a
+ * wrong verdict silently costs an app its interactivity.
+ *
+ * Pass-only except for orphans, deliberately. An elided component is the
+ * DESIRED outcome, so warning on one would fire on every healthy app and train
+ * the reader to skip doctor output. The passing message carries the elided
+ * inventory instead, which makes it the discovery surface, while `webjs
+ * elision` is the detail surface. The one always-wrong condition is an ORPHAN:
+ * a `class X extends WebComponent` with no literal-tag registration is
+ * invisible to the scanner, so it gets no verdict at all and `static
+ * interactive = true` cannot rescue it (nothing consults the component
+ * analyser for a component the scanner never saw). Never `fail`:
+ * an app that wants an orphan to break CI gates `ELISION_COMPONENTS` to
+ * `error` via `webjs.doctor.gate`.
+ *
+ * @param {Promise<any|null>} elisionPromise  the ONE shared report
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkElisionComponents(elisionPromise) {
+  const name = 'Component elision (what the browser drops)';
+  const report = await elisionPromise;
+  const notAnalysed = { name, status: /** @type {const} */ ('pass'), message: 'not analysed (no routable app or analysis unavailable)' };
+  if (!report) return notAnalysed;
+  if (!report.analysed) {
+    return report.skipped === 'elide-off'
+      ? { name, status: 'pass', message: 'elision is disabled (webjs.elide false or WEBJS_ELIDE), so every component module ships' }
+      : notAnalysed;
+  }
+  if (report.orphans.length > 0) {
+    const lines = report.orphans.map(({ file, className }) =>
+      `${className} in ${file} is never registered with a literal tag`,
+    );
+    return {
+      name,
+      status: 'warn',
+      message:
+        `${report.orphans.length} component class(es) get NO elision verdict:\n` +
+        lines.map((l) => `    ${l}`).join('\n') +
+        '\n    Either it has no registration call at all, or it registers a computed tag. The component '
+        + 'scanner matches only a literal tag, so either way it never sees the class: no elision verdict, no '
+        + 'registry entry, no preload hint, and `static interactive = true` cannot rescue it. With no '
+        + 'registration call the element never upgrades at all; with a computed tag it upgrades only while '
+        + 'its module still reaches the browser through an importer that ships.',
+      fix: 'Register it with a literal tag, Class.register(\'my-tag\') (invariant 3 already requires one), or delete the class if nothing uses it.',
+    };
+  }
+  const elided = report.components.filter((c) => c.verdict === 'elided');
+  const tags = elided.flatMap((c) => c.tags);
+  const shown = tags.slice(0, 8).join(', ');
+  const tail = tags.length > 8 ? `, +${tags.length - 8} more` : '';
+  return {
+    name,
+    status: 'pass',
+    message:
+      `${report.summary.elided} of ${report.summary.components} component module(s) are elided (never downloaded)` +
+      (tags.length ? `: ${shown}${tail}` : '') +
+      '. Run `webjs elision` for the full verdict.',
+  };
+}

package/lib/doctor/probes/env.js

@@ -0,0 +1,53 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseEnvKeys } from '../util.js';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * CHECK 3, .env presence + drift vs .env.example. WARN-level only (a missing
+ * env var is the app's runtime problem, not a toolchain crash). When no
+ * `.env.example`, PASS (nothing to compare). When `.env.example` exists but
+ * `.env` is absent, WARN to copy it. Otherwise WARN listing any example key
+ * missing from `.env`, else PASS.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkEnv(appDir) {
+  const examplePath = join(appDir, '.env.example');
+  if (!existsSync(examplePath)) {
+    return {
+      name: 'env-drift',
+      status: 'pass',
+      message: 'No .env.example to compare against.',
+    };
+  }
+  const exampleKeys = parseEnvKeys(await readFile(examplePath, 'utf8'));
+  const envPath = join(appDir, '.env');
+  if (!existsSync(envPath)) {
+    return {
+      name: 'env-drift',
+      status: 'warn',
+      message: '.env.example exists but .env does not.',
+      fix: 'Copy it: cp .env.example .env  (then fill in the values).',
+    };
+  }
+  const envKeys = parseEnvKeys(await readFile(envPath, 'utf8'));
+  const missing = [...exampleKeys].filter((k) => !envKeys.has(k));
+  if (missing.length === 0) {
+    return {
+      name: 'env-drift',
+      status: 'pass',
+      message: `.env has all ${exampleKeys.size} key(s) declared in .env.example.`,
+    };
+  }
+  return {
+    name: 'env-drift',
+    status: 'warn',
+    message: `.env is missing ${missing.length} key(s) from .env.example: ${missing.join(', ')}.`,
+    fix: 'Add the missing key(s) to .env (see .env.example for the expected names).',
+  };
+}