@webjsdev/cli 0.10.60 → 0.10.62

package/bin/webjs.js

@@ -6,10 +6,10 @@ import { fileURLToPath } from 'node:url';
 import { resolveBin } from '../lib/resolve-bin.js';
 import { dbGenerateTtyHint } from '../lib/db-hints.js';
 import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
-import { loadAppEnv, resolvePort } from '../lib/port.js';
+import { loadAppEnv, resolvePort, failFastOnPortInUse } 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';
+import { findCheckTarget, notAnAppMessage, notAnAppJson, findServeTarget, notAnAppServeMessage } from '../lib/check-target.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
@@ -147,7 +147,7 @@ const USAGE = `webjs commands:
 const HELP = {
   dev: {
     usage: 'webjs dev [--port <n>] [--no-hot]',
-    summary: 'Start the dev server with live reload (source is the runtime, no build step).',
+    summary: 'Start the dev server with live reload (source is the runtime, no build step). Run it in the app directory (the one holding app/); anywhere else it exits 1 naming the app to start.',
     options: [
       { flag: '--port <n>', description: 'Port to listen on (else PORT, else 8080).' },
       { flag: '--no-hot', description: 'Run in-process, without the hot-reload supervisor.' },
@@ -156,7 +156,7 @@ const HELP = {
   },
   start: {
     usage: 'webjs start [--port <n>]',
-    summary: 'Start the production server (serves source directly, plain HTTP/1.1).',
+    summary: 'Start the production server (serves source directly, plain HTTP/1.1). Exits 1 outside an app directory.',
     options: [
       { flag: '--port <n>', description: 'Port to listen on (else PORT, else 8080).' },
     ],
@@ -442,6 +442,19 @@ async function startDevParallelTasks(commands, cwd) {
   });
 }
 
+/**
+ * Exit 1 with a clear message when `webjs dev` / `webjs start` runs where there
+ * is no `app/` directory (#1526), naming the app to start instead.
+ *
+ * @param {'dev' | 'start'} command
+ */
+async function refuseOutsideApp(command) {
+  const target = await findServeTarget(process.cwd());
+  if (target.isApp) return;
+  console.error(notAnAppServeMessage(command, process.cwd(), target));
+  process.exit(1);
+}
+
 async function main() {
   // `--version` / `-v` (top level): print the installed CLI version and exit.
   if (cmd === '--version' || cmd === '-v') {
@@ -480,6 +493,15 @@ async function main() {
   // `ERR_MODULE_NOT_FOUND: Cannot find package '@webjsdev/core'`. Probe up front
   // and surface the cause + remedy instead. No-op (a cheap resolve) when the
   // framework resolves, so the happy-path boot is untouched.
+  // #1526: refuse to serve a directory that is not an app, FIRST: before the
+  // resolve probe (whose "run npm install" advice is wrong at a workspace
+  // root), any before-step (a `webjs db migrate` in the wrong directory), or a
+  // spawn. Started from a workspace root, the server used to boot, say it was
+  // ready, and answer 404 for every route. The dev child skips it: its parent
+  // checked the same cwd it spawned the child in.
+  if ((cmd === 'dev' || cmd === 'start') && process.env.__WEBJS_DEV_CHILD !== '1') {
+    await refuseOutsideApp(cmd);
+  }
   if (cmd === 'dev' || cmd === 'start') {
     const { checkFrameworkResolves } = await import('../lib/doctor.js');
     const probe = checkFrameworkResolves(process.cwd());
@@ -508,7 +530,7 @@ async function main() {
           process.channel?.unref?.();
           process.on('disconnect', () => process.exit(0));
         }
-        await startServer({ appDir: process.cwd(), port, dev: true });
+        await failFastOnPortInUse(startServer({ appDir: process.cwd(), port, dev: true }));
         break;
       }
 
@@ -546,7 +568,9 @@ async function main() {
         const { startServer } = await import('@webjsdev/server');
         loadAppEnv(process.cwd());
         const port = resolvePort(flag(rest, '--port'));
-        await startServer({ appDir: process.cwd(), port, dev: true });
+        await failFastOnPortInUse(startServer({ appDir: process.cwd(), port, dev: true }), {
+          exit: (code) => { killTasks(); process.exit(code); },
+        });
         killTasks();
         break;
       }
@@ -571,7 +595,7 @@ async function main() {
       const { readAppTasks } = await import('../lib/app-tasks.js');
       await runPhaseBeforeSteps('start', readAppTasks(process.cwd()).start.before, process.cwd());
       const port = resolvePort(flag(rest, '--port'));
-      await startServer({ appDir: process.cwd(), port, dev: false });
+      await failFastOnPortInUse(startServer({ appDir: process.cwd(), port, dev: false }));
       break;
     }
     case 'db': {

package/lib/check-target.js

@@ -24,7 +24,7 @@
 
 import { statSync } from 'node:fs';
 import { readFile, glob } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, dirname, relative } from 'node:path';
 
 /**
  * @typedef {{ isApp: boolean, workspaceApps: string[] }} CheckTarget
@@ -96,6 +96,71 @@ export async function workspaceApps(cwd) {
   return [...apps].sort();
 }
 
+/**
+ * The nearest STRICT ancestor of `cwd` that holds an `app/` directory, or
+ * `null`. Started from inside an app (its `app/` or `components/` dir), this is
+ * the app the user meant.
+ *
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function findAncestorApp(cwd) {
+  let dir = dirname(cwd);
+  for (;;) {
+    if (hasAppDir(dir)) return dir;
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+/**
+ * Where a server command (`webjs dev` / `webjs start`) that was started outside
+ * an app should have been started (#1526): the workspace's member apps when
+ * `cwd` is a workspace root, else the nearest ancestor app, else nothing.
+ * `isApp` is the same `app/` predicate `webjs check` refuses on (#1301).
+ *
+ * @param {string} cwd
+ * @returns {Promise<{ isApp: boolean, workspaceApps: string[], ancestorApp: string | null }>}
+ */
+export async function findServeTarget(cwd) {
+  const target = await findCheckTarget(cwd);
+  if (target.isApp) return { ...target, ancestorApp: null };
+  return { ...target, ancestorApp: target.workspaceApps.length ? null : findAncestorApp(cwd) };
+}
+
+/**
+ * The refusal `webjs dev` / `webjs start` print when started where there is no
+ * app (#1526). Without it the server boots, says it is ready, and answers 404
+ * for every route, which is how a launch from a workspace root used to look.
+ *
+ * @param {'dev' | 'start'} command
+ * @param {string} cwd
+ * @param {{ workspaceApps: string[], ancestorApp: string | null }} target
+ * @returns {string}
+ */
+export function notAnAppServeMessage(command, cwd, { workspaceApps, ancestorApp }) {
+  const lines = [
+    `webjs ${command}: this directory is not a WebJs app, so there is nothing to serve.`,
+    '',
+    `  ${cwd}`,
+    '',
+    'There is no `app/` directory here. Started anyway, the server would answer',
+    '404 for every route.',
+    '',
+  ];
+  if (workspaceApps.length) {
+    lines.push('This is a workspace root. Start the server inside the app:', '');
+    for (const app of workspaceApps) lines.push(`  cd ${app} && webjs ${command}`);
+  } else if (ancestorApp) {
+    lines.push('This directory is inside an app. Start the server from the app root:', '');
+    lines.push(`  cd ${relative(cwd, ancestorApp) || '.'} && webjs ${command}`);
+  } else {
+    lines.push('Change into your app directory (the one holding `app/`) and re-run.');
+  }
+  return lines.join('\n');
+}
+
 /**
  * The human refusal, for stderr.
  *

package/lib/create.js

@@ -17,7 +17,7 @@ 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 { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi, bunifyEnvExample } 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';
@@ -745,6 +745,9 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'AGENTS.md', 'CLAUDE.md', 'CONVENTIONS.md',
     '.agents/rules/workflow.md',
     'test/hello/browser/hello.test.js', 'test/hello/e2e/hello.test.ts',
+    // Comments that name a command (#1527): `npm run ci` in the hook, the
+    // Tailwind build note in the ignore file.
+    '.hooks/pre-commit', 'gitignore',
   ]);
   // compose.yaml builds from the (pure oven/bun) Dockerfile and inherits its
   // `bun --bun run start` CMD; only its healthcheck needs switching off node
@@ -753,6 +756,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'Dockerfile': bunifyDockerfile,
     'compose.yaml': bunifyCompose,
     '.github/workflows/ci.yml': bunifyCi,
+    '.env.example': bunifyEnvExample,
   };
   // Database axis (#1490): the compose + CI templates are the SQLite shape, so
   // a --db postgres app derives its variant (a Postgres service, DATABASE_URL
@@ -1240,7 +1244,13 @@ export type ActionResult<T> =
     const clearScriptSrc = join(TEMPLATES, 'scripts', 'clear-gallery.mjs');
     if (existsSync(clearScriptSrc)) {
       await mkdir(join(appDir, 'scripts'), { recursive: true });
-      await cp(clearScriptSrc, join(appDir, 'scripts', 'clear-gallery.mjs'));
+      // A Bun app gets the Bun spelling of the ui-kit command the script
+      // prints and writes into the reset layout (#1527): `bunx`, never `npx`.
+      const clearScript = await readFile(clearScriptSrc, 'utf8');
+      await writeFile(
+        join(appDir, 'scripts', 'clear-gallery.mjs'),
+        isBun ? clearScript.replaceAll('npx webjsdev ', 'bunx webjsdev ') : clearScript,
+      );
     }
 
     // Fail loudly if the @webjsdev/ui registry sources aren't on disk.
@@ -1293,6 +1303,18 @@ ${uiThemeRaw}
   --text-h1:      clamp(2rem, 1.5rem + 1.6vw, 2.85rem);
   --text-h2:      clamp(1.35rem, 1.15rem + 0.7vw, 1.7rem);
   --text-lede:    clamp(1.05rem, 0.95rem + 0.3vw, 1.2rem);
+  /* Each size carries its line height (and, for the large steps, its
+     tracking). Tailwind v4's text-* utility sets
+     line-height: var(--tw-leading, var(--text-<name>--line-height)), so a
+     size with no companion leaves an invalid value and the heading falls
+     back to the body's 1.6, opening huge gaps between wrapped lines.
+     A leading-* / tracking-* class on the element still wins. */
+  --text-display--line-height: 1.04;
+  --text-display--letter-spacing: -0.025em;
+  --text-h1--line-height: 1.1;
+  --text-h1--letter-spacing: -0.02em;
+  --text-h2--line-height: 1.2;
+  --text-lede--line-height: 1.55;
   --duration-fast: 140ms;
   --duration-slow: 380ms;
 }
@@ -1746,10 +1768,12 @@ ThemeToggle.register('theme-toggle');
   // single-bin fallback resolves it to the `webjs` binary, so behaviour
   // matches `@webjsdev/cli` exactly while keeping the command short
   // and unambiguous.
+  // A Bun app runs one-off binaries with `bunx` (#1527).
+  const x = isBun ? 'bunx' : 'npx';
   const uiNote = isApi
     ? `# If you later add a UI to this API project:
