@webjsdev/cli 0.10.50 → 0.10.52

package/README.md

@@ -39,12 +39,14 @@ Both `webjs create` and `create-webjs-app` auto-install dependencies in the new
 
 ```sh
 webjs create <name>            # scaffold a full-stack app (default; auth ships as a gallery card)
+                               # <name> must be a valid package name: letters, digits,
+                               # and - . _ , starting with a letter or a digit
 webjs create <name> --template api   # backend-only API app (routes + modules + Drizzle)
 
 webjs dev                      # dev server with live reload (runs webjs.dev.before, e.g. webjs db migrate, then serves; npm run dev is a thin alias)
 webjs start                    # production server (no build step, serves source directly)
 webjs check                    # validate source-code conventions (CI gate)
-webjs doctor                   # verify the project/toolchain setup (local onboarding, not CI)
+webjs doctor                   # verify the project/toolchain setup (per-check severity via webjs.doctor.gate, so CI can gate a subset)
 webjs test                     # run server + browser tests
 webjs vendor pin [--download]  # pin client deps to a committable importmap (offline/reproducible)
 webjs db <generate|migrate|push|studio|seed>   # drizzle-kit passthrough (+ seed)

package/bin/webjs.js

@@ -8,6 +8,7 @@ import { dbGenerateTtyHint } from '../lib/db-hints.js';
 import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
 import { loadAppEnv, resolvePort } from '../lib/port.js';
 import { planDevSupervisor } from '../lib/dev-supervisor.js';
+import { checkAppName, appNameErrorMessage } from '../lib/app-name.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
@@ -48,6 +49,40 @@ if (cmd !== 'help' && cmd !== undefined && !wantsHelp && !wantsVersion) {
 // .agents/rules/workflow.md / .github/copilot-instructions.md mirror it.
 const TEMPLATES = ['full-stack', 'api'];
 
+/**
+ * The one thing `webjs elision --verify` must say about its own boundary, in
+ * the command's own output rather than only in the docs. The differential masks
+ * the JS-loaded set by construction, so it can only ever see the DANGEROUS
+ * direction (elision changed the served bytes); a wrongly dropped module shows
+ * up as a dead click, which is bytes-identical.
+ */
+const VERIFY_CAVEAT = `
+This proves elision did not change the bytes your app serves. It does NOT prove
+post-hydration behaviour: a wrongly dropped module shows up as a dead click, not
+as different bytes. Run your browser or e2e suite twice to cover that half:
+  WEBJS_ELIDE=1 <your e2e command>
+  WEBJS_ELIDE=0 <your e2e command>`;
+
+/**
+ * `--routes /a,/b` or `--routes=/a,/b` -> ['/a', '/b']. Every value is
+ * normalized to a leading slash; empties drop.
+ * @param {string[]} argv
+ * @returns {string[]}
+ */
+function parseRoutesFlag(argv) {
+  /** @type {string[]} */
+  const raw = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--routes') { if (argv[i + 1]) raw.push(argv[i + 1]); i++; }
+    else if (argv[i].startsWith('--routes=')) raw.push(argv[i].slice('--routes='.length));
+  }
+  return raw
+    .flatMap((v) => v.split(','))
+    .map((v) => v.trim())
+    .filter(Boolean)
+    .map((v) => (v.startsWith('/') ? v : '/' + v));
+}
+
 const USAGE = `webjs commands:
   webjs dev   [--port 8080] [--no-hot]            Start dev server with live reload
                                                   (--no-hot: run in-process, no hot-reload supervisor)
