@webjsdev/cli 0.10.5 → 0.10.7

package/bin/webjs.js

@@ -42,6 +42,9 @@ const USAGE = `webjs commands:
   webjs start [--port 8080]                       Start production server (serves source directly, no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check                                     Run correctness checks on the app
+  webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, @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
                                                   (only 3 templates exist. default: full-stack with Prisma+SQLite)
                                                   Auto-runs the detected package manager's install in the new dir
@@ -277,6 +280,85 @@ async function main() {
       }
       break;
     }
+    case 'doctor': {
+      // Project-health checklist (#266). The checks are PURE (in lib/doctor.js);
+      // this branch only renders them and owns the exit code: non-zero iff any
+      // HARD check FAILS, so CI can gate on it. Warns are informational and do
+      // NOT fail the exit (env drift / pin staleness / version drift are the
+      // app's concern, not a broken toolchain).
+      const { runDoctorChecks } = await import('../lib/doctor.js');
+      const results = await runDoctorChecks(process.cwd());
+      const marker = { pass: '[pass]', warn: '[warn]', fail: '[fail]' };
+      console.log('webjs doctor: project-health checklist\n');
+      for (const r of results) {
+        console.log(`  ${marker[r.status]} ${r.name}`);
+        console.log(`    ${r.message}`);
+        if (r.fix && r.status !== 'pass') console.log(`    Fix: ${r.fix}`);
+        console.log();
+      }
+      const counts = results.reduce((acc, r) => {
+        acc[r.status] = (acc[r.status] || 0) + 1;
+        return acc;
+      }, /** @type {Record<string, number>} */ ({}));
+      const pass = counts.pass || 0;
+      const warn = counts.warn || 0;
+      const fail = counts.fail || 0;
+      console.log(`  ${pass} passed, ${warn} warning(s), ${fail} failed.`);
+      if (fail > 0) {
+        console.error(
+          `\nwebjs doctor: ${fail} hard check(s) failed. Fix the toolchain issue(s) above.`,
+        );
+        process.exit(1);
+      }
+      break;
+    }
+    case 'types': {
+      // Generate `.webjs/routes.d.ts` from the app's `app/` routes (#258),
+      // narrowing the @webjsdev/core `Route` href union + per-route `params`.
+      // Opt-in codegen: the static types in @webjsdev/core work without it
+      // (un-generated apps see `Route = string`).
+      const { generateRouteTypes } = await import('@webjsdev/server');
+      const { mkdir, writeFile } = await import('node:fs/promises');
+      const appDir = process.cwd();
+      const text = await generateRouteTypes(appDir);
+      const outDir = join(appDir, '.webjs');
+      await mkdir(outDir, { recursive: true });
+      const outFile = join(outDir, 'routes.d.ts');
+      await writeFile(outFile, text);
+      // Count the typed routes (each `WebjsRoutes` key is one route literal).
+      const count = (text.match(/^\s+".*": true;$/gm) || []).length;
+      console.log(
+        `webjs types: wrote .webjs/routes.d.ts (${count} route${count === 1 ? '' : 's'} typed). ` +
+        `Ensure tsconfig "include" lists ".webjs/routes.d.ts" so tsserver picks it up.`,
+      );
+      break;
+    }
+    case 'typecheck': {
+      // Type-check the app with the project's OWN tsc (it reads the app's
+      // tsconfig: strict + noEmit + erasableSyntaxOnly). The framework runs the
+      // standard compiler, it does not embed one. Extra args after `typecheck`
+      // pass through (e.g. `webjs typecheck --watch`). Exits non-zero on a type
+      // error, so it works as a CI gate and the scaffolded `typecheck` script.
+      const cwd = process.cwd();
+      const { createRequire } = await import('node:module');
+      let tscPath;
+      try {
+        const req = createRequire(join(cwd, 'package.json'));
+        tscPath = req.resolve('typescript/bin/tsc');
+      } catch {
+        console.error(
+          'webjs typecheck: TypeScript is not installed in this project.\n' +
+          'Install it with `npm install -D typescript`, then re-run `webjs typecheck`.',
+        );
+        process.exit(1);
+      }
+      const child = spawn(process.execPath, [tscPath, '--noEmit', ...rest], {
+        stdio: 'inherit',
+        cwd,
+      });
+      child.on('exit', (code) => process.exit(code ?? 1));
+      break;
+    }
     case 'create': {
       const name = rest[0];
       if (!name || name.startsWith('-')) {

package/lib/create.js

@@ -286,6 +286,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       'test:server': 'webjs test --server',
       'test:browser': 'webjs test --browser',
       check: 'webjs check',
+      typecheck: 'webjs typecheck',
+      // Onboarding/setup-verify: a contributor runs `npm run doctor` after
+      // cloning to assert the toolchain (Node floor, tsconfig flag, env drift,
+      // vendor pins, @webjsdev versions, git hook). Local tool, NOT a CI gate
+      // (its env-drift + network pin-freshness checks would make CI flaky).
+      doctor: 'webjs doctor',
       'db:migrate': 'prisma migrate dev',
       'db:generate': 'prisma generate',
       'db:studio': 'prisma studio',
@@ -298,6 +304,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     },
     devDependencies: {
       prisma: '^6.0.0',
+      // The TypeScript compiler, for `npm run typecheck` (webjs typecheck runs
+      // tsc --noEmit). Not needed at runtime (Node strips types in place), only
+      // to type-check the app.
+      typescript: '^5.6.0',
       '@web/test-runner': '^0.20.0',
       '@web/test-runner-playwright': '^0.11.0',
       'playwright': '^1.59.0',
@@ -346,6 +356,22 @@ export async function scaffoldApp(name, cwd, opts = {}) {
         { name: '@webjsdev/ts-plugin' },
       ],
     },
+    // `.webjs/routes.d.ts` is the OPT-IN generated route-types overlay (#258):
+    // run `webjs types` (or `webjs dev`, which emits it) to narrow the
+    // @webjsdev/core `Route` href union + per-route `params`. Listed in
+    // `include` so tsserver picks it up; it is gitignored (regenerated per
+    // machine), so a fresh clone runs `webjs dev` / `webjs types` to recreate
+    // it, and the static @webjsdev/core types work even when it is absent.
+    include: [
+      'app/**/*',
+      'components/**/*',
+      'modules/**/*',
+      'lib/**/*',
+      'middleware.js',
+      'middleware.ts',
+      '.webjs/routes.d.ts',
+    ],
+    exclude: ['node_modules', '.webjs/vendor', 'prisma/migrations'],
   }, null, 2) + '\n');
 
   // --- Templates (AGENTS.md, CONVENTIONS.md, CLAUDE.md, test files, Claude hooks) ---
@@ -397,6 +423,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // to main, mirroring the webjs framework's own CI.
     '.github/workflows/ci.yml',
     '.editorconfig',
+    // VS Code: associate the published webjs-config JSON Schema with the
+    // package.json `webjs` block, so an unknown / typo'd key (#259) is
+    // flagged natively in the editor instead of silently dropped.
+    '.vscode/settings.json',
     // Production / deploy scaffolding. `docker compose up --build` runs
     // the app locally with the same Dockerfile production builds from.
     'Dockerfile',

package/lib/doctor.js

@@ -0,0 +1,534 @@
+/**
+ * `webjs doctor`: a project-health checklist runner (issue #266).
+ *
+ * webjs has unusually many fragile preconditions, each an independent failure
+ * mode a contributor onboarding to an existing repo only hits at runtime: the
+ * Node 24+ strip-types floor, the `erasableSyntaxOnly` TS flag, importmap pin
+ * freshness, env drift vs `.env.example`, `@webjsdev/*` version coherence, 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
+ * the pin check, optionally the network), but NEVER calls `process.exit` and
+ * NEVER prints. The CLI (`bin/webjs.js`, `case 'doctor'`) renders the results
+ * and owns the exit code, which is what makes every check unit-testable in
+ * isolation against a tmp fixture appDir.
+ *
+ * HARD-FAIL vs WARN split (the CLI exits non-zero on any 'fail'):
+ *
+ *   - 'fail' is reserved for a genuinely-broken TOOLCHAIN that would crash or
+ *     500 at runtime, so CI can gate on it. Two checks can fail:
+ *       * Node version below the required major (the strip-types floor).
+ *       * `erasableSyntaxOnly` missing/false in an EXISTING tsconfig (non-erasable
+ *         TS would fail at strip time with a 500).
+ *   - 'warn' is for drift / preferences / best-effort signals that are the
+ *     app's own runtime concern, never a doctor hard-fail: a missing tsconfig
+ *     (a JS-only app legitimately has none), env drift, an outdated or
+ *     unverifiable vendor pin, a `@webjsdev/*` version drift or missing install,
+ *     and a 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.
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { checkNodeInline } from './node-preflight.js';
+
+/**
+ * @typedef {'pass' | 'warn' | 'fail'} DoctorStatus
+ * @typedef {{ name: string, status: DoctorStatus, message: string, fix?: string }} DoctorResult
+ */
+
+/**
+ * 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`.
+ * @param {string} cliDir  directory of THIS file's package (lib/ -> package root)
+ * @returns {Promise<string>}
+ */
+async function readEngines(cliDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(cliDir, '..', 'package.json'), 'utf8'));
+    return pkg?.engines?.node || '>=24.0.0';
+  } catch {
+    return '>=24.0.0';
+  }
+}
+
+/**
+ * Strip `//` line comments, block comments, and trailing commas from a JSONC
+ * string so a tsconfig (which permits all three) parses with `JSON.parse`.
+ * Deliberately simple: it does not honor comment-looking sequences inside
+ * string values, which is acceptable for a tsconfig (paths rarely contain `//`
+ * or block-comment markers, and the worst case is a parse failure the caller
+ * already degrades to a WARN).
+ * @param {string} text
+ * @returns {string}
+ */
+function stripJsonc(text) {
+  let out = '';
+  let inString = false;
+  let stringQuote = '';
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (inString) {
+      out += ch;
+      if (ch === '\\') {
+        // Copy the escaped char verbatim so an escaped quote does not end the string.
+        out += text[i + 1] || '';
+        i++;
+      } else if (ch === stringQuote) {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      stringQuote = ch;
+      out += ch;
+      continue;
+    }
+    if (ch === '/' && next === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      out += '\n';
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i++; // land on the '/'
+      continue;
+    }
+    out += ch;
+  }
+  // Drop trailing commas before } or ].
+  return out.replace(/,(\s*[}\]])/g, '$1');
+}
+
+/**
+ * Parse a `.env`-style file into the SET of KEY names it declares. A simple
+ * `KEY=value` line parse: comments (`#`) and blank lines are skipped, and only
+ * the key before the first `=` is taken (the value is irrelevant for drift).
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+function parseEnvKeys(text) {
+  const keys = new Set();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    let key = line.slice(0, eq).trim();
+    // Tolerate a leading `export ` (a common .env.example convention).
+    if (key.startsWith('export ')) key = key.slice('export '.length).trim();
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) keys.add(key);
+  }
+  return keys;
+}
+
+/**
+ * CHECK 1, Node version. HARD-FAIL when the running major is below the required
+ * major (the strip-types + recursive fs.watch floor). `opts.nodeVersion` lets a
+ * test inject the running version so the fail case is assertable without being
+ * on old Node.
+ * @param {string} cliDir
+ * @param {{ nodeVersion?: string }} opts
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkNode(cliDir, opts) {
+  const engines = await readEngines(cliDir);
+  const current = opts.nodeVersion || process.versions.node;
+  const r = checkNodeInline(current, engines);
+  if (r.ok) {
+    return {
+      name: 'node-version',
+      status: 'pass',
+      message: `Node ${r.current} satisfies the required Node ${r.requiredMajor}+.`,
+    };
+  }
+  return {
+    name: 'node-version',
+    status: 'fail',
+    message:
+      `Node ${r.current} is below the required Node ${r.requiredMajor}+. ` +
+      `webjs is buildless and relies on Node ${r.requiredMajor}'s built-in TypeScript ` +
+      `strip and recursive fs.watch.`,
+    fix: `Upgrade to Node ${r.requiredMajor}+ (see https://nodejs.org).`,
+  };
+}
+
+/**
+ * CHECK 2, tsconfig erasableSyntaxOnly. PASS when `true`; WARN when no tsconfig
+ * (a JS-only app legitimately has none) or the file is unparseable; HARD-FAIL
+ * when the file EXISTS but the flag is missing/false (non-erasable TS 500s at
+ * strip time).
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkTsconfig(appDir) {
+  const path = join(appDir, 'tsconfig.json');
+  if (!existsSync(path)) {
+    return {
+      name: 'tsconfig-erasable',
+      status: 'warn',
+      message: 'No tsconfig.json found. A JS-only app needs none; a TypeScript app requires one.',
+      fix: 'If this app uses TypeScript, add a tsconfig.json with "erasableSyntaxOnly": true.',
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(stripJsonc(await readFile(path, 'utf8')));
+  } catch {
+    return {
+      name: 'tsconfig-erasable',
+      status: 'warn',
+      message: 'tsconfig.json could not be parsed (even after stripping comments + trailing commas).',
+      fix: 'Fix the tsconfig.json syntax, then ensure "compilerOptions.erasableSyntaxOnly": true.',
+    };
+  }
+  const flag = parsed?.compilerOptions?.erasableSyntaxOnly;
+  if (flag === true) {
+    return {
+      name: 'tsconfig-erasable',
+      status: 'pass',
+      message: 'tsconfig.json sets "erasableSyntaxOnly": true.',
+    };
+  }
+  return {
+    name: 'tsconfig-erasable',
+    status: 'fail',
+    message:
+      'tsconfig.json is missing "compilerOptions.erasableSyntaxOnly": true. ' +
+      'Non-erasable TypeScript (enum, namespace, parameter properties, ...) 500s at strip time.',
+    fix: 'Set "compilerOptions": { "erasableSyntaxOnly": true } in tsconfig.json.',
+  };
+}
+
+/**
+ * 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>}
+ */
+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).',
+  };
+}
+
+/**
+ * CHECK 4, vendor pin freshness. Applies ONLY when a pin file exists. PASS/skip
+ * for an unpinned app (it resolves live, which is fine in dev). BEST-EFFORT +
+ * NETWORK-TOLERANT: any error (network, timeout) is a WARN "could not check",
+ * never a hard fail and never a throw. PASS when all pins current, WARN listing
+ * outdated packages otherwise.
+ *
+ * The vendor functions are injected via `opts.vendor` so a test can supply a
+ * stub without a real network call; absent the override, they are dynamically
+ * imported from `@webjsdev/server`.
+ * @param {string} appDir
+ * @param {{ vendor?: { hasVendorPin: (d: string) => boolean, findOutdated: (d: string) => Promise<Array<{ pkg: string, current: string, latest: string }>> } }} opts
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkVendorPin(appDir, opts) {
+  let vendor = opts.vendor;
+  if (!vendor) {
+    try {
+      const mod = await import('@webjsdev/server');
+      vendor = { hasVendorPin: mod.hasVendorPin, findOutdated: mod.findOutdated };
+    } catch {
+      return {
+        name: 'vendor-pin',
+        status: 'warn',
+        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`.',
+      };
+    }
+  }
+  let pinned = false;
+  try {
+    pinned = vendor.hasVendorPin(appDir);
+  } catch {
+    pinned = false;
+  }
+  if (!pinned) {
+    return {
+      name: 'vendor-pin',
+      status: 'pass',
+      message: 'No vendor pin file; the app resolves vendor imports live (fine in dev).',
+    };
+  }
+  let outdated;
+  try {
+    outdated = await vendor.findOutdated(appDir);
+  } catch {
+    // findOutdated is built to swallow fetch errors and return [], but guard
+    // anyway: a network check must NEVER throw out of doctor.
+    return {
+      name: 'vendor-pin',
+      status: 'warn',
+      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`.',
+    };
+  }
+  if (!Array.isArray(outdated) || outdated.length === 0) {
+    return {
+      name: 'vendor-pin',
+      status: 'pass',
+      message: 'All vendor pins are current.',
+    };
+  }
+  const list = outdated.map((o) => `${o.pkg} (${o.current} -> ${o.latest})`).join(', ');
+  return {
+    name: 'vendor-pin',
+    status: 'warn',
+    message: `${outdated.length} pinned package(s) are outdated: ${list}.`,
+    fix: 'Run `webjs vendor update` to re-pin to the latest versions.',
+  };
+}
+
+/**
+ * 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}
+ */
+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;
+}
+
+/**
+ * CHECK 5, @webjsdev/* version coherence. WARN-level only (a version drift is
+ * not a crash). Reads the app package.json `@webjsdev/*` ranges across
+ * dependencies + devDependencies, then for each reads the INSTALLED version from
+ * `node_modules/@webjsdev/<pkg>/package.json` and checks it satisfies the
+ * declared range. PASS when every @webjsdev dep is present + satisfied; WARN on
+ * a missing install or a range drift.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkWebjsVersions(appDir) {
+  const pkgPath = join(appDir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: 'No package.json found in this directory.',
+      fix: 'Run `webjs doctor` from the app root (where package.json lives).',
+    };
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+  } catch {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: 'package.json could not be parsed.',
+      fix: 'Fix the package.json syntax.',
+    };
+  }
+  const ranges = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const webjsDeps = Object.keys(ranges).filter((n) => n.startsWith('@webjsdev/'));
+  if (webjsDeps.length === 0) {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: 'No @webjsdev/* dependencies declared in package.json.',
+      fix: 'A webjs app depends on @webjsdev/core + @webjsdev/server (+ @webjsdev/cli).',
+    };
+  }
+  const missing = [];
+  const drift = [];
+  for (const dep of webjsDeps) {
+    const installedPkg = join(appDir, 'node_modules', dep, 'package.json');
+    if (!existsSync(installedPkg)) {
+      missing.push(dep);
+      continue;
+    }
+    let installedVersion = '';
+    try {
+      installedVersion = JSON.parse(await readFile(installedPkg, 'utf8')).version || '';
+    } catch {
+      missing.push(dep);
+      continue;
+    }
+    const ok = satisfiesRange(installedVersion, ranges[dep]);
+    // null = a range shape we cannot statically verify; do not warn on it.
+    if (ok === false) drift.push(`${dep}@${installedVersion} does not satisfy "${ranges[dep]}"`);
+  }
+  if (missing.length > 0) {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: `${missing.length} @webjsdev/* dependency not installed: ${missing.join(', ')}.`,
+      fix: 'Run `npm install` to install the declared dependencies.',
+    };
+  }
+  if (drift.length > 0) {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: `@webjsdev version drift: ${drift.join('; ')}.`,
+      fix: 'Run `npm install` to reconcile node_modules with the declared ranges.',
+    };
+  }
+  return {
+    name: 'webjs-versions',
+    status: 'pass',
+    message: `All ${webjsDeps.length} @webjsdev/* dependency satisfy their declared ranges.`,
+  };
+}
+
+/**
+ * CHECK 6 (optional), git pre-commit hook installed + executable. WARN when the
+ * repo is a git checkout but `.git/hooks/pre-commit` is absent or
+ * non-executable, since the test-gate / changelog hook would not fire. PASS when
+ * present + executable, or skip (PASS) when this is not a git checkout at all
+ * (an exported tarball, a non-repo dir). Respects a configured `core.hooksPath`
+ * is OUT of scope here: the common scaffold installs into `.git/hooks`, so this
+ * checks the default location and a configured path is the user's own concern.
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+function checkGitHook(appDir) {
+  const gitDir = join(appDir, '.git');
+  if (!existsSync(gitDir)) {
+    return {
+      name: 'git-hook',
+      status: 'pass',
+      message: 'Not a git checkout; no pre-commit hook expected.',
+    };
+  }
+  const hook = join(gitDir, 'hooks', 'pre-commit');
+  if (!existsSync(hook)) {
+    return {
+      name: 'git-hook',
+      status: 'warn',
+      message: 'No .git/hooks/pre-commit hook installed.',
+      fix: 'Install the project hooks (e.g. `npm install` runs the prepare step that wires them).',
+    };
+  }
+  let executable = false;
+  try {
+    // Owner-execute bit. On a checkout without exec bits (some Windows / CI
+    // setups) the hook will not run, so flag it.
+    executable = (statSync(hook).mode & 0o100) !== 0;
+  } catch {
+    executable = false;
+  }
+  if (!executable) {
+    return {
+      name: 'git-hook',
+      status: 'warn',
+      message: '.git/hooks/pre-commit exists but is not executable.',
+      fix: 'chmod +x .git/hooks/pre-commit',
+    };
+  }
+  return {
+    name: 'git-hook',
+    status: 'pass',
+    message: '.git/hooks/pre-commit is installed and executable.',
+  };
+}
+
+/**
+ * Run every doctor check against `appDir` and return the results. PURE: no
+ * printing, no `process.exit`; the CLI renders + decides the exit code.
+ *
+ * @param {string} appDir  the app directory to check (usually `process.cwd()`)
+ * @param {{
+ *   nodeVersion?: string,
+ *   cliDir?: string,
+ *   vendor?: { hasVendorPin: (d: string) => boolean, findOutdated: (d: string) => Promise<Array<{ pkg: string, current: string, latest: string }>> },
+ * }} [opts]  test-injection seams:
+ *   - `nodeVersion`: override the running Node version (asserts the fail case
+ *     without being on old Node);
+ *   - `cliDir`: directory of the CLI package whose `engines.node` sources the
+ *     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.
+ * @returns {Promise<DoctorResult[]>}
+ */
+export async function runDoctorChecks(appDir, opts = {}) {
+  const cliDir = opts.cliDir || new URL('.', import.meta.url).pathname;
+  const results = await Promise.all([
+    checkNode(cliDir, opts),
+    checkTsconfig(appDir),
+    checkEnv(appDir),
+    checkVendorPin(appDir, opts),
+    checkWebjsVersions(appDir),
+    Promise.resolve(checkGitHook(appDir)),
+  ]);
+  return results;
+}

