@webjsdev/cli 0.10.50 → 0.10.51

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);
@@ -56,11 +57,14 @@ const USAGE = `webjs commands:
   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 doctor [--json] [--strict]                Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout 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".
@@ -144,8 +148,17 @@ const HELP = {
     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 +176,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.' },
@@ -235,6 +254,12 @@ 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).
+  if (h.notes) {
+    console.log('\nConfig:');
+    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 +655,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 +697,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);
@@ -850,6 +938,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 +971,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');

package/lib/api-gallery.js

@@ -13,8 +13,7 @@ import { join } from 'node:path';
 /**
  * Write the api backend-features gallery into `<appDir>/app/api/features/**`
  * plus a boot-time env-validation example at `app/env.ts`. Each demo carries a
- * `webjs-scaffold-placeholder` marker so `webjs check` fails until it is
- * pruned or adapted.
+ * comment naming exactly what to delete when it is pruned.
  * @param {string} appDir
  */
 export async function writeApiGallery(appDir) {
@@ -35,7 +34,7 @@ export async function writeApiGallery(appDir) {
   ].join('\n'));
   await mkdir(feat('validate'), { recursive: true });
   await writeFile(feat('validate', 'route.ts'), [
-    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/validate route AND modules/widgets), then delete this marker line. webjs check fails while the marker remains.",
+    "// API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/validate route AND modules/widgets).",
     "// route() turns a 'use server' action into a REST endpoint: it merges the URL",
     "// query, route params, and JSON body into one input, runs `validate` at the",
     "// boundary (a { success:false, fieldErrors } return is a 422, no action call),",
@@ -76,7 +75,7 @@ export async function writeApiGallery(appDir) {
     "",
   ].join('\n'));
   await writeFile(feat('rate-limit', 'route.ts'), [
-    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/rate-limit route), then delete this marker line. webjs check fails while the marker remains.",
+    "// API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/rate-limit route).",
     "// The middleware.ts beside this file stamps X-RateLimit-* headers and returns",
     "// a 429 with Retry-After once the window is exhausted, so this handler never",
     "// runs on a limited request. Call it six times in ten seconds to see the 429.",
@@ -89,7 +88,7 @@ export async function writeApiGallery(appDir) {
   // 3) Streaming response (chunks flushed as produced, no buffering).
   await mkdir(feat('stream'), { recursive: true });
   await writeFile(feat('stream', 'route.ts'), [
-    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/stream route), then delete this marker line. webjs check fails while the marker remains.",
+    "// API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/stream route).",
     "// Streams JSON-per-line chunks as they are produced, so a slow or large",
     "// result is delivered incrementally instead of buffered whole. A hand-written",
     "// route.ts returns a ReadableStream for full control. Served as text/plain so",
@@ -115,7 +114,7 @@ export async function writeApiGallery(appDir) {
   // 4) File storage (upload + serve), both hand-written route.ts.
   await mkdir(feat('files', '[key]'), { recursive: true });
   await writeFile(feat('files', 'route.ts'), [
-    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/files route), then delete this marker line. webjs check fails while the marker remains.",
+    "// API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/files route).",
     "// POST a multipart file: the bytes stream into the FileStore (a local",
     "// .webjs/uploads dir by default, gitignored; swap for S3/R2 with one",
     "// setFileStore() call). Returns the key + a URL served by [key]/route.ts.",
@@ -166,7 +165,7 @@ export async function writeApiGallery(appDir) {
   // 5) WebSocket endpoint with broadcast fan-out.
   await mkdir(feat('ws'), { recursive: true });
   await writeFile(feat('ws', 'route.ts'), [
-    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/ws route), then delete this marker line. webjs check fails while the marker remains.",
+    "// API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/ws route).",
     "// A WebSocket endpoint: exporting WS(ws, req) upgrades this route to a socket.",
     "// The framework auto-registers each connection to its path, so broadcast()",
     "// fans a message out to every connected client. Connect two clients to",

package/lib/app-name.js

@@ -0,0 +1,208 @@
+/**
+ * App-name validation for `webjs create <name>` (issue #1066).
+ *
+ * The name a user passes to `webjs create` is not just a directory name. It is
+ * ALSO interpolated into generated source as a template-literal value (the
+ * `metadata.title` in `app/page.ts`, the `name` field of the api template's
+ * root route handler, the `{{APP_NAME}}` substitution in every copied template
+ * file) and written verbatim into the generated `package.json` `name` field. A
+ * name carrying a quote, a backtick, a `${`, or a backslash therefore breaks
+ * the emitted file at the JS/TS syntax level, and the failure surfaces as a
+ * parse error on the very first `npm run dev` of the fresh app, far from its
+ * actual cause.
+ *
+ * Rather than escape at each interpolation site (an open-ended list that grows
+ * every time the scaffold emits a new file), the name is validated ONCE at the
+ * boundary, before any file is written. The rule is npm's package-name rules
+ * MINUS the lowercase-only clause (see `ALLOWED_CHAR`), which is still strictly
+ * narrower than every interpolation site needs, so a name that passes is safe
+ * everywhere the scaffold puts it. `npm init` and `create-next-app` do refuse
+ * uppercase; this deliberately does not, because the scaffold's manifest is
+ * private and a capital letter breaks nothing.
+ *
+ * This module is pure and imports nothing, so both the CLI entry
+ * (`bin/webjs.js`) and the programmatic entry (`scaffoldApp` in `lib/create.js`)
+ * can share one rule.
+ */
+
+/** npm's hard cap on a package name. */
+export const APP_NAME_MAX_LENGTH = 214;
+
+/** One-line description of the allowed shape, reused by both error surfaces. */
+export const APP_NAME_SHAPE =
+  'letters, digits, and the separators "-", "." and "_", starting with a letter or a digit, at most 214 characters, and not a name npm reserves';
+
+/**
+ * npm rejects these outright, whatever else the name looks like. Matched
+ * case-insensitively, since the name is also a directory and `Node_Modules`
+ * collides with `node_modules` on a case-insensitive filesystem.
+ * @type {string[]}
+ */
+const RESERVED_NAMES = ['node_modules', 'favicon.ico'];
+
+/**
+ * Every character allowed in an app name.
+ *
+ * npm's own rule for a PUBLISHED package name is lowercase-only, and this guard
+ * followed it at first. Uppercase is allowed back deliberately: it never broke
+ * anything. The scaffold's `package.json` is `private: true`, so the name is
+ * never published, and npm installs a capitalized private package without
+ * complaint (checked, not assumed). Every OTHER character this rule refuses
+ * corrupts generated source or the manifest, which is what the guard is for, so
+ * refusing a capital letter alongside them would have been a naming convention
+ * wearing a correctness costume, and `webjs create MyApp` worked before.
+ */
+const ALLOWED_CHAR = /[A-Za-z0-9._-]/;
+
+/** What a name may start with, per the shape both error surfaces state. */
+const ALLOWED_FIRST_CHAR = /[A-Za-z0-9]/;
+
+/**
+ * How much of the rejected name to echo back. The name is attacker-shaped by
+ * definition here (it is the thing that just failed validation), and it is
+ * echoed into a terminal, so it is capped rather than printed whole.
+ */
+const DISPLAY_MAX_LENGTH = 48;
+
+/**
+ * Render the rejected name for an error message. Two things it must not do:
+ * break the message onto a second line (a thrown Error is read programmatically
+ * and documented as single-line, and a newline is a name `checkAppName`
+ * rejects), and replay a control sequence into the terminal it is printed to (a
+ * name of `\x1b[31m...` would otherwise repaint the user's shell). So every
+ * character with no safe visible form is named by code point, and the result is
+ * capped so a 214-character name cannot produce a 240-column line.
+ * @param {unknown} name
+ * @returns {string}
+ */
+function describeName(name) {
+  const raw = typeof name === 'string' ? name : String(name);
+  let out = '';
+  for (const ch of raw) {
+    const code = ch.codePointAt(0) ?? 0;
+    out += isUnprintable(code)
+      ? `<U+${code.toString(16).toUpperCase().padStart(4, '0')}>`
+      : ch;
+  }
+  return out.length > DISPLAY_MAX_LENGTH ? `${out.slice(0, DISPLAY_MAX_LENGTH)}...` : out;
+}
+
+/**
+ * Whether a code point has no safe visible form in an error message. C0 and
+ * DEL are the obvious set. Two additions matter here: the C1 range, which is
+ * where an 8-bit terminal reads control functions, and U+2028 / U+2029, which
+ * are JS LineTerminators, so they break the single-line contract exactly the
+ * way `\n` does while sailing past any `split('\n')` that claims to check it.
+ * @param {number} code
+ * @returns {boolean}
+ */
+function isUnprintable(code) {
+  return code < 0x20 || (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029;
+}
+
+/**
+ * Render a character for an error message. A control character has no visible
+ * form, so name it by code point instead of printing it. The quote delimiter is
+ * picked to avoid the character itself, so a rejected apostrophe does not print
+ * as the unreadable `'''`.
+ * @param {string} ch
+ * @returns {string}
+ */
+function describeChar(ch) {
+  const code = ch.codePointAt(0) ?? 0;
+  if (isUnprintable(code)) {
+    return `the control character U+${code.toString(16).toUpperCase().padStart(4, '0')}`;
+  }
+  if (ch === ' ') return 'a space';
+  const q = ch === "'" ? '"' : "'";
+  return `${q}${ch}${q}`;
+}
+
+/**
+ * Pure validator. Returns the first problem it finds, phrased as a sentence
+ * fragment that reads after "app name ... because".
+ *
+ * @param {unknown} name  the raw name as typed
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function checkAppName(name) {
+  // A non-string reaches here only from a programmatic caller, and calling it
+  // "empty" states something false about the input (a `123` is not empty), which
+  // is worse than no message at all when the reader is debugging their own call.
+  if (typeof name !== 'string') {
+    return { ok: false, reason: `an app name must be a string (this one is a ${typeof name})` };
+  }
+  if (name.length === 0) {
+    return { ok: false, reason: 'an app name cannot be empty' };
+  }
+  if (name.trim() !== name) {
+    return { ok: false, reason: 'an app name cannot start or end with whitespace' };
+  }
+  if (name.length > APP_NAME_MAX_LENGTH) {
+    return {
+      ok: false,
+      reason: `an app name cannot be longer than ${APP_NAME_MAX_LENGTH} characters (this one is ${name.length})`,
+    };
+  }
+  if (RESERVED_NAMES.includes(name.toLowerCase())) {
+    return { ok: false, reason: `'${name}' is reserved by npm and cannot be a package name` };
+  }
+  // Report the first offending character, since that is what the user has to
+  // change.
+  for (const ch of name) {
+    if (ALLOWED_CHAR.test(ch)) continue;
+    return { ok: false, reason: `${describeChar(ch)} is not allowed in an app name` };
+  }
+  // Checked after the character scan so a leading quote is reported as the bad
+  // character rather than as a leading-separator problem. Every separator is
+  // refused here, not just the leading dot and underscore npm itself refuses:
+  // the shape both error surfaces state is "starting with a letter or a digit",
+  // and a rule the message claims but does not enforce is worse than either
+  // rule on its own. A leading hyphen also reads as a flag everywhere the name
+  // is later used as a directory.
+  if (!ALLOWED_FIRST_CHAR.test(name[0])) {
+    return { ok: false, reason: `an app name cannot start with ${describeChar(name[0])}` };
+  }
+  return { ok: true };
+}
+
+/**
+ * The multi-line message the CLI prints. Kept here so the programmatic throw
+ * and the CLI output agree on the rule they state.
+ * @param {unknown} name
+ * @param {string} reason
+ * @returns {string}
+ */
+export function appNameErrorMessage(name, reason) {
+  return `Error: invalid app name "${describeName(name)}".
+
+${reason[0].toUpperCase()}${reason.slice(1)}.
+
+The name becomes the app's directory, its package.json name, AND a value the
+scaffold writes into generated source, so it is restricted to:
+
+  letters and digits
+  the separators "-", "." and "_"
+  starting with a letter or a digit
+  at most ${APP_NAME_MAX_LENGTH} characters
+  not ${RESERVED_NAMES.map((n) => `"${n}"`).join(' or ')} (npm reserves both)
+
+Example: webjs create my-app`;
+}
+
+/**
+ * Convenience wrapper for callers that want an exception. Throws with a
+ * single-line message (a thrown Error is read programmatically, so it stays
+ * compact) and returns the validated name otherwise.
+ * @param {unknown} name
+ * @returns {string}
+ */
+export function assertValidAppName(name) {
+  const result = checkAppName(name);
+  if (!result.ok) {
+    throw new Error(
+      `Invalid app name '${describeName(name)}'. ${result.reason[0].toUpperCase()}${result.reason.slice(1)}. Allowed: ${APP_NAME_SHAPE}.`,
+    );
+  }
+  return /** @type {string} */ (name);
+}

package/lib/create.js

@@ -18,6 +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';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -166,8 +167,11 @@ async function writeUiBootstrap(appDir) {
   );
   await writeFile(join(appDir, 'lib', 'utils', 'dom.ts'), domContent);
 
-  // 2) components.json: the same shape `webjsui init` writes for webjs
-  // projects (see packages/ui/src/utils/detect-project.js). The utils alias
+  // 2) components.json: byte for byte what `webjsui init` writes (see the
+  // DEFAULT_ALIASES / DEFAULT_TAILWIND_CSS constants in
+  // packages/ui/src/commands/init.js, which #1129 made the single source of
+  // these values). Keep the two in step: an app that scaffolds and one that
+  // runs `webjs ui init` must end up with the same config. The utils alias
   // is lib/utils/cn so get-config.js's `+ '.ts'` resolves to lib/utils/cn.ts.
   // The theme CSS lives at styles/globals.css, NOT app/globals.css: app/ is
   // routing-only, so a non-routing stylesheet does not belong there.
@@ -255,9 +259,15 @@ function assertUiRegistryAvailable() {
  * @param {string} cwd   Current working directory
  */
 export async function scaffoldApp(name, cwd, opts = {}) {
+  // Defence in depth, same as the template check below. `webjs create` already
+  // validates the name, but a programmatic caller can pass anything, and the
+  // name is interpolated into generated source as a template-literal value
+  // (#1066), so an unvalidated quote / backtick / `${` would emit a file that
+  // fails to parse. Throwing here happens before any directory is created.
+  assertValidAppName(name);
   const template = opts.template || 'full-stack';
-  // A human-friendly display title for the example home page. The npm `name`
-  // stays the raw slug (lowercase, hyphenated), but showing a hyphenated slug as
+  // A human-friendly display title for the example home page. The package
+  // `name` stays the raw slug as typed, but showing a hyphenated slug as
   // a hero title looks unpolished, so title-case it for display ("my-app" ->
   // "My App"). Replace this with your real brand anyway.
   const displayName = name.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
@@ -388,10 +398,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       '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).
+      // Project health: a contributor runs `npm run doctor` after cloning to
+      // assert the toolchain (Node floor, tsconfig flag, env drift, vendor
+      // pins, @webjsdev versions, git hook), and CI runs the same script. Which
+      // findings are FATAL comes from the `webjs.doctor.gate` block below, so
+      // the environment-shaped checks (env drift, pin freshness over the
+      // network, the git hook) stay warns and cannot make CI flaky.
       doctor: 'webjs doctor',
       'db:generate': 'webjs db generate',
       'db:migrate': 'webjs db migrate',
@@ -481,6 +493,17 @@ export async function scaffoldApp(name, cwd, opts = {}) {
         }),
       },
       start: { before: isApi ? ['webjs db migrate'] : ['webjs db migrate', cssBuildCmd] },
+      // Which doctor findings are FATAL is the app's own call (#1257), declared
+      // here rather than in the CI workflow so `npm run doctor` locally and the
+      // workflow step agree about what fails. UNMARKED_ASSET_LINKS starts at
+      // error because an un-versioned /public url is a real deploy-staleness
+      // bug (it shipped a visible regression on webjs.dev) and the generated
+      // layout already writes asset(), so a fresh app is green on day one.
+      // Two checks are fatal with no entry here at all, NODE_VERSION and
+      // TSCONFIG_ERASABLE, because either would 500 the app at runtime;
+      // everything else keeps its default warn. Add a code with "off" to
+      // silence it, or "error" to make it fatal too.
+      doctor: { gate: { UNMARKED_ASSET_LINKS: 'error' } },
     },
   }, null, 2) + '\n');
 
@@ -1149,6 +1172,7 @@ ${uiThemeRaw}
     await copyGallery(appDir);
 
   await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce, asset } from '@webjsdev/core';
+import type { LayoutProps } from '@webjsdev/core';
 import '#components/theme-toggle.ts';
 
 /**
@@ -1167,7 +1191,11 @@ import '#components/theme-toggle.ts';
 // lives at public/favicon.svg and serves at /public/favicon.svg.
 export const metadata = { icons: '/public/favicon.svg' };
 
-export default function RootLayout({ children }: { children: unknown }) {
+// LayoutProps types every layout argument (children, params, searchParams,
+// url) from the framework, so children is a TemplateResult rather than an
+// untyped value. Derive types like this everywhere instead of widening to
+// unknown; see .agents/skills/webjs/references/typescript.md.
+export default function RootLayout({ children }: LayoutProps) {
   // Read the in-flight request's CSP nonce so the theme-detection inline script
   // passes strict CSP. Returns '' when no CSP nonce is set.
   const nonce = cspNonce();