@@ -55,12 +90,17 @@ const USAGE = `webjs commands:
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check [--json]                            Run correctness checks (--json emits structured violations)
   webjs routes [--json|--table] [--no-headers]    Print the route table (path / owner file / methods). Default tree; --json matches the MCP list_routes shape; --no-headers drops the --table header
-  webjs mcp                                       Start the read-only MCP server (routes / actions / components / check)
-  webjs doctor [--json] [--strict]                Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision).
-                                                  --json emits the structured results (with stable codes). --strict also fails the exit on warnings
+  webjs elision [--json] [--verify]               Report which component modules are elided and why each shipped one ships;
+                                                  --verify diffs SSR output with elision on vs off (exits non-zero on a divergence)
+  webjs mcp                                       Start the read-only MCP server (routes / actions / components / elision / check)
+  webjs doctor [--json] [--strict]                Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision, component elision, un-versioned stylesheet links).
+                                                  --json emits the structured results (with stable codes). --strict additionally fails on every remaining warning.
+                                                  Per-check severity is CONFIG: map a code to off/warn/error under "webjs": { "doctor": { "gate": {...} } }
+                                                  in package.json, so CI gates on a chosen subset without every warning becoming fatal
   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] [--db sqlite|postgres] [--runtime node|bun] [--no-install]  Scaffold a new webjs app
+                                                  <name> must be a valid package name (letters, digits, - . _, starts with a letter or digit)
                                                   (only 2 templates exist. default: full-stack, Drizzle, --db sqlite, --runtime node)
                                                   --runtime bun emits a Bun-flavored app (bun.lock, bun Dockerfile/CI, bun docs);
                                                   also auto-detected when run via "bun create webjs".
@@ -140,12 +180,39 @@ const HELP = {
     ],
     examples: ['webjs routes', 'webjs routes --table', 'webjs routes --table --no-headers', 'webjs routes --json'],
   },
+  elision: {
+    usage: 'webjs elision [--json] [--verify] [--routes <paths>]',
+    summary:
+      'Report the elision verdict: which component modules the browser never downloads, and why each one that ships does.',
+    options: [
+      { flag: '--json', description: 'Emit the verdict as JSON (byte-identical to the MCP list_elision tool).' },
+      { flag: '--verify', description: 'Render every static page route with elision on and off and diff the observable SSR bytes. Exits non-zero on a divergence.' },
+      { flag: '--routes <paths>', description: 'Comma-separated URL paths to add to the --verify corpus (the only way to cover a dynamic route).' },
+    ],
+    notesTitle: 'What --verify proves',
+    notes: [
+      '--verify proves elision did not change the bytes your app serves. It does NOT',
+      'prove post-hydration behaviour: a wrongly dropped module shows up as a dead',
+      'click, not as different bytes. Run your browser or e2e suite twice',
+      '(WEBJS_ELIDE=1 then WEBJS_ELIDE=0) to cover that half.',
+    ],
+    examples: ['webjs elision', 'webjs elision --json', 'webjs elision --verify', 'webjs elision --verify --routes /,/blog/hello'],
+  },
   doctor: {
     usage: 'webjs doctor [--json] [--strict]',
     summary: 'Verify project health. Each result carries a stable code so an agent branches on the failure kind.',
     options: [
-      { flag: '--json', description: 'Emit the DoctorResult[] (with stable codes) + a summary as JSON.' },
-      { flag: '--strict', description: 'Also fail the exit on warnings, not just hard failures.' },
+      { flag: '--json', description: 'Emit the DoctorResult[] (with stable codes + severities) + a summary as JSON.' },
+      { flag: '--strict', description: 'Also fail the exit on EVERY remaining warning, not just hard failures and gated errors.' },
+    ],
+    notes: [
+      'Per-check severity is CONFIG, not a flag. Declare it in package.json under',
+      '"webjs": { "doctor": { "gate": { "<CODE>": "off" | "warn" | "error" } } }, so CI',
+      'gates on a chosen subset without --strict making every warning fatal. A malformed',
+      'gate exits 1 naming it (an unknown code, a bad severity, a non-object doctor/gate,',
+      'or a misspelled sibling like "gates"); under --json those come back as a',
+      'configErrors array with results empty. A "could not check" result (a network or',
+      'toolchain outage) is capped at warn and can never be escalated to error.',
     ],
     examples: ['webjs doctor', 'webjs doctor --json', 'webjs doctor --strict', 'webjs doctor --json --strict'],
   },
@@ -163,6 +230,12 @@ const HELP = {
     usage: 'webjs create <name> [--template full-stack|api] [--db sqlite|postgres] [--runtime node|bun] [--no-install]',
     summary: 'Scaffold a new app. Defaults: full-stack template, Drizzle + SQLite, Node runtime.',
     options: [
+      // Kept to one terminal line like every other row: printHelp does not
+      // wrap, so a long description renders as one 300-column line.
+      {
+        flag: '<name>',
+        description: 'Package name: letters, digits, - . _ , starts with a letter or digit.',
+      },
       { flag: '--template <t>', description: 'full-stack (default) or api (backend-only, no UI).' },
       { flag: '--db <d>', description: 'sqlite (default) or postgres.' },
       { flag: '--runtime <r>', description: 'node (default) or bun.' },
@@ -196,7 +269,7 @@ const HELP = {
   },
   mcp: {
     usage: 'webjs mcp',
-    summary: 'Start the read-only MCP server (routes / actions / components / check + a docs/source knowledge layer).',
+    summary: 'Start the read-only MCP server (routes / actions / components / elision / check + a docs/source knowledge layer).',
     examples: ['webjs mcp'],
   },
   version: {
@@ -235,6 +308,15 @@ function printCommandHelp(name) {
   const width = Math.max(...options.map((o) => o.flag.length));
   console.log('Options:');
   for (const o of options) console.log(`  ${o.flag.padEnd(width)}  ${o.description}`);
+  // Optional per-command prose for surface a flag table cannot carry (doctor's
+  // package.json severity gate is the one that needs it). The heading defaults
+  // to `Config:` because that is what doctor's block is and what its help test
+  // pins; a command whose prose is not configuration names its own heading
+  // (`webjs elision`'s is a caveat about what --verify proves).
+  if (h.notes) {
+    console.log(`\n${h.notesTitle || 'Config'}:`);
+    for (const line of h.notes) console.log(`  ${line}`);
+  }
   console.log('\nExamples:');
   for (const ex of h.examples) console.log(`  ${ex}`);
   return true;
@@ -630,7 +712,8 @@ async function main() {
       if (rest.includes('--rules')) {
         console.log('webjs check, correctness rules:');
         console.log('  Every rule catches code that is wrong to ship: a crash, a');
-        console.log('  security leak, or a build/type-strip failure. They always');
+        console.log('  security leak, a reactive prop that silently stops');
+        console.log('  re-rendering, or a build/type-strip failure. They always');
         console.log('  run. Project conventions (layout, style, process) are');
         console.log('  guidance in CONVENTIONS.md, not rules here.\n');
         for (const r of RULES) {
@@ -671,51 +754,113 @@ async function main() {
     }
     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());
+      // this branch only renders them and owns the exit code. The exit is
+      // non-zero when a HARD check FAILS or when a check the app gated `error`
+      // reports something; an UNGATED warn stays informational (env drift / pin
+      // staleness / version drift are the app's concern, not a broken
+      // toolchain). An app declares per-check severity
+      // in its package.json `webjs.doctor.gate` (#1257), which is what lets CI
+      // gate on a chosen subset without `--strict` making every warning fatal.
+      const { runDoctorChecks, readDoctorPolicy, applyDoctorPolicy, DOCTOR_CODES, DOCTOR_SEVERITIES } =
+        await import('../lib/doctor.js');
+      const appDir = process.cwd();
+      const strict = rest.includes('--strict');
+      const asJson = rest.includes('--json');
+
+      // Read the policy FIRST. A wrong shape, a key that is not a known code, or
+      // a value that is not a severity exits 1 without running the checks: a
+      // typo silently ignored would leave CI un-gated while looking gated,
+      // which is the worst failure a mechanism like this can have.
+      const policy = readDoctorPolicy(appDir);
+      const configErrors = [
+        ...policy.malformed.map(({ path, value }) => ({ kind: 'malformed', path, value })),
+        ...policy.unknownKeys.map((path) => ({ kind: 'unknown-key', path })),
+        ...policy.unknownCodes.map((code) => ({ kind: 'unknown-code', code })),
+        ...policy.badSeverities.map(({ code, value }) => ({ kind: 'bad-severity', code, value })),
+      ];
+      if (configErrors.length > 0) {
+        if (asJson) {
+          console.log(JSON.stringify({
+            results: [],
+            summary: { pass: 0, warn: 0, fail: 0, off: 0, strict, ok: false },
+            configErrors,
+          }));
+          process.exit(1);
+        }
+        // Header names the BLOCK, not `gate`: two of the four error kinds are
+        // about `webjs.doctor` itself or a misspelled sibling, so naming `gate`
+        // would point at a key the package.json may not even contain.
+        console.error('webjs doctor: invalid "webjs.doctor" config in package.json\n');
+        for (const e of configErrors) {
+          if (e.kind === 'malformed') console.error(`  Expected an object at ${e.path}, got ${JSON.stringify(e.value)}`);
+          else if (e.kind === 'unknown-key') console.error(`  Unknown config key: ${e.path} (the only key is "gate")`);
+          else if (e.kind === 'unknown-code') console.error(`  Unknown check code: ${e.code}`);
+          else console.error(`  Invalid severity for ${e.code}: ${JSON.stringify(e.value)}`);
+        }
+        console.error('\n  Shape: "webjs": { "doctor": { "gate": { "<CODE>": "<severity>" } } }');
+        console.error(`  Valid severities: ${DOCTOR_SEVERITIES.join(' / ')}`);
+        console.error(`  Valid codes: ${Object.values(DOCTOR_CODES).join(', ')}`);
+        process.exit(1);
+      }
+
+      const results = applyDoctorPolicy(await runDoctorChecks(appDir), policy.gate);
+      // Counts come off the EFFECTIVE severity, not the raw status, so a gated
+      // code lands in the bucket the app asked for. With no gate the two are
+      // identical (a `fail` defaults to `error`, a `warn` to `warn`), which is
+      // what keeps an un-configured app byte-identical to before.
       const counts = results.reduce((acc, r) => {
-        acc[r.status] = (acc[r.status] || 0) + 1;
+        acc[r.severity] = (acc[r.severity] || 0) + 1;
         return acc;
       }, /** @type {Record<string, number>} */ ({}));
       const pass = counts.pass || 0;
       const warn = counts.warn || 0;
-      const fail = counts.fail || 0;
-      // `--strict` also fails the exit on warnings, so an agent can gate on a
-      // fully-clean toolchain (drift / staleness / pin freshness) in a fix loop,
-      // not just on a hard toolchain break. Default keeps warnings non-fatal.
-      const strict = rest.includes('--strict');
+      const fail = counts.error || 0;
+      const off = counts.off || 0;
+      // `--strict` additionally fails the exit on every REMAINING warning, so an
+      // agent can gate on a fully-clean toolchain (drift / staleness / pin freshness) in a fix loop,
+      // not just on a hard toolchain break. Without it, a warn is fatal only
+      // where the app gated its code `error`, which folded into `fail` above.
       const failing = fail > 0 || (strict && warn > 0);
 
-      // --json emits the raw DoctorResult[] (each carries a stable `code`) plus
-      // a summary, so an agent consumes structured data instead of scraping the
-      // text. Shape mirrors `check --json`: a top-level array-bearing object
-      // with a `summary` count. The non-zero exit is preserved (an agent gates
-      // on the exit code AND parses the report).
-      if (rest.includes('--json')) {
+      // --json emits the raw DoctorResult[] (each carries a stable `code` and
+      // its effective `severity`) plus a summary, so an agent consumes
+      // structured data instead of scraping the text. Shape mirrors `check
+      // --json`: a top-level array-bearing object with a `summary` count. The
+      // non-zero exit is preserved (an agent gates on the exit code AND parses
+      // the report).
+      if (asJson) {
         console.log(JSON.stringify({
           results,
-          summary: { pass, warn, fail, strict, ok: !failing },
+          summary: { pass, warn, fail, off, strict, ok: !failing },
         }));
         if (failing) process.exit(1);
         break;
       }
 