package/lib/saas-template.js

@@ -173,58 +173,107 @@ export async function writeSaasFiles(appDir) {
     "",
   ].join('\n'));
 
-  // test/unit/auth.test.ts: minimal stub so the scaffold passes
-  // `webjs test` runs cleanly out of the
-  // box. The signup/current-user functions import from lib/prisma.server.ts
-  // and lib/auth.server.ts, both of which need `prisma generate` to have run before
-  // they can be imported, so we deliberately test only the runtime-
-  // dependency-free types.ts here. Replace with real tests once Prisma
-  // is set up (run `npm install && npx prisma migrate dev --name init`).
-  await writeFile(join(appDir, 'test', 'unit', 'auth.test.ts'), [
+  // test/auth/auth.test.ts: a REAL auth-flow test driven through the framework
+  // request pipeline with the @webjsdev/server test harness (createRequestHandler
+  // + the handle() helpers from @webjsdev/server/testing). It lives under the
+  // documented test/<feature>/ convention (test/auth/), not the old test/unit/
+  // path.
+  //
+  // Two layers, by DB availability:
+  //   - The protected-route gate (unauthenticated /dashboard -> 302 /login) runs
+  //     ALWAYS once the app modules import: auth() only reads a cookie, no DB
+  //     query. This is the headline security assertion and it is REAL.
+  //   - The signup -> login -> protected-route flow writes + reads a user, so it
+  //     needs Prisma generated AND migrated (`npm run db:generate` +
+  //     `npm run db:migrate`). When the Prisma client is not yet generated the
+  //     app modules can't import at all, so the whole suite skips with a clear
+  //     message instead of crashing. After you set up the DB it runs for real.
+  await mkdir(join(appDir, 'test', 'auth'), { recursive: true });
+  await writeFile(join(appDir, 'test', 'auth', 'auth.test.ts'), [
     "import { test } from 'node:test';",
     "import assert from 'node:assert/strict';",
+    "import { fileURLToPath } from 'node:url';",
+    "import { dirname, resolve } from 'node:path';",
+    "",
+    "import { createRequestHandler } from '@webjsdev/server';",
+    "import { testRequest, loginAndGetCookies, withSessionCookie } from '@webjsdev/server/testing';",
+    "",
+    "const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');",
+    "",
+    "// The auth pages + dashboard middleware import lib/prisma.server.ts, which",
+    "// imports @prisma/client. Until `npm run db:generate` (prisma generate) has",
+    "// run, that import is missing, so a request hitting those modules 500s. We",
+    "// detect that at the RESPONSE level (a 5xx on the dashboard) and SKIP with a",
+    "// clear message rather than reporting a misleading failure. After you run",
+    "//   npm install && npm run db:generate && npm run db:migrate",
+    "// every assertion below runs for real.",
+    "process.env.DATABASE_URL ||= 'file:./dev.db';",
+    "process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';",
+    "",
+    "function makeHandler() {",
+    "  // createRequestHandler builds lazily, so it succeeds even before prisma is",
+    "  // generated; the missing dependency only surfaces when a request reaches",
+    "  // the prisma-importing module. That is why readiness is probed per-response.",
+    "  return createRequestHandler({ appDir, dev: true });",
+    "}",
     "",
-    "import type { User, ActionResult } from '../../modules/auth/types.ts';",
-    "",
-    "test('User shape: id is numeric, email is required', () => {",
-    "  const u: User = { id: 1, name: 'Test', email: 'test@example.com' };",
-    "  assert.equal(typeof u.id, 'number');",
-    "  assert.equal(typeof u.email, 'string');",
-    "});",
-    "",
-    "test('ActionResult: success envelope carries data', () => {",
-    "  const r: ActionResult<User> = {",
-    "    success: true,",
-    "    data: { id: 1, name: 'Test', email: 'test@example.com' },",
-    "  };",
-    "  assert.equal(r.success, true);",
-    "  if (r.success) assert.equal(r.data.email, 'test@example.com');",
+    "test('protected route redirects to /login when unauthenticated', async (t) => {",
+    "  const app = await makeHandler();",
+    "  const res = await testRequest(app.handle, '/dashboard');",
+    "  if (res.status >= 500) {",
+    "    t.skip('app deps not ready (run `npm run db:generate` + `npm run db:migrate`)');",
+    "    return;",
+    "  }",
+    "  // The dashboard middleware calls auth(); with no session cookie it 302s to",
+    "  // /login. This needs no DB row, only a cookie read, so it is always real",
+    "  // once the modules import.",
+    "  assert.equal(res.status, 302, 'unauthenticated dashboard is gated');",
+    "  assert.equal(res.headers.get('location'), '/login');",
     "});",
     "",
-    "test('ActionResult: failure envelope carries error + status', () => {",
-    "  const r: ActionResult<User> = {",
-    "    success: false,",
-    "    error: 'Email already registered',",
-    "    status: 409,",
-    "  };",
-    "  assert.equal(r.success, false);",
-    "  if (!r.success) {",
-    "    assert.equal(r.status, 409);",
-    "    assert.ok(r.error.length > 0);",
+    "test('signup -> login -> dashboard renders for the authenticated user', async (t) => {",
+    "  const app = await makeHandler();",
+    "  // Probe readiness: a 5xx on the dashboard means deps/DB are not set up.",
+    "  const probe = await testRequest(app.handle, '/dashboard');",
+    "  if (probe.status >= 500) { t.skip('app deps not ready; run `npm run db:generate` + `npm run db:migrate`'); return; }",
+    "",
+    "  const email = `harness+${Date.now()}@example.com`;",
+    "  const password = 'password123';",
+    "",
+    "  // Real signup through the page server action (the no-JS form write-path).",
+    "  let canSignup = true;",
+    "  try {",
+    "    const signupRes = await testRequest(app.handle, '/signup', {",
+    "      method: 'POST',",
+    "      headers: { 'content-type': 'application/x-www-form-urlencoded' },",
+    "      body: new URLSearchParams({ name: 'Harness', email, password }).toString(),",
+    "    });",
+    "    // Success is a 303 PRG to /login; a 422 means validation failed (still a",
+    "    // real response, just not the happy path). Either way the action ran.",
+    "    assert.ok([303, 422].includes(signupRes.status), 'signup action ran');",
+    "    if (signupRes.status !== 303) canSignup = false;",
+    "  } catch {",
+    "    // No migrated DB table -> the action throws. Skip the DB-backed assertions.",
+    "    canSignup = false;",
     "  }",
-    "});",
+    "  if (!canSignup) { t.skip('no migrated DB; run `npm run db:migrate` to enable the full flow'); return; }",
     "",
-    "// TODO: once you've run `npm install && npx prisma migrate dev` you can",
-    "// import { signup } from '../../modules/auth/actions/signup.server.ts'",
-    "// and { currentUser } from '../../modules/auth/queries/current-user.server.ts'",
-    "// and write real integration tests against a test SQLite DB.",
+    "  // Real login captures the genuine signed session cookie.",
+    "  const { cookies } = await loginAndGetCookies(app.handle, { email, password });",
+    "",
+    "  // With the session cookie the protected route now renders (200).",
+    "  const dash = await testRequest(app.handle, '/dashboard', withSessionCookie({}, cookies));",
+    "  assert.equal(dash.status, 200, 'the session cookie unlocks the dashboard');",
+    "  const body = await dash.text();",
+    "  assert.match(body, /Dashboard/, 'the dashboard content rendered');",
+    "});",
     "",
   ].join('\n'));
 
   // app/api/auth/[...path]/route.ts
   await mkdir(join(appDir, 'app', 'api', 'auth', '[...path]'), { recursive: true });
   await writeFile(join(appDir, 'app', 'api', 'auth', '[...path]', 'route.ts'), [
-    "import { handlers } from '../../../../../lib/auth.server.ts';",
+    "import { handlers } from '../../../../lib/auth.server.ts';",
     "export const GET = handlers.GET;",
     "export const POST = handlers.POST;",
     "",
@@ -250,7 +299,7 @@ export async function writeSaasFiles(appDir) {
     "          <p class=${cardDescriptionClass()}>Welcome back: log in to continue.</p>",
     "        </div>",
     "        <div class=${cardContentClass()}>",
-    "          <form method=\"POST\" action=\"/api/auth/callback/credentials\" class=\"flex flex-col gap-4\">",
+    "          <form method=\"POST\" action=\"/api/auth/signin/credentials\" class=\"flex flex-col gap-4\">",
     "            <div class=\"flex flex-col gap-1.5\">",
     "              <label class=${labelClass()} for=\"email\">Email</label>",
     "              <input class=${inputClass()} id=\"email\" name=\"email\" type=\"email\" required>",

package/package.json

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

package/templates/.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["/package.json"],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "webjs": {
+            "$ref": "./node_modules/@webjsdev/server/webjs-config.schema.json"
+          }
+        }
+      }
+    }
+  ]
+}

