@webjsdev/cli 0.10.52 → 0.10.54

package/README.md

@@ -68,8 +68,8 @@ the CLI gives you `webjs ui` automatically. See
 
 The scaffold seeds opinionated defaults so AI agents produce consistent code:
 
-- `AGENTS.md` + `CONVENTIONS.md` (the machine-readable contract)
-- `.claude/`, `.cursorrules`, `.agents/rules/workflow.md` (Antigravity), `.github/copilot-instructions.md`
+- `AGENTS.md` + `CONVENTIONS.md` + `.agents/skills/webjs/` (single cross-agent source of truth)
+- `.agents/rules/workflow.md` & `.claude/` protective hooks
 - `test/<feature>/` (with optional `browser/` / `e2e/` subfolders per kind) with example tests
 - Tailwind CSS via CLI (no browser runtime at build time)
 - TypeScript, `.editorconfig`, `.gitignore`

package/bin/webjs.js

@@ -9,6 +9,7 @@ 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';
+import { findCheckTarget, notAnAppMessage, notAnAppJson } from '../lib/check-target.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
@@ -722,6 +723,22 @@ async function main() {
         break;
       }
 
+      // #1301: `webjs check` is an APP-level tool. At a workspace root it
+      // walks every package's tests and every app at once and reports
+      // cross-app collisions that no single runtime ever sees (67 false
+      // findings at this repo's root). Refuse instead, naming the member
+      // apps to run it in. Exit 1: an agent gates on the exit status, and
+      // 0 would read as "clean", the exact false signal this fixes.
+      const target = await findCheckTarget(process.cwd());
+      if (!target.isApp) {
+        if (rest.includes('--json')) {
+          console.log(JSON.stringify(notAnAppJson(process.cwd(), target.workspaceApps)));
+        } else {
+          console.error(notAnAppMessage(process.cwd(), target.workspaceApps));
+        }
+        process.exit(1);
+      }
+
       const violations = await checkConventions(process.cwd());
 
       // --json emits the raw structured violations + a summary count as JSON,

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/check-target.js

