@webjsdev/cli 0.10.58 → 0.10.59

package/README.md

@@ -33,7 +33,7 @@ npx @webjsdev/cli create my-app
 cd my-app && npm run dev
 ```
 
-Both `webjs create` and `create-webjs-app` auto-install dependencies in the new directory using your detected package manager (npm / pnpm / yarn / bun). Pass `--no-install` to opt out.
+Both `webjs create` and `create-webjs-app` auto-install dependencies in the new directory using your detected package manager (npm / pnpm / yarn / bun: the invoking tool, else the enclosing project's lockfile). Pass `--no-install` to opt out.
 
 ## Commands
 

package/bin/webjs.js

@@ -103,6 +103,8 @@ const USAGE = `webjs commands:
                                                   --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 audit [--json]                            Run the npm / bun dependency audit, failing at "webjs": { "audit": { "level" } } (default high)
+                                                  and above, minus the advisories "webjs.audit.ignore" accepts, each with its reason
   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] [--skip-ci]  Scaffold a new webjs app
@@ -226,6 +228,22 @@ const HELP = {
     ],
     examples: ['webjs elision', 'webjs elision --json', 'webjs elision --verify', 'webjs elision --verify --routes /,/blog/hello'],
   },
+  audit: {
+    usage: 'webjs audit [--json]',
+    summary:
+      'Run the package manager\'s dependency audit (npm or bun, found by the nearest lockfile) and fail on any advisory at or above ' +
+      'webjs.audit.level (default high), except the ones webjs.audit.ignore lists, each with the reason it is safe to accept.',
+    options: [
+      { flag: '--json', description: 'Emit { ok, manager, level, failing[], ignored[], stale[] } as JSON.' },
+    ],
+    notes: [
+      'Config lives in package.json, in one place:',
+      '"webjs": { "audit": { "level": "high", "ignore": [{ "id": "GHSA-...", "reason": "..." }] } }.',
+      'An entry with no reason, an unknown key, or a bad level exits 1 naming it. An ignored id',
+      'the audit no longer reports is printed as stale, so the list shrinks when a fix ships.',
+    ],
+    examples: ['webjs audit', 'webjs audit --json'],
+  },
   doctor: {
     usage: 'webjs doctor [--json] [--strict]',
     summary: 'Verify project health. Each result carries a stable code so an agent branches on the failure kind.',
@@ -749,7 +767,32 @@ async function main() {
         const useBrowserDir = !hasConfig && !serverOnly && existsSync(join(cwd, 'test', 'browser'));
         // Only resolve + run when there is actually something to run, so a
         // `webjs test` with no browser tests stays a no-op (not a hard error).
+        // Zero browser test files is a pass, not a failure (#1491). WTR throws
+        // `Could not find any test files` on an empty match, so an app with no
+        // browser tests yet (what `gallery:clear` leaves) would fail its own CI
+        // on this layer. Check the globs first and skip with a note. `null`
+        // patterns mean the config's `files` is not a plain literal, so WTR
+        // runs unchanged and reports for itself.
+        let noBrowserTests = false;
         if (hasConfig || useBrowserDir) {
+          const { readFile } = await import('node:fs/promises');
+          const { readWtrFilePatterns, findBrowserTestFiles } = await import('../lib/browser-test-files.js');
+          let patterns = ['test/browser/**/*.test.js'];
+          if (hasConfig) {
+            const cfg = existsSync(join(cwd, 'web-test-runner.config.js'))
+              ? 'web-test-runner.config.js' : 'web-test-runner.config.mjs';
+            patterns = readWtrFilePatterns(await readFile(join(cwd, cfg), 'utf8'));
+          }
+          if (patterns && (await findBrowserTestFiles(cwd, patterns)).length === 0) {
+            noBrowserTests = true;
+            console.log(
+              '\nwebjs test: no browser tests yet (no file matches '
+              + (patterns.length ? patterns.join(', ') : 'the configured `files`')
+              + '), skipping the browser layer.',
+            );
+          }
+        }
+        if ((hasConfig || useBrowserDir) && !noBrowserTests) {
           // Resolve the app's @web/test-runner bin and spawn it with the current
           // runtime, dropping `npx` (#570; absent in a pure oven/bun image).
           let wtrPath;
@@ -977,6 +1020,60 @@ async function main() {
       }
       break;
     }
+    case 'audit': {
+      // Dependency audit with a reviewable allowlist (#1492). npm has no ignore
+      // flag, so both managers' JSON reports are parsed and filtered the same
+      // way here (see lib/audit.js for why each part fails closed).
+      const cwd = process.cwd();
+      const json = rest.includes('--json');
+      const { readAuditConfigFrom, detectAuditManager, parseAuditReport, applyAuditConfig } = await import('../lib/audit.js');
+      const { config, errors } = readAuditConfigFrom(cwd);
+      if (errors.length) {
+        for (const e of errors) console.error(`webjs audit: ${e}`);
+        process.exit(1);
+      }
+      const pm = detectAuditManager(cwd);
+      if (pm !== 'npm' && pm !== 'bun') {
+        console.error(`webjs audit: drives npm and bun audits; this project uses ${pm}. Run \`${pm} audit\` directly.`);
+        process.exit(1);
+      }
+      const { spawnSync } = await import('node:child_process');
+      const res = spawnSync(pm, ['audit', '--json'], {
+        cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, shell: process.platform === 'win32',
+      });
+      const advisories = res.error ? null : parseAuditReport(pm, res.stdout || '');
+      if (!advisories) {
+        console.error(`webjs audit: \`${pm} audit --json\` produced no report${res.error ? ` (${res.error.message})` : ''}.`);
+        if (res.stderr) console.error(res.stderr.trim());
+        process.exit(1);
+      }
+      const { failing, ignored, stale } = applyAuditConfig(advisories, config);
+      const reasonOf = (id) => config.ignore.find((i) => i.id.toUpperCase() === id.toUpperCase())?.reason || '';
+      if (json) {
+        console.log(JSON.stringify({
+          ok: failing.length === 0, manager: pm, level: config.level, failing,
+          ignored: ignored.map((a) => ({ ...a, reason: reasonOf(a.id) })), stale,
+        }, null, 2));
+        process.exit(failing.length ? 1 : 0);
+      }
+      console.log(`webjs audit: ${pm} audit, failing at ${config.level} and above`);
+      for (const a of ignored) {
+        console.log(`  ignored ${a.id} (${a.severity}, ${a.packages.join(', ')}): ${reasonOf(a.id)}`);
+      }
+      for (const i of stale) {
+        console.log(`  stale   ${i.id} is no longer reported; remove it from webjs.audit.ignore`);
+      }
+      if (failing.length) {
+        for (const a of failing) {
+          console.log(`  FAIL    ${a.id} (${a.severity}, ${a.packages.join(', ')}): ${a.title}${a.url ? ` ${a.url}` : ''}`);
+        }
+        console.log(`\nwebjs audit: ${failing.length} advisor${failing.length === 1 ? 'y' : 'ies'} at ${config.level} or above. ` +
+          'Upgrade the dependency, or, when no patched release exists and it cannot reach users, add it to webjs.audit.ignore with a reason.');
+        process.exit(1);
+      }
+      console.log(`webjs audit: no ${config.level}+ advisories outside the allowlist ✓`);
+      break;
+    }
     case 'doctor': {
       // Project-health checklist (#266). The checks are PURE (in lib/doctor.js);
       // this branch only renders them and owns the exit code. The exit is

package/lib/audit.js

@@ -0,0 +1,218 @@
+/**
+ * `webjs audit`: the dependency audit with a reviewable allowlist (#1492).
+ *
+ * A freshly generated app used to fail its own `Security: dependency audit`
+ * CI step on the day it was created, because the dev toolchain reaches an
+ * advisory with NO patched release (braces, GHSA-vfj7-8cjw-p6xm, through the
+ * Tailwind watcher and the test runner's globber). Nothing can be upgraded,
+ * so the step was red until someone deleted it, which also throws away the
+ * signal for every advisory that DOES have a fix.
+ *
+ * So the app declares the advisories it accepts, in ONE place, each with the
+ * reason it is safe, under `webjs.audit` in package.json:
+ *
+ *   "audit": {
+ *     "level": "high",
+ *     "ignore": [{ "id": "GHSA-...", "reason": "why this cannot reach users" }]
+ *   }
+ *
+ * and `webjs audit` runs the package manager's own audit (`npm audit --json`
+ * or `bun audit --json`) and filters that report here, the same way for both,
+ * since npm has no ignore flag at all. Every other advisory at or above
+ * `level` still fails.
+ *
+ * The config fails CLOSED, like the doctor gate: an entry without an id or a
+ * reason, an unknown key, or a bad level exits 1 naming the problem, because
+ * an allowlist that silently stopped applying (or silently applied to
+ * everything) would be worse than none. An ignored id that no longer appears in
+ * the report is printed as stale, so the list shrinks when upstream ships a fix.
+ *
+ * @module audit
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const AUDIT_LEVELS = ['low', 'moderate', 'high', 'critical'];
+
+/**
+ * @typedef {{ id: string, reason: string }} AuditIgnore
+ * @typedef {{ level: string, ignore: AuditIgnore[] }} AuditConfig
+ * @typedef {{ id: string, url: string, severity: string, title: string, packages: string[] }} Advisory
+ */
+
+/**
+ * Read and validate `webjs.audit` from a parsed package.json.
+ *
+ * @param {Record<string, any>} pkg
+ * @returns {{ config: AuditConfig, errors: string[] }}
+ */
+export function readAuditConfig(pkg) {
+  /** @type {AuditConfig} */
+  const config = { level: 'high', ignore: [] };
+  /** @type {string[]} */
+  const errors = [];
+  const raw = pkg?.webjs?.audit;
+  if (raw === undefined) return { config, errors };
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { config, errors: ['webjs.audit must be an object'] };
+  }
+  for (const key of Object.keys(raw)) {
+    if (key !== 'level' && key !== 'ignore') errors.push(`webjs.audit: unknown key "${key}" (expected "level" or "ignore")`);
+  }
+  if (raw.level !== undefined) {
+    if (!AUDIT_LEVELS.includes(raw.level)) errors.push(`webjs.audit.level must be one of ${AUDIT_LEVELS.join(', ')}`);
+    else config.level = raw.level;
+  }
+  if (raw.ignore !== undefined) {
+    if (!Array.isArray(raw.ignore)) {
+      errors.push('webjs.audit.ignore must be an array of { id, reason }');
+    } else {
+      raw.ignore.forEach((entry, i) => {
+        const at = `webjs.audit.ignore[${i}]`;
+        if (!entry || typeof entry !== 'object') { errors.push(`${at} must be an object { id, reason }`); return; }
+        const extra = Object.keys(entry).filter((k) => k !== 'id' && k !== 'reason');
+        if (extra.length) errors.push(`${at}: unknown key "${extra[0]}" (expected "id" and "reason")`);
+        if (typeof entry.id !== 'string' || !/^(GHSA(-[0-9a-z]{4}){3}|CVE-\d{4}-\d+)$/i.test(entry.id)) {
+          errors.push(`${at}.id must be an advisory id such as GHSA-xxxx-xxxx-xxxx or CVE-2024-12345`);
+          return;
+        }
+        if (typeof entry.reason !== 'string' || entry.reason.trim() === '') {
+          errors.push(`${at} (${entry.id}) needs a non-empty "reason" saying why it is safe to accept`);
+          return;
+        }
+        config.ignore.push({ id: entry.id, reason: entry.reason });
+      });
+    }
+  }
+  return { config, errors };
+}
+
+/**
+ * Which package manager's audit to run. Walks up from `cwd` to the first
+ * lockfile, since an app inside a workspace has its lockfile at the root.
+ * Only bun and npm have an audit this command drives; anything else is
+ * reported as unsupported by the caller.
+ *
+ * @param {string} cwd
+ * @returns {'bun' | 'npm' | 'pnpm' | 'yarn'}
+ */
+export function detectAuditManager(cwd) {
+  let dir = cwd;
+  for (;;) {
+    if (existsSync(join(dir, 'bun.lock')) || existsSync(join(dir, 'bun.lockb'))) return 'bun';
+    if (existsSync(join(dir, 'package-lock.json')) || existsSync(join(dir, 'npm-shrinkwrap.json'))) return 'npm';
+    if (existsSync(join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (existsSync(join(dir, 'yarn.lock'))) return 'yarn';
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.versions.bun ? 'bun' : 'npm';
+}
+
+/** The advisory id at the end of a GitHub advisory url. */
+function idFromUrl(url) {
+  const m = /(GHSA(?:-[0-9a-z]{4}){3})/i.exec(url || '');
+  return m ? m[1] : '';
+}
+
+/**
+ * The source advisories in an `npm audit --json` (v2 report format) report,
+ * deduplicated by id. A vulnerability entry whose `via` holds only package
+ * NAMES is a dependent of one of these, not an advisory of its own, so it is
+ * covered by filtering the advisories it inherits from.
+ *
+ * @param {any} report
+ * @returns {Advisory[]}
+ */
+export function npmAdvisories(report) {
+  /** @type {Map<string, Advisory>} */
+  const byId = new Map();
+  for (const [name, vuln] of Object.entries(report?.vulnerabilities || {})) {
+    for (const via of /** @type {any} */ (vuln).via || []) {
+      if (!via || typeof via !== 'object') continue;
+      const id = idFromUrl(via.url) || String(via.source ?? via.url);
+      const cur = byId.get(id);
+      if (cur) { if (!cur.packages.includes(name)) cur.packages.push(name); continue; }
+      byId.set(id, { id, url: via.url || '', severity: via.severity || 'low', title: via.title || '', packages: [name] });
+    }
+  }
+  return [...byId.values()];
+}
+
+/**
+ * Split advisories into the ones that still fail and the ones the allowlist
+ * accepted, keeping only those at or above `level`.
+ *
+ * @param {Advisory[]} advisories
+ * @param {AuditConfig} config
+ * @returns {{ failing: Advisory[], ignored: Advisory[], stale: AuditIgnore[] }}
+ */
+export function applyAuditConfig(advisories, config) {
+  const floor = AUDIT_LEVELS.indexOf(config.level);
+  const atLevel = advisories.filter((a) => AUDIT_LEVELS.indexOf(a.severity) >= floor);
+  const ids = new Set(config.ignore.map((i) => i.id.toUpperCase()));
+  const failing = atLevel.filter((a) => !ids.has(a.id.toUpperCase()));
+  const ignored = atLevel.filter((a) => ids.has(a.id.toUpperCase()));
+  const seen = new Set(advisories.map((a) => a.id.toUpperCase()));
+  const stale = config.ignore.filter((i) => !seen.has(i.id.toUpperCase()));
+  return { failing, ignored, stale };
+}
+
+/**
+ * The source advisories in a `bun audit --json` report, which is keyed by
+ * package name with a list of advisories each.
+ *
+ * @param {any} report
+ * @returns {Advisory[]}
+ */
+export function bunAdvisories(report) {
+  /** @type {Map<string, Advisory>} */
+  const byId = new Map();
+  for (const [name, list] of Object.entries(report || {})) {
+    if (!Array.isArray(list)) continue;
+    for (const adv of list) {
+      const id = idFromUrl(adv?.url) || String(adv?.id ?? adv?.url);
+      const cur = byId.get(id);
+      if (cur) { if (!cur.packages.includes(name)) cur.packages.push(name); continue; }
+      byId.set(id, { id, url: adv?.url || '', severity: adv?.severity || 'low', title: adv?.title || '', packages: [name] });
+    }
+  }
+  return [...byId.values()];
+}
+
+/**
+ * Parse a package manager's `audit --json` stdout into advisories. Both
+ * managers exit non-zero when they find anything, so the exit code says
+ * nothing; an unparseable stdout (a registry outage, an old manager) returns
+ * `null` and the caller fails closed.
+ *
+ * @param {'bun' | 'npm'} pm
+ * @param {string} stdout
+ * @returns {Advisory[] | null}
+ */
+export function parseAuditReport(pm, stdout) {
+  let report;
+  try { report = JSON.parse(stdout); } catch { return null; }
+  if (!report || typeof report !== 'object') return null;
+  if (pm === 'npm') {
+    if (report.error) return null;
+    return npmAdvisories(report);
+  }
+  return bunAdvisories(report);
+}
+
+/**
+ * Read `webjs.audit` from the package.json in `cwd`.
+ *
+ * @param {string} cwd
+ */
+export function readAuditConfigFrom(cwd) {
+  const p = join(cwd, 'package.json');
+  if (!existsSync(p)) return { config: { level: 'high', ignore: [] }, errors: ['no package.json in this directory'] };
+  try {
+    return readAuditConfig(JSON.parse(readFileSync(p, 'utf8')));
+  } catch (e) {
+    return { config: { level: 'high', ignore: [] }, errors: [`package.json is not valid JSON: ${/** @type {Error} */ (e).message}`] };
+  }
+}

package/lib/browser-test-files.js

@@ -0,0 +1,125 @@
+/**
+ * Decide whether `webjs test --browser` has anything to run (#1491).
+ *
+ * web-test-runner throws `Could not find any test files with pattern(s)` when
+ * its `files` globs match nothing, so an app with no browser tests yet (the
+ * state `npm run gallery:clear` leaves behind) fails its own CI on the browser
+ * layer. A missing layer is not a failing layer: the server layer already
+ * passes with zero files, and the browser layer should too. WTR raises the
+ * error while building its session groups, after it has started, so the check
+ * has to happen here, before it is spawned.
+ *
+ * The globs are read from the config's SOURCE rather than by importing it,
+ * because the scaffold's config top-level-awaits a warmed webjs handler (the
+ * whole app boots) just to answer a question a file walk can answer. When the
+ * `files` value is not a plain literal (computed, imported, spread), the
+ * patterns come back `null` and the caller runs WTR exactly as before, so a
+ * config this reader does not understand never turns into a silent skip.
+ *
+ * @module browser-test-files
+ */
+import { readdir } from 'node:fs/promises';
+import { join, relative, sep, matchesGlob } from 'node:path';
+
+/**
+ * Pull the `files` globs out of a web-test-runner config's source text.
+ * Accepts `files: 'one/glob'` and `files: ['a', "b", ...]` with only string
+ * literals inside the array. Anything else returns `null` (unknown).
+ *
+ * @param {string} source
+ * @returns {string[] | null}
+ */
+export function readWtrFilePatterns(source) {
+  // Strip line + block comments first, so a commented-out `files:` cannot
+  // match and a comment inside the array does not read as a non-literal.
+  const code = stripComments(source);
+  const single = code.match(/\bfiles\s*:\s*(['"])([^'"]+)\1\s*[,}\n]/);
+  if (single) return [single[2]];
+  const arr = code.match(/\bfiles\s*:\s*\[([\s\S]*?)\]/);
+  if (!arr) return null;
+  const body = arr[1].trim();
+  if (body === '') return [];
+  const out = [];
+  // Every comma-separated element must be a quoted string literal.
+  for (const raw of body.split(',')) {
+    const el = raw.trim();
+    if (el === '') continue; // trailing comma
+    const m = el.match(/^(['"])([^'"]*)\1$/);
+    if (!m) return null;
+    out.push(m[2]);
+  }
+  return out;
+}
+
+/**
+ * Walk `cwd` and return the app-relative paths (forward slashes) matching
+ * the include globs and none of the `!`-prefixed exclude globs. Skips
+ * `node_modules` and dot directories, which WTR's globber skips too.
+ *
+ * @param {string} cwd
+ * @param {string[]} patterns
+ * @returns {Promise<string[]>}
+ */
+export async function findBrowserTestFiles(cwd, patterns) {
+  const include = patterns.filter((p) => !p.startsWith('!')).map(normalize);
+  const exclude = patterns.filter((p) => p.startsWith('!')).map((p) => normalize(p.slice(1)));
+  if (include.length === 0) return [];
+  const found = [];
+  const walk = async (dir) => {
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const ent of entries) {
+      if (ent.name === 'node_modules' || ent.name.startsWith('.')) continue;
+      const full = join(dir, ent.name);
+      if (ent.isDirectory()) { await walk(full); continue; }
+      if (!ent.isFile()) continue;
+      const rel = relative(cwd, full).split(sep).join('/');
+      if (include.some((g) => matchesGlob(rel, g)) && !exclude.some((g) => matchesGlob(rel, g))) {
+        found.push(rel);
+      }
+    }
+  };
+  await walk(cwd);
+  return found;
+}
+
+/**
+ * Remove `//` and `/* *\/` comments while leaving string literals intact. A
+ * regex strip is not enough: a glob such as `test/**\/browser` contains the
+ * very `/*` that opens a block comment.
+ *
+ * @param {string} src
+ * @returns {string}
+ */
+function stripComments(src) {
+  let out = '';
+  let quote = '';
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (quote) {
+      out += c;
+      if (c === '\\') { out += src[++i] ?? ''; continue; }
+      if (c === quote) quote = '';
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; continue; }
+    if (c === '/' && src[i + 1] === '/') {
+      while (i < src.length && src[i] !== '\n') i++;
+      out += '\n';
+      continue;
+    }
+    if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      i = end === -1 ? src.length : end + 1;
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
+/** @param {string} p */
+function normalize(p) {
+  return p.replace(/^\.\//, '');
+}

package/lib/create.js

@@ -18,24 +18,10 @@ 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 { postgresCompose, postgresCi } from './db-rewrite.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`,
- * which npm / pnpm / yarn / bun all set when running scripts or `npx`.
- * Falls back to `npm` when nothing is detected (matches what most users
- * actually have installed).
- *
- * @returns {'npm'|'pnpm'|'yarn'|'bun'}
- */
-function detectPackageManager() {
-  const ua = process.env.npm_config_user_agent || '';
-  if (ua.startsWith('pnpm/')) return 'pnpm';
-  if (ua.startsWith('yarn/')) return 'yarn';
-  if (ua.startsWith('bun/')) return 'bun';
-  return 'npm';
-}
+import { detectPackageManager } from './package-manager.js';
 
 /**
  * Run `<pm> install` inside the scaffolded app. Returns true on success.
@@ -327,7 +313,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   // with the explicit flag winning over detection. A bun-flavored app SERVES on
   // Bun (its dev/start scripts force `--bun`), commits `bun.lock`, sets
   // `trustedDependencies`, and ships a bun Dockerfile / CI / agent docs.
-  const runtime = opts.runtime || (detectPackageManager() === 'bun' ? 'bun' : 'node');
+  // Runtime detection reads ONLY the invoking tool (no lockfile walk): a
+  // global `webjs create` run inside someone else's Bun workspace should not
+  // silently flip the new app to serving on Bun.
+  const runtime = opts.runtime || (detectPackageManager({ cwd: null, prefer: 'agent' }) === 'bun' ? 'bun' : 'node');
   const VALID_RUNTIMES = ['node', 'bun'];
   if (!VALID_RUNTIMES.includes(runtime)) {
     throw new Error(`Unknown --runtime '${runtime}'. Only ${VALID_RUNTIMES.join(' / ')} are supported.`);
@@ -475,7 +464,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // The Tailwind v4 CLI that css:build runs to compile public/input.css into
       // the static public/tailwind.css the layout links. UI templates only (the
       // api template has no CSS). Build tooling, never shipped to the runtime.
-      ...(isApi ? {} : { '@tailwindcss/cli': '^4.1.0' }),
+      // `tailwindcss` itself is declared too (#1493): public/input.css starts
+      // with `@import "tailwindcss"`, so the app imports that package directly.
+      // Leaving it transitive (via @tailwindcss/cli) breaks under bun's isolated
+      // linker and pnpm, which link only declared packages into the app's
+      // node_modules, so the compile fails with `Can't resolve 'tailwindcss'`.
+      ...(isApi ? {} : { '@tailwindcss/cli': '^4.1.0', tailwindcss: '^4.1.0' }),
       // tsserver plugin, wired into tsconfig below. Gives the language
       // INTELLIGENCE (go-to-def, completions, diagnostics, hover inside html``
       // templates) in any tsserver editor with NO editor plugin installed,
@@ -523,8 +517,18 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // `npm audit fix --force` proposes: its @web/test-runner-chrome@1 still
     // declares puppeteer-core ^24, so the same vulnerable chain resolves and
     // the audit stays red after a breaking major.
+    //
+    // basic-ftp (#1492) is the same kind of floor for the same runner: it is
+    // reached through puppeteer-core's proxy-agent chain and 6.2.2 is its fixed
+    // release (GHSA-c475-qrg2-pj4r), so an install that still resolves an older
+    // chain cannot land below it.
+    //
+    // Overrides are honoured ONLY at a workspace root. When this app is a
+    // member of an npm or bun workspace, move this block into the root
+    // package.json (`webjs doctor` warns with WORKSPACE_OVERRIDES until then).
     overrides: {
       'puppeteer-core': '^25.7.0',
+      'basic-ftp': '^6.2.2',
     },
     // Dev + start task orchestration (#550). `webjs dev` / `webjs start` read
     // `before` and run it in-process, so `npm run dev` / `start` (thin aliases
@@ -576,6 +580,23 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // 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' } },
+      // The dependency audit's allowlist (#1492), the ONE place an accepted
+      // advisory is listed, each with the reason it is safe. `webjs audit`
+      // (the CI step below) fails on every other advisory at `level` or above,
+      // and prints an entry as stale once the audit stops reporting it, so
+      // remove it then. Only accept an advisory with NO patched release that
+      // the app's users cannot reach; anything with a fix gets upgraded.
+      audit: {
+        level: 'high',
+        ignore: [
+          {
+            id: 'GHSA-vfj7-8cjw-p6xm',
+            reason: 'braces <=3.0.3 (no patched release) is reached only through dev tooling: the Tailwind '
+              + 'CLI file watcher and the test runner globber, on glob patterns this repo writes. Nothing '
+              + 'in the served app expands a pattern from request input.',
+          },
+        ],
+      },
       // Local CI (#1471), the Rails `bin/ci` posture. `npm run ci` runs this
       // list on a developer machine and the generated GitHub workflow runs the
       // SAME list through the same command, so the two cannot drift. Bare
@@ -593,10 +614,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
               { title: 'Conventions', run: 'webjs check' },
               { title: 'Health', run: 'webjs doctor' },
               { title: 'Types', run: 'webjs typecheck' },
-              {
-                title: 'Security: dependency audit',
-                run: isBun ? 'bun audit --audit-level=high' : 'npm audit --audit-level=high',
-              },
+              // `webjs audit` (#1492) runs `npm audit` or `bun audit` (by the
+              // nearest lockfile) and fails at webjs.audit.level, minus the
+              // advisories webjs.audit.ignore accepts below.
+              { title: 'Security: dependency audit', run: 'webjs audit' },
               {
                 title: 'Tests',
                 steps: [
@@ -733,6 +754,14 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'compose.yaml': bunifyCompose,
     '.github/workflows/ci.yml': bunifyCi,
   };
+  // Database axis (#1490): the compose + CI templates are the SQLite shape, so
+  // a --db postgres app derives its variant (a Postgres service, DATABASE_URL
+  // pointed at it) by a pure transform, like the Bun rewrite above. Applied
+  // FIRST; the two touch disjoint lines, so they compose. SQLite copies as is.
+  const DB_REWRITE = dialect === 'postgres' ? {
+    'compose.yaml': (c) => postgresCompose(c, toDatabaseName(name)),
+    '.github/workflows/ci.yml': (c) => postgresCi(c, toDatabaseName(name)),
+  } : {};
   for (const f of templateFiles) {
     // `--skip-ci` drops only the workflow; the PR template still ships.
     if (skipCi && f === '.github/workflows/ci.yml') continue;
@@ -754,6 +783,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
         const playbook = await readFile(join(TEMPLATES, 'partials', playbookFile), 'utf8');
         content = content.replace('{{PLAYBOOK}}', () => playbook.trimEnd());
       }
+      if (DB_REWRITE[f]) content = DB_REWRITE[f](content);
       if (isBun) {
         if (PROSE_REWRITE.has(f)) content = bunifyProse(content);
         else if (FILE_REWRITE[f]) content = FILE_REWRITE[f](content);
@@ -1663,8 +1693,11 @@ ThemeToggle.register('theme-toggle');
   // that exercise the scaffold without paying the install cost.
   // In bun mode, install with bun regardless of the invoking PM, so the app
   // commits `bun.lock` (text JSONC, git-diffable) instead of `package-lock.json`
-  // (#541). Otherwise honour the invoking PM (npm / pnpm / yarn / bun).
-  const pm = isBun ? 'bun' : detectPackageManager();
+  // (#541). Otherwise honour the invoking PM (npm / pnpm / yarn / bun), and when
+  // nothing invoked us through a package manager (a global `webjs` bin), the
+  // lockfile of the enclosing project or workspace (#1494), so an app created
+  // inside a bun workspace does not get a stray package-lock.json.
+  const pm = isBun ? 'bun' : detectPackageManager({ cwd: dirname(appDir), prefer: 'agent' });
   let installed = false;
   let generatedMigration = false;
   if (shouldInstall) {

package/lib/db-rewrite.js

@@ -0,0 +1,137 @@
+/**
+ * Database-dialect rewrites for the deploy files (#1490).
+ *
+ * The canonical `compose.yaml` and `.github/workflows/ci.yml` templates are the
+ * SQLite shape (a `file:` DATABASE_URL, a named volume for the db file). A
+ * `--db postgres` app needs a real Postgres in both places, so these pure
+ * transforms DERIVE the Postgres variant from the canonical template, the same
+ * way `runtime-rewrite.js` derives the Bun variant. There is no parallel
+ * Postgres template to drift, and SQLite output stays byte-identical because
+ * nothing here runs for it.
+ *
+ * Order: create.js applies these BEFORE the Bun rewrites. They only touch the
+ * DATABASE_URL lines, the volume, and add a database service, none of which
+ * the Bun rewrites match (those swap `node -e` healthchecks, `npm` commands and
+ * the setup-node block), so the two axes compose in either order. Every anchor
+ * is asserted, so a template edit that moves one fails loudly in the scaffold
+ * tests instead of shipping a half-rewritten file.
+ *
+ * The credentials are local-only (a throwaway compose volume, an ephemeral CI
+ * service container), never a production value; production points
+ * DATABASE_URL at its own managed Postgres.
+ *
+ * @module db-rewrite
+ */
+
+/** Local Postgres user + password for compose and CI (never production). */
+export const LOCAL_PG_USER = 'webjs';
+export const LOCAL_PG_PASSWORD = 'webjs';
+/** The Postgres image both files run. */
+export const PG_IMAGE = 'postgres:17-alpine';
+
+/**
+ * @param {string} s
+ * @param {string} from
+ * @param {string} to
+ * @param {string} file
+ */
+function replaceOnce(s, from, to, file) {
+  if (!s.includes(from)) {
+    throw new Error(`db-rewrite: ${file} template no longer contains the anchor ${JSON.stringify(from.slice(0, 60))}`);
+  }
+  return s.replace(from, () => to);
+}
+
+/**
+ * Rewrite compose.yaml for a Postgres app: a sibling `db` service with a
+ * `pg_isready` healthcheck and its own named volume, the app's DATABASE_URL
+ * pointed at it, and `depends_on` with `service_healthy` so the app's boot-time
+ * `webjs db migrate` never races the database's startup.
+ *
+ * @param {string} s
+ * @param {string} dbName fold-stable database name (toDatabaseName(appName))
+ * @returns {string}
+ */
+export function postgresCompose(s, dbName) {
+  const url = `postgres://${LOCAL_PG_USER}:${LOCAL_PG_PASSWORD}@db:5432/${dbName}`;
+  let out = s;
+  out = replaceOnce(out, 'using the same Dockerfile, one service.',
+    'using the same Dockerfile, plus a Postgres service.', 'compose.yaml');
+  out = replaceOnce(out,
+    "# In production your host provides DATABASE_URL + AUTH_SECRET. Locally this\n" +
+    "# uses the scaffold's SQLite file on a named volume so data survives\n" +
+    '# `compose down`.',
+    '# In production your host provides DATABASE_URL + AUTH_SECRET. Locally this\n' +
+    '# runs Postgres in the `db` service on a named volume so data survives\n' +
+    '# `compose down`.',
+    'compose.yaml');
+  out = replaceOnce(out,
+    '      # SQLite on a volume for local dev. For production, scaffold with\n' +
+    '      # --db postgres (or swap db/columns.server.ts + db/connection.server.ts\n' +
+    '      # for the pg variant) and point DATABASE_URL at your managed Postgres.\n' +
+    '      DATABASE_URL: file:/data/dev.db\n',
+    '      # The `db` service below. In production, point DATABASE_URL at your\n' +
+    '      # managed Postgres instead.\n' +
+    `      DATABASE_URL: ${url}\n`,
+    'compose.yaml');
+  // The app no longer owns a db file, so it needs no volume; it waits for a
+  // healthy database instead, because `webjs start` migrates before serving.
+  out = replaceOnce(out,
+    '    volumes:\n      - app-data:/data\n',
+    '    depends_on:\n      db:\n        condition: service_healthy\n',
+    'compose.yaml');
+  out = replaceOnce(out,
+    '\nvolumes:\n  app-data:\n',
+    '\n' +
+    '  db:\n' +
+    `    image: ${PG_IMAGE}\n` +
+    '    environment:\n' +
+    `      POSTGRES_USER: ${LOCAL_PG_USER}\n` +
+    `      POSTGRES_PASSWORD: ${LOCAL_PG_PASSWORD}\n` +
+    `      POSTGRES_DB: ${dbName}\n` +
+    '    volumes:\n' +
+    '      - db-data:/var/lib/postgresql/data\n' +
+    '    healthcheck:\n' +
+    `      test: ["CMD-SHELL", "pg_isready -U ${LOCAL_PG_USER} -d ${dbName}"]\n` +
+    '      interval: 5s\n' +
+    '      timeout: 3s\n' +
+    '      retries: 10\n' +
+    '\n' +
+    'volumes:\n' +
+    '  db-data:\n',
+    'compose.yaml');
+  return out;
+}
+
+/**
+ * Rewrite the GitHub Actions CI workflow for a Postgres app: a `postgres`
+ * service container with a health check (the job waits until it is healthy
+ * before the first step) and DATABASE_URL pointed at it on localhost.
+ *
+ * @param {string} s
+ * @param {string} dbName
+ * @returns {string}
+ */
+export function postgresCi(s, dbName) {
+  return replaceOnce(s,
+    '    env:\n      DATABASE_URL: file:./ci.db\n',
+    '    env:\n' +
+    `      DATABASE_URL: postgres://${LOCAL_PG_USER}:${LOCAL_PG_PASSWORD}@localhost:5432/${dbName}\n` +
+    '    # The app is scaffolded with --db postgres, so CI runs against a real\n' +
+    '    # Postgres. The job waits for the health check before the first step.\n' +
+    '    services:\n' +
+    '      postgres:\n' +
+    `        image: ${PG_IMAGE}\n` +
+    '        env:\n' +
+    `          POSTGRES_USER: ${LOCAL_PG_USER}\n` +
+    `          POSTGRES_PASSWORD: ${LOCAL_PG_PASSWORD}\n` +
+    `          POSTGRES_DB: ${dbName}\n` +
+    '        ports:\n' +
+    '          - 5432:5432\n' +
+    '        options: >-\n' +
+    `          --health-cmd "pg_isready -U ${LOCAL_PG_USER} -d ${dbName}"\n` +
+    '          --health-interval 5s\n' +
+    '          --health-timeout 5s\n' +
+    '          --health-retries 10\n',
+    '.github/workflows/ci.yml');
+}

package/lib/doctor/codes.js

@@ -49,6 +49,7 @@ export const DOCTOR_CODES = {
   'Component elision (what the browser drops)': 'ELISION_COMPONENTS',
   'Static build outputs (dev.regenerate freshness)': 'STATIC_ASSET_FRESHNESS',
   'Asset urls (unmarked stylesheet links)': 'UNMARKED_ASSET_LINKS',
+  'workspace-overrides': 'WORKSPACE_OVERRIDES',
 };
 
 /**

package/lib/doctor/probes/workspace-overrides.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, sep, matchesGlob } from 'node:path';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/** @param {string} p */
+function readJson(p) {
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+/**
+ * The workspace globs a root package.json declares (npm / bun / yarn), in
+ * either the array form or yarn's `{ packages: [...] }` form, else null.
+ * @param {any} pkg
+ * @returns {string[] | null}
+ */
+function workspaceGlobs(pkg) {
+  const ws = pkg?.workspaces;
+  if (Array.isArray(ws)) return ws;
+  if (ws && Array.isArray(ws.packages)) return ws.packages;
+  return null;
+}
+
+/**
+ * Find the workspace root that `appDir` is a MEMBER of: the nearest ancestor
+ * whose package.json `workspaces` globs match the app's relative path. A plain
+ * parent with a package.json but no matching glob is not a workspace for this
+ * app, so it does not count.
+ * @param {string} appDir
+ * @returns {string | null}
+ */
+export function findWorkspaceRoot(appDir) {
+  let dir = dirname(appDir);
+  for (;;) {
+    const pkg = existsSync(join(dir, 'package.json')) ? readJson(join(dir, 'package.json')) : null;
+    const globs = workspaceGlobs(pkg);
+    if (globs) {
+      const rel = relative(dir, appDir).split(sep).join('/');
+      const included = globs.filter((g) => !g.startsWith('!')).some((g) => matchesGlob(rel, g.replace(/^\.\//, '').replace(/\/$/, '')));
+      const excluded = globs.filter((g) => g.startsWith('!')).some((g) => matchesGlob(rel, g.slice(1).replace(/^\.\//, '')));
+      if (included && !excluded) return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * CHECK (#1492), dependency overrides declared in a workspace MEMBER. npm and
+ * bun honour `overrides` (and yarn / bun `resolutions`) only in the workspace
+ * ROOT package.json, so the same block in a member is silently ignored and the
+ * security floor it encodes (the scaffold's puppeteer-core and basic-ftp
+ * floors) never applies. WARN naming the root to move it to; PASS otherwise.
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+export function checkWorkspaceOverrides(appDir) {
+  const name = 'workspace-overrides';
+  const pkg = readJson(join(appDir, 'package.json'));
+  const keys = ['overrides', 'resolutions'].filter((k) => pkg && pkg[k] && typeof pkg[k] === 'object' && Object.keys(pkg[k]).length);
+  if (keys.length === 0) {
+    return { name, status: 'pass', message: 'No dependency overrides in this package.json.' };
+  }
+  const root = findWorkspaceRoot(appDir);
+  if (!root) {
+    return { name, status: 'pass', message: `\`${keys.join('` / `')}\` apply: this app is not a workspace member.` };
+  }
+  const rel = relative(appDir, join(root, 'package.json')) || 'package.json';
+  return {
+    name,
+    status: 'warn',
+    message: `package.json declares \`${keys.join('` / `')}\`, but this app is a member of the workspace at ${rel}, `
+      + 'and package managers honour overrides only at the workspace root, so these are ignored.',
+    fix: `Move the \`${keys.join('` / `')}\` block into ${rel} (merge it with any the root already has).`,
+  };
+}

package/lib/doctor/runner.js

@@ -11,6 +11,7 @@ import { checkElisionCarriers, checkElisionComponents } from './probes/elision.j
 import { checkStaticAssetFreshness } from './probes/static-asset-freshness.js';
 import { checkUnmarkedAssetLinks } from './probes/unmarked-asset-links.js';
 import { checkFrameworkResolves, checkFrameworkLinks } from './probes/framework-resolves.js';
+import { checkWorkspaceOverrides } from './probes/workspace-overrides.js';
 
 /**
  * @typedef {import('./codes.js').DoctorResult} DoctorResult
@@ -64,6 +65,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkElisionComponents(elision),
     checkStaticAssetFreshness(appDir),
     checkUnmarkedAssetLinks(appDir),
+    Promise.resolve(checkWorkspaceOverrides(appDir)),
   ]);
   // Attach the stable machine code to every result (#975). Centralized here so
   // each check function stays free of the code-contract concern.

package/lib/package-manager.js

@@ -0,0 +1,93 @@
+/**
+ * Package-manager detection for `webjs create` (#1494).
+ *
+ * KEEP IN SYNC with `packages/ui/src/utils/package-manager.js`, the copy
+ * `webjs ui add` uses. The two published
+ * packages carry the same small module rather than one importing the other,
+ * so a `@webjsdev/cli` release can never fail at import time against an older
+ * `@webjsdev/ui` that lacks the export. `packages/cli/test/package-manager.test.mjs`
+ * asserts both copies agree on every fixture.
+ *
+ * Detection order (with `prefer: 'lockfile'`, the default):
+ *   1. A lockfile in `cwd` or any ancestor. The walk stops at the first
+ *      workspace root (a package.json declaring `workspaces`, or a
+ *      `pnpm-workspace.yaml`) or at the filesystem root, so an app nested in a
+ *      workspace finds the root's lockfile. Within one directory the order is
+ *      pnpm, yarn, bun (`bun.lock`, the text lockfile Bun writes since 1.2,
+ *      and the older binary `bun.lockb`), then npm.
+ *   2. `npm_config_user_agent`, which npm, pnpm, yarn and bun set when they
+ *      run a script or a `dlx` / `bunx` / `npx` binary.
+ *   3. `npm`.
+ * With `prefer: 'agent'` steps 1 and 2 swap, which suits `webjs create`: the
+ * tool that invoked it is the strongest signal for a directory that has no
+ * lockfile yet.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/** @typedef {'npm'|'pnpm'|'yarn'|'bun'} PackageManager */
+
+/** Lockfile name to manager, in per-directory precedence order. */
+const LOCKFILES = /** @type {const} */ ([
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['yarn.lock', 'yarn'],
+  ['bun.lock', 'bun'],
+  ['bun.lockb', 'bun'],
+  ['package-lock.json', 'npm'],
+  ['npm-shrinkwrap.json', 'npm'],
+]);
+
+/**
+ * Whether `dir` is a workspace root, where the lockfile walk stops.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isWorkspaceRoot(dir) {
+  if (existsSync(join(dir, 'pnpm-workspace.yaml'))) return true;
+  const pkgPath = join(dir, 'package.json');
+  if (!existsSync(pkgPath)) return false;
+  try {
+    return Boolean(JSON.parse(readFileSync(pkgPath, 'utf8')).workspaces);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk up from `cwd` looking for a lockfile.
+ * @param {string} cwd
+ * @returns {PackageManager | null}
+ */
+export function managerFromLockfile(cwd) {
+  let dir = resolve(cwd);
+  for (;;) {
+    for (const [file, manager] of LOCKFILES) {
+      if (existsSync(join(dir, file))) return manager;
+    }
+    if (isWorkspaceRoot(dir)) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Read the manager from an `npm_config_user_agent` value such as
+ * `bun/1.3.14 npm/? node/v24.0.0 linux x64`.
+ * @param {string | undefined} ua
+ * @returns {PackageManager | null}
+ */
+export function managerFromUserAgent(ua) {
+  const name = String(ua || '').split('/')[0];
+  return name === 'pnpm' || name === 'yarn' || name === 'bun' || name === 'npm' ? name : null;
+}
+
+/**
+ * @param {{ cwd?: string | null, env?: Record<string, string | undefined>, prefer?: 'lockfile' | 'agent' }} [opts]
+ * @returns {PackageManager}
+ */
+export function detectPackageManager({ cwd = null, env = process.env, prefer = 'lockfile' } = {}) {
+  const fromLock = () => (cwd ? managerFromLockfile(cwd) : null);
+  const fromAgent = () => managerFromUserAgent(env.npm_config_user_agent);
+  return (prefer === 'agent' ? fromAgent() ?? fromLock() : fromLock() ?? fromAgent()) ?? 'npm';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.58",
+  "version": "0.10.59",
   "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": {
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "@webjsdev/mcp": "^0.1.0",
-    "@webjsdev/server": "^0.8.67",
+    "@webjsdev/server": "^0.8.68",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

package/templates/.agents/skills/webjs/references/auth-and-sessions.md

@@ -113,6 +113,17 @@ export const POST = handlers.POST;
 <form method="POST" action="/api/auth/signout"><button>Log out</button></form>
 ```
 
+**OAuth sign-in returns the user where they started, with the same one form.** POST to `/api/auth/signin/github` (or `google`) with a hidden `redirectTo`, or link to `GET /api/auth/signin/github?redirectTo=/dashboard/x`; `signIn('github', undefined, { redirectTo })` does the same from an action. The target rides through the provider round trip in a short-lived signed cookie and the callback lands on it, so no wrapper around the auth route is needed:
+
+```html
+<form method="POST" action="/api/auth/signin/github">
+  <input type="hidden" name="redirectTo" value="/dashboard/x">
+  <button>Sign in with GitHub</button>
+</form>
+```
+
+A `redirectTo` that arrives from a request (a form field or a query param, for OAuth or credentials) must be a same-origin local path: one leading `/`, not followed by `/` or `\`. An absolute URL, a protocol-relative `//host`, or a backslash variant is dropped (not repaired) and the sign-in lands on `/`, so the field is never an open redirect. A denied sign-in still goes to `pages.error`.
+
 For a programmatic sign-in (the auto-login-after-signup pattern), `signIn('credentials', creds, { redirectTo })` returns a `302` `Response` that a form-bound action can return directly (the framework honors a returned `Response` verbatim).
 
 Sessions are JWT by default (stateless, scales horizontally). OAuth

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

@@ -22,6 +22,24 @@ Read this when wiring caching or rate limiting, storing uploads, hardening heade
 | `REDIS_URL` | When set, sessions, rate limit, and cache use Redis instead of memory |
 | `SESSION_SECRET` / `AUTH_SECRET` | Session and auth signing (see `auth-and-sessions.md`) |
 | `PORT` | Listen port. Precedence `--port` flag, then `PORT` (real env or `.env`), then `8080` |
+| `WEBJS_SOURCE_LOCATIONS` | `webjs dev` only. `1` stamps `data-webjs-src="<app-relative-file>:<line>"` on the elements of the app's `html` templates (see below). Ignored by `webjs start` |
+| `WEBJS_EMBED_ORIGINS` | `webjs dev` only. Comma-separated parent origins (`https://builder.dev,http://localhost:8080`) allowed to frame the dev server and receive the embed bridge's messages (see below). Ignored by `webjs start` |
+
+**Source locations for tooling (`WEBJS_SOURCE_LOCATIONS=1`, dev only).** A tool that hosts the app (an inspector, click-to-edit in an embedding builder) can map a clicked element back to the line that wrote it. With the variable set, `webjs dev` adds `data-webjs-src="components/todo-list.ts:12"` to every element opening tag written in an `html` template inside the app, both in the SSR markup and in client renders (one source transform applied to the served module and to the module the server imports, so the two agree and hydration is unaffected). Read it with `el.closest('[data-webjs-src]')`. Not annotated: `*.server.*` modules, `node_modules`, `css` / `svg` tagged templates, `html` / `head` / `body` / head-only and raw-text elements, and the descendants of `svg` / `math`. Lines are exact; nothing reaches production. The importmap `<script>` in `<head>` carries an unrelated `data-webjs-src` (the app-source deploy id), so match the `file:line` value shape when querying the whole document.
+
+**Embed bridge for iframe previews (`WEBJS_EMBED_ORIGINS`, dev only).** A tool that previews the app inside an iframe (an app builder, a docs playground) sets `WEBJS_EMBED_ORIGINS` to its own origin(s). `webjs dev` then (1) drops `X-Frame-Options` and adds those origins to a CSP `frame-ancestors`, so the frame loads without the app stripping headers in `webjs.headers`, and (2) inlines a small nonce-signed script into every document that, when framed by a listed origin, posts to `window.parent` (with that exact target origin, never `*`):
+
+```js
+{ source: 'webjs-embed', type: 'ready', path, title }            // document parsed
+{ source: 'webjs-embed', type: 'navigate', path, title }         // every client-router navigation + popstate
+{ source: 'webjs-embed', type: 'console', level: 'error' | 'warn', message, dropped? } // max 20/s
+{ source: 'webjs-embed', type: 'error', message, stack, file, line, column }          // window error + unhandledrejection
+{ source: 'webjs-embed', type: 'network', method, url, status, error? }               // fetch/XHR status >= 500, or status 0 on failure
+{ source: 'webjs-embed', type: 'server-error', kind, message, file, line, path }      // the dev error overlay went up
+{ source: 'webjs-embed', type: 'select', src, tag, text, rect: { x, y, width, height } } // a click in inspect mode
+```
+
+and accepts, only from `window.parent` on a listed origin: `{ source: 'webjs-embed-host', type: 'navigate', path }` (a local path; a soft navigation when the client router is on), `{ source: 'webjs-embed-host', type: 'reload' }`, and `{ source: 'webjs-embed-host', type: 'inspect', enabled: true | false }` (hover highlight plus click capture that posts `select`; `src` is the nearest `data-webjs-src`, so pair it with `WEBJS_SOURCE_LOCATIONS=1` for click-to-edit). Paths are app paths (`/api/x`, `/components/x.ts`). Unset adds zero bytes; `webjs start` never injects it nor relaxes a header.
 
 Defaults are single-instance memory stores. To scale horizontally, switch the store once at startup: `setStore(redisStore({ url: process.env.REDIS_URL }))`.
 
@@ -275,6 +293,25 @@ Three levels, the same scale ESLint uses: `error` fails the exit, `warn` reports
 
 Two guarantees worth knowing. A result that could not check (a network or toolchain outage) is capped at `warn` and can never be escalated, so a jspm or npm outage cannot red your CI. And a malformed gate exits 1 naming the offender rather than being ignored, so a typo cannot silently un-gate the build. That covers an unknown code, a bad severity, a wrong shape (a non-object `doctor` or `gate`), and a misspelled sibling of `gate` such as `gates`, since every one of those would otherwise leave the build un-gated while the `package.json` looks gated. Under `--json` the offenders come back as a `configErrors` array alongside an empty `results`, each entry a `{ kind }` of `malformed` / `unknown-key` / `unknown-code` / `bad-severity`. Wire it up with one workflow step, `npm run doctor`, and change what is fatal in `package.json` rather than in the workflow.
 
+### Dependency audit allowlist
+
+`webjs audit` runs `npm audit` or `bun audit` (by the nearest lockfile, so a workspace member uses the root's) and fails on any advisory at or above `webjs.audit.level` (default `high`) that `webjs.audit.ignore` does not list. The scaffold's `Security: dependency audit` CI step runs it.
+
+```jsonc
+{ "webjs": {
+  "audit": {
+    "level": "high",
+    "ignore": [
+      { "id": "GHSA-vfj7-8cjw-p6xm", "reason": "braces has no patched release; reached only through dev tooling" }
+    ]
+  }
+} }
+```
+
+The allowlist is the ONE place an accepted advisory lives, each with its reason. Accept only an advisory with no patched release that the app's users cannot reach; upgrade anything that has a fix. Never "fix" a red audit with `npm audit fix --force`, which proposes breaking majors that often keep the same vulnerable chain. A malformed block (unknown key, bad level, an entry without an id or a reason) exits 1, and an id the audit stops reporting prints as stale, so remove it then.
+
+Overrides apply only at a WORKSPACE ROOT. The scaffold's `overrides` block (the `puppeteer-core` and `basic-ftp` security floors) is ignored once the app is a member of an npm or bun workspace, so move it into the root `package.json`; `webjs doctor` warns with `WORKSPACE_OVERRIDES` until you do.
+
 ## Observability
 
 Wired at the single response funnel, covering pages, routes, actions, and assets uniformly.

package/templates/.agents/skills/webjs/references/testing.md

@@ -63,6 +63,8 @@ WEBJS_E2E=1 npm run test  # adds the e2e layer
 
 `npm run test` dispatches on the runtime (`node --test` on Node, `bun test` on Bun). The scaffold's `web-test-runner.config.js` globs `test/**/browser/**/*.test.js` and is already wired, so you do not set it up.
 
+An app with no browser tests yet (for example right after `npm run gallery:clear`) is not a failure: `webjs test --browser` sees that no file matches the config's `files` globs, prints `no browser tests yet`, and exits 0, the same way the server layer passes with zero files. So `npm run ci` stays green until you write the first browser test, and from then on the browser layer runs as normal.
+
 A scaffolded app has one root `test/` directory shaped the same way (feature first, kind second):
 
 ```

package/templates/.dockerignore

@@ -18,7 +18,7 @@ build
 out
 .cache
 
-# Local env files. The container gets its env from compose / uncloud, not a
+# Local env files. The container gets its env from compose or the host, not a
 # committed file. Keep the example for reference.
 .env
 !.env.example

package/templates/Dockerfile

@@ -1,7 +1,7 @@
 # Production image for the {{APP_NAME}} webjs app.
 #
-# Works with a plain `docker build` / `docker compose up`, and is the same
-# artifact the webdeploy hosting tool (ubicloud + uncloud) builds and ships.
+# Works with a plain `docker build` / `docker compose up`, and with any host
+# that builds from a Dockerfile.
 #
 # webjs serves .ts directly by stripping types at the runtime layer, so there is
 # NO JavaScript build step (webjs is buildless end to end; there is no bundler or
@@ -41,7 +41,7 @@ COPY . .
 # step runs `webjs db migrate`). See the CMD note below.
 
 ENV NODE_ENV=production
-# webjs start reads $PORT (default 8080). compose / uncloud / Railway set it.
+# webjs start reads $PORT (default 8080). compose and most hosts set it.
 ENV PORT=8080
 EXPOSE 8080
 

package/templates/compose.yaml

@@ -2,9 +2,9 @@
 #
 #   docker compose up --build   →   http://localhost:8080
 #
-# In production the webdeploy tool (ubicloud + uncloud) provisions a managed
-# Postgres and injects DATABASE_URL + AUTH_SECRET for you. Locally this uses
-# the scaffold's SQLite file on a named volume so data survives `compose down`.
+# In production your host provides DATABASE_URL + AUTH_SECRET. Locally this
+# uses the scaffold's SQLite file on a named volume so data survives
+# `compose down`.
 services:
   app:
     build: .