package/templates/AGENTS.md

@@ -112,6 +112,15 @@ layered on top:
 See [docs.webjs.com → Editor setup](https://docs.webjs.com/docs/editor-setup)
 for the full walkthrough.
 
+**Config validation in `package.json`.** The scaffold ships
+`.vscode/settings.json`, which associates the published webjs-config JSON
+Schema (`@webjsdev/server/webjs-config.schema.json`) with the `webjs` block
+of `package.json`. In VS Code an unknown / typo'd `webjs.*` key (`redirect`
+for `redirects`, say) is then flagged inline instead of silently dropped to
+the default. The same shape is typed by the `WebjsConfig` type from
+`@webjsdev/core` (`import type { WebjsConfig } from '@webjsdev/core'`) for a
+typed reference.
+
 ## UI components: Webjs UI (preinstalled)
 
 This scaffold ships with the standard Webjs UI component kit
@@ -267,6 +276,28 @@ test/<feature>/                feature-scoped tests, one folder per concern
 middleware.ts            root middleware (optional, outermost)
 ```
 
+### Typed page / layout / route-handler props
+
+Type page / layout / route-handler arguments with the exported helpers so a
+param typo is a compile-time error:
+
+```ts
+import type { PageProps, LayoutProps, RouteHandlerContext } from '@webjsdev/core';
+
+export default function Post({ params }: PageProps<'/blog/[slug]'>) {
+  return html`<h1>${params.slug}</h1>`;   // params typed { slug: string }
+}
+export default function RootLayout({ children }: LayoutProps) { /* ... */ }
+export async function GET(req: Request, ctx: RouteHandlerContext) { /* ctx.params */ }
+```
+
+Run `webjs types` once (and ensure `tsconfig.json` `include` lists
+`.webjs/routes.d.ts`, the scaffold already does) to generate the route union:
+`PageProps<'/blog/[slug]'>['params']` then narrows to `{ slug: string }` and
+`navigate()` only accepts real app routes. `webjs dev` regenerates the file on
+startup, so it stays current. Without it, `params` is `Record<string, string>`
+and `navigate()` accepts any string (non-breaking).
+
 ## Database (Prisma + SQLite by default)
 
 Every scaffold includes a Prisma setup pointed at a local SQLite file.
@@ -709,8 +740,13 @@ return html`
 ```
 
 The router's `closest('webjs-frame')` detection takes precedence over
-layout markers. Only the frame's content swaps. Use this sparingly -
-folder-based layouts handle 99% of cases.
+layout markers. Only the frame's content swaps. Use this sparingly,
+folder-based layouts handle 99% of cases. When a frame nav's response
+lacks the matching `<webjs-frame id>` (e.g. an auth redirect), the router
+fires a cancelable, bubbling `webjs:frame-missing` event (detail
+`{ frameId, url, document }`) and leaves the frame unchanged rather than
+silently swapping the whole page; call `preventDefault()` to take over
+the outcome (e.g. `location.assign(e.detail.url)`).
 
 ### 5. `loading.ts` for per-segment skeletons
 

package/templates/CONVENTIONS.md

@@ -61,6 +61,17 @@ even if the user doesn't explicitly ask.**
 4. Sync with parent: `git fetch origin && git rebase origin/main` if behind
 5. Don't mix unrelated work on the wrong branch
 
+### After cloning: verify the toolchain
+
+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
+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
+gate (its env-drift + network pin-freshness checks would make CI flaky).
+
 ### Every code change must include:
 
 1. **Commit and push per logical unit, not at the end.** A logical unit is
@@ -86,6 +97,12 @@ even if the user doesn't explicitly ask.**
 4. **Convention check.** Run `webjs check` after changes and fix
    any violations before reporting the task as done.
 
+5. **Type check.** Run `npm run typecheck` (which runs `webjs typecheck`,
+   a `tsc --noEmit` over the app) and fix any type errors. `webjs check` is
+   correctness-only and does NOT type-check, so this is the separate
+   is-my-TypeScript-valid gate. It exits non-zero on a type error, so add it
+   to CI once the app type-checks cleanly.
+
 ### Definition of done (MUST be addressed BEFORE opening the PR)
 
 This is the per-PR contract. Before running `gh pr create`, walk through
@@ -433,6 +450,40 @@ test/
 - `webjs test --browser` (or `npx wtr`) runs the browser tests.
 - `WEBJS_E2E=1 webjs test` adds the e2e tests.
 
+### The handle() test harness (full-pipeline node tests)
+
+For a node test that needs the REAL request pipeline (middleware, routing,
+SSR, page actions, server-action RPC, auth + CSRF), drive
+`createRequestHandler({ appDir }).handle(request)` and assert on the
+`Response`. `@webjsdev/server/testing` ships thin builders over it:
+
+```ts
+import { createRequestHandler } from '@webjsdev/server';
+import { testRequest, getCsrf, invokeActionForTest, loginAndGetCookies, withSessionCookie }
+  from '@webjsdev/server/testing';
+
+const app = await createRequestHandler({ appDir: process.cwd(), dev: true });
+
+// fire a request, assert the response
+const res = await testRequest(app.handle, '/about');
+
+// real login, reuse the captured session cookie on a protected route
+const { cookies } = await loginAndGetCookies(app.handle, { email, password });
+const dash = await testRequest(app.handle, '/dashboard', withSessionCookie({}, cookies));
+
+// round-trip a server action through the REAL /__webjs/action/<hash>/<fn> path
+const out = await invokeActionForTest(app, 'modules/posts/actions/create.server.ts', 'createPost', [input]);
+```
+
+Prefer `invokeActionForTest` over a direct import of the action when you want
+to verify the production contract: it exercises the wire serializer (a `Date` /
+`Map` arg survives), CSRF, and prod error sanitization, which a direct call
+bypasses. The saas template's `test/auth/auth.test.ts` is a worked example.
+
+This is also why the auth test lives at `test/auth/auth.test.ts` (the
+feature-folder convention), NOT `test/unit/auth.test.ts`. Test KIND is a
+subfolder inside a feature, never the top level.
+
 **Every change ships with a test.** For Claude Code, a commit that
 stages app code (`app/`, `modules/`, `components/`, `lib/`) without
 staging a test is blocked by `.claude/hooks/require-tests-with-src.sh`.