@@ -0,0 +1,145 @@
+/**
+ * `webjs check` invocation-target guard (#1301).
+ *
+ * `webjs check` is an APP-level tool: every rule assumes one application,
+ * meaning one module graph, one custom-element registry, one runtime. Run at a
+ * workspace root it walks whatever JS/TS happens to live under that path (two
+ * apps, every package's test suite, editor fixtures, the scaffold templates)
+ * and reports collisions no single runtime ever sees. At this repo's root that
+ * was 67 findings, all false.
+ *
+ * The predicate is the presence of an `app/` directory, nothing else. That is
+ * the same test `check.js` already applies per-rule, `app/` cannot be renamed
+ * (AGENTS.md "App layout"), and BOTH scaffold templates create it. Next.js
+ * refuses on the identical predicate in
+ * `packages/next/src/lib/find-pages-dir.ts`. A `workspaces` key is NOT part of
+ * the predicate (a directory with no `app/` is not an app either way); it only
+ * enriches the MESSAGE with the member apps to run instead.
+ *
+ * PURE apart from directory reads: it never prints and never exits. The bin
+ * owns rendering and the exit code.
+ *
+ * @module check-target
+ */
+
+import { statSync } from 'node:fs';
+import { readFile, glob } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * @typedef {{ isApp: boolean, workspaceApps: string[] }} CheckTarget
+ */
+
+/**
+ * Whether `dir` holds an `app/` DIRECTORY. A plain file named `app` is not one,
+ * and `existsSync` alone would call it one, so the type is checked. A broken
+ * symlink or an unreadable parent throws out of `statSync` rather than
+ * returning false, so it is caught: an unreadable path is not an app either.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function hasAppDir(dir) {
+  try {
+    return statSync(join(dir, 'app')).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Classify `cwd` as a checkable app or not, and (when it declares npm
+ * workspaces) list the member directories that ARE apps, sorted, as
+ * cwd-relative POSIX paths.
+ *
+ * @param {string} cwd
+ * @returns {Promise<CheckTarget>}
+ */
+export async function findCheckTarget(cwd) {
+  if (hasAppDir(cwd)) return { isApp: true, workspaceApps: [] };
+  return { isApp: false, workspaceApps: await workspaceApps(cwd) };
+}
+
+/**
+ * Expand `package.json` `workspaces` (the array form and yarn's
+ * `{ packages: [...] }` form) and keep the members that have an `app/`
+ * directory. Any read / parse failure yields an empty list: the message
+ * degrades to the generic form and the refusal still stands.
+ *
+ * @param {string} cwd
+ * @returns {Promise<string[]>}
+ */
+async function workspaceApps(cwd) {
+  let patterns;
+  try {
+    const pkg = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8'));
+    const ws = pkg.workspaces;
+    patterns = Array.isArray(ws) ? ws : Array.isArray(ws?.packages) ? ws.packages : null;
+  } catch {
+    return [];
+  }
+  if (!patterns) return [];
+  /** @type {Set<string>} */
+  const apps = new Set();
+  for (const pattern of patterns) {
+    if (typeof pattern !== 'string') continue;
+    try {
+      for await (const match of glob(pattern, { cwd })) {
+        // `glob` yields whatever matched, files included, so the app test is
+        // what filters a stray same-named file out too.
+        if (hasAppDir(join(cwd, match))) apps.add(match.split('\\').join('/'));
+      }
+    } catch {
+      // A malformed pattern drops out of the listing, never out of the refusal.
+    }
+  }
+  return [...apps].sort();
+}
+
+/**
+ * The human refusal, for stderr.
+ *
+ * @param {string} cwd
+ * @param {string[]} apps
+ * @returns {string}
+ */
+export function notAnAppMessage(cwd, apps) {
+  const lines = [
+    'webjs check: this directory is not a WebJs app, so nothing was checked.',
+    '',
+    `  ${cwd}`,
+    '',
+    'There is no `app/` directory here. Every check assumes ONE application',
+    '(one module graph, one custom-element registry, one runtime), so running',
+    'them over a workspace root reports collisions no single runtime ever sees.',
+    '',
+  ];
+  if (apps.length) {
+    lines.push('This is a workspace root. Run the check inside each app:', '');
+    for (const app of apps) lines.push(`  ( cd ${app} && npx webjs check )`);
+  } else {
+    lines.push('Change into your app directory (the one holding `app/`) and re-run.');
+  }
+  lines.push('', '`webjs check --rules` lists the rules and works from anywhere.');
+  return lines.join('\n');
+}
+
+/**
+ * The `--json` refusal. It carries NO `violations` key on purpose: a consumer
+ * that ignores the exit code and reads `report.violations.length` must throw
+ * rather than be told the workspace is clean.
+ *
+ * @param {string} cwd
+ * @param {string[]} apps
+ * @returns {{ error: { code: string, message: string, cwd: string, apps: string[] } }}
+ */
+export function notAnAppJson(cwd, apps) {
+  return {
+    error: {
+      code: 'NOT_AN_APP',
+      message: 'No `app/` directory here, so webjs check has no application to check.',
+      cwd,
+      apps,
+    },
+  };
+}

package/lib/create.js

@@ -12,13 +12,14 @@
  */
 
 import { mkdir, writeFile, readFile, cp } from 'node:fs/promises';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 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';
+import { isGalleryAppShellFile } from './gallery-shell-files.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -116,13 +117,20 @@ const UI_REGISTRY_ROOT = resolveUiRegistryRoot();
  * Ships verbatim (no `{{APP_NAME}}` substitution): the examples are self-
  * contained and reference only `@webjsdev/*`, drizzle, `#db/*`, and each other.
  * The scaffold's own `app/page.ts` / `app/layout.ts` are written AFTER this and
