@webjsdev/server 0.8.91 → 0.9.0

package/index.d.ts

@@ -573,6 +573,47 @@ export interface ElisionReport {
  */
 export declare function analyzeAppElision(appDir: string): Promise<ElisionReport>;
 
+// ---------------------------------------------------------------------------
+// dev-regenerate.js (#967, #1672)
+// ---------------------------------------------------------------------------
+
+/**
+ * Where a `webjs.dev.regenerate` output stands against the build record in
+ * `.webjs/regenerate.json`: `fresh` (built by this rule's command from inputs
+ * that have not changed since, and not rewritten since), `stale`, `missing`
+ * (no output on disk), or `unrecorded` (an output no recorded build produced,
+ * such as one compiled by hand).
+ */
+export type RegenerateState = 'fresh' | 'stale' | 'missing' | 'unrecorded';
+
+/** One rule's outcome from `regenerateOutputs`. */
+export type RegenerateResult = { output: string; state: RegenerateState; built: boolean } & (
+  | { ok: true }
+  | { ok: false; reason: 'failed' | 'no-output' }
+);
+
+/**
+ * Build every `webjs.dev.regenerate` output that is not fresh, one at a time,
+ * and record what each was built from (#1672). The engine behind
+ * `webjs regenerate`, which an app runs in `dev.before` / `start.before` so a
+ * build outside the dev server records freshness the way a dev request does.
+ * A rule whose command fails, or exits 0 without writing its `output`, keeps
+ * its previous output and is reported `ok: false`.
+ */
+export declare function regenerateOutputs(
+  appDir: string,
+  opts?: { force?: boolean; warn?: (message: string) => void },
+): Promise<RegenerateResult[]>;
+
+/**
+ * Every `webjs.dev.regenerate` output's state against the build record,
+ * building nothing. What `webjs doctor` reads, so it and the dev server share
+ * one definition of fresh.
+ */
+export declare function regenerateStatus(
+  appDir: string,
+): Promise<Array<{ output: string; command: string; state: RegenerateState }>>;
+
 // ---------------------------------------------------------------------------
 // elision-differential.js (#1308)
 // ---------------------------------------------------------------------------

package/index.js

@@ -44,6 +44,7 @@ export {
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';
 export { analyzeAppElision } from './src/elision-report.js';
+export { regenerateOutputs, regenerateStatus } from './src/dev-regenerate.js';
 export { maskJsSet, staticPageRoutes } from './src/elision-differential.js';
 export { headers, cookies, getRequest, withRequest, cspNonce, requestId } from './src/context.js';
 export { defaultLogger } from './src/logger.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.91",
+  "version": "0.9.0",
   "type": "module",
   "description": "The server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Provides the file-based router, SSR, server actions, route handlers, middleware, and live reload on Node 24+ or Bun.",
   "main": "index.js",
@@ -55,9 +55,9 @@
     "amaro": "^1.1.10"
   },
   "peerDependencies": {
-    "@webjsdev/core": "^0.7.51"
+    "@webjsdev/core": "^0.8.0"
   },
   "devDependencies": {
-    "@webjsdev/core": "^0.7.51"
+    "@webjsdev/core": "^0.8.0"
   }
 }

package/src/action-input.js