-      const marker = { pass: '[pass]', warn: '[warn]', fail: '[fail]' };
+      const marker = { pass: '[pass]', off: '[off]', warn: '[warn]', error: '[fail]' };
       console.log('webjs doctor: project-health checklist\n');
       for (const r of results) {
-        console.log(`  ${marker[r.status]} ${r.name} (${r.code})`);
-        console.log(`    ${r.message}`);
-        if (r.fix && r.status !== 'pass') console.log(`    Fix: ${r.fix}`);
+        // Name the gate whenever it moved a result off its default, so the
+        // reason a warning is fatal (or silenced) is on the line itself.
+        const dflt = r.status === 'fail' ? 'error' : 'warn';
+        const gated = r.status !== 'pass' && r.severity !== dflt ? `, gated: ${r.severity}` : '';
+        console.log(`  ${marker[r.severity]} ${r.name} (${r.code}${gated})`);
+        // A silenced check reports NOTHING beyond its name: an app that gated a
+        // code `off` asked not to hear about it, and printing the finding plus
+        // a Fix line every run is exactly the noise it turned off (ESLint's
+        // `off` drops the message too). The checklist still lists it as [off]
+        // and the summary still counts it, so a silenced check is never
+        // invisible, and `--json` keeps the whole result for tooling.
+        if (r.severity !== 'off') {
+          console.log(`    ${r.message}`);
+          if (r.fix && r.status !== 'pass') console.log(`    Fix: ${r.fix}`);
+        }
         console.log();
       }