- * the gallery ships neither, so there is no clobber. `cp` merges into existing
- * `app/` and `modules/` dirs rather than replacing them.
+ * are filtered out of the copy here (see GALLERY_APP_SHELL_FILES), so there is
+ * no clobber. `cp` merges into existing `app/` and `modules/` dirs rather than
+ * replacing them.
+ *
+ * The source is the canonical repo-root `gallery/` app in monorepo dev, and the
+ * `templates/gallery/` copy `prepack` bundles into the tarball when installed
+ * from npm. Both are filtered identically, so the two modes emit the same app.
  *
  * @param {string} appDir
  */
 async function copyGallery(appDir) {
-  const galleryDir = join(TEMPLATES, 'gallery');
+  const bundledGallery = join(TEMPLATES, 'gallery');
+  const repoRootGallery = resolve(__dirname, '..', '..', '..', 'gallery');
+  const galleryDir = existsSync(bundledGallery) ? bundledGallery : repoRootGallery;
   // `test` carries the auth card's real request-pipeline test (test/auth); it
   // ships with the gallery and is pruned by gallery:clear alongside the card.
   // `components` carries the gallery's EXAMPLE design system (components/ui/ class
@@ -135,7 +143,15 @@ async function copyGallery(appDir) {
   // the ui bootstrap's cn.ts/dom.ts (written earlier); gallery:clear removes just
   // ui.ts. cp is recursive-merge, so the pre-written lib/utils/ files are kept.
   for (const sub of ['app', 'modules', 'test', 'components', 'lib']) {
-    await cp(join(galleryDir, sub), join(appDir, sub), { recursive: true });
+    const srcSub = join(galleryDir, sub);
+    if (!existsSync(srcSub)) continue;
+    await cp(srcSub, join(appDir, sub), {
+      recursive: true,
+      // Skip the gallery's own app shell (root layout, home page, theme toggle,
+      // cn.ts). Those exist because gallery/ is a live app; the scaffold writes
+      // its own, with the app's displayName and the ui-registry cn.ts.
+      filter: (src) => !isGalleryAppShellFile(relative(galleryDir, src)),
+    });
   }
 }
 
@@ -541,6 +557,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 +573,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       'components/**/*',
       'modules/**/*',
       'lib/**/*',
+      'test/**/*',
       'middleware.js',
       'middleware.ts',
       '.webjs/routes.d.ts',
@@ -562,26 +584,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   // --- Templates (AGENTS.md, CONVENTIONS.md, CLAUDE.md, test files, Claude hooks) ---
 
   const templateFiles = [
-    // Single cross-agent source: a thin AGENTS.md points at the skill; the
+    // Single cross-agent source: AGENTS.md points at .agents/skills/webjs/; the
     // .agents/rules workflow rules and the Claude enforcement hooks back it up.
     'AGENTS.md',
     'CONVENTIONS.md',
     '.agents/rules/workflow.md',
-    // Per-agent files. Content is single-source (AGENTS.md + the skill); these
-    // are thin bridges plus each tool's own config and commit-nudge hook. Claude
-    // Code (CLAUDE.md @-imports AGENTS.md), Gemini CLI (GEMINI.md), Copilot in VS
-    // Code (copilot-instructions.md). Cursor / opencode / Antigravity read
-    // AGENTS.md natively; Cursor also gets a .cursorrules bridge, and each of
-    // Cursor / Gemini / opencode ships a "commit often" nudge hook.
     'CLAUDE.md',
-    'GEMINI.md',
-    '.github/copilot-instructions.md',
-    '.cursorrules',
-    '.cursor/hooks.json',
-    '.cursor/hooks/nudge-uncommitted.sh',
-    '.gemini/settings.json',
-    '.gemini/hooks/nudge-uncommitted.sh',
-    '.opencode/plugins/nudge-uncommitted.ts',
     // Claude Code config + the protective enforcement hooks (no design ceremony).
     '.claude.json',
     '.claude/settings.json',
@@ -623,7 +631,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   // rewrites; the three infra files get their file-specific transform. On Node,
   // every file is copied byte-identical (the map is empty).
   const PROSE_REWRITE = new Set([
-    'AGENTS.md', 'CLAUDE.md', 'CONVENTIONS.md', '.cursorrules',
+    'AGENTS.md', 'CLAUDE.md', 'CONVENTIONS.md',
     '.agents/rules/workflow.md',
     'test/hello/browser/hello.test.js', 'test/hello/e2e/hello.test.ts',
   ]);
@@ -877,9 +885,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)) {
@@ -1365,13 +1378,16 @@ import { cardClass } from '#components/ui/card.ts';
 import { badgeClass } from '#components/ui/badge.ts';
 // The demo index is defined once in modules/gallery/nav.ts (the same source the
 // left sidebar reads), so the home cards and the sidebar can never drift.
-import { FEATURES, EXAMPLES } from '#modules/gallery/nav.ts';
+import { featureList, EXAMPLES } from '#modules/gallery/nav.ts';
 
 export const metadata = {
   title: '${displayName}',
 };
 
 export default function Home() {
+  // Flattened HERE rather than at module scope. A top-level call is a module
+  // side effect, which would ship this page to the browser for nothing.
+  const FEATURES = featureList();
   return html\`
     <div class="py-8 flex flex-col items-center gap-16">
       <!-- Hero -->
@@ -1596,7 +1612,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

package/lib/doctor.js

@@ -52,7 +52,7 @@
 
 import { existsSync, statSync, readdirSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { createRequire } from 'node:module';
 import { checkNodeInline } from './node-preflight.js';
 
@@ -837,13 +837,87 @@ async function checkImportmapCoherence(appDir, opts) {
   };
 }
 
+/**
+ * Read a dependency's INSTALLED version as resolved FROM `appDir`, or null when
+ * it does not resolve there at all.
+ *
+ * Node's own resolver is the ground truth here, not a directory read. The check
+ * this serves asks "would this app resolve this dependency at runtime, and at
+ * what version", and Node's resolution algorithm IS that question's definition,
+ * so anything re-implementing it can only be a worse approximation. Asking Node
+ * handles workspace hoisting (the bug this fixes: under npm workspaces the
+ * `@webjsdev/*` deps hoist to the ROOT node_modules, so an app subdirectory has
+ * no local copy and a per-app `node_modules/<dep>/package.json` read reported
+ * every declared dep missing on a healthy install), symlinked workspace links,
+ * nested non-hoisted trees, and `package.json` `imports`, for free and for ever.
+ *
+ * The direct `<dep>/package.json` resolve is attempted FIRST because a package
+ * may declare no main entry at all: `@webjsdev/cli` is bin-only (no `main`, no
+ * `exports`), so `require.resolve('@webjsdev/cli')` throws MODULE_NOT_FOUND.
+ * The ERR_PACKAGE_PATH_NOT_EXPORTED fallback exists because a package may lock
+ * its manifest out of its `exports` map: `@webjsdev/server` exports only `.`,
+ * `./check`, `./testing`, and `./webjs-config.schema.json`, so the direct
+ * manifest resolve is refused and the main entry plus a bounded walk up to the
+ * package root is the way in. Neither strategy alone resolves all four
+ * `@webjsdev/*` packages; both halves are required.
+ *
+ * Local rather than `getPackageVersion` from `@webjsdev/server` for two reasons.
+ * Doctor must stay usable when the framework does not resolve from the app dir
+ * at all, which is the #954 fresh-worktree case doctor exists to diagnose, so
+ * this check cannot import the server (the same argument `frameworkResolves`
+ * below already follows). And `getPackageVersion` resolves the main entry only,
+ * so it returns null for a bin-only package, which would leave `@webjsdev/cli`
+ * reported missing: the same false positive with more machinery.
+ *
+ * Pinned by the workspace, bin-only, and exports-locked fixtures in
+ * `test/cli/doctor.test.mjs`.
+ * @param {string} dep package name, e.g. `@webjsdev/server`
+ * @param {string} appDir directory to anchor resolution at
+ * @returns {Promise<string|null>} the installed version, or null when unresolvable
+ */
+async function readInstalledVersion(dep, appDir) {
+  // The base file need not exist; createRequire only uses it to anchor the
+  // node_modules lookup at appDir.
+  const require = createRequire(join(appDir, '__webjs_resolve_probe__.js'));
+  let manifestPath = null;
+  try {
+    manifestPath = require.resolve(dep + '/package.json');
+  } catch (err) {
+    if (err?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') return null;
+    let entry;
+    try {
+      entry = require.resolve(dep);
+    } catch {
+      return null;
+    }
+    let dir = dirname(entry);
+    for (let i = 0; i < 12; i++) {
+      const candidate = join(dir, 'package.json');
+      if (existsSync(candidate)) {
+        manifestPath = candidate;
+        break;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    if (!manifestPath) return null;
+  }
+  try {
+    return JSON.parse(await readFile(manifestPath, 'utf8')).version || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * CHECK 5, @webjsdev/* version coherence. WARN-level only (a version drift is
  * not a crash). Reads the app package.json `@webjsdev/*` ranges across
- * dependencies + devDependencies, then for each reads the INSTALLED version from
- * `node_modules/@webjsdev/<pkg>/package.json` and checks it satisfies the
- * declared range. PASS when every @webjsdev dep is present + satisfied; WARN on
- * a missing install or a range drift.
+ * dependencies + devDependencies, then for each resolves the INSTALLED version
+ * through Node's own resolver anchored at the app dir (see
+ * `readInstalledVersion`, which is why a workspace-hoisted install resolves)
+ * and checks it satisfies the declared range. PASS when every @webjsdev dep is
+ * present + satisfied; WARN on a missing install or a range drift.
  * @param {string} appDir
  * @returns {Promise<DoctorResult>}
  */
@@ -881,15 +955,8 @@ async function checkWebjsVersions(appDir) {
   const missing = [];
   const drift = [];
   for (const dep of webjsDeps) {
-    const installedPkg = join(appDir, 'node_modules', dep, 'package.json');
-    if (!existsSync(installedPkg)) {
-      missing.push(dep);
-      continue;
-    }
-    let installedVersion = '';
-    try {
-      installedVersion = JSON.parse(await readFile(installedPkg, 'utf8')).version || '';
-    } catch {
+    const installedVersion = await readInstalledVersion(dep, appDir);
+    if (!installedVersion) {
       missing.push(dep);
       continue;
     }
@@ -1329,11 +1396,19 @@ function unmarkedStylesheetHref(tag, basePath = '') {
  * Ported rather than imported because that helper is not on `@webjsdev/server`'s
  * public surface, and because doctor must stay usable when the framework does
  * not resolve from the app dir at all (the #954 fresh-worktree case this same
- * command exists to diagnose). `test/cli/doctor.test.mjs` pins the forms.
+ * command exists to diagnose). The port is intentional and stays. What makes it
+ * safe is that the drift is tested rather than trusted.
+ *
+ * `test/cli/base-path-parity.test.mjs` feeds one input table through BOTH this
+ * function and the server's `readBasePath`, asserting they agree with each other
+ * and with the expected value. Change either side without the other and it reds.
+ * So edit this body only alongside `packages/server/src/base-path.js`, and run
+ * that test. (`test/cli/doctor.test.mjs` covers the check that consumes this,
+ * not the normalization forms themselves.)
  * @param {string} appDir
  * @returns {Promise<string>}
  */
-async function readAppBasePath(appDir) {
+export async function readAppBasePath(appDir) {
   let raw;
   try {
     const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));

package/lib/gallery-shell-files.js

@@ -0,0 +1,36 @@
+/**
+ * The files the canonical `gallery/` app owns only because it is a RUNNABLE
+ * WebJs app, and which the scaffold (`webjs create`) generates itself.
+ *
+ * `gallery/` is both the single source of the scaffold's feature gallery AND a
+ * live app deployed on its own, so it needs a root layout, a home page, a theme
+ * toggle, and the `cn()` helper. The scaffold writes all four itself, with
+ * things the gallery's copies cannot carry: the app's `displayName`, the
+ * `cspNonce()` wiring, `LayoutProps` typing, the `metadata.icons` favicon, and
+ * a `cn.ts` read verbatim from the `@webjsdev/ui` registry so `webjs ui add`
+ * stays in lockstep with the kit.
+ *
+ * So they are the ONE part of `gallery/` that is not scaffold payload. They are
+ * dropped from the published bundle (`scripts/sync-scaffold-gallery.mjs`) and
+ * skipped by `copyGallery()` so monorepo-dev and installed-npm scaffolding emit
+ * byte-identical apps. Paths are POSIX-relative to the gallery root.
+ *
+ * @type {readonly string[]}
+ */
+export const GALLERY_APP_SHELL_FILES = Object.freeze([
+  'app/layout.ts',
+  'app/page.ts',
+  'components/theme-toggle.ts',
+  'lib/utils/cn.ts',
+]);
+
+/**
+ * True when `relPath` (POSIX-relative to the gallery root) is a gallery-only
+ * app-shell file rather than scaffold payload.
+ *
+ * @param {string} relPath
+ * @returns {boolean}
+ */
+export function isGalleryAppShellFile(relPath) {
+  return GALLERY_APP_SHELL_FILES.includes(relPath.split('\\').join('/'));
+}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.52",
+  "version": "0.10.54",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
     "webjs": "bin/webjs.js"
   },
   "scripts": {
-    "prepack": "node ../../scripts/sync-scaffold-skill.mjs",
-    "postpack": "node ../../scripts/sync-scaffold-skill.mjs --clean"
+    "prepack": "node ../../scripts/sync-scaffold-skill.mjs && node ../../scripts/sync-scaffold-gallery.mjs",
+    "postpack": "node ../../scripts/sync-scaffold-skill.mjs --clean && node ../../scripts/sync-scaffold-gallery.mjs --clean"
   },
   "files": [
     "bin",

package/templates/.agents/skills/webjs/SKILL.md

@@ -38,7 +38,7 @@ Classify the task first, then load the smallest useful reference set. Each refer
 | Task involves...                                                            | Start with                                    |
 | --------------------------------------------------------------------------- | --------------------------------------------- |
 | Pages, layouts, dynamic routes, route handlers, metadata, redirects, 404s   | `references/routing-and-pages.md`             |
-| Writing components: reactive props, signals, lifecycle, light vs shadow DOM  | `references/components.md`                     |
+| Writing components: what a component owns, reactive props, signals, lifecycle, light vs shadow DOM  | `references/components.md`                     |
 | Why a component's JS was or was not downloaded, `webjs elision`, `static interactive = true` | `references/components.md`                     |
 | Server actions, mutations, queries, validation, the `ActionResult` envelope | `references/data-and-actions.md`              |
 | Sessions, login flows, route protection, `forbidden()` / `unauthorized()`   | `references/auth-and-sessions.md`             |
@@ -238,8 +238,12 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 - Writing a bare `<form method="post">` and expecting a page `action` export to catch it. There is no such export; bind the action with `action=${fn}` or the submission is a 405.
 - Putting a submitter's `formaction=${fn}` on anything that is not a submit control, or on a button carrying its own `name` / `value`. The identity IS the button's name/value pair, so both halves are spoken for.
 - Writing `formmethod="get"` or `formenctype="text/plain"` on a button that BINDS an action. Neither can carry that action's body, so the pair contradicts itself and throws. On a button that binds nothing it is a legal native override and is honoured.
-- Binding an action whose file declares `export const method = 'GET'`. That is a 405 at runtime and a `webjs check` error.
+- Binding an action whose file declares `export const method = 'GET'`. Form-bound actions strictly require POST (default). Binding a GET action to a form is a 405 at runtime and a `webjs check` error (`form-action-not-a-get-action`).
+- Leaving read-only RPC server query actions as default `POST`. Always export `export const method = 'GET'` for RPC data queries so arguments ride URL params, ETags/304 caching work, and CSRF is safely bypassed.
+- Writing `method="get"` on a bound `<form action=${fn}>`. WebJs supplies `method="post"` and `formenctype` automatically, and a bound form declaring `method="get"` is REFUSED at render (a thrown error, not a warning), because a GET sends no body for the action to read.
 - Throwing `redirect()` / `notFound()` inside a `route.ts` handler (uncaught 500). Return a `Response` there.
 - A placeholder first paint that fetches in `connectedCallback`. SSR does not call `connectedCallback`; put first-paint data in the constructor (server-known inputs) or use `async render()`.
 - A browser global (`window`, `document`, `localStorage`) in the constructor or `render()`. It throws at SSR; do browser-only work in `connectedCallback`.
 - Interpolating into a component's `<style>` / `<script>` body. Use `static styles` or Tailwind.
+- Driving a component's markup from a delegated `document` listener in a page or layout, coupled by a class selector. The markup, the state, and the listener belong in one component.
+- Parking one component's UI state on `<body>` or `<html>`. The router's swap range never covers the document shell, so the flag outlives the markup it described. A document-wide SETTING such as the theme is the exception, and a transient effect such as a scroll lock is released in `disconnectedCallback`.

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -145,7 +145,7 @@ setFileStore(diskStore({ dir: '/var/data/uploads', baseUrl: '/files' }));
 
 ## The `"webjs"` config block (package.json)
 
-All keys are optional, and a malformed entry in a key the SERVER reads is dropped at boot with a warning, never crashing the pipeline. The one exception is `doctor.gate`, which is read by the `webjs doctor` CLI rather than the server and rejects a bad entry outright (see the doctor severity gate below): a gate whose typo was quietly ignored would leave CI un-gated while looking gated, which is the one thing that mechanism cannot afford.
+All keys are optional, and a malformed entry in a key the SERVER reads is dropped at boot rather than crashing the pipeline, some readers warning as they drop it. `headers` and `redirects` warn on every drop. Both warn for the key itself when it is present but not an array, and for each rule or entry inside it; `headers` has a third level and warns per header directive too. An absent key is the default and says nothing. An UNKNOWN top-level key no longer passes in silence either (#1300): the block is validated against the published JSON Schema once per boot, in dev and in prod alike, and one aggregated warning names what was ignored. So a `"redirect"` typed for `"redirects"` now says so in the server output instead of silently leaving the feature at its default. It never fails the boot. Know its exact reach, since what it passes over looks like what it catches. It reports any unknown TOP-LEVEL key, whatever it is called, and it checks the VALUE of 9 of the 17 known keys, being the one `enum` and the `boolean` / `integer` leaves. It does not descend into a nested object, so a misspelling inside `dev` or `start` is not reported, and it does not type-check the other 8 (`headers`, `redirects`, `basePath`, `allowedOrigins`, `csp`, `dev`, `start`, `doctor`), whose schemas are the free-form ones a blunt check would start refusing working configs over. Whether anything else notices a value this check passes over is up to that value's own reader, and it varies by reader. `doctor.gate` varies furthest, since the boot check never descends into any key and the `webjs doctor` CLI, not the server, is what reads this one, rejecting a bad entry outright (see the doctor severity gate below): a gate whose typo was quietly ignored would leave CI un-gated while looking gated, which is the one thing that mechanism cannot afford.
 
 ### Security headers