@fuzdev/fuz_app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) fuz.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @fuzdev/fuz_app
+
+> fullstack app library ⚠️ pre-alpha, do not use in production
+
+fuz_app is a fullstack app library for
+TypeScript, [Svelte](https://svelte.dev/), SvelteKit,
+[Hono](https://hono.dev/), and [PostgreSQL](https://www.postgresql.org/)
+with [PGlite](https://pglite.dev/) for embedded targets.
+It provides auth, sessions, accounts, database integration, middleware, CLI utilities, and more,
+the goal being an excellent and flexible whole-stack experience
+for developers, operators, and end-users.
+
+fuz_app supports deploying with Deno, Node, and Bun,
+to servers, static websites, and local-first binaries, with more to come,
+eventually with compatible alternatives written in Rust.
+
+fuz_app is part of the [Fuz stack](https://www.fuz.dev/),
+for more see the <a href="https://github.com/fuzdev/fuz_app/discussions">fuz_app discussions</a>.
+
+> ⚠️ This is a pre-alpha release, not ready for production.
+> There are no known security vulnerabilities,
+> and security has been \_the\_ primary focus for the initial release,
+> but it shouldn't be trusted until audited.
+
+## Usage
+
+```bash
+npm i -D @fuzdev/fuz_app
+```
+
+Some projects using fuz_app are in progress and will be open source soon.
+Usage currently looks something like this:
+
+```ts
+import {create_app_backend} from '@fuzdev/fuz_app/server/app_backend.js';
+import {create_app_server} from '@fuzdev/fuz_app/server/app_server.js';
+
+const backend = await create_app_backend({...});
+
+const {app} = await create_app_server({backend, ...});
+
+Deno.serve({port: PORT, hostname: HOST}, app.fetch);
+```
+
+See [CLAUDE.md](CLAUDE.md) for more usage patterns and the AI-generated docs.
+
+## License
+
+[MIT](LICENSE)

package/dist/actions/action_bridge.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Bridge functions to derive `RouteSpec` and `SseEventSpec` from `ActionSpec`.
+ *
+ * Action specs define the contract (method, input/output, auth, side effects).
+ * Bridge functions produce transport-specific specs from them. HTTP-specific
+ * concerns (path, handler) come from options.
+ *
+ * @module
+ */
+import type { z } from 'zod';
+import type { ActionSpec, ActionAuth as ActionSpecAuth, ActionSideEffects } from './action_spec.js';
+import type { RouteSpec, RouteAuth, RouteMethod, RouteHandler } from '../http/route_spec.js';
+import type { SseEventSpec } from '../realtime/sse.js';
+import type { RouteErrorSchemas } from '../http/error_schemas.js';
+/** Options for deriving a `RouteSpec` from an `ActionSpec`. */
+export interface ActionRouteOptions {
+    path: string;
+    handler: RouteHandler;
+    /** URL path parameter schema. Use `z.strictObject()` with string fields matching `:param` segments. */
+    params?: z.ZodObject;
+    /** URL query parameter schema. Use `z.strictObject()` with string fields. */
+    query?: z.ZodObject;
+    /** Override the default HTTP method (default: `side_effects` → POST, else GET). */
+    http_method?: RouteMethod;
+    /** Override the default auth mapping (default: `'public'` → none, `'authenticated'` → authenticated, `'keeper'` → keeper, `{role}` → role). */
+    auth?: RouteAuth;
+    /** Handler-specific error schemas (HTTP status code → Zod schema). Transport-specific — not on ActionSpec. */
+    errors?: RouteErrorSchemas;
+}
+/** Options for deriving an `SseEventSpec` from an `ActionSpec`. */
+export interface ActionEventOptions {
+    channel?: string;
+}
+/** Map an `ActionAuth` value to a `RouteAuth`. */
+export declare const map_action_auth: (auth: ActionSpecAuth) => RouteAuth;
+/** Derive the default HTTP method from side effects. */
+export declare const derive_http_method: (side_effects: ActionSideEffects) => RouteMethod;
+/**
+ * Derive a `RouteSpec` from an `ActionSpec` and options.
+ *
+ * Only `request_response` actions (which require non-null `auth`) can become routes.
+ * `remote_notification` actions (auth null) should use `event_spec_from_action`.
+ * `local_call` actions are not for HTTP transport.
+ *
+ * Error schemas are transport-specific (keyed by HTTP status codes) and belong
+ * on the options, not the action spec. Action specs define the contract;
+ * transport concerns like HTTP error codes are added at the bridge layer.
+ *
+ * @param spec - the action spec (must have non-null `auth`)
+ * @param options - HTTP-specific options (path, handler, optional overrides)
+ * @returns a `RouteSpec` ready for `apply_route_specs`
+ * @throws if `spec.auth` is null
+ */
+export declare const route_spec_from_action: (spec: ActionSpec, options: ActionRouteOptions) => RouteSpec;
+/**
+ * Derive an `SseEventSpec` from an `ActionSpec`.
+ *
+ * Only `remote_notification` actions can become SSE events.
+ *
+ * @param spec - the action spec (must have `kind: 'remote_notification'`)
+ * @param options - optional SSE-specific options (channel)
+ * @returns an `SseEventSpec` ready for `create_validated_broadcaster`
+ */
+export declare const event_spec_from_action: (spec: ActionSpec, options?: ActionEventOptions) => SseEventSpec;
+//# sourceMappingURL=action_bridge.d.ts.map

package/dist/actions/action_bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action_bridge.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,UAAU,EAAE,UAAU,IAAI,cAAc,EAAE,iBAAiB,EAAC,MAAM,kBAAkB,CAAC;AAClG,OAAO,KAAK,EAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAC,MAAM,uBAAuB,CAAC;AAC3F,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,0BAA0B,CAAC;AAEhE,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,uGAAuG;IACvG,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+IAA+I;IAC/I,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,8GAA8G;IAC9G,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,eAAO,MAAM,eAAe,GAAI,MAAM,cAAc,KAAG,SAKtD,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,GAAI,cAAc,iBAAiB,KAAG,WAEpE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,UAAU,EAChB,SAAS,kBAAkB,KACzB,SAkBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,UAAU,EAChB,UAAU,kBAAkB,KAC1B,YAYF,CAAC"}

package/dist/actions/action_bridge.js

@@ -0,0 +1,76 @@
+/**
+ * Bridge functions to derive `RouteSpec` and `SseEventSpec` from `ActionSpec`.
+ *
+ * Action specs define the contract (method, input/output, auth, side effects).
+ * Bridge functions produce transport-specific specs from them. HTTP-specific
+ * concerns (path, handler) come from options.
+ *
+ * @module
+ */
+/** Map an `ActionAuth` value to a `RouteAuth`. */
+export const map_action_auth = (auth) => {
+    if (auth === 'public')
+        return { type: 'none' };
+    if (auth === 'authenticated')
+        return { type: 'authenticated' };
+    if (auth === 'keeper')
+        return { type: 'keeper' };
+    return { type: 'role', role: auth.role };
+};
+/** Derive the default HTTP method from side effects. */
+export const derive_http_method = (side_effects) => {
+    return side_effects === true ? 'POST' : 'GET';
+};
+/**
+ * Derive a `RouteSpec` from an `ActionSpec` and options.
+ *
+ * Only `request_response` actions (which require non-null `auth`) can become routes.
+ * `remote_notification` actions (auth null) should use `event_spec_from_action`.
+ * `local_call` actions are not for HTTP transport.
+ *
+ * Error schemas are transport-specific (keyed by HTTP status codes) and belong
+ * on the options, not the action spec. Action specs define the contract;
+ * transport concerns like HTTP error codes are added at the bridge layer.
+ *
+ * @param spec - the action spec (must have non-null `auth`)
+ * @param options - HTTP-specific options (path, handler, optional overrides)
+ * @returns a `RouteSpec` ready for `apply_route_specs`
+ * @throws if `spec.auth` is null
+ */
+export const route_spec_from_action = (spec, options) => {
+    if (spec.auth === null) {
+        throw new Error(`Cannot derive route spec from action '${spec.method}': auth is null (only request_response actions with non-null auth can become routes)`);
+    }
+    return {
+        method: options.http_method ?? derive_http_method(spec.side_effects),
+        path: options.path,
+        auth: options.auth ?? map_action_auth(spec.auth),
+        handler: options.handler,
+        description: spec.description,
+        ...(options.params ? { params: options.params } : {}),
+        ...(options.query ? { query: options.query } : {}),
+        input: spec.input,
+        output: spec.output,
+        ...(options.errors ? { errors: options.errors } : {}),
+    };
+};
+/**
+ * Derive an `SseEventSpec` from an `ActionSpec`.
+ *
+ * Only `remote_notification` actions can become SSE events.
+ *
+ * @param spec - the action spec (must have `kind: 'remote_notification'`)
+ * @param options - optional SSE-specific options (channel)
+ * @returns an `SseEventSpec` ready for `create_validated_broadcaster`
+ */
+export const event_spec_from_action = (spec, options) => {
+    if (spec.kind !== 'remote_notification') {
+        throw new Error(`Cannot derive event spec from action '${spec.method}': kind is '${spec.kind}' (must be 'remote_notification')`);
+    }
+    return {
+        method: spec.method,
+        params: spec.input,
+        description: spec.description,
+        channel: options?.channel,
+    };
+};

package/dist/actions/action_codegen.d.ts

@@ -0,0 +1,97 @@
+import type { ActionSpecUnion, ActionEventPhase } from './action_spec.js';
+/**
+ * Represents an import item with its kind (type, value, or namespace).
+ */
+interface ImportItem {
+    name: string;
+    kind: 'type' | 'value' | 'namespace';
+}
+/**
+ * Manages imports for generated code, building them on demand.
+ * Automatically optimizes type-only imports to use `import type` syntax.
+ *
+ * Why this matters:
+ * - `import type` statements are completely removed during compilation
+ * - Mixed imports like `import { type A, B }` cannot be safely removed
+ * - This ensures optimal tree-shaking and smaller bundle sizes
+ *
+ * @example
+ * ```typescript
+ * const imports = new ImportBuilder();
+ * imports.add_types('./types.js', 'Foo', 'Bar');
+ * imports.add('./utils.js', 'helper');
+ * imports.add_type('./utils.js', 'HelperOptions');
+ * imports.add('./action_specs.js', '* as specs');
+ *
+ * // Generates:
+ * // import type {Foo, Bar} from './types.js';
+ * // import {helper, type HelperOptions} from './utils.js';
+ * // import * as specs from './action_specs.js';
+ * ```
+ */
+export declare class ImportBuilder {
+    #private;
+    imports: Map<string, Map<string, ImportItem>>;
+    /**
+     * Add a value import to be included in the generated code.
+     * @param from - the module to import from
+     * @param what - what to import (value)
+     */
+    add(from: string, what: string): this;
+    /**
+     * Add a type import to be included in the generated code.
+     * @param from - the module to import from
+     * @param what - what to import (type)
+     */
+    add_type(from: string, what: string): this;
+    /**
+     * Add multiple value imports from the same module.
+     */
+    add_many(from: string, ...items: Array<string>): this;
+    /**
+     * Add multiple type imports from the same module.
+     */
+    add_types(from: string, ...items: Array<string>): this;
+    /**
+     * Generate the import statements.
+     * If all imports from a module are types, uses `import type` syntax.
+     */
+    build(): string;
+    /**
+     * Check if the builder has any imports.
+     */
+    has_imports(): boolean;
+    /**
+     * Get the number of import statements that will be generated.
+     */
+    get import_count(): number;
+    /**
+     * Preview what imports will be generated (useful for debugging).
+     * @returns array of import statement strings
+     */
+    preview(): Array<string>;
+    /**
+     * Clear all imports.
+     */
+    clear(): this;
+}
+/**
+ * Determines which phases an executor can handle based on the action spec.
+ */
+export declare const get_executor_phases: (spec: ActionSpecUnion, executor: "frontend" | "backend") => Array<ActionEventPhase>;
+/**
+ * Gets the handler return type for a specific phase and spec.
+ * Also adds necessary imports to the `ImportBuilder`.
+ */
+export declare const get_handler_return_type: (spec: ActionSpecUnion, phase: ActionEventPhase, imports: ImportBuilder, path_prefix: string) => string;
+/**
+ * Generates the phase handlers for an action spec using the unified ActionEvent type
+ * with the new phase/step type parameters.
+ */
+export declare const generate_phase_handlers: (spec: ActionSpecUnion, executor: "frontend" | "backend", imports: ImportBuilder) => string;
+/**
+ * Creates a file banner comment.
+ */
+export declare const create_banner: (origin_path: string) => string;
+export {};
+//# sourceMappingURL=action_codegen.d.ts.map

package/dist/actions/action_codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,eAAe,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAKxE;;GAEG;AACH,UAAU,UAAU;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;;IACzB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAa;IAE1D;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAOrD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI;IAgCtD;;;OAGG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;IAIxB;;OAEG;IACH,KAAK,IAAI,IAAI;CAqDb;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,KAC9B,KAAK,CAAC,gBAAgB,CA4DxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,OAAO,gBAAgB,EACvB,SAAS,aAAa,EACtB,aAAa,MAAM,KACjB,MAkBF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,eAAe,EACrB,UAAU,UAAU,GAAG,SAAS,EAChC,SAAS,aAAa,KACpB,MA+BF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,aAAa,MAAM,KAAG,MACU,CAAC"}

package/dist/actions/action_codegen.js

@@ -0,0 +1,280 @@
+import { UnreachableError } from '@fuzdev/fuz_util/error.js';
+/**
+ * Manages imports for generated code, building them on demand.
+ * Automatically optimizes type-only imports to use `import type` syntax.
+ *
+ * Why this matters:
+ * - `import type` statements are completely removed during compilation
+ * - Mixed imports like `import { type A, B }` cannot be safely removed
+ * - This ensures optimal tree-shaking and smaller bundle sizes
+ *
+ * @example
+ * ```typescript
+ * const imports = new ImportBuilder();
+ * imports.add_types('./types.js', 'Foo', 'Bar');
+ * imports.add('./utils.js', 'helper');
+ * imports.add_type('./utils.js', 'HelperOptions');
+ * imports.add('./action_specs.js', '* as specs');
+ *
+ * // Generates:
+ * // import type {Foo, Bar} from './types.js';
+ * // import {helper, type HelperOptions} from './utils.js';
+ * // import * as specs from './action_specs.js';
+ * ```
+ */
+export class ImportBuilder {
+    imports = new Map();
+    /**
+     * Add a value import to be included in the generated code.
+     * @param from - the module to import from
+     * @param what - what to import (value)
+     */
+    add(from, what) {
+        // Handle namespace imports specially
+        if (what.startsWith('* as ')) {
+            return this.#add_import(from, what, 'namespace');
+        }
+        return this.#add_import(from, what, 'value');
+    }
+    /**
+     * Add a type import to be included in the generated code.
+     * @param from - the module to import from
+     * @param what - what to import (type)
+     */
+    add_type(from, what) {
+        return this.#add_import(from, what, 'type');
+    }
+    /**
+     * Add multiple value imports from the same module.
+     */
+    add_many(from, ...items) {
+        for (const item of items) {
+            this.add(from, item);
+        }
+        return this;
+    }
+    /**
+     * Add multiple type imports from the same module.
+     */
+    add_types(from, ...items) {
+        for (const item of items) {
+            this.add_type(from, item);
+        }
+        return this;
+    }
+    /**
+     * Internal method to add an import with its kind.
+     */
+    #add_import(from, name, kind) {
+        // Skip empty imports
+        if (!name || (kind !== 'namespace' && name === '')) {
+            return this;
+        }
+        if (!this.imports.has(from)) {
+            this.imports.set(from, new Map());
+        }
+        const module_imports = this.imports.get(from);
+        const existing = module_imports.get(name);
+        // If already imported as a value, don't downgrade to type
+        if (existing?.kind === 'value' && kind === 'type') {
+            return this;
+        }
+        module_imports.set(name, { name, kind });
+        return this;
+    }
+    /**
+     * Generate the import statements.
+     * If all imports from a module are types, uses `import type` syntax.
+     */
+    build() {
+        return this.#generate_import_statements().join('\n');
+    }
+    /**
+     * Check if the builder has any imports.
+     */
+    has_imports() {
+        return this.imports.size > 0;
+    }
+    /**
+     * Get the number of import statements that will be generated.
+     */
+    get import_count() {
+        return this.imports.size;
+    }
+    /**
+     * Preview what imports will be generated (useful for debugging).
+     * @returns array of import statement strings
+     */
+    preview() {
+        return this.#generate_import_statements();
+    }
+    /**
+     * Clear all imports.
+     */
+    clear() {
+        this.imports.clear();
+        return this;
+    }
+    /**
+     * Internal helper to generate import statements from the current state.
+     * Shared by both build() and preview() methods.
+     */
+    #generate_import_statements() {
+        const statements = [];
+        for (const [from, module_imports] of this.imports) {
+            const items = Array.from(module_imports.values());
+            // Check if all imports are types
+            const all_types = items.every((item) => item.kind === 'type');
+            if (all_types) {
+                // Use type-only import syntax
+                const sorted_names = items
+                    .map((item) => item.name)
+                    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+                statements.push(`import type {${sorted_names.join(', ')}} from '${from}';`);
+            }
+            else {
+                // Check for namespace imports (should be only one per module)
+                const namespace_import = items.find((item) => item.kind === 'namespace');
+                if (namespace_import) {
+                    statements.push(`import ${namespace_import.name} from '${from}';`);
+                }
+                else {
+                    // Mixed imports - sort values first, then types, alphabetically within each group
+                    const sorted_items = items.sort((a, b) => {
+                        // First sort by kind: values before types
+                        if (a.kind !== b.kind) {
+                            return a.kind === 'value' ? -1 : 1;
+                        }
+                        // Then sort alphabetically within the same kind using standard comparison
+                        return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+                    });
+                    const formatted_imports = sorted_items.map((item) => {
+                        if (item.kind === 'namespace') {
+                            return item.name; // namespace imports like "* as foo" are used as-is
+                        }
+                        return item.kind === 'type' ? `type ${item.name}` : item.name;
+                    });
+                    statements.push(`import {${formatted_imports.join(', ')}} from '${from}';`);
+                }
+            }
+        }
+        return statements;
+    }
+}
+/**
+ * Determines which phases an executor can handle based on the action spec.
+ */
+export const get_executor_phases = (spec, executor) => {
+    const { kind, initiator } = spec;
+    const phases = [];
+    switch (kind) {
+        case 'request_response': {
+            // Executor can send/receive based on initiator
+            const can_send = initiator === executor || initiator === 'both';
+            const can_receive = initiator === 'both' || initiator !== executor;
+            switch (executor) {
+                case 'frontend':
+                    if (can_send) {
+                        phases.push('send_request', 'receive_response');
+                        // Add error phases for send/receive
+                        phases.push('send_error', 'receive_error');
+                    }
+                    if (can_receive)
+                        phases.push('receive_request', 'send_response');
+                    break;
+                case 'backend':
+                    if (can_send) {
+                        phases.push('send_request', 'receive_response');
+                        // Add error phases for send/receive
+                        phases.push('send_error', 'receive_error');
+                    }
+                    if (can_receive) {
+                        phases.push('receive_request', 'send_response');
+                        // TODO @action-system-review This adds send_error redundantly when initiator:'both'
+                        // (already added above). Deduplication via Set at the end handles it,
+                        // but the logic should be consolidated when the action system is revisited.
+                        phases.push('send_error');
+                    }
+                    break;
+                default:
+                    throw new UnreachableError(executor);
+            }
+            break;
+        }
+        case 'remote_notification': {
+            const can_send = initiator === executor || initiator === 'both';
+            const can_receive = initiator === 'both' || initiator !== executor;
+            if (can_send)
+                phases.push('send');
+            if (can_receive)
+                phases.push('receive');
+            break;
+        }
+        case 'local_call': {
+            const can_execute = initiator === executor || initiator === 'both';
+            if (can_execute)
+                phases.push('execute');
+            break;
+        }
+        default:
+            throw new UnreachableError(kind);
+    }
+    // Deduplicate phases (e.g., send_error added twice for initiator:'both' backend actions)
+    return Array.from(new Set(phases));
+};
+/**
+ * Gets the handler return type for a specific phase and spec.
+ * Also adds necessary imports to the `ImportBuilder`.
+ */
+export const get_handler_return_type = (spec, phase, imports, path_prefix) => {
+    // For request_response receive_request, handler returns the output
+    if (spec.kind === 'request_response' && phase === 'receive_request') {
+        imports.add_type(`${path_prefix}action_collections.js`, 'ActionOutputs');
+        const base_type = `ActionOutputs['${spec.method}']`;
+        // Request/response actions are always async
+        return `${base_type} | Promise<${base_type}>`;
+    }
+    // For local_call execute, handler returns the output
+    if (spec.kind === 'local_call' && phase === 'execute') {
+        imports.add_type(`${path_prefix}action_collections.js`, 'ActionOutputs');
+        const base_type = `ActionOutputs['${spec.method}']`;
+        return spec.async ? `${base_type} | Promise<${base_type}>` : base_type;
+    }
+    // All other phases return void
+    return 'void | Promise<void>';
+};
+/**
+ * Generates the phase handlers for an action spec using the unified ActionEvent type
+ * with the new phase/step type parameters.
+ */
+export const generate_phase_handlers = (spec, executor, imports) => {
+    const { method } = spec;
+    const phases = get_executor_phases(spec, executor);
+    if (phases.length === 0) {
+        return `${method}?: never`;
+    }
+    // Add necessary imports for the unified system
+    // Backend types file is in server/ subdirectory, so needs different relative paths
+    const path_prefix = executor === 'frontend' ? './' : '../';
+    imports.add_type(`${path_prefix}action_event.js`, 'ActionEvent');
+    // Add environment type import
+    const environment_type = executor === 'frontend' ? 'Frontend' : 'Backend';
+    const environment_module = executor === 'frontend' ? './frontend.svelte.js' : './backend.js';
+    imports.add_type(environment_module, environment_type);
+    // Generate handler definitions for each phase
+    const phase_handlers = phases
+        .map((phase) => {
+        // Pass imports to get_handler_return_type so it can add necessary imports
+        const return_type = get_handler_return_type(spec, phase, imports, path_prefix);
+        // Use the new type parameter approach
+        return `${phase}?: (
+			action_event: ActionEvent<'${method}', ${environment_type}, '${phase}', 'handling'>
+		) => ${return_type}`;
+    })
+        .join(';\n\t\t');
+    return `${method}?: {\n\t\t${phase_handlers};\n\t}`;
+};
+/**
+ * Creates a file banner comment.
+ */
+export const create_banner = (origin_path) => `generated by ${origin_path} - DO NOT EDIT OR RISK LOST DATA`;

package/dist/actions/action_registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `ActionRegistry` — query and filter utility over `ActionSpecUnion[]`.
+ *
+ * @module
+ */
+import type { ActionSpecUnion, RequestResponseActionSpec, RemoteNotificationActionSpec, LocalCallActionSpec } from './action_spec.js';
+/**
+ * Utility class to manage and query action specifications.
+ * Provides helper methods to get actions by various criteria.
+ */
+export declare class ActionRegistry {
+    readonly specs: Array<ActionSpecUnion>;
+    constructor(specs: Array<ActionSpecUnion>);
+    get spec_by_method(): Map<string, ActionSpecUnion>;
+    get request_response_specs(): Array<RequestResponseActionSpec>;
+    get remote_notification_specs(): Array<RemoteNotificationActionSpec>;
+    get local_call_specs(): Array<LocalCallActionSpec>;
+    get backend_specs(): Array<ActionSpecUnion>;
+    get frontend_specs(): Array<ActionSpecUnion>;
+    get backend_to_frontend_specs(): Array<ActionSpecUnion>;
+    get frontend_to_backend_specs(): Array<ActionSpecUnion>;
+    get public_specs(): Array<ActionSpecUnion>;
+    get authenticated_specs(): Array<ActionSpecUnion>;
+    get methods(): Array<string>;
+    get request_response_methods(): Array<string>;
+    get remote_notification_methods(): Array<string>;
+    get local_call_methods(): Array<string>;
+    get backend_methods(): Array<string>;
+    get frontend_methods(): Array<string>;
+    get frontend_to_backend_methods(): Array<string>;
+    get backend_to_frontend_methods(): Array<string>;
+    get public_methods(): Array<string>;
+    get authenticated_methods(): Array<string>;
+}
+//# sourceMappingURL=action_registry.d.ts.map

package/dist/actions/action_registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action_registry.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,eAAe,EACf,yBAAyB,EACzB,4BAA4B,EAC5B,mBAAmB,EACnB,MAAM,kBAAkB,CAAC;AAQ1B;;;GAGG;AACH,qBAAa,cAAc;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;gBAE3B,KAAK,EAAE,KAAK,CAAC,eAAe,CAAC;IAIzC,IAAI,cAAc,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAEjD;IAED,IAAI,sBAAsB,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAE7D;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAEnE;IAED,IAAI,gBAAgB,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAEjD;IAKD,IAAI,aAAa,IAAI,KAAK,CAAC,eAAe,CAAC,CAE1C;IAED,IAAI,cAAc,IAAI,KAAK,CAAC,eAAe,CAAC,CAE3C;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEtD;IAED,IAAI,yBAAyB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEtD;IAED,IAAI,YAAY,IAAI,KAAK,CAAC,eAAe,CAAC,CAEzC;IAED,IAAI,mBAAmB,IAAI,KAAK,CAAC,eAAe,CAAC,CAEhD;IAED,IAAI,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,CAE3B;IAED,IAAI,wBAAwB,IAAI,KAAK,CAAC,MAAM,CAAC,CAE5C;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAED,IAAI,kBAAkB,IAAI,KAAK,CAAC,MAAM,CAAC,CAEtC;IAED,IAAI,eAAe,IAAI,KAAK,CAAC,MAAM,CAAC,CAEnC;IAED,IAAI,gBAAgB,IAAI,KAAK,CAAC,MAAM,CAAC,CAEpC;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAED,IAAI,2BAA2B,IAAI,KAAK,CAAC,MAAM,CAAC,CAE/C;IAED,IAAI,cAAc,IAAI,KAAK,CAAC,MAAM,CAAC,CAElC;IAED,IAAI,qBAAqB,IAAI,KAAK,CAAC,MAAM,CAAC,CAEzC;CACD"}