-      console.log(`  ${pass} passed, ${warn} warning(s), ${fail} failed.`);
+      console.log(`  ${pass} passed, ${warn} warning(s), ${fail} failed${off > 0 ? `, ${off} silenced` : ''}.`);
       if (failing) {
         const reason = fail > 0
-          ? `${fail} hard check(s) failed. Fix the toolchain issue(s) above.`
+          ? `${fail} check(s) failed. Fix the issue(s) above, or adjust "webjs.doctor.gate" in package.json.`
           : `${warn} warning(s) found and --strict was set.`;
         console.error(`\nwebjs doctor: ${reason}`);
         process.exit(1);
@@ -799,6 +944,251 @@ async function main() {
       }
       break;
     }
+    case 'elision': {
+      // Report the elision verdict for the app in cwd (#1308): which component
+      // modules the browser never downloads, why each one that ships does,
+      // which page/layout is inert / import-only / ships whole, and any orphan
+      // class that gets no verdict at all. Reuses the ONE analysis pass
+      // (`analyzeAppElision`, the same reporting layer `webjs doctor` and
+      // the MCP `list_elision` tool call), so `--json` is byte-identical to
+      // that tool. Read-only: no autofix, and nothing is written to disk.
+      const appDir = process.cwd();
+
+      // --verify: the app-level differential. Renders every static page route
+      // with elision ON and OFF in this one process and diffs the observable
+      // SSR bytes, which is literally the framework's own guard
+      // (`packages/server/test/elision/differential-elision.test.js`) pointed
+      // at an arbitrary app's route table.
+      if (rest.includes('--verify')) {
+        const { createRequestHandler, buildRouteTable, maskJsSet, staticPageRoutes } =
+          await import('@webjsdev/server');
+
+        const extra = parseRoutesFlag(rest);
+        let table;
+        try {
+          table = await buildRouteTable(appDir);
+        } catch (err) {
+          console.error(`webjs elision --verify: cannot read the route table here (${err && err.message}).`);
+          process.exit(1);
+        }
+        const staticRoutes = staticPageRoutes(table);
+        const dynamic = (table.pages || [])
+          .filter((r) => r.paramNames && r.paramNames.length)
+          .map((r) => (r.routeDir && r.routeDir !== '.' ? '/' + r.routeDir : '/'))
+          .sort();
+        // An extra route the author named explicitly is REQUIRED to render; a
+        // static one that does not is merely reported (a page may legitimately
+        // throw notFound() for every visitor).
+        const required = new Set(extra);
+        const routes = [...new Set([...staticRoutes, ...extra])];
+
+        // The app's access log would drown the verdict, and a verification
+        // run is not a server: keep errors (a real boot failure must surface)
+        // and drop the per-request info lines.
+        const quiet = { info: () => {}, warn: () => {}, debug: () => {}, error: (...a) => console.error(...a) };
+
+        const capture = async (h, r) => {
+          const resp = await h.handle(new Request('http://localhost' + r));
+          return { status: resp.status, html: await resp.text() };
+        };
+        // The module URLs a response preloads, with the content-hash query
+        // stripped. Comparing the two sides' sets is how the run reports what
+        // elision actually DROPPED, which is the only thing that distinguishes
+        // a real pass from two identical renders.
+        const preloadSet = (html) => new Set(
+          [...html.matchAll(/<link rel="modulepreload" href="([^"]+)"/g)].map((m) => m[1].split('?')[0]),
+        );
+
+        const ORIG = process.env.WEBJS_ELIDE;
+        /** @type {Record<string, {status:number, html:string}>} */
+        const onA = {}, onB = {}, off = {};
+        try {
+          // Elision ON, FORCED. Deleting the override would only fall back to
+          // `webjs.elide`, so on an app that opts out this side would run with
+          // elision OFF too and the command would compare two identical renders
+          // and report them "identical with elision on vs off", which is false
+          // about a run where elision was never on. The env override wins over
+          // the config key, which is exactly what makes it the right seam here.
+          // Warm fully so the memoized verdict is locked before the env flips
+          // for the second handler.
+          process.env.WEBJS_ELIDE = '1';
+          const hOn = await createRequestHandler({ appDir, dev: false, logger: quiet });
+          if (hOn.warmup) await hOn.warmup();
+          for (const r of routes) onA[r] = await capture(hOn, r);
+          // A SECOND capture through the same warm handler. A route whose two
+          // ON captures already differ is nondeterministic (live data, a random
+          // id, a clock the masker does not normalize), so a differential over
+          // it proves nothing and reporting it as a failure would be a red the
+          // author cannot act on. The framework's own test needs no such pass
+          // because its corpus is fixed and known; an arbitrary app's is not.
+          for (const r of routes) onB[r] = await capture(hOn, r);
+          // Elision OFF via the env override; a fresh handler reads it on its
+          // own first warm.
+          process.env.WEBJS_ELIDE = '0';
+          const hOff = await createRequestHandler({ appDir, dev: false, logger: quiet });
+          if (hOff.warmup) await hOff.warmup();
+          for (const r of routes) off[r] = await capture(hOff, r);
+        } catch (err) {
+          console.error(`webjs elision --verify: could not boot the app (${err && err.message}).`);
+          process.exit(1);
+        } finally {
+          if (ORIG === undefined) delete process.env.WEBJS_ELIDE;
+          else process.env.WEBJS_ELIDE = ORIG;
+        }
+
+        const unrenderable = [], nondeterministic = [], diverged = [];
+        /** @type {Set<string>} modules the OFF side preloads and the ON side does not */
+        const dropped = new Set();
+        let compared = 0;
+        for (const r of routes) {
+          if (onA[r].status >= 400) { unrenderable.push(`${r} (${onA[r].status})`); continue; }
+          if (maskJsSet(onA[r].html) !== maskJsSet(onB[r].html)) { nondeterministic.push(r); continue; }
+          compared++;
+          // What elision removed on this route. A pass over a corpus where this
+          // stays empty is TRUE but trivially so, and the author needs to see
+          // that rather than read it as proof elision was exercised.
+          const onSet = preloadSet(onA[r].html);
+          for (const u of preloadSet(off[r].html)) if (!onSet.has(u)) dropped.add(u);
+          const a = maskJsSet(onA[r].html);
+          const b = maskJsSet(off[r].html);
+          if (onA[r].status !== off[r].status) {
+            diverged.push({ route: r, kind: 'status', a: String(onA[r].status), b: String(off[r].status), at: 0 });
+            continue;
+          }
+          if (a !== b) {
+            let i = 0;
+            while (i < a.length && i < b.length && a[i] === b[i]) i++;
+            diverged.push({
+              route: r, kind: 'body', at: i,
+              a: a.slice(Math.max(0, i - 40), i + 40),
+              b: b.slice(Math.max(0, i - 40), i + 40),
+            });
+          }
+        }
+
+        for (const d of diverged) {
+          console.error(
+            d.kind === 'status'
+              ? `FAIL ${d.route}: status differs with elision on vs off (on=${d.a}, off=${d.b})`
+              : `FAIL ${d.route}: elision changed observable output near offset ${d.at}\n` +
+                `  ON : ...${JSON.stringify(d.a)}\n  OFF: ...${JSON.stringify(d.b)}`,
+          );
+        }
+        const badRequired = unrenderable.filter((u) => required.has(u.split(' ')[0]));
+        for (const u of badRequired) console.error(`FAIL ${u}: a --routes path must render`);
+
+        const skips = [
+          dynamic.length ? `${dynamic.length} skipped (dynamic: ${dynamic.join(', ')})` : '0 skipped (dynamic)',
+          `${nondeterministic.length} skipped (nondeterministic${nondeterministic.length ? ': ' + nondeterministic.join(', ') : ''})`,
+        ];
+        if (unrenderable.length) skips.push(`${unrenderable.length} skipped (did not render: ${unrenderable.join(', ')})`);
+
+        if (diverged.length || badRequired.length) {
+          console.error(`\nwebjs elision --verify: ${diverged.length} route(s) diverged out of ${compared} compared.`);
+          process.exit(1);
+        }
+        if (compared === 0) {
+          // A vacuous pass is a failure, the same posture scripts/run-bun-tests.js
+          // takes for a run that executed zero tests.
+          console.error(
+            `webjs elision --verify: nothing was compared (${skips.join(', ')}).\n` +
+            'Pass --routes /a,/b to name renderable paths, or add a static page route.',
+          );
+          process.exit(1);
+        }
+        console.log(
+          `webjs elision --verify: ${compared} route(s) identical with elision on vs off, ${skips.join(', ')}.\n` +
+          (dropped.size
+            ? `Elision dropped ${dropped.size} module(s) across that corpus, so the comparison was a real one.`
+            : 'Elision dropped NO modules across that corpus: nothing on these routes was elidable, so '
+              + 'there was nothing for elision to change. The comparison holds, it just had no work to '
+              + 'do. Run `WEBJS_ELIDE=1 webjs elision` to see why every module here ships (the same '
+              + 'override this run used, so the verdict matches even in an app that opts out).'),
+        );
+        console.log(VERIFY_CAVEAT);
+        break;
+      }
+
+      const { analyzeAppElision } = await import('@webjsdev/server');
+      const report = await analyzeAppElision(appDir);
+
+      // --json: the machine contract, identical to the MCP `list_elision` shape.
+      if (rest.includes('--json')) {
+        console.log(JSON.stringify(report));
+        break;
+      }
+
+      if (!report.analysed) {
+        const why = {
+          'no-app': 'no app/ directory here, so there is nothing to analyse',
+          'elide-off': 'elision is disabled (webjs.elide false, or WEBJS_ELIDE), so every module ships',
+          unanalysable: 'the app could not be analysed (`webjs check` and `webjs dev` name the real problem)',
+        }[report.skipped] || 'nothing was analysed';
+        console.log(`webjs elision: ${why}.`);
+        break;
+      }
+
+      const s = report.summary;
+      console.log(
+        `webjs elision: ${s.components} component module(s), ${s.elided} elided, ${s.shipped} shipped. ` +
+        `${s.routeModules} route module(s): ${s.inert} inert, ${s.importOnly} import-only, ${s.shippedWhole} ship whole.\n`,
+      );
+
+      const elided = report.components.filter((c) => c.verdict === 'elided');
+      const shipped = report.components.filter((c) => c.verdict === 'shipped');
+      // Column width, capped so one outlier does not push every other row off
+      // the terminal. An over-long cell overflows its own row rather than
+      // widening the table. The FILE column gets the generous cap because a
+      // module path is what a reader scans by; the tag column gets the tight
+      // one because a file registering five tags is the rare case.
+      const pad = (rows, col, cap) => Math.min(cap, Math.max(0, ...rows.map((r) => r[col].length)));
+      const FILE_W = 58, TAG_W = 30;
+
+      if (elided.length) {
+        console.log('Elided components (the browser never downloads these)');
+        const rows = elided.map((c) => [c.file, c.tags.join(', ')]);
+        const w = pad(rows, 0, FILE_W);
+        for (const [file, tags] of rows) console.log(`  ${file.padEnd(w)}  ${tags}`.trimEnd());
+        console.log();
+      }
+      if (shipped.length) {
+        console.log('Shipped components (and the evidence that forced each one)');
+        const rows = shipped.map((c) => [c.file, c.tags.join(', '), `${c.evidence || 'unknown'}: ${c.reason || 'no evidence recorded'}`]);
+        const w0 = pad(rows, 0, FILE_W), w1 = pad(rows, 1, TAG_W);
+        for (const [file, tags, why] of rows) console.log(`  ${file.padEnd(w0)}  ${tags.padEnd(w1)}  ${why}`.trimEnd());
+        console.log();
+      }
+      if (report.routeModules.length) {
+        console.log('Route modules');
+        const rows = report.routeModules.map((r) => [
+          r.verdict, r.file,
+          r.verdict === 'import-only' ? `emits ${r.emits.join(', ') || '(nothing)'}`
+            : r.verdict === 'shipped' ? (r.blocker ? `blocked by ${r.blocker}, which ${r.reason}` : `it ${r.reason}`)
+            : '',
+        ]);
+        const w0 = pad(rows, 0, 12), w1 = pad(rows, 1, FILE_W);
+        for (const [verdict, file, note] of rows) {
+          console.log(`  ${verdict.padEnd(w0)}  ${file.padEnd(w1)}${note ? '  ' + note : ''}`.trimEnd());
+        }
+        console.log();
+      }
+      if (report.orphans.length) {
+        console.log('Orphan components (no elision verdict; `static interactive = true` cannot rescue these)');
+        for (const o of report.orphans) {
+          console.log(`  ${o.className} in ${o.file} is never registered with a literal tag`);
+        }
+        console.log('  Either there is no registration call at all, or the tag is computed. The scanner matches');
+        console.log('  only a literal tag, so either way the module gets no verdict, no registry entry, and no');
+        console.log('  preload hint. With no registration call the element never upgrades at all; with a computed');
+        console.log('  tag it upgrades only while its module still reaches the browser through a shipping importer.');
+        console.log('  Fix: register it with a literal tag, Class.register(\'my-tag\'), or delete the class.');
+        console.log();
+      }
+      if (!report.components.length && !report.routeModules.length) {
+        console.log('  Nothing to report. Add a component or a page under app/.');
+      }
+      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`.
@@ -850,6 +1240,11 @@ async function main() {
       const name = rest[0];
       if (!name || name.startsWith('-')) {
         console.error('Usage: webjs create <app-name> [--template full-stack|api]');
+        // This branch fires for a MISSING name or one starting with `-`, so the
+        // rule it prints has to lead with the first-character requirement. An
+        // earlier wording listed the separators as allowed characters, which
+        // reads as permission to the one user who just typed a leading hyphen.
+        console.error('<app-name> must start with a letter or a digit, then letters, digits, "-", "." or "_".');
         process.exit(1);
       }
       const template = flag(rest, '--template', 'full-stack');
@@ -878,6 +1273,16 @@ files.
 Full docs: https://webjs.dev/docs`);
         process.exit(1);
       }
+      // The name lands in the generated package.json `name` field AND is
+      // interpolated into generated source (#1066), so a quote / backtick /
+      // `${` in it emits a file that fails to parse on the first `webjs dev`.
+      // Validate before anything is written, so a bad name leaves no directory
+      // behind. `scaffoldApp` re-checks for programmatic callers.
+      const nameCheck = checkAppName(name);
+      if (!nameCheck.ok) {
+        console.error(appNameErrorMessage(name, nameCheck.reason));
+        process.exit(1);
+      }
       const noInstall = rest.includes('--no-install');
       // --db picks the database dialect: sqlite (default) or postgres.
       const db = flag(rest, '--db', 'sqlite');