@@ -0,0 +1,208 @@
+/**
+ * The input shape a server action receives from a form submission.
+ *
+ * A `'use server'` action is reachable three ways, and before this module each
+ * handed it a different first argument: the deserialized arguments over RPC, a
+ * merged plain object through the `route()` adapter, and a raw `FormData` from
+ * a bound `<form action=${fn}>`. A validator written for the RPC shape
+ * (`input.title`) read `undefined` off the `FormData` and answered every form
+ * submission with a 422, while `webjs check` and typecheck both passed.
+ *
+ * `formInput` returns a `FormInput`: a real `FormData` (so `instanceof
+ * FormData`, the readers, the writers and `fetch(url, { body: input })` all
+ * behave as they always did) that ALSO carries every submitted field as an own
+ * enumerable property, so `input.title`, destructuring, spreading and a schema
+ * library's `parse(input)` read it like the plain object RPC delivers. Next
+ * and TanStack Start hand an action a `FormData`; this keeps that and adds the
+ * property view the RPC shape needs, so neither set of habits breaks.
+ *
+ *   - A property holds the field's LAST value (the `Object.fromEntries`
+ *     semantics). A name ending in `[]` collects every value into an array
+ *     under the name without the brackets, the convention Rails' parameter
+ *     builder uses for a checkbox group. A `File` stays a real `File`.
+ *   - `get`, `getAll` and `has` also accept the bracket-less name, so
+ *     `input.getAll('tags')` reads a `tags[]` group and agrees with
+ *     `input.tags`. Iteration (`entries`, `keys`, `values`, `forEach`,
+ *     `Object.fromEntries(input)`) reports names as SUBMITTED, brackets
+ *     included, like any `FormData`.
+ *   - A name submitted both plain and with `[]` (`x=1&x[]=2`) is one array
+ *     group, so nothing is dropped. Rails rejects that shape as a parameter
+ *     type error, so dev warns once about it.
+ *   - The writers (`append`, `set`, `delete`) keep the property in step.
+ *
+ * Fields are defined with `Object.defineProperty`, never assigned, so a field
+ * named `__proto__` becomes an own data property instead of reaching the
+ * prototype setter. A field that shares a method's name wins as data on the
+ * instance: the data is what the author named.
+ *
+ * @module
+ */
+
+/** Names already warned about, so a repeated name warns once per process. */
+const warned = new Set();
+
+/**
+ * A `FormData` whose submitted fields are also own enumerable properties.
+ * Built only by `formInput`.
+ */
+class FormInput extends FormData {
+  /**
+   * @param {string} name
+   * @returns {FormDataEntryValue | null}
+   */
+  get(name) {
+    if (super.has(name)) return super.get(name);
+    const alias = arrayName(name);
+    return alias && super.has(alias) ? super.get(alias) : null;
+  }
+
+  /**
+   * @param {string} name
+   * @returns {FormDataEntryValue[]}
+   */
+  getAll(name) {
+    const alias = arrayName(name);
+    return alias ? [...super.getAll(name), ...super.getAll(alias)] : super.getAll(name);
+  }
+
+  /** @param {string} name */
+  has(name) {
+    const alias = arrayName(name);
+    return super.has(name) || (!!alias && super.has(alias));
+  }
+
+  /**
+   * @param {string} name
+   * @param {string | Blob} value
+   * @param {string} [filename]
+   */
+  append(name, value, filename) {
+    if (filename === undefined) super.append(name, /** @type {any} */ (value));
+    else super.append(name, /** @type {Blob} */ (value), filename);
+    syncField(this, name);
+  }
+
+  /**
+   * @param {string} name
+   * @param {string | Blob} value
+   * @param {string} [filename]
+   */
+  set(name, value, filename) {
+    if (filename === undefined) super.set(name, /** @type {any} */ (value));
+    else super.set(name, /** @type {Blob} */ (value), filename);
+    syncField(this, name);
+  }
+
+  /** @param {string} name */
+  delete(name) {
+    super.delete(name);
+    syncField(this, name);
+  }
+}
+
+/**
+ * Convert a submitted `FormData` into the action input.
+ *
+ * @param {FormData} formData
+ * @param {{ warn?: (message: string) => void, label?: string, omit?: string }} [opts]
+ *   `warn` is passed in dev only: it reports a plain name submitted more than
+ *   once (its property keeps only the last value) and a name submitted under
+ *   both spellings. `label` names the action in that message and keys the
+ *   once-per-process dedupe. `omit` is a field to leave out (the framework's
+ *   own `__webjs_action` identity).
+ * @returns {FormData & Record<string, FormDataEntryValue | FormDataEntryValue[]>}
+ */
+export function formInput(formData, opts = {}) {
+  const input = new FormInput();
+  /** @type {Map<string, number>} */
+  const counts = new Map();
+  /** @type {Set<string>} */
+  const plain = new Set();
+  for (const [name, value] of formData.entries()) {
+    if (name === opts.omit) continue;
+    FormData.prototype.append.call(input, name, value);
+    const key = isArrayName(name) ? name.slice(0, -2) : name;
+    counts.set(key, (counts.get(key) || 0) + 1);
+    if (!isArrayName(name)) plain.add(name);
+  }
+  for (const key of counts.keys()) syncField(input, key);
+
+  if (typeof opts.warn === 'function') {
+    for (const [key, n] of counts) {
+      const grouped = FormData.prototype.has.call(input, key + '[]');
+      let message = null;
+      if (grouped && plain.has(key)) {
+        message = `[webjs] the form field "${key}" was submitted both as "${key}" and as "${key}[]"${opts.label ? ` to ${opts.label}` : ''}, `
+          + `so input.${key} holds every value as one array. Give the controls one spelling, "${key}[]" for a group.`;
+      } else if (!grouped && n > 1) {
+        message = `[webjs] the form field "${key}" was submitted ${n} times${opts.label ? ` to ${opts.label}` : ''}, `
+          + `so input.${key} holds only the last value. Name the controls "${key}[]" to receive an array `
+          + `as input.${key}, or read every value with input.getAll('${key}').`;
+      }
+      if (!message) continue;
+      const warnKey = `${opts.label || ''}\u0000${key}`;
+      if (warned.has(warnKey)) continue;
+      warned.add(warnKey);
+      opts.warn(message);
+    }
+  }
+
+  return /** @type {any} */ (input);
+}
+
+/**
+ * True for a real `FormData` that `formInput` has not converted yet.
+ * @param {unknown} value
+ */
+export function isFormData(value) {
+  return typeof FormData !== 'undefined' && value instanceof FormData && !(value instanceof FormInput);
+}
+
+/**
+ * Recompute the property for the field a submitted name belongs to, from the
+ * entries currently in the form: an array when the name ever arrived as `[]`,
+ * else the last value, else no property at all.
+ * @param {FormInput} input
+ * @param {string} name a submitted name, with or without `[]`
+ */
+function syncField(input, name) {
+  const key = isArrayName(name) ? name.slice(0, -2) : name;
+  const own = FormData.prototype.getAll.call(input, key);
+  if (FormData.prototype.has.call(input, key + '[]')) {
+    // Plain and bracketed entries in submission order, so a mixed form keeps
+    // every value in the order the browser sent it.
+    /** @type {FormDataEntryValue[]} */
+    const values = [];
+    for (const [n, v] of FormData.prototype.entries.call(input)) if (n === key || n === key + '[]') values.push(v);
+    define(input, key, values);
+  } else if (own.length) {
+    define(input, key, own[own.length - 1]);
+  } else if (Object.prototype.hasOwnProperty.call(input, key)) {
+    delete /** @type {any} */ (input)[key];
+  }
+}
+
+/**
+ * True for a submitted name in the array form (`tags[]`).
+ * @param {string} name
+ */
+function isArrayName(name) {
+  return name.length > 2 && name.endsWith('[]');
+}
+
+/**
+ * The `[]` spelling of a bracket-less name, or null for a name already in it.
+ * @param {string} name
+ */
+function arrayName(name) {
+  return isArrayName(name) ? null : name + '[]';
+}
+
+/**
+ * @param {object} target
+ * @param {string} key
+ * @param {unknown} value
+ */
+function define(target, key, value) {
+  Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}

