@webjsdev/cli 0.10.4 → 0.10.6

package/bin/webjs.js

@@ -2,10 +2,36 @@
 import { resolve, join, dirname } from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
 
+// Node-version preflight (issue #238), INLINE and dependency-free.
+// This MUST run before any `import @webjsdev/server`: importing the server
+// package links `src/dev.js`, which references Node 24+ builtins, so on an old
+// Node that import would LINK-fail before any preflight inside the server
+// package could run. The primary guard is therefore `checkNodeInline` (from
+// `../lib/node-preflight.js`, which imports nothing), depending only on
+// `process.versions.node`. The richer `assertNodeVersion` import inside main()
+// stays as belt-and-suspenders for the link-ok (>= 22.13) cases.
+// `help` / no-arg is exempt so a user on an old Node can still read usage.
+if (cmd !== 'help' && cmd !== undefined) {
+  let engines = '>=24.0.0';
+  try {
+    const { readFileSync } = await import('node:fs');
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, '..', 'package.json'), 'utf8'),
+    );
+    engines = pkg?.engines?.node || engines;
+  } catch {}
+  const r = checkNodeInline(process.versions.node, engines);
+  if (!r.ok) {
+    console.error(nodeInlineMessage(r));
+    process.exit(1);
+  }
+}
+
 // Exactly three scaffolds exist. Keep this list as the single source of
 // truth. AI-agent docs in README.md / AGENTS.md / .cursorrules /
 // .agents/rules/workflow.md / .github/copilot-instructions.md mirror it.
