@ashley-shrok/viewmodel-shell 0.16.0 → 1.1.0

package/dist/server.d.ts

@@ -1,15 +1,29 @@
 import type { ViewNode, ShellSideEffect } from "./index.js";
 export * from "./index.js";
+/**
+ * Walk a ViewNode tree and assert that every dispatch-bearing action name names
+ * exactly one operation. Two occurrences are considered "the same operation"
+ * iff they share the same enclosing FormNode reference; otherwise a duplicate
+ * action name is a violation.
+ *
+ * Call this from your GET handler before returning the initial response if you
+ * want the same protection at initial-load time — the action-handler wrapper
+ * (`createAction`) calls it automatically on every response that carries `vm`.
+ *
+ * @throws Error when a violation is found. The message names the colliding
+ *   action and suggests the two fixes (rename one node, or move both into the
+ *   same enclosing form).
+ */
+export declare function validateActionNames(vm: ViewNode): void;
 export interface ActionPayload<TState> {
     name: string;
-    context: Record<string, unknown> | null;
     state: TState;
     /** Populated only on multipart submissions (FormData). Empty for JSON bodies. */
     files: Record<string, File>;
 }
 /** Parse a multipart/form-data action body — the wire format the TypeScript shell uses. */
 export declare function parseFormDataAction<TState>(formData: FormData): ActionPayload<TState>;
-/** Parse a flat JSON action body — { name, context, state }. For curl/agent callers. */
+/** Parse a flat JSON action body — `{name, state}`. For curl/agent callers. */
 export declare function parseJsonAction<TState>(body: string | object): ActionPayload<TState>;
 /** What an action handler returns. All fields are optional — see ShellResponse reference in AGENTS.md. */
 export interface ShellResponseBody<TState> {
@@ -43,6 +57,63 @@ export declare const shellSideEffect: {
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url: string, filename?: string) => ShellSideEffect;
 };