package/src/actions.js

@@ -19,8 +19,9 @@ import { ifNoneMatchSatisfied } from './conditional-get.js';
 import { getBodyLimits } from './context.js';
 import { basePath } from './importmap.js';
 import { withBasePath } from './base-path.js';
-import { FORM_ACTION_ID_KEY } from '@webjsdev/core';
+import { FORM_ACTION_ID_KEY, FORM_ACTION_FIELD } from '@webjsdev/core';
 import { devImport } from './dev-import.js';
+import { formInput, isFormData } from './action-input.js';
 
 /**
  * The JSON / RPC body cap in effect for the current request: the per-request
@@ -447,8 +448,11 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
  *   it so a throwing sink can never affect the response.
  * @param {string[]} [allowedOrigins] cross-site origins the CSRF check allows
  *   (the app's `webjs.allowedOrigins`), for reverse-proxy / multi-domain setups.
+ * @param {{ warn?: (msg: string) => void }} [logger] where a dev diagnostic
+ *   goes (the repeated-field warning, #1664), so it lands with the form path's
+ *   warnings instead of on the console. Falls back to `console.warn`.
  */
-export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigins = []) {
+export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigins = [], logger) {
   const file = idx.hashToFile.get(hash);
   if (!file) return rpcResponse({ error: 'Unknown action' }, { status: 404 });
   const mod = await loadModule(file, idx.dev);
@@ -496,6 +500,17 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
   } catch {
     return rpcResponse({ error: 'Invalid request body' }, { status: 400 });
   }
+  // A FormData first argument (the serializer round-trips one) gets the same
+  // shape a bound form submission does, so an action's input never depends on
+  // the boundary it was reached through (#1664, `action-input.js`). It stays a
+  // real FormData, so a caller that built one keeps every FormData behaviour.
+  // A component that intercepts a bound form and passes `new FormData(form)`
+  // carries the framework's hidden identity field, which the form path removes
+  // before the action runs; it is removed here too.
+  if (isFormData(args[0])) {
+    const warn = logger && logger.warn ? (m) => logger.warn(m) : (m) => console.warn(m);
+    args = [formInput(args[0], { omit: FORM_ACTION_FIELD, ...(idx.dev ? { warn, label: fnName } : {}) }), ...args.slice(1)];
+  }
   // Input validation (#245): a validator declared via the `validate` config
   // export (#488) runs SERVER-SIDE before the body on this RPC path. The RPC
   // stub sends an args array; an action conventionally takes one input object,

