@webjsdev/cli 0.10.50 → 0.10.51

package/lib/doctor.js

@@ -6,7 +6,8 @@
  * Node 24+ strip-types floor, the `erasableSyntaxOnly` TS flag, importmap pin
  * freshness, env drift vs `.env.example`, `@webjsdev/*` version coherence,
  * whether the framework even resolves from the app dir (the fresh-git-worktree
- * trap, #954), and the git pre-commit hook activation. `webjs doctor` verifies
+ * trap, #954), whether a route-module stylesheet link is content-hashed (#1095),
+ * and the git pre-commit hook activation. `webjs doctor` verifies
  * each one up front and prints pass/warn/fail with an actionable fix line.
  *
  * This module is PURE: `runDoctorChecks(appDir, opts?)` reads files (and, for
@@ -30,22 +31,52 @@
  *     missing/non-executable git hook.
  *   - 'pass' is the green path.
  *
- * Every NETWORK touch (only the vendor-pin freshness check) is BEST-EFFORT: a
- * fetch failure is a WARN ("could not check, network"), never a hard fail and
- * never a throw that crashes the command. Network is flaky, and a doctor that
- * fails CI because npm was briefly unreachable is worse than useless.
+ * Every NETWORK touch (the vendor-pin freshness check, plus the live resolve in
+ * the importmap-coherence check) is BEST-EFFORT: a fetch failure is a WARN
+ * ("could not check, network"), never a hard fail and never a throw that
+ * crashes the command. Network is flaky, and a doctor that fails CI because npm
+ * was briefly unreachable is worse than useless. A result that reports "could
+ * not check" rather than a real finding carries `bestEffort: true`, and that
+ * flag is what the severity gate below reads to CLAMP it: an app may declare a
+ * code fatal, but an outage still cannot red its CI.
+ *
+ * SEVERITY POLICY (#1257) is CONFIG, not a flag, and lives one layer up. The
+ * checks below stay policy-unaware; `readDoctorPolicy(appDir)` reads the app's
+ * `webjs.doctor.gate` map out of package.json and `applyDoctorPolicy` folds it
+ * over the results, attaching the EFFECTIVE severity each one contributes. So a
+ * project declares which health signals it treats as fatal in ONE place that
+ * travels with the repo, and its CI workflow, its `npm run doctor`, and an
+ * agent's `--json` loop all read that one policy. `--strict` stays what it is:
+ * the blunt "every warning is fatal" switch, layered on top.
  */
 
-import { existsSync, statSync, readdirSync } from 'node:fs';
+import { existsSync, statSync, readdirSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { createRequire } from 'node:module';
 import { checkNodeInline } from './node-preflight.js';
 
 /**
+ * `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 {{ name: string, code: string, status: DoctorStatus, message: string, fix?: string }} DoctorResult
+ * @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
@@ -73,6 +104,7 @@ export const DOCTOR_CODES = {
   'git-hook': 'GIT_HOOK',
   'Page/layout elision (carrier hygiene)': 'ELISION_CARRIERS',
   'Static build outputs (dev.regenerate freshness)': 'STATIC_ASSET_FRESHNESS',
+  'Asset urls (unmarked stylesheet links)': 'UNMARKED_ASSET_LINKS',
 };
 
 /**
@@ -86,6 +118,124 @@ 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
+ */
+
+/** 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 };
+  });
+}
+
 /**
  * Read the CLI package's own `engines.node` so the required Node major lives in
  * one place (mirrors how `bin/webjs.js` sources it). Falls back to `>=24.0.0`.
@@ -321,6 +471,8 @@ async function checkVendorPin(appDir, opts) {
       return {
         name: 'vendor-pin',
         status: 'warn',
+        // "Could not check", not a finding: never escalatable by a gate.
+        bestEffort: true,
         message: 'Could not load the vendor toolchain to check pin freshness.',
         fix: 'Run `npm install` so @webjsdev/server is available, then re-run `webjs doctor`.',
       };
@@ -348,6 +500,7 @@ async function checkVendorPin(appDir, opts) {
     return {
       name: 'vendor-pin',
       status: 'warn',
+      bestEffort: true,
       message: 'Could not check pin freshness (network unreachable or registry error).',
       fix: 'Re-run `webjs doctor` when connectivity is back, or run `webjs vendor outdated`.',
     };
@@ -577,6 +730,7 @@ async function checkImportmapCoherence(appDir, opts) {
       return {
         name: 'importmap-coherence',
         status: 'warn',
+        bestEffort: true,
         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`.',
       };
@@ -670,6 +824,7 @@ async function checkImportmapCoherence(appDir, opts) {
     return {
       name: 'importmap-coherence',
       status: 'warn',
+      bestEffort: true,
       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`.',
     };
@@ -967,6 +1122,322 @@ async function checkStaticAssetFreshness(appDir) {
   };
 }
 
+// Directories the route-module walk never descends into (deps, VCS, framework
+// and build caches). Mirrors FRESHNESS_IGNORE; kept separate so either walk can
+// change its exclusions without silently moving the other.
+const ROUTE_WALK_IGNORE = new Set(['node_modules', '.git', '.webjs', 'dist', '.next', 'coverage']);
+
+/**
+ * A route module that renders markup on the server, which is where `asset()`
+ * belongs. Page and layout are the common case, but the BOUNDARY modules matter
+ * too and are easy to miss: `error` / `not-found` / `forbidden` / `unauthorized`
+ * / `loading` are always shipped and never elided, and `global-error` renders
+ * its OWN `<!doctype><html><head>` and is returned verbatim with no framework
+ * head splice, which makes it the likeliest place outside the root layout for
+ * an author to hand-write a stylesheet link.
+ * @type {RegExp}
+ */
+const ROUTE_MODULE_RE =
+  /^(?:page|layout|error|not-found|forbidden|unauthorized|loading)\.(?:js|ts|mjs|mts)$/;
+
+/**
+ * The two boundary stems `router.js` registers ONLY at the app root (both are
+ * guarded by `dir === '.'` there). A nested `app/admin/global-error.ts` is never
+ * in the route table and never renders, so scanning one would advise on dead
+ * code, the same defect the `_private` skip exists to avoid.
+ * @type {RegExp}
+ */
+const ROOT_ONLY_MODULE_RE = /^(?:global-error|global-not-found)\.(?:js|ts|mjs|mts)$/;
+
+/**
+ * One whole `<link …>` tag. QUOTE-AWARE (`(?:[^>"']|"[^"]*"|'[^']*')*`), the
+ * same shape `ssr.js`'s hoist scanner uses, so a `>` inside a quoted attribute
+ * value cannot terminate the tag early.
+ * @type {RegExp}
+ */
+const LINK_TAG_RE = /<link\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi;
+
+/**
+ * One attribute inside a tag: a name, then optionally `=` and a double-quoted,
+ * single-quoted, or unquoted value. Matching attributes as WHOLE units is what
+ * makes the scan correct, because each quoted value is consumed in one step and
+ * can therefore never be re-scanned as if it contained an attribute of its own.
+ * @type {RegExp}
+ */
+const ATTR_RE = /([a-zA-Z_:][-\w:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+
+/**
+ * Parse a tag's attributes into a lowercased-name map. The value is `null` for a
+ * valueless attribute and carries a `quoted` flag, since this check treats an
+ * UNQUOTED href (a template hole) as undecidable rather than as a path.
+ * @param {string} tag
+ * @returns {Map<string, { value: string | null, quoted: boolean }>}
+ */
+function parseTagAttrs(tag) {
+  /** @type {Map<string, { value: string | null, quoted: boolean }>} */
+  const attrs = new Map();
+  // Skip the tag name itself so `link` is not read as an attribute.
+  const body = tag.replace(/^<[a-zA-Z_:][-\w:.]*/, '');
+  ATTR_RE.lastIndex = 0;
+  for (const m of body.matchAll(ATTR_RE)) {
+    const name = m[1].toLowerCase();
+    if (attrs.has(name)) continue; // first wins, as in HTML parsing
+    const quoted = m[2] !== undefined || m[3] !== undefined;
+    const value = m[2] ?? m[3] ?? m[4] ?? null;
+    attrs.set(name, { value, quoted });
+  }
+  return attrs;
+}
+
+/**
+ * Whether a parsed `<link>` is an unmarked stylesheet, and if so its href.
+ *
+ * Attribute PARSING rather than a lookahead over the raw tag is load-bearing,
+ * not tidiness. A scan that merely looks ahead for `rel=…stylesheet` anywhere in
+ * the tag matches the string inside ANOTHER attribute's value, which flags the
+ * two shapes this check most needs to leave alone: the canonical async-CSS
+ * `<link rel="preload" as="style" href="/public/app.css" onload="this.rel='stylesheet'">`
+ * (where the advised `asset()` fix would actively BREAK the preload, since the
+ * versioned hint could then never match the unversioned request), and a
+ * `data-rel="stylesheet"` sitting on a `rel="icon"`. Reading real attributes
+ * makes `rel` mean the `rel` attribute and nothing else.
+ *
+ * Returns the href only when every condition holds:
+ *   - `rel` is a token list CONTAINING `stylesheet` (so `rel="preload"` with an
+ *     onload swap, and `rel="icon"`, are both out).
+ *   - `href` is QUOTED. An unquoted value is a template hole
+ *     (`href=${asset('/public/app.css')}`), undecidable from source, and is
+ *     exactly the shape the marked form uses.
+ *   - the path is under `/public/` (after the app's `webjs.basePath` is
+ *     stripped, since under a sub-path deploy the author writes the prefix
+ *     themselves and `resolveAssetUrl` strips it before its own `public/` gate).
+ *   - `resolveAssetUrl` would actually fingerprint it. It returns a path
+ *     carrying a QUERY or a `..` unchanged, so wrapping one in `asset()` is a
+ *     runtime NO-OP: the author does the work and the url they ship is
+ *     byte-identical. Advising it would be advising a change that buys nothing.
+ *     A hand-rolled `?v=` cache-buster is exactly what an author who has not
+ *     adopted `asset()` is most likely to have written, so this is the common
+ *     case, not a corner. (The warning itself would clear, since this check
+ *     reads the SOURCE shape and a wrapped href is an unquoted hole. Clearing a
+ *     warning without improving the caching is the outcome to avoid.)
+ *
+ * @param {string} tag
+ * @param {string} basePath  the app's normalized `webjs.basePath` (`''` at root)
+ * @returns {string | null}
+ */
+function unmarkedStylesheetHref(tag, basePath = '') {
+  const attrs = parseTagAttrs(tag);
+  const rel = attrs.get('rel');
+  if (!rel || !rel.value) return null;
+  if (!rel.value.toLowerCase().split(/\s+/).includes('stylesheet')) return null;
+  const href = attrs.get('href');
+  if (!href || !href.quoted || !href.value) return null;
+  const url = href.value;
+  if (url[0] !== '/' || url[1] === '/') return null;
+  // Mirror `resolveAssetUrl`'s refusals IN ITS ORDER, so every flagged href is
+  // one `asset()` can actually fingerprint. It strips the base path, cuts at
+  // `?` / `#`, DECODES, and only then tests `..` and the `public/` prefix.
+  // Testing the raw value instead disagrees at both ends: `/public/%2e%2e/x`
+  // would be flagged although wrapping it changes nothing, and
+  // `/%70ublic/app.css` would be skipped although `asset()` fingerprints it.
+  let probe = url;
+  if (basePath && probe.startsWith(basePath + '/')) probe = probe.slice(basePath.length);
+  const cuts = [probe.indexOf('?'), probe.indexOf('#')].filter((i) => i !== -1);
+  let decoded = probe.slice(0, cuts.length ? Math.min(...cuts) : probe.length);
+  try { decoded = decodeURIComponent(decoded); } catch { /* keep raw */ }
+  if (decoded.includes('..') || !decoded.startsWith('/public/')) return null;
+  // A query is refused outright (an author query may carry meaning we do not
+  // own, so `resolveAssetUrl` returns the url untouched); a `#fragment` is not,
+  // since it is split off and preserved.
+  const beforeFragment = url.indexOf('#') === -1 ? url : url.slice(0, url.indexOf('#'));
+  if (beforeFragment.includes('?')) return null;
+  return url;
+}
+
+/**
+ * The app's `webjs.basePath`, normalized to `''` (root mount) or `/segment…`.
+ *
+ * A faithful port of `normalizeBasePath` (`packages/server/src/base-path.js`),
+ * which is the source of truth: it trims, PREPENDS the leading slash (so the
+ * documented `"myapp"`, `"/myapp"` and `"/myapp/"` all normalize alike), and
+ * fails safe to `''` on a value that is not a plain same-origin prefix. Reading
+ * only `startsWith('/')` would leave this check inert for an app configured
+ * `"myapp"`, which is exactly the silently-inert case it exists to close.
+ *
+ * Ported rather than imported because that helper is not on `@webjsdev/server`'s
+ * public surface, and because doctor must stay usable when the framework does
+ * not resolve from the app dir at all (the #954 fresh-worktree case this same
+ * command exists to diagnose). `test/cli/doctor.test.mjs` pins the forms.
+ * @param {string} appDir
+ * @returns {Promise<string>}
+ */
+async function readAppBasePath(appDir) {
+  let raw;
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    raw = pkg?.webjs?.basePath;
+  } catch {
+    return '';
+  }
+  if (typeof raw !== 'string') return '';
+  let v = raw.trim();
+  if (v === '' || v === '/') return '';
+  // Not a plain same-origin path prefix: fail safe to no base path.
+  if (v.includes('..') || v.includes('://') || v.includes('\\') || /\s/.test(v)) return '';
+  // A network-path reference (`//host`) is rejected BEFORE leading slashes are
+  // collapsed, since collapsing would turn an origin escape into `/host`.
+  if (v.startsWith('//')) return '';
+  v = ('/' + v.replace(/^\/+/, '')).replace(/\/+$/, '');
+  return v === '' || v === '/' ? '' : v;
+}
+
+/**
+ * Whether the `<link>` tag at `idx` is commented out, so dead markup is never
+ * reported as a live finding.
+ *
+ * A DELIMITED comment is decided by an unclosed opener behind the tag. Neither
+ * `<!--` nor `/*` nests, so "nearest opener beats nearest closer" is exact, and
+ * it covers a multi-line block whose interior lines carry no marker of their
+ * own (what an editor's toggle-block-comment writes). A `//` has no closer, so
+ * it is decided from the tag's own line: a `//` inside an href later in the
+ * line cannot match, because the line does not START with it.
+ *
+ * Do NOT replace this with a lexer. Two attempts did, and both shipped bugs a
+ * stateless test cannot have: a line-blanking regex killed any line holding a
+ * protocol-relative url, and a quote-tracking walk inverted string/code
+ * polarity on a nested ``html`...` `` inside a `${}` hole (one quote char
+ * cannot model nesting), so an unbalanced apostrophe in template text
+ * desynchronized the rest of the file. This check does not need to lex
+ * JavaScript. If it ever genuinely does, export `redactStringsAndTemplates`
+ * from `@webjsdev/server` (`src/js-scan.js`, fuzz-tested differentially against
+ * a real TypeScript parse) rather than growing a third one here.
+ *
+ * Residual gap: a tag behind a `//` that trails real code on the same line
+ * stays reported. Rare, and it fails toward reporting rather than toward the
+ * silent inertness both lexers produced.
+ *
+ * @param {string} src
+ * @param {number} idx  index of the tag's `<`
+ * @returns {boolean}
+ */
+function isCommentedOut(src, idx) {
+  const before = src.slice(0, idx);
+  if (before.lastIndexOf('<!--') > before.lastIndexOf('-->')) return true;
+  if (before.lastIndexOf('/*') > before.lastIndexOf('*/')) return true;
+  const lineStart = before.lastIndexOf('\n') + 1;
+  return before.slice(lineStart).trimStart().startsWith('//');
+}
+
+/**
+ * Collect every `app/**` route module that renders markup, depth-first.
+ * Best-effort: an unreadable directory contributes nothing rather than throwing.
+ * @param {string} dir
+ * @param {string[]} [out]
+ * @returns {string[]}
+ */
+function collectRouteModules(dir, root = dir, out = []) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || ROUTE_WALK_IGNORE.has(e.name)) continue;
+    if (e.isSymbolicLink()) continue; // never follow: can cycle or escape into deps
+    // `_`-prefixed folders are PRIVATE: `router.js` drops any route whose
+    // directory has such a segment, so markup under one is never routed and
+    // never rendered. Advising on it would be advice about dead code.
+    if (e.isDirectory() && e.name.startsWith('_')) continue;
+    const abs = join(dir, e.name);
+    if (e.isDirectory()) collectRouteModules(abs, root, out);
+    else if (ROUTE_MODULE_RE.test(e.name)) out.push(abs);
+    else if (dir === root && ROOT_ONLY_MODULE_RE.test(e.name)) out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * ADVISORY (#1095): a route module hand-writes a `<link rel="stylesheet"
+ * href="/public/…">` without `asset()`, so the url is un-versioned and a deploy
+ * cannot bust a CDN's copy of it.
+ *
+ * The failure this names was caught in production on webjs.dev: the edge served
+ * a `public/tailwind.css` built BEFORE the deploy (`cf-cache-status: HIT`,
+ * `max-age=14400`) against post-deploy HTML, so the new page rendered with its
+ * content edge to edge and its grid collapsed, because the cached css was
+ * missing the arbitrary-value utilities that page introduced. It is invisible
+ * while a deploy only restyles existing classes and maximally visible the moment
+ * one adds a page using new utilities.
+ *
+ * Why this is an ADVISORY over the author's SOURCE rather than a rewrite of the
+ * framework's OUTPUT. The first attempt at the automatic form (#1196) matched
+ * urls in the assembled HTML, and two deep-review rounds found six major
+ * defects, five of them one bug: at that layer framework output and author data
+ * are indistinguishable, so the matcher kept editing things it did not own. That
+ * is why `asset()` (#1194) is opt-in, and it is what Rails (a
+ * `stylesheet_link_tag` helper over a digest manifest) and Remix (a hashed url
+ * from the build graph, surfaced through `links()`) both do: take the
+ * fingerprint from an authoritative source at the point the url is PRODUCED, and
+ * never rewrite a rendered document. The gap `asset()` leaves is purely
+ * ergonomic. In Rails the helper is the only idiomatic way to write the tag, so
+ * forgetting it is nearly impossible; in WebJs the `<link>` is hand-written HTML,
+ * so it is easy to omit. This check closes exactly that gap, at authoring time,
+ * where the author's meaning is unambiguous and nothing is rewritten.
+ *
+ * Scoped to `rel="stylesheet"` on purpose. An icon is a legitimate deliberate
+ * NON-mark (the website leaves its favicons bare so the SEO repo-health tests
+ * can parse the hrefs literally), and a `rel="preload"` must NOT be marked at
+ * all, since its versioned hint could never match the unversioned request a CSS
+ * `url()` actually makes. Flagging either would nag about a correct choice.
+ *
+ * WARN only: an un-versioned stylesheet still SERVES correctly, it just caches
+ * badly, and an app fronted by no CDN may not care.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkUnmarkedAssetLinks(appDir) {
+  const name = 'Asset urls (unmarked stylesheet links)';
+  const routeDir = join(appDir, 'app');
+  if (!existsSync(routeDir)) {
+    return { name, status: 'pass', message: 'no app/ directory to analyse' };
+  }
+  const basePath = await readAppBasePath(appDir);
+  const findings = [];
+  for (const file of collectRouteModules(routeDir)) {
+    let src;
+    try { src = await readFile(file, 'utf8'); } catch { continue; }
+    // Cheap bail before any tag scanning. Case-INSENSITIVE to match the tag
+    // regex: a file whose only link tag is written `<LINK …>` must still be
+    // scanned, or the scanner's own case-insensitivity is unreachable exactly
+    // where it is needed.
+    if (!/<link/i.test(src)) continue;
+    LINK_TAG_RE.lastIndex = 0;
+    for (const m of src.matchAll(LINK_TAG_RE)) {
+      const href = unmarkedStylesheetHref(m[0], basePath);
+      if (!href) continue;
+      // A commented-out tag emits nothing, so advising on it is advice about
+      // dead markup.
+      if (isCommentedOut(src, /** @type {number} */ (m.index))) continue;
+      // 1-indexed line of the match, for a jump-to reference.
+      const line = src.slice(0, m.index).split('\n').length;
+      findings.push({ file, line, href });
+    }
+  }
+  if (findings.length === 0) {
+    return { name, status: 'pass', message: 'every route-module stylesheet link is content-hashed (or has none)' };
+  }
+  const rel = (f) => relative(appDir, f) || f;
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${findings.length} stylesheet link(s) are served at an un-versioned url, so a deploy cannot bust a cached copy:\n` +
+      findings.map((f) => `    ${rel(f.file)}:${f.line} href="${f.href}"`).join('\n'),
+    fix:
+      "Wrap the path in asset(): `import { asset } from '@webjsdev/core'` then "
+      + '`<link rel="stylesheet" href=${asset(\'/public/app.css\')}>`. It appends a content hash in prod '
+      + '(the framework then serves that url immutable for a year) and is a no-op in dev and in the browser. '
+      + 'Call it inside the render function, not at module scope.',
+  };
+}
+
 /**
  * Probe whether `@webjsdev/core` resolves from `appDir`. Node resolution is
  * directory-relative, so this must probe FROM the app (not the CLI's own
@@ -1058,6 +1529,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     Promise.resolve(checkGitHook(appDir)),
     checkElisionCarriers(appDir),
     checkStaticAssetFreshness(appDir),
+    checkUnmarkedAssetLinks(appDir),
   ]);
   // Attach the stable machine code to every result (#975). Centralized here so
   // each check function stays free of the code-contract concern.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.50",
+  "version": "0.10.51",
   "type": "module",
-  "description": "webjs CLI - dev, start, create, db",
+  "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
     "webjs": "bin/webjs.js"
   },

package/templates/.agents/rules/workflow.md

@@ -50,7 +50,15 @@ Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
 2. Browser tests in `test/<feature>/browser/*.test.js` for hydration, DOM, slots,
    and the client router.
 3. Documentation stays in sync on the SAME PR as the code, never a follow-up.
-4. `npm run check` must pass.
+4. `npm run check` must pass (correctness), and so must `npm run doctor`
+   (project health). CI runs both. Doctor fails on whatever your `package.json`
+   `webjs.doctor.gate` marks `error`, which starts as the un-versioned
+   stylesheet link check, plus the two hard toolchain checks that default to
+   `error` with no gate entry at all: `NODE_VERSION` (the Node floor) and
+   `TSCONFIG_ERASABLE` (`erasableSyntaxOnly` missing from an existing
+   tsconfig), either of which would 500 the app at runtime. Everything else it
+   reports is a warning that cannot fail the build. Widen or narrow the gate in
+   `package.json` rather than in the workflow.
 5. Pre-merge self-review: before saying a PR is ready, run fresh-context review
    rounds until one round finds zero issues (minimum two rounds, rotate focus).
    Skip only for a one-line trivial change.