+/**
+ * Thrown by an action handler to signal a malformed/invalid request. The
+ * createAction wrapper catches this and returns a 400 with the error
+ * message in the body, matching the .NET twin's BadRequest("...") path.
+ * Reserved for "structurally invalid request the user can't see" (missing
+ * required action field, etc.) — NOT for routine app validation (that stays
+ * state-based per gotcha #4). No `code` is set on the wire entry (D-08).
+ */
+export declare class BadRequestError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown by an action handler to signal that the dispatched action name is
+ * not recognised. The createAction wrapper catches this and returns a 400
+ * with `code: "unknown_action"` in the envelope, allowing agents to distinguish
+ * "I sent a name your tree doesn't expose" from "your handler crashed."
+ *
+ * Usage — add a default arm to your dispatch switch:
+ *   default: throw new UnknownActionError(payload.name);
+ *
+ * Mirrors .NET `UnknownActionException` — both backends use the same wire code.
+ */
+export declare class UnknownActionError extends Error {
+    /** The offending action name sent by the client. */
+    readonly actionName: string;
+    constructor(actionName: string);
+}
+/**
+ * The entry shape inside the `errors[]` array of an `ok: false` envelope.
+ * `path` and `code` are optional — absent (not null) when not applicable,
+ * per the WhenWritingNull / conditional-spread null-omission contract.
+ */
+export interface ErrorEntry {
+    path?: string;
+    message: string;
+    code?: string;
+}
+/**
+ * Stable, framework-only error code vocabulary. Apps MUST NOT set these —
+ * the framework sets `code` on framework-detected failures only. Agents
+ * that want generic handling check `ok`; agents that want to branch by
+ * failure class check `code` against these constants.
+ *
+ * D-03 lock: "small, stable, framework-only set."
+ */
+export declare const ERR_CODES: {
+    /** Malformed / unparseable request body. HTTP 400. */
+    readonly PARSE: "parse_error";
+    /** App threw `UnknownActionError` (action name not recognised). HTTP 400. */
+    readonly UNKNOWN_ACTION: "unknown_action";
+    /** Built view tree violates the action-name uniqueness rule. HTTP 500. */
+    readonly INVALID_TREE: "invalid_tree";
+    /** App handler threw an unrecognised exception. HTTP 500. */
+    readonly UNCAUGHT: "uncaught_exception";
+};
+/** Union type of the framework error codes from ERR_CODES. Useful for narrowing `errors[0].code`. */
+export type ErrCode = typeof ERR_CODES[keyof typeof ERR_CODES];
 /**
  * Web Fetch API–native request handler factory. Auto-detects content-type
  * (application/json vs multipart/form-data), parses the body, calls your

package/dist/server.js

@@ -8,6 +8,172 @@
 // Re-export the ViewNode hierarchy and wire types so a backend can import
 // everything it needs from one place.
 export * from "./index.js";
+/**
+ * Walk a ViewNode tree and assert that every dispatch-bearing action name names
+ * exactly one operation. Two occurrences are considered "the same operation"
+ * iff they share the same enclosing FormNode reference; otherwise a duplicate
+ * action name is a violation.
+ *
+ * Call this from your GET handler before returning the initial response if you
+ * want the same protection at initial-load time — the action-handler wrapper
+ * (`createAction`) calls it automatically on every response that carries `vm`.
+ *
+ * @throws Error when a violation is found. The message names the colliding
+ *   action and suggests the two fixes (rename one node, or move both into the
+ *   same enclosing form).
+ */
+export function validateActionNames(vm) {
+    const occurrences = [];
+    collectActions(vm, null, occurrences);
+    // Group by action name; for each group, verify all occurrences share the
+    // same enclosing FormNode (and that form is non-null). Anything else is a
+    // violation.
+    const byName = new Map();
+    for (const occ of occurrences) {
+        const bucket = byName.get(occ.name);
+        if (bucket)
+            bucket.push(occ);
+        else
+            byName.set(occ.name, [occ]);
+    }
+    for (const [name, group] of byName) {
+        if (group.length < 2)
+            continue;
+        const firstForm = group[0].enclosingForm;
+        // Allowed iff every occurrence is inside the SAME non-null form.
+        const allInSameForm = firstForm !== null && group.every((o) => o.enclosingForm === firstForm);
+        if (!allInSameForm) {
+            throw new Error(`Duplicate action name '${name}' dispatched from semantically distinct nodes. ` +
+                `Each action name must name exactly one operation. Either rename one of the ` +
+                `nodes (e.g. '${name}-X' / '${name}-Y') or move them into the same surrounding ` +
+                `form if they are intended to fire the same operation.`);
+        }
+    }
+}
+function collectActions(node, enclosingForm, out) {
+    switch (node.type) {
+        case "page": {
+            const page = node;
+            for (const child of page.children)
+                collectActions(child, enclosingForm, out);
+            return;
+        }
+        case "section": {
+            const section = node;
+            for (const child of section.children)
+                collectActions(child, enclosingForm, out);
+            return;
+        }
+        case "list": {
+            const list = node;
+            for (const child of list.children)
+                collectActions(child, enclosingForm, out);
+            return;
+        }
+        case "list-item": {
+            const li = node;
+            for (const child of li.children)
+                collectActions(child, enclosingForm, out);
+            return;
+        }
+        case "form": {
+            const form = node;
+            if (form.submitAction)
+                recordAction(form.submitAction, form, out);
+            if (form.buttons) {
+                for (const btn of form.buttons)
+                    recordAction(btn.action, form, out);
+            }
+            for (const child of form.children)
+                collectActions(child, form, out);
+            return;
+        }
+        case "field": {
+            const field = node;
+            if (field.action)
+                recordAction(field.action, enclosingForm, out);
+            return;
+        }
+        case "checkbox": {
+            const cb = node;
+            if (cb.action)
+                recordAction(cb.action, enclosingForm, out);
+            return;
+        }
+        case "button": {
+            const btn = node;
+            recordAction(btn.action, enclosingForm, out);
+            return;
+        }
+        case "tabs": {
+            const tabs = node;
+            for (const tab of tabs.tabs)
+                recordAction(tab.action, enclosingForm, out);
+            return;
+        }
+        case "modal": {
+            const modal = node;
+            if (modal.dismissAction)
+                recordAction(modal.dismissAction, enclosingForm, out);
+            for (const child of modal.children)
+                collectActions(child, enclosingForm, out);
+            if (modal.footer) {
+                for (const child of modal.footer)
+                    collectActions(child, enclosingForm, out);
+            }
+            return;
+        }
+        case "table": {
+            const table = node;
+            if (table.sortActions) {
+                for (const action of Object.values(table.sortActions)) {
+                    recordAction(action, enclosingForm, out);
+                }
+            }
+            if (table.filterAction)
+                recordAction(table.filterAction, enclosingForm, out);
+            if (table.pagination?.prevAction) {
+                recordAction(table.pagination.prevAction, enclosingForm, out);
+            }
+            if (table.pagination?.nextAction) {
+                recordAction(table.pagination.nextAction, enclosingForm, out);
+            }
+            for (const row of table.rows) {
+                if (row.actions) {
+                    // row.actions is ViewNode[] — it can include bind-only nodes (e.g. a
+                    // per-row CheckboxNode used for selection has no .action). Filter to
+                    // ButtonNodes the same way the .NET validator does (OfType<ButtonNode>())
+                    // before recording — otherwise the validator throws on a non-button
+                    // entry's missing .action property. Phase 6 surfaced this when
+                    // TableSelection was removed and per-row selection moved into
+                    // row.actions as bound CheckboxNodes (06-04).
+                    for (const node of row.actions) {
+                        // TableRow.actions is typed ButtonNode[] but Phase 6 (06-04)
+                        // started using it for bind-only CheckboxNodes too — the .NET
+                        // twin types it IReadOnlyList<ViewNode>. Narrow through unknown
+                        // so both branches type-check until the TS type widens.
+                        const n = node;
+                        if (n.type === "button") {
+                            recordAction(n.action, enclosingForm, out);
+                        }
+                        else if (n.type === "checkbox") {
+                            if (n.action)
+                                recordAction(n.action, enclosingForm, out);
+                        }
+                    }
+                }
+            }
+            return;
+        }
+        // Nodes with no dispatch-bearing actions of their own:
+        //   text, link, image, stat-bar, progress, copy-button
+        default:
+            return;
+    }
+}
+function recordAction(action, enclosingForm, out) {
+    out.push({ name: action.name, enclosingForm });
+}
 /** Parse a multipart/form-data action body — the wire format the TypeScript shell uses. */
 export function parseFormDataAction(formData) {
     const actionRaw = formData.get("_action");
@@ -30,19 +196,20 @@ export function parseFormDataAction(formData) {
     }
     return {
         name: action.name,
-        context: action.context ?? null,
         state,
         files,
     };
 }
