@webjsdev/cli 0.10.50 → 0.10.52

package/templates/gallery/modules/file-storage/actions/store-upload.server.ts

@@ -1,21 +1,32 @@
-// 'use server' so the page's action can call it (server-side, a direct call) and
-// it never crashes the browser module that imports it (the client gets a safe
-// RPC stub, not the node:fs code). getFileStore() is the pluggable storage
-// singleton: a local diskStore rooted at <cwd>/.webjs/uploads by default
-// (gitignored), swappable for S3/R2/GCS with one setFileStore() call at boot.
-// generateKey() mints a collision-free, traversal-safe key preserving a
-// whitelisted extension.
 'use server';
+
+// The directive comes FIRST, ahead of this header: the framework reads it from
+// the file's first few lines, so a long comment block above it would push it
+// out of range and the file would not register as an action at all.
+//
+// The action the upload <form> is bound to. 'use server' means it never
+// crashes the browser module that imports it (the client gets a safe RPC stub,
+// not the node:fs code). getFileStore() is the pluggable storage singleton: a
+// local diskStore rooted at <cwd>/.webjs/uploads by default (gitignored),
+// swappable for S3/R2/GCS with one setFileStore() call at boot. generateKey()
+// mints a collision-free, traversal-safe key preserving a whitelisted
+// extension.
+//
+// It takes the FormData, which is what a form-bound action always receives, and
+// pulls the File out of it. The framework emits the multipart enctype the
+// upload needs, so a bound form carries a file with no extra attribute.
 import { getFileStore, generateKey } from '@webjsdev/server';
 // Importing the config module runs setFileStore(diskStore(...)) once at load,
 // so uploads land in the configured store. See ../store.server.ts.
 import '../store.server.ts';
 
-export async function storeUpload(file: File) {
+export async function storeUpload(formData: FormData) {
+  const file = formData.get('file');
   if (!(file instanceof File) || file.size === 0) {
-    return { success: false as const, error: 'No file provided.' };
+    return { success: false as const, error: 'Choose a file to upload.' };
   }
   const key = generateKey(file.name);
   const { size, contentType } = await getFileStore().put(key, file, { contentType: file.type });
-  return { success: true as const, data: { key, name: file.name, size, contentType } };
+  const q = new URLSearchParams({ key, name: file.name, size: String(size) });
+  return { success: true as const, redirect: '/features/file-storage?' + q.toString(), data: { key, name: file.name, size, contentType } };
 }

package/templates/gallery/modules/forms/actions/send-message.server.ts

@@ -0,0 +1,34 @@
+'use server';
+
+// The action a <form action=${sendMessage}> submits to. It receives the
+// FormData directly: a form-bound action always does, on the JS path and the
+// no-JS path alike.
+//
+// Return a FAILURE to re-render the SAME page at 422 with the result on
+// `actionData` (so the fields repopulate), or a SUCCESS with a same-site
+// `redirect` for a 303 Post-Redirect-Get.
+//
+// FOOTGUN: to redirect on success, RETURN `{ success: true, redirect: '/path' }`
+// (a 303 See Other, so the browser follows with a GET). Do NOT THROW `redirect()`
+// from a form action, that is a 307 which PRESERVES the POST method and body, so
+// the browser re-POSTs to the target and re-runs the mutation (a duplicate
+// write). Throw `redirect()` only from a page render / GET context.
+export interface Result {
+  success: boolean;
+  fieldErrors?: Record<string, string>;
+  values?: Record<string, string>;
+  redirect?: string;
+}
+
+export async function sendMessage(formData: FormData): Promise<Result> {
+  const name = String(formData.get('name') ?? '').trim();
+  const email = String(formData.get('email') ?? '').trim();
+  const message = String(formData.get('message') ?? '').trim();
+  const fieldErrors: Record<string, string> = {};
+  if (!name) fieldErrors.name = 'Your name is required.';
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) fieldErrors.email = 'A valid email is required.';
+  if (message.length < 5) fieldErrors.message = 'Message must be at least 5 characters.';
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values: { name, email, message } };
+  // A real app would persist / email here. We just confirm.
+  return { success: true, redirect: '/features/forms?sent=1' };
+}

