@webjsdev/cli 0.10.51 → 0.10.53

package/bin/webjs.js

@@ -49,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)
@@ -56,8 +90,10 @@ 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, un-versioned stylesheet links).
+  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
@@ -144,6 +180,24 @@ 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.',
@@ -215,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: {
@@ -255,9 +309,12 @@ function printCommandHelp(name) {
   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).
+  // 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('\nConfig:');
+    console.log(`\n${h.notesTitle || 'Config'}:`);
     for (const line of h.notes) console.log(`  ${line}`);
   }
   console.log('\nExamples:');
@@ -887,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`.

package/lib/app-name.js

@@ -206,3 +206,76 @@ export function assertValidAppName(name) {
   }
   return /** @type {string} */ (name);
 }
+
+/**
+ * PostgreSQL's hard cap on an identifier, `NAMEDATALEN - 1` bytes. An
+ * over-length `CREATE DATABASE` name is silently truncated to this with only a
+ * NOTICE, which would reproduce the same name mismatch in a new guise, so the
+ * derivation caps it here instead.
+ */
+export const DB_NAME_MAX_LENGTH = 63;
+
+/**
+ * Derive the PostgreSQL database name the scaffold writes into the generated
+ * `.env.example` `DATABASE_URL`. The APP NAME itself is never touched by this:
+ * the directory, the `package.json` `name`, the `{{APP_NAME}}` substitution and
+ * `metadata.title` all keep the name exactly as typed. Only the database
+ * segment of that one URL is normalized.
+ *
+ * The point is a QUOTING-INVARIANT name. A result in `[a-z_][a-z0-9_]*` under
+ * 63 bytes folds to itself under `CREATE DATABASE <name>;` AND is passed
+ * through unquoted by `createdb` (which builds its statement through `fmtId`),
+ * so the emitted URL names the same database whichever route the user takes.
+ * A case-preserving name does not have that property: `CREATE DATABASE MyApp;`
+ * creates `myapp` while `createdb MyApp` creates `MyApp`.
+ *
+ * One qualification on that property. A name that folds to a PostgreSQL
+ * KEYWORD (`order`, `user`, `table`, `group`, `check`, `window`, `limit`) is
+ * still not quoting-invariant: `CREATE DATABASE order;` is a syntax error
+ * rather than a fold, while `createdb order` succeeds because `fmtId` quotes a
+ * keyword. That is deliberately not detected here. The keyword list is
+ * version-dependent and roughly 470 entries, which is disproportionate in a
+ * helper whose whole point is being pure and dependency-free, and the failure
+ * is a loud syntax error on a placeholder line the user is editing anyway,
+ * not the silent wrong-database mismatch this function exists to remove.
+ *
+ * Three sub-rules, in this order, and the order is load-bearing:
+ *
+ *   1. Fold with `toLowerCase()`, NOT `toLocaleLowerCase()`. The latter is
+ *      locale-dependent, so a Turkish-locale machine would fold `I` to the
+ *      dotless `ı`, which the class below then turns into `_`, making the
+ *      generated file machine-dependent.
+ *   2. Map every remaining character outside `[a-z0-9_]` to `_`, one for one.
+ *      No run-collapsing, no trimming: both are legal identifier characters,
+ *      and a 1:1 fold is one a reader can apply by eye. `checkAppName` already
+ *      restricts the input to `[A-Za-z0-9._-]`, so in practice this only ever
+ *      rewrites `.` and `-`.
+ *   3. Prefix a single `_` when the first character is a digit, BEFORE the
+ *      slice so the cap governs the final string. `ALLOWED_FIRST_CHAR` admits
+ *      a leading digit, and an unquoted PostgreSQL identifier may not start
+ *      with one.
+ *
+ * Slicing LAST is what makes the byte cap correct: after the fold every
+ * surviving character is one ASCII byte, so a code-unit slice is a byte slice,
+ * and there is no surrogate pair or percent-escape for it to bisect (every
+ * character is unreserved under RFC 3986, so the segment needs no encoding).
+ *
+ * Precondition: `name` has passed `checkAppName`. `scaffoldApp` asserts that
+ * before any file is written. That is what guarantees a non-empty result (a
+ * validated name's first character is `[A-Za-z0-9]`, which folds into the
+ * class and survives), so there is no empty-result fallback branch here.
+ *
+ * Collisions are accepted and NOT detected. `My-App` and `my_app` both fold to
+ * `my_app`. This is a placeholder in `.env.example`, not a provisioned
+ * resource: the scaffold contacts no server and cannot know what exists, and a
+ * uniquifying suffix would make the name untraceable to the app name. Rails
+ * takes the same position in `railties/lib/rails/generators/app_name.rb`.
+ *
+ * @param {string} name  an app name that has passed `checkAppName`
+ * @returns {string}     a fold-stable, unquoted-safe PostgreSQL database name
+ */
+export function toDatabaseName(name) {
+  const folded = name.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+  const prefixed = /^[0-9]/.test(folded) ? `_${folded}` : folded;
+  return prefixed.slice(0, DB_NAME_MAX_LENGTH);
+}

package/lib/create.js

@@ -18,7 +18,7 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
-import { assertValidAppName } from './app-name.js';
+import { assertValidAppName, toDatabaseName } from './app-name.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -541,6 +541,11 @@ export async function scaffoldApp(name, cwd, opts = {}) {
         { name: '@webjsdev/intellisense' },
       ],
     },
+    // `test/**/*` is in so `webjs typecheck` reads the tests you write, the
+    // same way Next / Remix / Astro's generated configs do (#1299). A type
+    // error in a test is then a gate failure rather than something a reviewer
+    // has to catch by eye, and it needs no second config to remember to run.
+    //
     // `.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
@@ -552,6 +557,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       'components/**/*',
       'modules/**/*',
       'lib/**/*',
+      'test/**/*',
       'middleware.js',
       'middleware.ts',
       '.webjs/routes.d.ts',
@@ -877,9 +883,14 @@ export default defineConfig({
 `);
 
   // Env vars: append DATABASE_URL to the .env.example the template already
-  // copied (if present), idempotently.
+  // copied (if present), idempotently. The database segment is the app name
+  // normalized to a fold-stable PostgreSQL identifier, so the emitted URL
+  // names the same database whether the user runs `createdb` or types
+  // `CREATE DATABASE`. Hoisted because the post-scaffold guidance below names
+  // the same value, and the two must not be able to drift.
+  const dbName = toDatabaseName(name);
   const dbUrlLine = dialect === 'postgres'
-    ? 'DATABASE_URL=postgres://user:password@localhost:5432/' + name.replace(/[^a-z0-9_]/gi, '_')
+    ? 'DATABASE_URL=postgres://user:password@localhost:5432/' + dbName
     : 'DATABASE_URL=file:./db/dev.db';
   const envExample = join(appDir, '.env.example');
   if (existsSync(envExample)) {
@@ -1596,7 +1607,7 @@ ThemeToggle.register('theme-toggle');
   // local file with no .env). Point it at a running database; `dev` / `start`
   // then apply pending migrations via webjs.*.before.
   const pgNote = dialect === 'postgres'
-    ? `\nPostgres: copy .env.example to .env and set DATABASE_URL to a running database before \`${pm} run dev\`.\n`
+    ? `\nPostgres: copy .env.example to .env and set DATABASE_URL to a running database before \`${pm} run dev\`.\nThe example URL names the database \`${dbName}\`. Create that database or edit the URL.\n`
     : '';
   // Use `npx webjsdev ui ...` here, not `npx webjs ui ...`. The bare
   // `webjs` npm name is owned by an unrelated package; `npx webjs