-/** Parse a flat JSON action body — { name, context, state }. For curl/agent callers. */
+/** Parse a flat JSON action body — `{name, state}`. For curl/agent callers. */
 export function parseJsonAction(body) {
     const parsed = typeof body === "string"
         ? JSON.parse(body)
         : body;
+    if (typeof parsed.name !== "string" || parsed.name === "") {
+        throw new Error("Missing required 'name' field in action payload");
+    }
     return {
         name: parsed.name,
-        context: parsed.context ?? null,
         state: parsed.state,
         files: {},
     };
@@ -64,6 +231,92 @@ export const shellSideEffect = {
     download: (url, filename) => ({ type: "download", url, ...(filename != null ? { filename } : {}) }),
 };
 // ─── Action handler factory ──────────────────────────────────────────────────
+/**
+ * Thrown by an action handler to signal a malformed/invalid request. The
+ * createAction wrapper catches this and returns a 400 with the error
+ * message in the body, matching the .NET twin's BadRequest("...") path.
+ * Reserved for "structurally invalid request the user can't see" (missing
+ * required action field, etc.) — NOT for routine app validation (that stays
+ * state-based per gotcha #4). No `code` is set on the wire entry (D-08).
+ */
+export class BadRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BadRequestError";
+    }
+}
+/**
+ * Thrown by an action handler to signal that the dispatched action name is
+ * not recognised. The createAction wrapper catches this and returns a 400
+ * with `code: "unknown_action"` in the envelope, allowing agents to distinguish
+ * "I sent a name your tree doesn't expose" from "your handler crashed."
+ *
+ * Usage — add a default arm to your dispatch switch:
+ *   default: throw new UnknownActionError(payload.name);
+ *
+ * Mirrors .NET `UnknownActionException` — both backends use the same wire code.
+ */
+export class UnknownActionError extends Error {
+    /** The offending action name sent by the client. */
+    actionName;
+    constructor(actionName) {
+        super(`Unknown action: ${actionName}`);
+        this.name = "UnknownActionError";
+        this.actionName = actionName;
+    }
+}
+/**
+ * Stable, framework-only error code vocabulary. Apps MUST NOT set these —
+ * the framework sets `code` on framework-detected failures only. Agents
+ * that want generic handling check `ok`; agents that want to branch by
+ * failure class check `code` against these constants.
+ *
+ * D-03 lock: "small, stable, framework-only set."
+ */
+export const ERR_CODES = {
+    /** Malformed / unparseable request body. HTTP 400. */
+    PARSE: "parse_error",
+    /** App threw `UnknownActionError` (action name not recognised). HTTP 400. */
+    UNKNOWN_ACTION: "unknown_action",
+    /** Built view tree violates the action-name uniqueness rule. HTTP 500. */
+    INVALID_TREE: "invalid_tree",
+    /** App handler threw an unrecognised exception. HTTP 500. */
+    UNCAUGHT: "uncaught_exception",
+};
+/**
+ * Build a JSON-stringified `{ok: false, errors: [...]}` envelope.
+ * Uses the conditional-spread pattern to omit `path` and `code` when
+ * undefined — matching the .NET WhenWritingNull null-omission contract.
+ */
+function errorEnvelope(entries) {
+    const serialized = entries.map(({ message, path, code }) => ({
+        message,
+        ...(path != null ? { path } : {}),
+        ...(code != null ? { code } : {}),
+    }));
+    return JSON.stringify({ ok: false, errors: serialized });
+}
+/**
+ * Derive a safe wire message from an unknown thrown value.
+ * T1 info-disclosure mitigation: only copies `Error.prototype.message`
+ * for Error instances; substitutes a generic string for non-Error throws
+ * so unknown shapes never reach the wire.
+ */
+function errorMessageFromUnknownThrow(err) {
+    if (err instanceof Error)
+        return err.message;
+    return "Internal server error";
+}
+/**
+ * Shared response factory — deduplicates the JSON + Content-Type header
+ * boilerplate across the four error cases and the success path.
+ */
+function jsonResponse(body, status) {
+    return new Response(body, {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
 /**
  * Web Fetch API–native request handler factory. Auto-detects content-type
  * (application/json vs multipart/form-data), parses the body, calls your
@@ -92,14 +345,42 @@ export function createAction(handler) {
             }
         }
         catch (err) {
-            return new Response(JSON.stringify({ error: err.message }), {
-                status: 400,
-                headers: { "Content-Type": "application/json" },
-            });
-        }
-        const result = await handler(payload);
-        return new Response(JSON.stringify(result), {
-            headers: { "Content-Type": "application/json" },
-        });
+            // Parse failure — client sent malformed input. 400.
+            return jsonResponse(errorEnvelope([{ message: err.message, code: ERR_CODES.PARSE }]), 400);
+        }
+        let result;
+        try {
+            result = await handler(payload);
+        }
+        catch (err) {
+            if (err instanceof BadRequestError) {
+                // Structurally invalid request — no `code` per D-08.
+                return jsonResponse(errorEnvelope([{ message: err.message }]), 400);
+            }
+            if (err instanceof UnknownActionError) {
+                // App threw to signal an unknown action name. 400 per D-11.
+                return jsonResponse(errorEnvelope([{ message: err.message, code: ERR_CODES.UNKNOWN_ACTION }]), 400);
+            }
+            // Any other throw: server-side failure. Log server-side for observability
+            // (T1: stack trace stays on the server, only safe message reaches the wire).
+            console.error("[ViewModelShell] Uncaught exception in action handler:", err);
+            return jsonResponse(errorEnvelope([{ message: errorMessageFromUnknownThrow(err), code: ERR_CODES.UNCAUGHT }]), 500);
+        }
+        // Phase 06 / WIRE-05 — enforce action-name uniqueness on the built tree
+        // before it leaves the server. A violation here is a server-side bug, so
+        // we surface it as a 500 (the parse-error path above is a 400 because the
+        // client sent malformed input). Only run when the response carries a vm
+        // (redirect-only responses have nothing to walk).
+        if (result.vm) {
+            try {
+                validateActionNames(result.vm);
+            }
+            catch (err) {
+                return jsonResponse(errorEnvelope([{ message: err.message, code: ERR_CODES.INVALID_TREE }]), 500);
+            }
+        }
+        // Phase 07 / ERROR-01 — every successful response acquires ok:true at the
+        // response edge. Controllers / app handlers do NOT set ok themselves.
+        return jsonResponse(JSON.stringify({ ok: true, ...result }), 200);
     };
 }

package/dist/tui.d.ts

@@ -1,4 +1,4 @@
-import type { Adapter, ActionEvent, ViewNode } from "./index.js";
+import type { Adapter, ActionEvent, ViewNode, StateAccess } from "./index.js";
 interface TuiOpts {
     /** "fill" (default) takes the full terminal via alternate-screen buffer;
      *  "content" renders intrinsic content size in the inline scrollback. */
@@ -49,7 +49,7 @@ export declare class TuiAdapter implements Adapter {
     private setPendingButton;
     private copy;
     private resolveFieldValue;
-    render(vm: ViewNode, onAction: (action: ActionEvent) => void): void;
+    render(vm: ViewNode, onAction: (action: ActionEvent) => void, _stateAccess?: StateAccess): void;
     private init;
     private flushPending;
     private navigateForLinks;