package/templates/gallery/modules/gallery/nav.ts

@@ -29,7 +29,7 @@ export const FEATURE_GROUPS: NavGroup[] = [
     items: [
       { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, plus the HTTP-verb config exports that make a read a cached GET.' },
       { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the WebJs equivalent of a Next route handler.' },
-      { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
+      { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form bound to a server action, with server-side validation errors.' },
       { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
     ],
   },

package/templates/gallery/modules/server-actions/actions/greet.test.ts

@@ -13,7 +13,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createRequestHandler, buildRouteTable, matchPage, matchApi, invokeActionForTest } from '@webjsdev/server';
-import { testRequest, loginAndGetCookies } from '@webjsdev/server/testing';
+import { submitForm, loginAndGetCookies } from '@webjsdev/server/testing';
 
 const appDir = process.cwd();
 process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';
@@ -54,10 +54,11 @@ test('an authenticated greet reads the caller off the session via actionContext(
   // migrated (run db:generate + db:migrate) rather than fail misleadingly.
   const email = `greet+${Date.now()}@example.com`;
   const password = 'password123';
-  const signupRes = await testRequest(app.handle, '/features/auth/signup', {
-    method: 'POST',
-    headers: { 'content-type': 'application/x-www-form-urlencoded' },
-    body: new URLSearchParams({ name: 'Ada', email, password }).toString(),
+  // `submitForm` renders the signup page and reuses the identity the server put
+  // in the form's hidden `__webjs_action` field, which is what tells the
+  // dispatcher which action to run; a POST without it is answered 405.
+  const signupRes = await submitForm(app.handle, '/features/auth/signup', {
+    name: 'Ada', email, password,
   });
   if (signupRes.status !== 302) { t.skip('app deps/db not ready; run db:generate + db:migrate'); return; }
   const { cookies } = await loginAndGetCookies(app.handle, { email, password });

package/templates/gallery/modules/todo/actions/submit-todo.server.ts

@@ -0,0 +1,33 @@
+'use server';
+
+import { createTodo } from './create-todo.server.ts';
+import { toggleTodo } from './toggle-todo.server.ts';
+import { deleteTodo } from './delete-todo.server.ts';
+
+// The no-JS write path for the todo forms. Every <form> in <todo-app> binds
+// THIS action, and the submit button's own `name="intent"` says which mutation
+// to run, which is how one form serves several buttons.
+//
+// Why an intent dispatcher here rather than binding each button to its own
+// action: this form carries the todo's `id` on a hidden input and needs the
+// SAME id for whichever mutation runs, so one action reading both fields is the
+// simpler shape. When the buttons need no shared payload, bind each one
+// directly instead, with `formaction=${action}` on a <button>. The enclosing
+// <form> does NOT have to be bound: a bound submitter carries its own
+// `formmethod` and enctype, so it works in any form or none. The identity rides
+// that button's own name/value pair, so it works with JS off too. Two things to
+// know: it must be a <button> (on an
+// <input type="submit"> the identity would occupy `value`, which is also that
+// control's visible label), and a bound submitter cannot carry its own
+// `name`/`value`, which is exactly the channel `name="intent"` uses below.
+//
+// With JS the component intercepts the submit and calls the underlying action
+// directly for the optimistic path, so this runs only with JS off.
+export async function submitTodo(formData: FormData) {
+  const intent = String(formData.get('intent') ?? '');
+  const id = String(formData.get('id') ?? '');
+  if (intent === 'create') return createTodo({ title: String(formData.get('title') ?? '') });
+  if (intent === 'toggle') return toggleTodo({ id });
+  if (intent === 'delete') return deleteTodo({ id });
+  return { success: false as const, error: 'Unknown action.', status: 400 };
+}

package/templates/gallery/modules/todo/components/todo-app.ts

@@ -1,6 +1,6 @@
 // The interactive surface. Demonstrates: the WebComponent factory + reactive
 // prop, the DECLARATIVE optimistic() API (instant update, auto-rollback), and
-// progressive enhancement (each mutation is a <form> posting to the page action,
+// progressive enhancement (each mutation is a <form action=${submitTodo}> bound to a server action,
 // intercepted by JS for the optimistic path). All interactivity lives in a
 // component; a page/layout cannot be interactive in its own markup.
 //
@@ -17,6 +17,7 @@ import { cn } from '#lib/utils/cn.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
+import { submitTodo } from '../actions/submit-todo.server.ts';
 import type { Todo } from '../types.ts';
 
 type Op =
@@ -95,9 +96,9 @@ export class TodoApp extends WebComponent({
           </div>
         </header>
 
-        <!-- Add: a real <form> so it works with JS off (posts to the page action);
-             with JS, @submit intercepts and runs the optimistic path. -->
-        <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
+        <!-- Add: a real <form> bound to the server action, so it works with JS
+             off; with JS, @submit intercepts and runs the optimistic path. -->
+        <form action=${submitTodo} @submit=${(e: SubmitEvent) => this.add(e)}
           class="${cardClass()} flex items-center gap-2 p-2 pl-4 shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
@@ -109,7 +110,9 @@ export class TodoApp extends WebComponent({
         <ul class="list-none m-0 p-0 grid gap-2">
           ${list.length ? list.map((todo) => html`
             <li>
-              <form method="post" action=""
+              <!-- One form, two submit buttons: each carries its own
+                   name="intent", which the bound action dispatches on. -->
+              <form action=${submitTodo}
                 class="group flex items-center gap-3 px-3 py-2.5 rounded-xl bg-card border border-border transition-colors hover:border-border-strong ${todo.pending ? 'opacity-55' : ''}">
                 <input type="hidden" name="id" value=${todo.id} />
                 <!-- Toggle is a submit button (degrades to a form POST no-JS); with JS

package/templates/gallery/modules/todo/types.ts

@@ -1,12 +1,17 @@
-// WHY a hand-written interface (not `typeof todos.$inferSelect` from the schema):
-// this type is imported by the browser-shipped <todo-app> component. A VALUE
-// import from `db/*.server.ts` would pin the component to a server module and
-// crash it at load (webjs check flags it). A browser-safe shape here is safe.
-// See the server-actions section in this app's AGENTS.md.
-export interface Todo {
-  id: string;
-  title: string;
-  completed: boolean;
-  createdAt: Date;
+// The row shape is DERIVED from the schema, never re-declared: rename a column
+// in db/schema.server.ts and every consumer of this type is a compile error
+// instead of a silent `undefined` at runtime.
+//
+// `import type` is what makes that safe here. This type is imported by the
+// browser-shipped <todo-app> component, and a VALUE import from a
+// `db/*.server.ts` file would pin the component to a server module and crash it
+// at load (webjs check's no-server-import-in-browser-module flags it). A
+// type-only import is erased by the TypeScript stripper before it can reach the
+// browser, so it is exempt from that rule and costs the client nothing.
+import type { todos } from '#db/schema.server.ts';
+
+type TodoRow = typeof todos.$inferSelect;
+
+export interface Todo extends TodoRow {
   pending?: boolean; // client-only: true while an optimistic create is in flight
 }

package/templates/gallery/test/auth/auth.test.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 
 import { createRequestHandler } from '@webjsdev/server';
-import { testRequest, loginAndGetCookies, withSessionCookie } from '@webjsdev/server/testing';
+import { testRequest, submitForm, loginAndGetCookies, withSessionCookie } from '@webjsdev/server/testing';
 
 const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -14,7 +14,11 @@ const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 // we detect that at the RESPONSE level (a 5xx on the dashboard) and SKIP with a
 // clear message rather than report a misleading failure. After the db is set up
 // every assertion runs for real.
-process.env.DATABASE_URL ||= 'file:./dev.db';
+// The SAME path `.env.example` and `drizzle.config.ts` use, so `db:migrate`
+// prepares the database this test connects to. Pointing somewhere else made the
+// skip below permanent: it told you to run `db:migrate`, and running it
+// migrated a different file.
+process.env.DATABASE_URL ||= 'file:./db/dev.db';
 process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';
 
 function makeHandler() {
@@ -47,24 +51,35 @@ test('signup -> login -> dashboard renders for the authenticated user', async (t
   const email = `harness+${Date.now()}@example.com`;
   const password = 'password123';
 
-  // Real signup through the page server action (the no-JS form write-path).
-  let canSignup = true;
+  // Real signup through the bound server action (the no-JS form write-path).
+  // `submitForm` renders the page and reuses the identity the server put in the
+  // form's hidden field, exactly as a browser with JS off submits it; a POST
+  // without that field is not a form submission and is answered 405.
+  // Only the REQUEST is guarded: an unmigrated table makes the action throw, and
+  // that is the one condition worth skipping for. The assertions below stay
+  // outside the try on purpose, so a genuine regression fails loudly instead of
+  // being caught and reported as a database that was never set up.
+  let signupRes: Response | null = null;
   try {
-    const signupRes = await testRequest(app.handle, '/features/auth/signup', {
-      method: 'POST',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body: new URLSearchParams({ name: 'Harness', email, password }).toString(),
+    signupRes = await submitForm(app.handle, '/features/auth/signup', {
+      name: 'Harness', email, password,
     });
-    // Success auto-logs-in and 302s to the dashboard (carrying the session
-    // cookie); a 422 means validation failed. Either way the action ran.
-    assert.ok([302, 422].includes(signupRes.status), 'signup action ran');
-    if (signupRes.status === 302) assert.equal(signupRes.headers.get('location'), '/features/auth/dashboard', 'signup lands on the dashboard');
-    if (signupRes.status !== 302) canSignup = false;
   } catch {
-    // No migrated DB table -> the action throws. Skip the DB-backed assertions.
-    canSignup = false;
+    signupRes = null;
+  }
+  if (!signupRes || signupRes.status >= 500) {
+    t.skip('no migrated DB; run db:migrate to enable the full flow');
+    return;
+  }
+  // Success auto-logs-in and 302s to the dashboard (carrying the session
+  // cookie); a 422 means validation failed. Either way the action ran.
+  assert.ok([302, 422].includes(signupRes.status), 'signup action ran');
+  if (signupRes.status === 302) {
+    assert.equal(signupRes.headers.get('location'), '/features/auth/dashboard', 'signup lands on the dashboard');
+  } else {
+    t.skip('signup was rejected by validation; run db:migrate to enable the full flow');
+    return;
   }
-  if (!canSignup) { t.skip('no migrated DB; run db:migrate to enable the full flow'); return; }
 
   // Real login captures the genuine signed session cookie.
   const { cookies } = await loginAndGetCookies(app.handle, { email, password });

package/templates/partials/agents-playbook-api.md

@@ -47,6 +47,10 @@ cross-origin access use the `cors()` middleware from `@webjsdev/server`; with
 Run each of these and fix what it reports, in order:
 
 - `npm run check` (correctness: no browser-import or boundary violation).
+- `npm run doctor` (project health; CI runs it too). It fails on whatever
+  `package.json` `webjs.doctor.gate` marks `error`, plus the two hard toolchain
+  checks that are fatal with no gate entry, `NODE_VERSION` and
+  `TSCONFIG_ERASABLE`.
 - `npm run typecheck` (zero type errors).
 - `npm test` (unit tests for the endpoints and modules you built).
 
@@ -63,5 +67,6 @@ npm run start           # production server
 npm test                # unit + browser tests
 npm run typecheck
 npm run check           # correctness checks
+npm run doctor          # project health (severity per check: webjs.doctor.gate)
 npm run db:generate && npm run db:migrate
 ```

package/templates/partials/agents-playbook-fullstack.md

@@ -98,6 +98,10 @@ accessor). Use the shorthand for primitives
 Run each of these and fix what it reports, in order:
 
 - `npm run check` (correctness: no browser-import or boundary violation).
+- `npm run doctor` (project health; CI runs it too). It fails on whatever
+  `package.json` `webjs.doctor.gate` marks `error`, plus the two hard toolchain
+  checks that are fatal with no gate entry, `NODE_VERSION` and
+  `TSCONFIG_ERASABLE`.
 - `npm run typecheck` (zero type errors).
 - `npm test` (unit and browser tests for the features you built).
 - `npm run css:build` (compile Tailwind).
@@ -118,6 +122,7 @@ npm test                     # unit + browser tests
 npm run typecheck
 npm run css:build            # compile Tailwind
 npm run check                # correctness checks
+npm run doctor               # project health (severity per check: webjs.doctor.gate)
 npx webjsdev ui add <name>   # copy a ui primitive into components/ui/
 npx webjsdev ui view <name>  # inspect a primitive's exact signature
 npm run db:generate && npm run db:migrate

package/templates/scripts/clear-gallery.mjs

@@ -79,9 +79,9 @@ const galleryPaths = [
 // query), pruned with the rest of the card.
 const galleryModules = [
   'async-render', 'auth', 'broadcast', 'caching', 'client-router', 'components',
-  'directives', 'file-storage', 'frames', 'gallery', 'optimistic-ui', 'rate-limit',
-  'route-handler', 'server-actions', 'sessions', 'stream', 'streaming', 'suspense',
-  'todo', 'websockets',
+  'directives', 'file-storage', 'forms', 'frames', 'gallery', 'optimistic-ui',
+  'rate-limit', 'route-handler', 'server-actions', 'sessions', 'stream',
+  'streaming', 'suspense', 'todo', 'websockets',
 ].map((m) => `modules/${m}`);
 
 let removed = 0;
@@ -174,6 +174,7 @@ export default function Home() {
 
 function MINIMAL_LAYOUT() {
   return `import { html, asset } from '@webjsdev/core';
+import type { LayoutProps } from '@webjsdev/core';
 
 /**
  * Root layout: the ONLY file that writes the document shell. It links the
@@ -191,7 +192,7 @@ function MINIMAL_LAYOUT() {
 // hand-written <link> in the template body is ignored by browsers).
 export const metadata = { icons: '/public/favicon.svg' };
 
-export default function RootLayout({ children }: { children: unknown }) {
+export default function RootLayout({ children }: LayoutProps) {
   return html\`
     <meta name="color-scheme" content="light dark">
     <!-- asset() content-hashes the url in production, so a deploy that changes

package/templates/test/hello/e2e/hello.test.ts

@@ -12,9 +12,26 @@
 import { test, describe, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
 import { createServer } from 'node:net';
 
-let browser: any, page: any, serverProcess: any, baseUrl: string;
+// puppeteer-core is an optional dev dependency, so `import type { Browser,
+// Page } from 'puppeteer-core'` does not resolve until you install it. These
+// minimal structural types keep the file typed in the meantime; swap them for
+// the real imports once puppeteer-core is in package.json. Reaching for `any`
+// here would silently un-type every call below.
+type Page = {
+  // goto resolves an HTTPResponse this file never reads, and modelling that
+  // type would mean re-declaring puppeteer's. Returning void is the honest
+  // narrow shape for the surface actually used.
+  goto(url: string, opts?: { waitUntil?: string; timeout?: number }): Promise<void>;
+  title(): Promise<string>;
+  on(event: string, handler: (e: Error) => void): void;
+  removeAllListeners(event: string): void;
+};
+type Browser = { newPage(): Promise<Page>; close(): Promise<void> };
+
+let browser: Browser, page: Page, serverProcess: ChildProcess, baseUrl: string;
 
 function freePort(): Promise<number> {
   return new Promise((resolve, reject) => {