@@ -16,6 +42,7 @@ const USAGE = `webjs commands:
   webjs start [--port 8080]                       Start production server (serves source directly, no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check                                     Run correctness checks on the app
+  webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs create <name> [--template full-stack|api|saas] [--no-install]  Scaffold a new webjs app
                                                   (only 3 templates exist. default: full-stack with Prisma+SQLite)
                                                   Auto-runs the detected package manager's install in the new dir
@@ -41,6 +68,15 @@ function flag(args, name, def) {
 }
 
 async function main() {
+  // Preflight: webjs needs Node 24+ (built-in TS strip + recursive fs.watch).
+  // Run before any subcommand so an older Node fails fast with a clear,
+  // actionable message naming the found + required version, exiting non-zero
+  // instead of crashing cryptically later. `help` is exempt so a user on an
+  // old Node can still read usage.
+  if (cmd !== 'help' && cmd !== undefined) {
+    const { assertNodeVersion } = await import('@webjsdev/server');
+    assertNodeVersion({ onFail: 'exit' });
+  }
   switch (cmd) {
     case 'dev': {
       // If we're already inside the --watch child, start the server directly.
@@ -242,6 +278,27 @@ async function main() {
       }
       break;
     }
+    case 'types': {
+      // Generate `.webjs/routes.d.ts` from the app's `app/` routes (#258),
+      // narrowing the @webjsdev/core `Route` href union + per-route `params`.
+      // Opt-in codegen: the static types in @webjsdev/core work without it
+      // (un-generated apps see `Route = string`).
+      const { generateRouteTypes } = await import('@webjsdev/server');
+      const { mkdir, writeFile } = await import('node:fs/promises');
+      const appDir = process.cwd();
+      const text = await generateRouteTypes(appDir);
+      const outDir = join(appDir, '.webjs');
+      await mkdir(outDir, { recursive: true });
+      const outFile = join(outDir, 'routes.d.ts');
+      await writeFile(outFile, text);
+      // Count the typed routes (each `WebjsRoutes` key is one route literal).
+      const count = (text.match(/^\s+".*": true;$/gm) || []).length;
+      console.log(
+        `webjs types: wrote .webjs/routes.d.ts (${count} route${count === 1 ? '' : 's'} typed). ` +
+        `Ensure tsconfig "include" lists ".webjs/routes.d.ts" so tsserver picks it up.`,
+      );
+      break;
+    }
     case 'create': {
       const name = rest[0];
       if (!name || name.startsWith('-')) {

package/lib/create.js

@@ -346,6 +346,22 @@ export async function scaffoldApp(name, cwd, opts = {}) {
         { name: '@webjsdev/ts-plugin' },
       ],
     },
+    // `.webjs/routes.d.ts` is the OPT-IN generated route-types overlay (#258):
+    // run `webjs types` (or `webjs dev`, which emits it) to narrow the
+    // @webjsdev/core `Route` href union + per-route `params`. Listed in
+    // `include` so tsserver picks it up; it is gitignored (regenerated per
+    // machine), so a fresh clone runs `webjs dev` / `webjs types` to recreate
+    // it, and the static @webjsdev/core types work even when it is absent.
+    include: [
+      'app/**/*',
+      'components/**/*',
+      'modules/**/*',
+      'lib/**/*',
+      'middleware.js',
+      'middleware.ts',
+      '.webjs/routes.d.ts',
+    ],
+    exclude: ['node_modules', '.webjs/vendor', 'prisma/migrations'],
   }, null, 2) + '\n');
 
   // --- Templates (AGENTS.md, CONVENTIONS.md, CLAUDE.md, test files, Claude hooks) ---
@@ -397,6 +413,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // to main, mirroring the webjs framework's own CI.
     '.github/workflows/ci.yml',
     '.editorconfig',
+    // VS Code: associate the published webjs-config JSON Schema with the
+    // package.json `webjs` block, so an unknown / typo'd key (#259) is
+    // flagged natively in the editor instead of silently dropped.
+    '.vscode/settings.json',
     // Production / deploy scaffolding. `docker compose up --build` runs
     // the app locally with the same Dockerfile production builds from.
     'Dockerfile',
@@ -494,6 +514,27 @@ if (process.env.NODE_ENV !== 'production') g.__prisma = prisma;
   if (isApi) {
     // API-only template: no layout, no page, no components.
     // Just a health route and an example module with route wrapper.
+
+    // Root middleware applying CORS to every route. An API consumed by a
+    // browser from another origin needs this; the `cors()` primitive
+    // handles origin reflection, the OPTIONS preflight, Vary: Origin, and
+    // the credentials rule, so route handlers stay focused on data.
+    await writeFile(join(appDir, 'middleware.ts'), `import { cors } from '@webjsdev/server';
+
+/**
+ * App-wide CORS policy. Replace the allow-list with your real frontend
+ * origins. With \`credentials: true\` a wildcard origin is invalid per the
+ * CORS spec, so list explicit origins (never \`'*'\` + credentials).
+ */
+export default cors({
+  origin: ['http://localhost:3000', 'https://app.example.com'],
+  credentials: true,
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+  allowedHeaders: ['content-type', 'authorization'],
+  maxAge: 86400,
+});
+`);
+
     await mkdir(join(appDir, 'app', 'api', 'health'), { recursive: true });
     await mkdir(join(appDir, 'app', 'api', 'users'), { recursive: true });
     await writeFile(join(appDir, 'app', 'api', 'health', 'route.ts'), `export async function GET() {

package/lib/node-preflight.js

@@ -0,0 +1,46 @@
+/**
+ * Inline, dependency-free Node-version preflight for the CLI (issue #238).
+ *
+ * This is deliberately SEPARATE from `@webjsdev/server`'s `node-version.js`:
+ * importing the server package links `src/dev.js`, which references Node 24+
+ * builtins, so on an old Node that import LINK-fails before any preflight could
+ * run. The CLI's primary guard must therefore depend on nothing but
+ * `process.versions.node`. `bin/webjs.js` imports `checkNodeInline` from here
+ * and runs it before any `import @webjsdev/server`. This module imports nothing.
+ */
+
+/**
+ * Pure Node-major check. Reads the minimum from the passed `engines` range
+ * (the CLI's own `engines.node`, so the requirement lives in one place) and
+ * compares the running major. Fails open (`ok: true`) on an unparseable running
+ * version so an unusual runtime is not blocked; falls back to 24 when the
+ * engines range carries no integer.
+ * @param {string} current  running Node version (e.g. `process.versions.node`)
+ * @param {string} engines  the CLI package's `engines.node` range
+ * @returns {{ ok: boolean, current: string, currentMajor: number, requiredMajor: number }}
+ */
+export function checkNodeInline(current, engines) {
+  const cm = String(current).match(/^v?(\d+)/);
+  const rm = String(engines).match(/(\d+)/);
+  const currentMajor = cm ? Number(cm[1]) : NaN;
+  const requiredMajor = rm ? Number(rm[1]) : 24;
+  const ok = Number.isNaN(currentMajor) || currentMajor >= requiredMajor;
+  return { ok, current, currentMajor, requiredMajor };
+}
+
+/**
+ * Compose the actionable stderr message for an unsupported Node. Names the found
+ * and required version and the reason (the built-in TS strip + recursive
+ * fs.watch need Node 24+).
+ * @param {{ current: string, currentMajor: number, requiredMajor: number }} r
+ * @returns {string}
+ */
+export function nodeInlineMessage(r) {
+  return (
+    `webjs requires Node ${r.requiredMajor}+ but found Node ${r.current}. ` +
+    `webjs is buildless and relies on Node ${r.requiredMajor}'s built-in ` +
+    `TypeScript strip (module.stripTypeScriptTypes) and recursive fs.watch, ` +
+    `neither of which exists on Node ${r.currentMajor}. ` +
+    `Upgrade to Node ${r.requiredMajor} or newer (see https://nodejs.org).`
+  );
+}

package/lib/saas-template.js

@@ -276,6 +276,7 @@ export async function writeSaasFiles(appDir) {
   await mkdir(join(appDir, 'app', 'signup'), { recursive: true });
   await writeFile(join(appDir, 'app', 'signup', 'page.ts'), [
     "import { html } from '@webjsdev/core';",
+    "import { signup } from '../../modules/auth/actions/signup.server.ts';",
     "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '../../components/ui/card.ts';",
     "import { buttonClass } from '../../components/ui/button.ts';",
     "import { inputClass } from '../../components/ui/input.ts';",
@@ -283,7 +284,30 @@ export async function writeSaasFiles(appDir) {
     "",
     "export const metadata = { title: 'Sign up' };",
     "",
-    "export default function SignupPage() {",
+    "// Page server action: handles the POST from the form below. With JS",
+    "// disabled this is a plain <form> round-trip; with JS the client router",
+    "// swaps the 422 re-render (errors) or follows the 303 (success) in place.",
+    "// A validation failure returns fieldErrors + values so the page re-renders",
+    "// with messages and the user's typed input preserved (#244).",
+    "export async function action({ formData }: { formData: FormData }) {",
+    "  const name = String(formData.get('name') || '').trim();",
+    "  const email = String(formData.get('email') || '').trim();",
+    "  const password = String(formData.get('password') || '');",
+    "  const values = { name, email };",
+    "  const fieldErrors: Record<string, string> = {};",
+    "  if (!name) fieldErrors.name = 'Name is required';",
+    "  if (!email.includes('@')) fieldErrors.email = 'Enter a valid email';",
+    "  if (password.length < 8) fieldErrors.password = 'At least 8 characters';",
+    "  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values, status: 422 };",
+    "  const result = await signup({ name, email, password });",
+    "  if (!result.success) return { success: false, fieldErrors: { email: result.error }, values, status: result.status };",
+    "  // Account created. Redirect to login via PRG so a reload will not resubmit.",
+    "  return { success: true, redirect: '/login' };",
+    "}",
+    "",
+    "export default function SignupPage({ actionData }: { actionData?: { fieldErrors?: Record<string, string>; values?: Record<string, string> } }) {",
+    "  const errors = actionData?.fieldErrors || {};",
+    "  const values = actionData?.values || {};",
     "  return html`",
     "    <div class=\"max-w-sm mx-auto mt-12\">",
     "      <div class=${cardClass()}>",
@@ -292,18 +316,21 @@ export async function writeSaasFiles(appDir) {
     "          <p class=${cardDescriptionClass()}>Get started with your new workspace.</p>",
     "        </div>",
     "        <div class=${cardContentClass()}>",
-    "          <form id=\"signup-form\" class=\"flex flex-col gap-4\">",
+    "          <form method=\"POST\" class=\"flex flex-col gap-4\">",
     "            <div class=\"flex flex-col gap-1.5\">",
     "              <label class=${labelClass()} for=\"name\">Name</label>",
-    "              <input class=${inputClass()} id=\"name\" name=\"name\" type=\"text\" required>",
+    "              <input class=${inputClass()} id=\"name\" name=\"name\" type=\"text\" value=${values.name || ''} required>",
+    "              ${errors.name ? html`<p class=\"text-sm text-destructive\">${errors.name}</p>` : ''}",
     "            </div>",
     "            <div class=\"flex flex-col gap-1.5\">",
     "              <label class=${labelClass()} for=\"email\">Email</label>",
-    "              <input class=${inputClass()} id=\"email\" name=\"email\" type=\"email\" required>",
+    "              <input class=${inputClass()} id=\"email\" name=\"email\" type=\"email\" value=${values.email || ''} required>",
+    "              ${errors.email ? html`<p class=\"text-sm text-destructive\">${errors.email}</p>` : ''}",
     "            </div>",
     "            <div class=\"flex flex-col gap-1.5\">",
     "              <label class=${labelClass()} for=\"password\">Password</label>",
-    "              <input class=${inputClass()} id=\"password\" name=\"password\" type=\"password\" required>",
+    "              <input class=${inputClass()} id=\"password\" name=\"password\" type=\"password\" minlength=\"8\" required>",
+    "              ${errors.password ? html`<p class=\"text-sm text-destructive\">${errors.password}</p>` : ''}",
     "            </div>",
     "            <button class=${buttonClass()} type=\"submit\">Create account</button>",
     "          </form>",

package/package.json

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

package/templates/.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["/package.json"],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "webjs": {
+            "$ref": "./node_modules/@webjsdev/server/webjs-config.schema.json"
+          }
+        }
+      }
+    }
+  ]
+}

package/templates/AGENTS.md

@@ -112,6 +112,15 @@ layered on top:
 See [docs.webjs.com → Editor setup](https://docs.webjs.com/docs/editor-setup)
 for the full walkthrough.
 
+**Config validation in `package.json`.** The scaffold ships
+`.vscode/settings.json`, which associates the published webjs-config JSON
+Schema (`@webjsdev/server/webjs-config.schema.json`) with the `webjs` block
+of `package.json`. In VS Code an unknown / typo'd `webjs.*` key (`redirect`
+for `redirects`, say) is then flagged inline instead of silently dropped to
+the default. The same shape is typed by the `WebjsConfig` type from
+`@webjsdev/core` (`import type { WebjsConfig } from '@webjsdev/core'`) for a
+typed reference.
+
 ## UI components: Webjs UI (preinstalled)
 
 This scaffold ships with the standard Webjs UI component kit
@@ -267,6 +276,28 @@ test/<feature>/                feature-scoped tests, one folder per concern
 middleware.ts            root middleware (optional, outermost)
 ```
 
+### Typed page / layout / route-handler props
+
+Type page / layout / route-handler arguments with the exported helpers so a
+param typo is a compile-time error:
+
+```ts
+import type { PageProps, LayoutProps, RouteHandlerContext } from '@webjsdev/core';
+
+export default function Post({ params }: PageProps<'/blog/[slug]'>) {
+  return html`<h1>${params.slug}</h1>`;   // params typed { slug: string }
+}
+export default function RootLayout({ children }: LayoutProps) { /* ... */ }
+export async function GET(req: Request, ctx: RouteHandlerContext) { /* ctx.params */ }
+```
+
+Run `webjs types` once (and ensure `tsconfig.json` `include` lists
+`.webjs/routes.d.ts`, the scaffold already does) to generate the route union:
+`PageProps<'/blog/[slug]'>['params']` then narrows to `{ slug: string }` and
+`navigate()` only accepts real app routes. `webjs dev` regenerates the file on
+startup, so it stays current. Without it, `params` is `Record<string, string>`
+and `navigate()` accepts any string (non-breaking).
+
 ## Database (Prisma + SQLite by default)
 
 Every scaffold includes a Prisma setup pointed at a local SQLite file.
@@ -440,7 +471,7 @@ import { createContext } from '@webjsdev/core/context';
 import { Task } from '@webjsdev/core/task';
 import { fixture, waitForUpdate } from '@webjsdev/core/testing';
 
-import { rateLimit, cache, createAuth, Credentials, Session } from '@webjsdev/server';
+import { rateLimit, cors, cache, createAuth, Credentials, Session } from '@webjsdev/server';
 ```
 
 ## Environment variables (server vs browser)
@@ -709,8 +740,13 @@ return html`
 ```
 
 The router's `closest('webjs-frame')` detection takes precedence over
-layout markers. Only the frame's content swaps. Use this sparingly -
-folder-based layouts handle 99% of cases.
+layout markers. Only the frame's content swaps. Use this sparingly,
+folder-based layouts handle 99% of cases. When a frame nav's response
+lacks the matching `<webjs-frame id>` (e.g. an auth redirect), the router
+fires a cancelable, bubbling `webjs:frame-missing` event (detail
+`{ frameId, url, document }`) and leaves the frame unchanged rather than
+silently swapping the whole page; call `preventDefault()` to take over
+the outcome (e.g. `location.assign(e.detail.url)`).
 
 ### 5. `loading.ts` for per-segment skeletons
 

package/templates/Dockerfile

@@ -8,6 +8,14 @@
 # falls back to esbuild, whose class-declaration transform breaks webjs's SSR
 # walker for multi-class component files. Do not lower this base image
 # below 24 (the same version the CI workflow and the framework pin).
+#
+# Security headers are set by the framework, not the proxy. webjs emits
+# X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and
+# Permissions-Policy on every response, plus Strict-Transport-Security in
+# production over HTTPS (detected from X-Forwarded-Proto on the trusted
+# edge). So the baseline needs no reverse-proxy config. Override or extend
+# per path with package.json "webjs": { "headers": [...] }. See the
+# framework AGENTS.md "Secure response headers" section.
 FROM node:24-alpine
 
 # openssl + ca-certificates are required by Prisma's query engine at runtime.