-  #   npx webjsdev ui init && npx webjsdev ui add button card dialog`
-    : `npx webjsdev ui add <name>     # add more ui-* components later`;
+  #   ${x} webjsdev ui init && ${x} webjsdev ui add button card dialog`
+    : `${x} webjsdev ui add <name>     # add more ui-* components later`;
   console.log(`
 Next steps:
   ${runCommand}

package/lib/dev-reload.js

@@ -21,6 +21,8 @@
 import { spawn } from 'node:child_process';
 import { watch, statSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { watchRecursive } from './watch-recursive.js';
+import { PORT_IN_USE_EXIT_CODE } from './port.js';
 
 /**
  * Quiet window between a file event and the restart. `node --watch` used
@@ -127,10 +129,14 @@ export function watchRestartPaths(cwd, { dirs, files, ignore, onChange, onError,
   const watchDir = (name) => {
     if (closed || watchers.has(name) || !isDir(name)) return;
     try {
-      watchers.set(name, guard(watchFn(join(cwd, name), { recursive: true }, (_type, filename) => {
+      // `watchRecursive` (#1529): on Linux under Node a per-directory walker,
+      // since Node 24's recursive watcher goes deaf to a file once it is
+      // replaced (`sed -i`, an editor's atomic save), so a second edit to the
+      // same file never restarted the server.
+      watchers.set(name, guard(watchRecursive(join(cwd, name), (_type, filename) => {
         const rel = filename ? join(name, String(filename)) : name;
         if (!ignore(rel)) onChange(rel);
-      })));
+      }, { ignore: (rel) => ignore(join(name, rel)), watchFn })));
     } catch (err) {
       onError(/** @type {NodeJS.ErrnoException} */ (err));
     }
@@ -197,6 +203,8 @@ export function watchRestartPaths(cwd, { dirs, files, ignore, onChange, onError,
  *   backoffMs?: number[],
  *   stableMs?: number,
  *   killTimeoutMs?: number,
+ *   finalExitCodes?: number[],
+ *   onFinal?: (code: number) => void,
  * }} opts
  */
 export function createSupervisor({
@@ -209,6 +217,10 @@ export function createSupervisor({
   backoffMs = CRASH_BACKOFF_MS,
   stableMs = STABLE_MS,
   killTimeoutMs = KILL_TIMEOUT_MS,
+  // Exit codes a restart cannot fix (a taken port, #1527): the supervisor
+  // stops and reports instead of retrying on its backoff forever.
+  finalExitCodes = [PORT_IN_USE_EXIT_CODE],
+  onFinal = () => {},
 }) {
   /** @type {ChildLike | null} */
   let child = null;
@@ -260,6 +272,12 @@ export function createSupervisor({
       return;
     }
     // Exited on its own: a crash, a fatal boot error, or an outside kill.
+    if (!signal && code !== null && finalExitCodes.includes(code)) {
+      stopping = true;
+      debounceTimer = clear(debounceTimer);
+      onFinal(code);
+      return;
+    }
     if (now() - startedAt >= stableMs) crashes = 0;
     const delay = backoffMs[Math.min(crashes, backoffMs.length - 1)];
     crashes++;
@@ -326,9 +344,22 @@ export function superviseDevServer({ cwd, plan, env, onExit }) {
   // watcher keeps running either way.
   const ignoreWatchError = () => {};
 
+  let exiting = false;
+  /** @type {() => void} */
+  let closeWatch = () => {};
+  const shutdown = (code) => {
+    if (exiting) return;
+    exiting = true;
+    closeWatch();
+    sup.stop().then(() => onExit(code));
+  };
+
   const sup = createSupervisor({
     restartOnChange: plan.restartOnChange,
     log,
+    // The child already printed why (the port and its holder); stop with its
+    // code rather than restarting a server that can never bind.
+    onFinal: (code) => shutdown(code),
     spawnChild: () => {
       const c = spawn(process.execPath, plan.args, {
         // The IPC channel lets the child notice this process is gone and exit,
@@ -348,7 +379,7 @@ export function superviseDevServer({ cwd, plan, env, onExit }) {
   });
 
   const outputs = readRegenerateOutputs(cwd);
-  const closeWatch = watchRestartPaths(cwd, {
+  closeWatch = watchRestartPaths(cwd, {
     dirs: plan.watchDirs,
     files: plan.watchFiles,
     ignore: (rel) => shouldIgnoreRestartPath(rel) || outputs.has(rel.replace(/\\/g, '/')),
@@ -356,13 +387,6 @@ export function superviseDevServer({ cwd, plan, env, onExit }) {
     onError: ignoreWatchError,
   });
 
-  let exiting = false;
-  const shutdown = (code) => {
-    if (exiting) return;
-    exiting = true;
-    closeWatch();
-    sup.stop().then(() => onExit(code));
-  };
   process.on('SIGINT', () => shutdown(0));
   process.on('SIGTERM', () => shutdown(0));
   process.on('SIGHUP', () => shutdown(0));

package/lib/port.js

@@ -58,3 +58,35 @@ export function resolvePort(portFlag, env = process.env) {
   if (env.PORT) return Number(env.PORT);
   return 8080;
 }
+
+/**
+ * The exit code of a server that could not bind because its port is taken
+ * (#1527): Linux's EADDRINUSE errno. The dev supervisor treats it as final and
+ * stops instead of restarting a child that can never bind.
+ */
+export const PORT_IN_USE_EXIT_CODE = 98;
+
+/**
+ * Await a server start; on a taken port print the server's message (it names
+ * the process holding the port) and exit with `PORT_IN_USE_EXIT_CODE`. Any
+ * other error propagates unchanged.
+ *
+ * @template T
+ * @param {Promise<T>} started
+ * @param {{ error?: (line: string) => void, exit?: (code: number) => never }} [io]
+ * @returns {Promise<T>}
+ */
+export async function failFastOnPortInUse(started, io = {}) {
+  const error = io.error || ((line) => console.error(line));
+  const exit = io.exit || ((code) => process.exit(code));
+  try {
+    return await started;
+  } catch (e) {
+    const err = /** @type {any} */ (e);
+    if (err && err.code === 'EADDRINUSE') {
+      error(`[webjs] ${err.message || 'the port is already in use'}`);
+      return exit(PORT_IN_USE_EXIT_CODE);
+    }
+    throw e;
+  }
+}

package/lib/runtime-rewrite.js

@@ -161,7 +161,22 @@ export function bunifyDockerfile(s) {
  * @returns {string}
  */
 export function bunifyCompose(s) {
-  return s.replace('test: ["CMD", "node", "-e", "fetch(', 'test: ["CMD", "bun", "-e", "fetch(');
+  return s
+    .replace('test: ["CMD", "node", "-e", "fetch(', 'test: ["CMD", "bun", "-e", "fetch(')
+    // The secret-generation hint (#1527): a Bun app may have no node at all.
+    .replaceAll('# Generate: node -e ', '# Generate: bun -e ');
+}
+
+/**
+ * Rewrite `.env.example` for Bun (#1527): its secret-generation hint runs
+ * `node -e`, which a Bun-only machine (the oven/bun image, a Bun-only dev box)
+ * does not have. `bun -e` runs the same one-liner.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function bunifyEnvExample(s) {
+  return s.replaceAll('# Generate: node -e ', '# Generate: bun -e ');
 }
 
 /**

package/lib/watch-recursive.js

@@ -0,0 +1,147 @@
+/**
+ * A recursive directory watcher that keeps hearing a file after it is
+ * replaced (#1529).
+ *
+ * KEEP IN SYNC: `packages/cli/lib/watch-recursive.js` and
+ * `packages/server/src/dev/watch-recursive.js` are byte-identical copies (the
+ * CLI does not depend on server internals); `packages/cli/test/dev-supervisor/
+ * watch-recursive.test.js` fails when they drift.
+ *
+ * Node 24's `fs.watch(dir, { recursive: true })` on Linux is implemented in JS
+ * (`internal/fs/recursive_watch`) with one inotify watch per FILE plus a map of
+ * the files it knows. `sed -i`, an editor's save through a temp file, and every
+ * atomic write REPLACE the file (a new inode renamed over the old name). The
+ * per-file watch dies with the old inode, and the new file is never watched
+ * again because its name is already in the map, so every later edit to that
+ * file is silent: no dev restart, no live reload. Node 26 fixed it, but WebJs
+ * supports Node 24.
+ *
+ * A plain `fs.watch` on a DIRECTORY reports a replaced child by name on every
+ * Node version, so on Linux under Node this watches each directory
+ * non-recursively (one inotify watch per directory, fewer than one per file),
+ * adds a watcher when a subdirectory appears, and drops one when it goes away.
+ * Everywhere else the native recursive watcher is used unchanged: macOS and
+ * Windows have a kernel-level recursive watch, and Bun's `bun --hot` reloads
+ * edits itself.
+ *
+ * @module watch-recursive
+ */
+import { watch, readdirSync, realpathSync, statSync } from 'node:fs';
+import { EventEmitter } from 'node:events';
+import { join, sep } from 'node:path';
+
+/**
+ * Whether this runtime needs the per-directory walker rather than the native
+ * recursive watcher.
+ *
+ * @param {{ platform?: string, isBun?: boolean }} [env]
+ * @returns {boolean}
+ */
+export function needsDirWalker({ platform = process.platform, isBun = !!process.versions.bun } = {}) {
+  return platform === 'linux' && !isBun;
+}
+
+/**
+ * Watch `dir` and everything under it. The listener gets `(eventType,
+ * filename)` with `filename` relative to `dir`, like the native recursive
+ * watcher. The returned watcher emits `'error'` for any watch or scan failure
+ * (never throws for one) and has `close()`.
+ *
+ * @param {string} dir
+ * @param {(eventType: string, filename: string | null) => void} listener
+ * @param {{
+ *   ignore?: (relPath: string) => boolean,
+ *   watchFn?: typeof watch,
+ *   walker?: boolean,
+ * }} [opts]  `ignore` skips a subdirectory (never walked, never watched) and
+ *   its events; `watchFn` is injectable for tests; `walker` forces the mode.
+ * @returns {import('node:events').EventEmitter & { close: () => void }}
+ */
+export function watchRecursive(dir, listener, opts = {}) {
+  const { ignore = () => false, watchFn = watch, walker = needsDirWalker() } = opts;
+  if (!walker) return /** @type {any} */ (watchFn(dir, { recursive: true }, listener));
+
+  const out = /** @type {EventEmitter & { close: () => void }} */ (new EventEmitter());
+  /** @type {Map<string, import('node:fs').FSWatcher>} rel dir -> watcher */
+  const watchers = new Map();
+  /** @type {Map<string, string>} real path -> rel dir (a symlink loop guard) */
+  const reals = new Map();
+  let closed = false;
+  // Errors from the initial walk happen before the caller can attach an
+  // 'error' listener, so they are held and emitted on the next tick.
+  /** @type {unknown[] | null} */
+  let early = [];
+
+  const fail = (err) => {
+    if (closed) return;
+    if (early) early.push(err);
+    else if (out.listenerCount('error') > 0) out.emit('error', err);
+  };
+  const abs = (rel) => (rel ? join(dir, rel) : dir);
+  const isDir = (rel) => {
+    try { return statSync(abs(rel)).isDirectory(); } catch { return false; }
+  };
+  const within = (rel, root) => root === '' || rel === root || rel.startsWith(root + sep);
+
+  const drop = (root) => {
+    for (const [rel, w] of [...watchers]) {
+      if (!within(rel, root)) continue;
+      try { w.close(); } catch {}
+      watchers.delete(rel);
+    }
+    for (const [real, rel] of [...reals]) if (within(rel, root)) reals.delete(real);
+  };
+
+  const add = (rel) => {
+    if (closed || watchers.has(rel) || (rel && ignore(rel))) return;
+    let real;
+    try { real = realpathSync(abs(rel)); } catch (err) { if (!rel) fail(err); return; }
+    if (reals.has(real)) return;
+    /** @type {import('node:fs').FSWatcher} */
+    let w;
+    try {
+      w = watchFn(abs(rel), (type, name) => onEvent(rel, type, name));
+    } catch (err) {
+      fail(err);
+      return;
+    }
+    w.on('error', (err) => {
+      // A directory removed while watched errors on some kernels; that is the
+      // removal, already reported through the parent, not a failure.
+      const gone = !isDir(rel);
+      drop(rel);
+      if (!gone) fail(err);
+    });
+    watchers.set(rel, w);
+    reals.set(real, rel);
+    let entries = [];
+    try { entries = readdirSync(abs(rel), { withFileTypes: true }); } catch (err) { fail(err); }
+    for (const e of entries) {
+      const child = rel ? join(rel, e.name) : e.name;
+      if (e.isDirectory() || (e.isSymbolicLink() && isDir(child))) add(child);
+    }
+  };
+
+  const onEvent = (rel, type, name) => {
+    if (closed) return;
+    if (name == null) { listener(type, rel || null); return; }
+    const child = rel ? join(rel, String(name)) : String(name);
+    if (ignore(child)) return;
+    // A subdirectory appeared (created, or renamed into place) or went away.
+    if (isDir(child)) add(child);
+    else if (watchers.has(child)) drop(child);
+    listener(type, child);
+  };
+
+  out.close = () => {
+    closed = true;
+    drop('');
+  };
+  add('');
+  process.nextTick(() => {
+    const held = early || [];
+    early = null;
+    for (const err of held) fail(err);
+  });
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.60",
+  "version": "0.10.62",
   "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.68",
+    "@webjsdev/server": "^0.8.73",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

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

@@ -21,7 +21,8 @@ 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` |
+| `PORT` | Listen port. Precedence `--port` flag, then `PORT` (real env or `.env`), then `8080`. A taken port fails fast: `webjs dev` / `webjs start` exit 98 with `port 8080 is already in use by PID <n> (<command>)`, on Node and Bun alike |
+| `WEBJS_REUSE_PORT` | `1` lets several `webjs dev` / `webjs start` processes share one port (`SO_REUSEPORT`, Linux; the kernel balances connections across them). Off by default, so a second server on a taken port fails instead of silently taking a share of the requests |
 | `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); `0` turns off a config default. Same as `webjs.dev.sourceLocations: true`. 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). Replaces `webjs.dev.embedOrigins` when set. Ignored by `webjs start` |
 | `WEBJS_DEV_RELOAD_IDLE` | `webjs dev` only. Seconds of no edit and no interaction after which the live-reload stream closes so an idle host can sleep (`webjs.dev.reloadIdle`; this wins). Off by default; see `runtime.md` |
@@ -37,10 +38,11 @@ Read this when wiring caching or rate limiting, storing uploads, hardening heade
 { 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
+{ source: 'webjs-embed', type: 'select', src, tag, text, rect: { x, y, width, height }, shiftKey, metaKey, altKey, ctrlKey } // a click in inspect mode (modifiers for multi-select, #1532)
+{ source: 'webjs-embed', type: 'hold', enabled }                  // acknowledges a host hold command (#1532)
 ```
 
-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' }`, `{ source: 'webjs-embed-host', type: 'resume' }` (reopens a live-reload stream closed by `webjs.dev.reloadIdle`; every host command does this too), 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.
+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' }`, `{ source: 'webjs-embed-host', type: 'resume' }` (reopens a live-reload stream closed by `webjs.dev.reloadIdle`; every host command does this too), 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), and `{ source: 'webjs-embed-host', type: 'hold', enabled: true | false }` (#1532: while held, live-reload signals are collected instead of applied, so a builder's agent can edit many files without the preview flickering through each save; releasing applies ONE reload at the strongest verdict collected, or none when nothing changed; the hold is kept in `sessionStorage`, so a new document in the same tab starts held, and only the host's release ends it). A full dev reload or a host `reload` keeps the scroll position of the path it reloads (#1532). 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 }))`.
 

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

@@ -185,9 +185,9 @@ For an array-typed prop pass `Array`, not `Object` (`array-prop-uses-array-type`
 
 **A `reflect: true` property holding a FUNCTION drops its attribute instead of writing one, and so does one holding an array that carries a function, unless the prop is `Object` or `Array` typed.** A function has no HTML attribute representation, and the serializations it would otherwise get are both useless and dangerous. `String(fn)` is the function's SOURCE, so a reflected `'use server'` action would ship its whole body, closure secrets included, to every visitor, and `JSON.stringify(fn)` is `undefined`, which lands in the attribute as the literal four-character string. So the reflection path treats a function like `null`, removes the attribute, and warns naming the property, the tag, and the attribute. This holds on both sides, since SSR and the client-side setter run the same path, and it holds for every property name (the leak was never specific to one called `action`). Two exceptions. A property with a custom `converter.toAttribute` runs that converter first and is left alone, because an author who writes one has taken responsibility for serializing whatever they are handed. And an `Object` or `Array` typed property CARRYING a function keeps its data, because `JSON.stringify` drops the function to `null` and omits the key, so `[1, 2, fn]` reflects as `[1,2,null]` with no source and nothing else lost. If you need a function on a component, use a plain property or a signal and do not mark it `reflect`.
 
-**An `Object` or `Array` typed reflected property whose value `JSON.stringify` cannot serialize AT ALL drops its attribute the same way, and warns.** Three shapes do this: a cycle (an object or array that reaches itself, which arrives from a parent/child graph, a linked node, a memo table, or anything a library hands back with a back-reference), a `BigInt` anywhere inside the value, and an author `toJSON()` that throws. The line to keep straight is that a value which serializes WITH A GAP in it keeps its data (the carried-function case above), while one that does not serialize at all has no string to put in the attribute and so has no attribute representation, exactly like a function. The property itself is untouched and still holds the value; only the attribute goes. Before this guard the throw escaped reflection entirely, which meant a client upgrade threw before the component's first render, and an SSR render was swallowed by per-component error isolation, which shows an error box in dev and renders the component EMPTY on a page that still returned 200 in production. To reflect something about a graph-shaped value, reflect a derived scalar (an id, a count) and keep the graph on a non-reflected property. On the read side an attribute that is PRESENT but not parseable JSON reads back as `null` rather than as the raw string, on both the SSR and the client reader. An ABSENT attribute is a different case: neither reader sees it, so the property keeps its constructor value. The two readers also see the same attribute SET, not merely the same fallback: a `state: true` prop, a camelCase attribute name, and an attribute matching no declared property are all ignored by both, and both are handed a value whose HTML character references are already decoded.
+**An `Object` or `Array` typed reflected property whose value `JSON.stringify` cannot serialize AT ALL drops its attribute the same way, and warns.** Three shapes do this: a cycle (an object or array that reaches itself, which arrives from a parent/child graph, a linked node, a memo table, or anything a library hands back with a back-reference), a `BigInt` anywhere inside the value, and an author `toJSON()` that throws. The line to keep straight is that a value which serializes WITH A GAP in it keeps its data (the carried-function case above), while one that does not serialize at all has no string to put in the attribute and so has no attribute representation, exactly like a function. The property itself is untouched and still holds the value; only the attribute goes. Before this guard the throw escaped reflection entirely, which meant a client upgrade threw before the component's first render, and an SSR render was swallowed by per-component error isolation, which shows an error box in dev and renders the component EMPTY on a page that still returned 200 in production. To reflect something about a graph-shaped value, reflect a derived scalar (an id, a count) and keep the graph on a non-reflected property. On the read side an attribute that is PRESENT but not parseable JSON reads back as `null` rather than as the raw string, on both the SSR and the client reader. An ABSENT attribute is a different case: neither reader sees it, so the property keeps its constructor value. The two readers also see the same attribute SET, not merely the same fallback: a `state: true` prop and an attribute matching no declared property are ignored by both, and a camelCase attribute name reaches its prop on both through the lowercased alias, and both are handed a value whose HTML character references are already decoded.
 
-**Writing attributes in markup.** Names are case-insensitive and the browser lowercases them while parsing, so write kebab-case (`user-name`); a camelCase attribute (`userName="…"`) reaches no property on either side. A prop that renames its attribute answers to the new name ONLY, so `open: prop(Boolean, { attribute: 'is-open' })` is written `<my-el is-open>` and `<my-el open>` reaches nothing. Character references are decoded before the value is coerced, so `cfg="&#123;&quot;a&quot;:1&#125;"` parses as the object it spells and `label="Tom &amp; Jerry"` is `Tom & Jerry`; the legacy semicolon-less forms decode exactly where a browser decodes them (`&nbsp` at the end of a value is a non-breaking space, `&nbspx` and `&nbsp=x` stay literal), and writing the semicolon avoids the question. A `state: true` prop takes an SSR value only through a `.prop=${value}` binding from the parent template, never from an attribute.
+**Writing attributes in markup.** Names are case-insensitive and the browser lowercases them while parsing, so a camelCase prop answers to BOTH its kebab-case name (`user-name`, the one reflection writes) and its lowercased name (`username`, lit's default), which is what a camelCase attribute in markup (`userName="…"`) arrives as; all three spellings reach `userName` on both sides. Prefer kebab-case. A prop that renames its attribute answers to the new name ONLY, so `open: prop(Boolean, { attribute: 'is-open' })` is written `<my-el is-open>` and `<my-el open>` reaches nothing. Character references are decoded before the value is coerced, so `cfg="&#123;&quot;a&quot;:1&#125;"` parses as the object it spells and `label="Tom &amp; Jerry"` is `Tom & Jerry`; the legacy semicolon-less forms decode exactly where a browser decodes them (`&nbsp` at the end of a value is a non-breaking space, `&nbspx` and `&nbsp=x` stay literal), and writing the semicolon avoids the question. A `state: true` prop takes an SSR value only through a `.prop=${value}` binding from the parent template, never from an attribute.
 
 **Never use a class-field declaration OR initializer** (`count = 0`, `student: Student = {...}`, `todos!: Todo[]`). Under `useDefineForClassFields` even a type-only `todos!: Todo[]` compiles to define an own property after `super()`, which clobbers the prototype's reactive accessor and silently breaks reactivity. Only declare props in the factory and read/write them off `this`. The `reactive-props-no-class-field` rule catches this.
 

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

@@ -42,9 +42,11 @@ Three seams pick a runtime-specific implementation, all inside the framework, no
 
 **The in-place dev refresh (#1398) needs the server process to SURVIVE the edit,** which is the whole of the Node-versus-Bun difference in that row. A page or layout never hydrates, so a freshly rendered page is the complete truth for it and the client router can swap it in without a reload, keeping scroll and (for a page edit) the hydrated state of components outside the changed region. The server classifies the changed file and puts the verdict on the live-reload event, so this needs a process that is still alive to do the classifying.
 
-Bun's `bun --hot` invalidates modules in place without restarting, so it gets the refresh. On Node the `webjs dev` supervisor (it replaced `node --watch` in #1521) RESTARTS the server process on a change under `app`, `components`, `modules`, `lib`, or `actions`, or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
+Bun's `bun --hot` invalidates modules in place without restarting, so it gets the refresh. On Node the `webjs dev` supervisor (it replaced `node --watch` in #1521) RESTARTS the server process on a change under `app`, `components`, `modules`, `lib`, or `actions`, or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. An in-place refresh loads the rebuilt stylesheets (a `webjs.dev.regenerate` compile runs on that request) BEFORE it swaps the new markup in, and drops the old sheets only after, so an element that gained a utility class never paints without its rule (#1535; a full reload never had the gap, since a head stylesheet is render-blocking). A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
 
-**`webjs dev` does not stay down (#1521).** The supervisor and the server's own watcher handle every watcher error: a file in a watched dir the dev server cannot read or watch (the 0600 temp file `sed -i` creates when another user runs it, a file removed mid-scan) logs one `file watcher skipped <path> (EACCES)` warning and both keep running, where `node --watch` used to crash and leave the preview dead. A server process that crashes is started again on the next file change, or by itself after a backoff of 0.5s growing to 10s for repeated crashes. On Bun the supervisor does only the crash recovery, since `bun --hot` reloads edits in place. Stopping `webjs dev` (Ctrl-C, SIGTERM) stops the server child too, and a child whose supervisor was killed outright exits on its own, so nothing is left holding the port.
+**`webjs dev` and `webjs start` serve the directory they are started in, and refuse anywhere else (#1526).** Run them in the app directory, the one holding `app/`. In a workspace (`apps/web` under a root `package.json` with `workspaces`) that is the member, even when the CLI is hoisted to the root `node_modules`: the hoisted bin and the Bun `--hot` child both keep the directory they were started in. Started where there is no `app/` (the workspace root, or a subdirectory such as `app/` itself), both exit 1 before any `before` step runs, naming the app to start (`cd apps/web && webjs dev`), instead of booting a server that answers 404 for every route.
+
+**`webjs dev` does not stay down (#1521).** The supervisor and the server's own watcher handle every watcher error: a file in a watched dir the dev server cannot read or watch (the 0600 temp file `sed -i` creates when another user runs it, a file removed mid-scan) logs one `file watcher skipped <path> (EACCES)` warning and both keep running, where `node --watch` used to crash and leave the preview dead. Edits that REPLACE a file (`sed -i`, an editor saving through a temp file, an atomic write) are heard every time, however often the same file is replaced (#1529: on Linux under Node the watchers watch each directory, since Node 24's own recursive watcher stopped hearing a file after its first replacement). A server process that crashes is started again on the next file change, or by itself after a backoff of 0.5s growing to 10s for repeated crashes. On Bun the supervisor does only the crash recovery, since `bun --hot` reloads edits in place. Stopping `webjs dev` (Ctrl-C, SIGTERM) stops the server child too, and a child whose supervisor was killed outright exits on its own, so nothing is left holding the port.
 
 The 103 Early Hints gap costs only a small first-load latency edge where an edge proxy forwards the 103, never correctness. The `modulepreload` hints still ship in the document head on both runtimes.