package/src/check/helpers.js

@@ -179,6 +179,91 @@ const HTMLELEMENT_MEMBERS = [
   'focus', 'blur', 'scrollIntoView',
 ];
 
+/**
+ * Writes to a signal field of a WebComponent class body: any `this.<name>`
+ * assignment (plain, compound, `++` / `--`) where `<name>` is a field the same
+ * class creates with `signal(` / `computed(`, either as a class-field
+ * initializer (`readonly #open = signal(false)`) or in the constructor
+ * (`this.open = signal(false)`). That creation is the one write allowed.
+ * Assigning to the field replaces the signal object: the component stays
+ * subscribed to the old one, so nothing re-renders, and the next `.get()`
+ * throws. Expects the redacted body (strings and template text blanked,
+ * holes kept).
+ *
+ * @param {string} body
+ * @returns {string[]} the offending field names, each once, `#` kept
+ */
+export function findSignalFieldWrites(body) {
+  const MAKE = String.raw`(?:signal|computed)\s*(?:<[^()]*>)?\s*\(`;
+  // Brace depth at each index, so a field initializer counts only at the
+  // class body's own level.
+  const depth = new Int32Array(body.length + 1);
+  for (let i = 0, d = 0; i < body.length; i++) {
+    if (body[i] === '{') d++;
+    else if (body[i] === '}') d--;
+    depth[i + 1] = d;
+  }
+  const fields = new Set();
+  // Find each class-level `= signal(` / `= computed(`, then read the field
+  // name from the start of its member, so a type annotation of any shape
+  // (`Signal<{ open: boolean }>`, `Signal<() => void>`, one spanning lines)
+  // sits in between.
+  const make = new RegExp(String.raw`(?<![=!<>])=(?!=)\s*` + MAKE, 'g');
+  const head = /^\s*((?:(?:public|private|protected|readonly|static|declare|override)\s+)*)(#?[A-Za-z_$][\w$]*)/;
+  let m;
+  while ((m = make.exec(body))) {
+    if (depth[m.index] !== 0) continue;
+    const h = head.exec(body.slice(memberStart(body, m.index), m.index));
+    if (h && !/\bstatic\s/.test(h[1])) fields.add(h[2]);
+  }
+  const ctor = methodBodyOf(body, 'constructor');
+  const made = new RegExp(String.raw`this\.(#?[A-Za-z_$][\w$]*)\s*=\s*` + MAKE, 'g');
+  const created = new Set();
+  while ((m = made.exec(ctor))) { fields.add(m[1]); created.add(m.index); }
+  if (!fields.size) return [];
+  const bad = new Set();
+  const write = /this\.(#?[A-Za-z_$][\w$]*)\s*(?:(\+\+|--)|(?:[-+*\/%]|\*\*|\|\||&&|\?\?|<<|>>>?|[&|^])?=(?![=>]))|(?:\+\+|--)\s*this\.(#?[A-Za-z_$][\w$]*)/g;
+  const ctorStart = ctor ? body.indexOf(ctor) : -1;
+  while ((m = write.exec(body))) {
+    const name = m[1] || m[3];
+    if (!fields.has(name)) continue;
+    // The creation in the constructor is the one allowed write.
+    if (ctorStart !== -1 && m.index >= ctorStart && m.index < ctorStart + ctor.length && created.has(m.index - ctorStart)) continue;
+    bad.add(name);
+  }
+  return [...bad];
+}
+
+/**
+ * Index where the class member holding `end` starts: just past the previous
+ * `;`, line break, or method body, skipping any of those nested inside
+ * brackets (a type annotation can hold all three).
+ * @param {string} body
+ * @param {number} end
+ * @returns {number}
+ */
+function memberStart(body, end) {
+  let nest = 0;
+  for (let i = end - 1; i >= 0; i--) {
+    const c = body[i];
+    if (c === '>' && body[i - 1] === '=') { i--; continue; }
+    if (c === ')' || c === ']' || c === '}' || c === '>') {
+      // A method body ends the previous member: `m() { ... } x = signal(0)`.
+      if (c === '}' && nest === 0) {
+        let j = i - 1;
+        for (let d = 1; j >= 0 && d; j--) d += body[j] === '}' ? 1 : body[j] === '{' ? -1 : 0;
+        if (/\)\s*$/.test(body.slice(0, j + 1))) return i + 1;
+      }
+      nest++;
+    } else if (c === '(' || c === '[' || c === '{' || c === '<') {
+      nest--;
+    } else if (nest === 0 && (c === ';' || c === '\n')) {
+      return i + 1;
+    }
+  }
+  return 0;
+}
+
 /**
  * Extract the body text of a named method from a (redacted) class body, or
  * '' if absent. Handles `async`, a TS return-type annotation, and params.

package/src/check/rules-components.js

@@ -10,8 +10,8 @@ import {
   extractWebComponentClassBodies, matchClosingBrace, parsePropEntries,
 } from '../js-scan.js';
 import {
-  isComponentFile, arrayPropUsesObject, findFieldInitializers, methodBodyOf,
-  findBrowserMemberUses,
+  isComponentFile, arrayPropUsesObject, findFieldInitializers,
+  findSignalFieldWrites, methodBodyOf, findBrowserMemberUses,
 } from './helpers.js';
 
 /**
@@ -88,6 +88,37 @@ export function checkNoStaticProperties(files, violations) {
   }
 }
 
+/**
+ * Rule: `no-signal-field-assignment`.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkNoSignalFieldAssignment(files, violations) {
+  // --- Rule: no-signal-field-assignment ---
+  // A signal field is written through `.set()`, never by assignment, which
+  // swaps the signal object out from under the component (#1679). TypeScript
+  // `readonly` catches this where tsc runs; this rule covers plain `.js` and a
+  // forgotten `readonly`. It only sees writes inside the declaring class,
+  // which for a `#private` field is every write there can be.
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+(?:\s*<[^{}();]*?>)?\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        for (const name of findSignalFieldWrites(body)) {
+          violations.push({
+            rule: 'no-signal-field-assignment',
+            file: rel,
+            message: `\`this.${name}\` holds a signal and is assigned to. Assignment replaces the signal object: the component stays subscribed to the old one, nothing re-renders, and the next \`.get()\` throws.`,
+            fix: `Write through the signal: \`this.${name}.set(value)\` (or \`this.${name}.set(this.${name}.get() + 1)\` for a counter), and declare the field \`readonly\` in TypeScript so the compiler catches the next one.`,
+          });
+        }
+      }
+    }
+  }
+}
+
 /**
  * Rule: `reactive-props-no-class-field`.
  *

package/src/check/rules.js

@@ -46,6 +46,11 @@ export const RULES = [
     description:
       'Reactive properties must be declared via the `extends WebComponent({ … })` factory, never a hand-written `static properties = { … }` field in the class body. The factory types each field for you (no `declare` needed) and the runtime throws on a direct `static properties`. Migrate `class X extends WebComponent { static properties = { count: { type: Number } } }` to `class X extends WebComponent({ count: Number })`; use the `prop()` helper for options (`prop(Number, { reflect: true })`) and set defaults in the constructor after super().',
   },
+  {
+    name: 'no-signal-field-assignment',
+    description:
+      'A field a WebComponent class creates with `signal(` / `computed(` (a class-field initializer like `readonly #open = signal(false)`, or `this.open = signal(false)` in the constructor) is written through `.set()`, never assigned. `this.open = true` replaces the signal object: the component stays subscribed to the old signal, nothing re-renders, and the next `this.open.get()` throws. Fix: `this.open.set(true)`. Declare signal fields `readonly` in TypeScript so the compiler catches it too; this rule covers plain `.js` and a forgotten `readonly`, for writes inside the declaring class.',
+  },
   {
     name: 'reactive-props-no-class-field',
     description:

package/src/check/runner.js

@@ -7,6 +7,7 @@ import {
 import {
   checkComponentsHaveRegister,
   checkNoStaticProperties,
+  checkNoSignalFieldAssignment,
   checkReactivePropsNoClassField,
   checkArrayPropUsesArrayType,
   checkNoBrowserGlobalsInRender,
@@ -90,6 +91,7 @@ export async function checkConventions(appDir) {
 
   checkComponentsHaveRegister(files, violations);
   checkNoStaticProperties(files, violations);
+  checkNoSignalFieldAssignment(files, violations);
   checkReactivePropsNoClassField(files, violations);
   checkArrayPropUsesArrayType(files, violations);
   checkNoBrowserGlobalsInRender(files, violations);