@webjsdev/cli 0.10.39 → 0.10.40

package/lib/app-tasks.js

@@ -4,15 +4,20 @@ import { join } from 'node:path';
 /**
  * Read the dev/start task orchestration from an app's `package.json` `"webjs"`
  * block (#550). This is what lets `webjs dev` / `webjs start` behave identically
- * to `npm run dev` / `npm run start`: the orchestration (Tailwind's watcher, a
- * `db migrate` before prod boot) moves OUT of `concurrently` + `pre*` npm hooks
+ * to `npm run dev` / `npm run start`: the orchestration (a Tailwind compile, a
+ * `db migrate` before boot) moves OUT of `concurrently` + `pre*` npm hooks
  * and INTO the framework primitive, so a bare `webjs dev` is not a degraded run.
  *
+ * Reads only `before` / `parallel` here (the CLI-run tasks). The dev-only
+ * `regenerate` key (#967, on-request rebuilds of a stale served output like
+ * `public/tailwind.css`) is read by the SERVER, not this reader, so the scaffold
+ * keeps its static CSS fresh WITHOUT a `--watch` under `parallel`.
+ *
  * Shape:
  *   "webjs": {
  *     "dev":   {
- *       "before":   ["webjs db migrate"],
- *       "parallel": ["tailwindcss -i ./public/input.css -o ./public/tailwind.css --watch"]
+ *       "before":   ["webjs db migrate", "tailwindcss -i ./public/input.css -o ./public/tailwind.css --minify"]
+ *       // dev.regenerate keeps the CSS fresh on request (server-read, see dev-regenerate.js)
  *     },
  *     "start": { "before": ["webjs db migrate"] }
  *   }
@@ -20,9 +25,10 @@ import { join } from 'node:path';
  * `before` commands run sequentially to completion BEFORE the server boots (the
  * old `predev` / `prestart` hooks: a one-shot `webjs db migrate`).
  * `parallel` (dev only) commands run as long-lived child processes ALONGSIDE the
- * server (the old `concurrently` watchers: Tailwind). Returns normalized arrays
- * (never undefined) so callers iterate without guards, and a missing/empty
- * config yields empty arrays so a plain app runs `webjs dev`/`start` unchanged.
+ * server (the old `concurrently` watchers), for a genuinely long-lived side
+ * process. Returns normalized arrays (never undefined) so callers iterate
+ * without guards, and a missing/empty config yields empty arrays so a plain app
+ * runs `webjs dev`/`start` unchanged.
  *
  * Pure (reads one file, never spawns / prints / exits) so it is unit-testable
  * without a process, matching `lib/port.js` and `lib/dev-supervisor.js`.

package/lib/create.js

@@ -348,12 +348,11 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   // (not the browser runtime), so it renders styled with JavaScript off. The
   // compiler is a node-shebang CLI, so a Bun app (whose Dockerfile is a node-less
   // `oven/bun:1` image, #595) must run it under Bun via `bun --bun`; a Node app
-  // runs it directly (the before / parallel steps get node_modules/.bin on PATH
+  // runs it directly (the before / regenerate steps get node_modules/.bin on PATH
   // via envWithLocalBin). Deliberately NOT `npm run css:build` in the hooks: the
   // Bun image has no npm, so that step would exit 127 and abort the boot.
   const twBin = isBun ? 'bun --bun tailwindcss' : 'tailwindcss';
   const cssBuildCmd = `${twBin} -i ./public/input.css -o ./public/tailwind.css --minify`;
-  const cssWatchCmd = `${twBin} -i ./public/input.css -o ./public/tailwind.css --watch`;
   const appDir = join(cwd, name);
   if (existsSync(appDir)) {
     console.error(`Error: directory '${name}' already exists.`);
@@ -489,15 +488,31 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // migrate` (idempotent, a no-op when the db is current), so a freshly
     // generated migration is applied without a manual step (#725). For a UI
     // template it ALSO compiles Tailwind in `before` so a freshly cloned app is
-    // styled on the very first boot with no manual step, and runs the Tailwind
-    // `--watch` under `parallel` for live recompiles in dev. The compile command
-    // is the runtime-aware `cssBuildCmd` (a Bun app runs it under Bun, since its
+    // styled on the very first boot with no manual step. The compile command is
+    // the runtime-aware `cssBuildCmd` (a Bun app runs it under Bun, since its
     // image has no npm or Node), NOT `npm run css:build`. The api template has no
     // CSS, so it gets neither.
+    //
+    // In dev the static public/tailwind.css is kept fresh by `dev.regenerate`
+    // (#967), NOT a background `tailwindcss --watch`. A watch that dies mid-
+    // session or never starts serves stale/missing CSS with no error (a newly
+    // added utility class has no backing rule, so the app renders unstyled
+    // locally while prod is fine). `regenerate` instead recompiles ON REQUEST
+    // when the output is older than a source (or missing): the framework rebuilds
+    // it before serving `/public/tailwind.css`, so there is no watch process to
+    // die and no staleness window. Same `cssBuildCmd` as prod, so dev and prod
+    // resolve classes identically (nothing to diverge). `inputs` mirrors the
+    // input.css @source globs (the dirs Tailwind scans for classes).
     webjs: {
       dev: {
         before: isApi ? ['webjs db migrate'] : ['webjs db migrate', cssBuildCmd],
-        ...(isApi ? {} : { parallel: [cssWatchCmd] }),
+        ...(isApi ? {} : {
+          regenerate: [{
+            output: 'public/tailwind.css',
+            command: cssBuildCmd,
+            inputs: ['app', 'components', 'modules', 'lib', 'public/input.css'],
+          }],
+        }),
       },
       start: { before: isApi ? ['webjs db migrate'] : ['webjs db migrate', cssBuildCmd] },
     },
@@ -1226,8 +1241,9 @@ export default function RootLayout({ children }: { children: unknown }) {
       })();
     </script>
     <!-- Tailwind: a STATIC stylesheet compiled from public/input.css to
-         public/tailwind.css by css:build / css:watch (run automatically by the
-         dev and start tasks). A real stylesheet, so the app is fully styled with
+         public/tailwind.css by css:build (run automatically by the dev and start
+         tasks; in dev it is also recompiled on request when a source changes, so
+         it never goes stale). A real stylesheet, so the app is fully styled with
          JavaScript DISABLED (no in-browser compile). -->
     <link rel="stylesheet" href="/public/tailwind.css">
     <style>

package/lib/doctor.js

@@ -36,7 +36,7 @@
  * fails CI because npm was briefly unreachable is worse than useless.
  */
 
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, readdirSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { createRequire } from 'node:module';
@@ -802,7 +802,7 @@ function checkGitHook(appDir) {
  * Advisory (#646): name why a page/layout SHIPS its module to the browser
  * instead of being elided. A page/layout that is a pure carrier (import-only
  * #605 / inert #179) stays out of the browser; one that ships whole is pinned
- * by a specific client-effecting NON-component in its closure (a util touching
+ * by a specific client-effecting NON-component on a component-free path from it, #963 (a util touching
  * a client global, a module-scope side effect, a bare side-effect import) or by
  * its own client work. This turns that invisible #605/#179 regression into a
  * named line. WARN only: a page legitimately MAY ship, and the analyser is
@@ -881,6 +881,89 @@ async function checkScaffoldDesign(appDir) {
   };
 }
 
+// Directories never worth walking for the CSS-freshness advisory (mirrors
+// dev-regenerate's IGNORE_DIRS): build output, deps, VCS + framework caches.
+const FRESHNESS_IGNORE = new Set(['node_modules', '.git', '.webjs', 'dist', '.next', 'coverage']);
+
+/**
+ * Newest mtime (ms) of any FILE under a path (a file's own, or the max over the
+ * files in a directory tree, skipping dependencies / dotfiles). Directory-node
+ * mtimes are NOT counted, matching dev-regenerate's walker: a content edit only
+ * shows through the file mtime, and a directory mtime is a flaky moving target.
+ * A missing path is 0. Best-effort: never throws.
+ * @param {string} abs
+ * @returns {number}
+ */
+function newestMtimeMs(abs) {
+  let st;
+  try { st = statSync(abs); } catch { return 0; }
+  if (!st.isDirectory()) return st.mtimeMs;
+  let newest = 0;
+  let entries;
+  try { entries = readdirSync(abs, { withFileTypes: true }); } catch { return newest; }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || FRESHNESS_IGNORE.has(e.name)) continue;
+    // Skip symlinks: following one can cycle into unbounded recursion (a stack
+    // overflow here) or escape into node_modules. Same tradeoff as the server
+    // walker in dev-regenerate.js.
+    if (e.isSymbolicLink()) continue;
+    const m = newestMtimeMs(join(abs, e.name));
+    if (m > newest) newest = m;
+  }
+  return newest;
+}
+
+/**
+ * ADVISORY: a declared `webjs.dev.regenerate` output is STALE on disk (a source
+ * is newer than the committed/built output). In DEV the framework recompiles it
+ * on request (#967), so this never bites locally, but the check is the explicit
+ * dev/prod PARITY backstop: it catches a stale `public/tailwind.css` that would
+ * be served as-is by `webjs start` (prod does NOT recompile on request) or
+ * committed into the repo. WARN-level: the fix is a one-line rebuild, and a
+ * missing output (a fresh clone before the first `css:build`) is not this app's
+ * bug to hard-fail on.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkStaticAssetFreshness(appDir) {
+  const name = 'Static build outputs (dev.regenerate freshness)';
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    return { name, status: 'pass', message: 'no package.json to analyse' };
+  }
+  const rules = pkg && pkg.webjs && pkg.webjs.dev ? pkg.webjs.dev.regenerate : null;
+  if (!Array.isArray(rules) || rules.length === 0) {
+    return { name, status: 'pass', message: 'no webjs.dev.regenerate rules declared' };
+  }
+  const stale = [];
+  for (const rule of rules) {
+    if (!rule || typeof rule.output !== 'string') continue;
+    const output = rule.output.replace(/^\/+/, '');
+    const outMtime = newestMtimeMs(join(appDir, output));
+    if (outMtime === 0) continue; // missing output: not a staleness fail (built on first boot)
+    let newestSrc = 0;
+    for (const inp of Array.isArray(rule.inputs) ? rule.inputs : []) {
+      const m = newestMtimeMs(join(appDir, inp));
+      if (m > newestSrc) newestSrc = m;
+    }
+    if (newestSrc > outMtime) stale.push({ output, command: rule.command });
+  }
+  if (stale.length === 0) {
+    return { name, status: 'pass', message: 'every declared build output is up to date with its sources' };
+  }
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${stale.length} static build output(s) are older than a source file:\n` +
+      stale.map((s) => `    ${s.output} (rebuild: ${s.command})`).join('\n') +
+      '\n    In dev the framework recompiles these on request, so this only bites a `webjs start` (prod) or a committed stale file.',
+    fix: 'Rebuild the output(s) with the command shown (e.g. `npm run css:build`) before deploying or committing. `webjs dev` regenerates them on request automatically.',
+  };
+}
+
 /**
  * Probe whether `@webjsdev/core` resolves from `appDir`. Node resolution is
  * directory-relative, so this must probe FROM the app (not the CLI's own
@@ -972,6 +1055,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     Promise.resolve(checkGitHook(appDir)),
     checkElisionCarriers(appDir),
     checkScaffoldDesign(appDir),
+    checkStaticAssetFreshness(appDir),
   ]);
   return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.39",
+  "version": "0.10.40",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/AGENTS.md

@@ -493,22 +493,32 @@ npm run dev                   # webjs dev, then serves
 
 `npm run dev` and `npm start` are the documented entrypoints, and they
 are thin aliases for `webjs dev` / `webjs start`. The start orchestration
-(applying migrations, and any parallel watcher like the Tailwind CLI)
-lives in the `webjs` block of `package.json` and runs INSIDE
-`webjs dev` / `webjs start`:
+(applying migrations, and compiling Tailwind) lives in the `webjs` block
+of `package.json` and runs INSIDE `webjs dev` / `webjs start`:
 
 ```jsonc
 "webjs": {
-  "dev": { "before": ["webjs db migrate"] },
-  "start": { "before": ["webjs db migrate"] }
+  "dev": {
+    "before": ["webjs db migrate", "tailwindcss -i ./public/input.css -o ./public/tailwind.css --minify"],
+    "regenerate": [
+      { "output": "public/tailwind.css",
+        "command": "tailwindcss -i ./public/input.css -o ./public/tailwind.css --minify",
+        "inputs": ["app", "components", "modules", "lib", "public/input.css"] }
+    ]
+  },
+  "start": { "before": ["webjs db migrate", "tailwindcss -i ./public/input.css -o ./public/tailwind.css --minify"] }
 }
 ```
 
 Both `dev` and `start` apply pending migrations via `webjs db migrate`
-(idempotent, a no-op when the db is current), so a freshly generated
-migration is applied without a manual step. An app that adds the Tailwind
-CLI puts its `--watch` command under `webjs.dev.parallel` and it runs
-alongside the server, torn down on exit.
+(idempotent, a no-op when the db is current) and compile the static
+`public/tailwind.css`, so a freshly generated migration is applied and
+the app is fully styled with no manual step. In dev the stylesheet is
+then kept fresh by `webjs.dev.regenerate`: the dev server recompiles it
+ON REQUEST whenever a source changes, so a newly added utility class is
+never served stale and there is no `tailwindcss --watch` process that can
+die mid-session (`webjs.dev.parallel` still exists for a genuinely
+long-lived side process, torn down on exit).
 `before` steps run to completion first; a failed `webjs db migrate`
 aborts the boot with a clear message rather than serving a stale schema.
 
@@ -830,7 +840,7 @@ Practical consequences for agents writing webjs code.
 | Fetch in `connectedCallback` / `firstUpdated` | Empty first paint (neither hook runs in SSR) | Fetch in the page function, pass as props |
 | `Task` for initial-paint data | SSR ships the pending state, flashes to resolved on hydration | Page function fetch, pass as props, OR an `async render()` in the component (`Task` is fine for client-time async) |
 | Expecting a sync `render()` only | webjs allows `async render() { const d = await getData(); ... }`; SSR bakes the data into the first paint | Use it for request-time server data; `renderFallback()` is the re-fetch loading UI (never first paint); error isolation is automatic |
-| Assuming an `async render()` always ships its module | A bare one (no other client signal) is ELIDED, so it costs zero JS and skips the on-hydration re-fetch, first paint unchanged | Rely on it for a fetch-and-display leaf. `static refresh = true` keeps the on-load refresh, `static shadow = true` always ships |
+| Assuming an `async render()` always ships its module | A bare one (no other client signal) is ELIDED, so it costs zero JS and skips the on-hydration re-fetch, first paint unchanged | Rely on it for a fetch-and-display leaf. `static interactive = true` forces a ship the analyser would otherwise elide, `static shadow = true` always ships |
 | `window.X` / `document.X` in constructor or `render()` | SSR crash | Move to `connectedCallback` |
 | Top-level `import` of a browser-only library | SSR crash | Dynamic `import()` inside `connectedCallback` |
 | Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | Pass the shape to the base-class factory `WebComponent({ student: Object })` and set the default in the constructor (flagged by `reactive-props-no-class-field`) |

package/templates/gallery/modules/async-render/components/server-clock.ts

@@ -11,12 +11,13 @@ import { WebComponent, html } from '@webjsdev/core';
 import { serverGreeting } from '../queries/server-greeting.server.ts';
 
 export class ServerClock extends WebComponent {
-  // A bare async-render component (no other client signal) is ELIDED, since its
-  // SSR'd HTML is already the complete output. `static refresh = true` opts into
-  // keeping the on-load re-fetch so the module ships (drop it for request-stable
-  // data you are happy to leave server-rendered).
-  static refresh = true;
-
+  // A bare async-render component (no other client signal, light DOM) is
+  // ELIDED: its SSR'd HTML is already the complete output, so the framework
+  // serves it with ZERO JavaScript and skips the redundant on-hydration
+  // re-fetch. This is the common fetch-and-display leaf shape. If you ever need
+  // to force a component to ship when the analyser would elide it (for
+  // interactivity static analysis cannot see, like a dynamically-computed tag
+  // string), declare `static interactive = true`.
   async render() {
     const info = await serverGreeting();
     return html`<p class="font-mono text-sm">server rendered this at