@fuzdev/fuz_app 0.47.0 → 0.48.0

package/dist/actions/CLAUDE.md

@@ -107,20 +107,22 @@ should not appear in consumer-owned typed surfaces (`ActionMethod`,
 `include_composables: true` only if a consumer genuinely owns composables
 in their typed API.
 
-**Consumer tiers and the single-namespace assumption.** Single-source consumers
-(zzz, undying — every spec lives in one local `action_specs.ts`) drop straight
-into the helpers. Multi-source consumers (tx, visiones — which stitch local
-specs together with `all_admin_action_specs` / `all_permit_offer_action_specs` /
-`all_account_action_specs` / `all_self_service_role_action_specs` from fuz_app)
-need a per-method namespace lookup, and the helpers that emit
-`specs.{method}_action_spec` (`generate_action_specs_record`,
-`generate_action_inputs_outputs`, `generate_backend_actions_api`) currently
-assume one `* as specs from specs_module` import covers everything. Multi-source
-consumers keep using the lower-level primitives directly
-(`to_action_spec_input_identifier`, `to_action_spec_output_identifier`,
-`ActionRegistry`) — see tx's `action_collections.gen.ts` for the current
-pattern. A `qualify_spec?: (spec) => string` callback is the planned extension
-point; design it against the Step 3 (tx parity) consumer.
+**Consumer tiers and namespace handling.** Single-source consumers (zzz,
+undying — every spec lives in one local `action_specs.ts`) drop straight
+into the helpers and accept the default `* as specs from specs_module`
+namespace import. Multi-source consumers (tx, visiones — which stitch
+local specs together with `all_admin_action_specs` /
+`all_permit_offer_action_specs` / `all_account_action_specs` /
+`all_self_service_role_action_specs` from fuz_app) pass
+`qualify_spec?: (spec) => string` to the three multi-source helpers
+(`generate_action_specs_record`, `generate_action_inputs_outputs`,
+`generate_backend_actions_api`). When `qualify_spec` is set, the helper
+emits the callback's return value (e.g.
+`admin_specs.account_list_action_spec`) and skips the default `* as specs`
+import — the consumer manages its own multi-namespace imports. The helper
+appends `.input` / `.output` to the qualified identifier in
+`generate_action_inputs_outputs` automatically; the callback returns the
+bare spec identifier.
 
 Tier 1 (HTTP-only, e.g. tx/visiones) emits a smaller surface — typically just
 `ActionMethod` + `ActionsApi` + `ActionInputs` / `ActionOutputs` interfaces —
@@ -131,12 +133,12 @@ zzz) emits the full set including `ActionEventDatas`, `TypedActionEvent`, and
 
 - `generate_action_method_enums(specs, imports, {emit?})` — up to six `z.enum` + `z.infer` pairs (`ActionMethod`, `RequestResponseActionMethod`, `RemoteNotificationActionMethod`, `LocalCallActionMethod`, `FrontendActionMethod`, `BackendActionMethod`). `emit: ReadonlySet<ActionMethodEnumKind>` restricts to a subset (Tier 1 HTTP-only consumers don't need all six). Skips kinds whose method list is empty (`z.enum([])` is invalid) and skips the `zod` import when no blocks are emitted. Adds `import {z} from 'zod'` only when at least one block is produced.
 - `generate_typed_action_event_alias(imports, {collections_path?, metatypes_path?})` — fixed-shape `TypedActionEvent<TMethod, TPhase, TStep>` alias narrowing `ActionEvent.data` against `ActionEventDatas`. Adds the three fuz_app type imports + `ActionEventDatas` (from `collections_path`) + `ActionMethod` (from `metatypes_path`).
-- `generate_action_specs_record(specs, imports, {specs_module?})` — `ActionSpecs` runtime const + interface + `action_specs: Array<ActionSpecUnion>` value. Adds `* as specs` from `specs_module`.
-- `generate_action_inputs_outputs(specs, imports, {specs_module?})` — `ActionInputs` and `ActionOutputs` runtime consts + interfaces. Adds `* as specs` from `specs_module`.
-- `generate_action_event_datas(specs, imports, {collections_path?})` — `ActionEventDatas` interface; per-spec variant by kind (`ActionEventRequestResponseData` / `ActionEventRemoteNotificationData` / `ActionEventLocalCallData`). When `collections_path` is set, adds `ActionInputs` / `ActionOutputs` type imports from that path; default (unset) assumes same-file scope, the zzz pattern where this helper feeds the same `action_collections.ts` output as `generate_action_inputs_outputs`.
+- `generate_action_specs_record(specs, imports, {specs_module?, qualify_spec?})` — `ActionSpecs` runtime const + interface + `action_specs: Array<ActionSpecUnion>` value. Adds `* as specs` from `specs_module` unless `qualify_spec` is set (then `specs_module` is ignored and the consumer owns namespace imports).
+- `generate_action_inputs_outputs(specs, imports, {specs_module?, qualify_spec?})` — `ActionInputs` and `ActionOutputs` runtime consts + interfaces. Same `qualify_spec` semantics as `generate_action_specs_record`; the helper appends `.input` / `.output` to the qualified identifier.
+- `generate_action_event_datas(specs, imports, {same_file?, collections_path?})` — `ActionEventDatas` interface; per-spec variant by kind (`ActionEventRequestResponseData` / `ActionEventRemoteNotificationData` / `ActionEventLocalCallData`). `same_file` (default `true`) is the file-layout switch: when `true`, assumes `ActionInputs` / `ActionOutputs` are in the same module and adds no import (the zzz pattern); when `false`, adds the type imports from `collections_path` (default `'./action_collections.js'`). `collections_path` alone is a no-op — the surprising omit-vs-default behavior of earlier versions has been replaced.
 - `generate_actions_api(specs, imports, {method_filter?, collections_path?, sync_returns_value?})` — `ActionsApi` interface. Composables filtered by default; `method_filter: (spec) => boolean` runs after the composable filter for tx-style additional subsets.
 - `generate_frontend_action_handlers(specs, imports, {collections_path?})` — `FrontendActionHandlers` interface (Tier 2 only — wraps `generate_phase_handlers` with `action_event_type: 'TypedActionEvent'`). Pair with `generate_typed_action_event_alias`.
-- `generate_backend_actions_api(specs, imports, {specs_module?, collections_path?})` — `BackendActionsApi` interface AND `broadcast_action_specs: ReadonlyArray<ActionSpecUnion>` array. Filter: `kind === 'remote_notification' && initiator !== 'frontend'`. Adds the `* as specs` namespace import + `ActionInputs` (from `collections_path`) + `ActionSpecUnion`.
+- `generate_backend_actions_api(specs, imports, {specs_module?, collections_path?, qualify_spec?})` — `BackendActionsApi` interface AND `broadcast_action_specs: ReadonlyArray<ActionSpecUnion>` array. Filter: `kind === 'remote_notification' && initiator !== 'frontend'`. Adds `ActionInputs` (from `collections_path`) + `ActionSpecUnion`, plus `* as specs` from `specs_module` unless `qualify_spec` is set.
 
 ## HTTP bridge (`action_bridge.ts`)
 

package/dist/actions/action_codegen.d.ts

@@ -209,14 +209,16 @@ export declare const generate_typed_action_event_alias: (imports: ImportBuilder,
  * Array<ActionSpecUnion>` value bundling every spec. Adds the `* as specs`
  * namespace import + the `ActionSpecUnion` type import.
  *
- * **Single-namespace.** Every spec is referenced as `specs.{method}_action_spec`.
- * Multi-source consumers (tx, visiones) need a per-method namespace lookup
- * and currently use lower-level primitives instead — see the `--- High-level
- * codegen helpers ---` banner above for the rationale and the planned
- * `qualify_spec?` extension point.
+ * @param options.qualify_spec - per-spec qualified identifier callback for
+ *   multi-source consumers (e.g. ``(s) => `admin_specs.${s.method}_action_spec` ``).
+ *   When set, the helper emits the callback's return value instead of
+ *   ``specs.${method}_action_spec`` and skips the default `* as specs`
+ *   import — the consumer manages its own namespace imports. `specs_module`
+ *   is ignored when `qualify_spec` is set. Single-source consumers omit it.
  */
 export declare const generate_action_specs_record: (specs: ReadonlyArray<ActionSpecUnion>, imports: ImportBuilder, options?: {
     specs_module?: string;
+    qualify_spec?: (spec: ActionSpecUnion) => string;
     include_composables?: boolean;
 }) => string;
 /**
@@ -226,11 +228,15 @@ export declare const generate_action_specs_record: (specs: ReadonlyArray<ActionS
  *
  * Adds `import {z} from 'zod';` and the `* as specs` namespace import.
  *
- * **Single-namespace.** Same caveat as `generate_action_specs_record` —
- * multi-source consumers use the lower-level primitives.
+ * @param options.qualify_spec - per-spec qualified identifier callback for
+ *   multi-source consumers. The helper appends `.input` / `.output` to the
+ *   callback's return value. When set, the helper skips the default
+ *   `* as specs` import — the consumer manages its own namespace imports —
+ *   and `specs_module` is ignored. Single-source consumers omit it.
  */
 export declare const generate_action_inputs_outputs: (specs: ReadonlyArray<ActionSpecUnion>, imports: ImportBuilder, options?: {
     specs_module?: string;
+    qualify_spec?: (spec: ActionSpecUnion) => string;
     include_composables?: boolean;
 }) => string;
 /**
@@ -242,14 +248,19 @@ export declare const generate_action_inputs_outputs: (specs: ReadonlyArray<Actio
  *
  * Adds the per-kind data type imports (only the kinds that appear in `specs`).
  *
- * @param options.collections_path - when set, adds `ActionInputs` /
- *   `ActionOutputs` type imports from this path. Leave unset (default) when
- *   the producer emits `ActionEventDatas` in the same file as
- *   `ActionInputs` / `ActionOutputs` — same-file scope means no imports
- *   needed (the zzz pattern, where `generate_action_inputs_outputs` and
- *   this helper feed the same `action_collections.ts` output).
+ * @param options.same_file - when `true` (default), assumes `ActionInputs` /
+ *   `ActionOutputs` are in the same module as the emitted `ActionEventDatas`
+ *   and adds no import (the zzz pattern, where `generate_action_inputs_outputs`
+ *   and this helper feed the same `action_collections.ts` output). When
+ *   `false`, adds `ActionInputs` / `ActionOutputs` type imports from
+ *   `collections_path`.
+ * @param options.collections_path - import path used when `same_file: false`.
+ *   Defaults to `'./action_collections.js'`. Ignored when `same_file: true`
+ *   — `same_file` is the file-layout switch; `collections_path` is just the
+ *   path the import resolves to.
  */
 export declare const generate_action_event_datas: (specs: ReadonlyArray<ActionSpecUnion>, imports: ImportBuilder, options?: {
+    same_file?: boolean;
     collections_path?: string;
     include_composables?: boolean;
 }) => string;
@@ -290,12 +301,17 @@ export declare const generate_frontend_action_handlers: (specs: ReadonlyArray<Ac
  * `ActionInputs` type import (from `collections_path`), and the
  * `ActionSpecUnion` type import.
  *
- * **Single-namespace.** Same caveat as `generate_action_specs_record` —
- * multi-source consumers use the lower-level primitives.
+ * @param options.qualify_spec - per-spec qualified identifier callback for
+ *   multi-source consumers. When set, the helper emits the callback's return
+ *   value instead of ``specs.${method}_action_spec`` in the broadcast array
+ *   and skips the default `* as specs` import — the consumer manages its own
+ *   namespace imports. `specs_module` is ignored when `qualify_spec` is set.
+ *   Single-source consumers omit it.
  */
 export declare const generate_backend_actions_api: (specs: ReadonlyArray<ActionSpecUnion>, imports: ImportBuilder, options?: {
     specs_module?: string;
     collections_path?: string;
+    qualify_spec?: (spec: ActionSpecUnion) => string;
     include_composables?: boolean;
 }) => string;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"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"}

package/dist/actions/action_codegen.js

@@ -372,6 +372,22 @@ export const ACTION_METHOD_ENUM_KINDS_ALL = new Set([
  * surfaces (`ActionMethod`, `ActionsApi`, `ActionInputs`, etc.) by default.
  */
 const filter_composables = (specs, include_composables) => include_composables ? specs : specs.filter((s) => !is_composable_action_method(s.method));
+/**
+ * Resolve the per-spec identifier qualifier used by the multi-source helpers
+ * (`generate_action_specs_record`, `generate_action_inputs_outputs`,
+ * `generate_backend_actions_api`). When `qualify_spec` is set, returns the
+ * caller's callback verbatim — the consumer is managing its own namespace
+ * imports. Otherwise, registers the default `* as specs from specs_module`
+ * import (defaulting to `'./action_specs.js'`) and returns the matching
+ * `specs.${method}_action_spec` qualifier.
+ */
+const resolve_spec_qualifier = (imports, options) => {
+    if (options?.qualify_spec)
+        return options.qualify_spec;
+    const specs_module = options?.specs_module ?? DEFAULT_SPECS_MODULE;
+    imports.add(specs_module, '* as specs');
+    return (s) => `specs.${s.method}_action_spec`;
+};
 /**
  * Emit one or more `z.enum([...])` declarations for action method names —
  * `ActionMethod`, `RequestResponseActionMethod`, `RemoteNotificationActionMethod`,
@@ -449,11 +465,12 @@ type TypedActionEvent<
  * Array<ActionSpecUnion>` value bundling every spec. Adds the `* as specs`
  * namespace import + the `ActionSpecUnion` type import.
  *
- * **Single-namespace.** Every spec is referenced as `specs.{method}_action_spec`.
- * Multi-source consumers (tx, visiones) need a per-method namespace lookup
- * and currently use lower-level primitives instead — see the `--- High-level
- * codegen helpers ---` banner above for the rationale and the planned
- * `qualify_spec?` extension point.
+ * @param options.qualify_spec - per-spec qualified identifier callback for
+ *   multi-source consumers (e.g. ``(s) => `admin_specs.${s.method}_action_spec` ``).
+ *   When set, the helper emits the callback's return value instead of
+ *   ``specs.${method}_action_spec`` and skips the default `* as specs`
+ *   import — the consumer manages its own namespace imports. `specs_module`
+ *   is ignored when `qualify_spec` is set. Single-source consumers omit it.
  */
 export const generate_action_specs_record = (specs, imports, options) => {
     const filtered = filter_composables(specs, options?.include_composables);
@@ -470,14 +487,9 @@ export interface ActionSpecs {}
 
 export const action_specs: Array<ActionSpecUnion> = Object.values(ActionSpecs);`;
     }
-    const specs_module = options?.specs_module ?? DEFAULT_SPECS_MODULE;
-    imports.add(specs_module, '* as specs');
-    const value_lines = filtered
-        .map((s) => `\t${s.method}: specs.${s.method}_action_spec,`)
-        .join('\n');
-    const type_lines = filtered
-        .map((s) => `\t${s.method}: typeof specs.${s.method}_action_spec;`)
-        .join('\n');
+    const qualify = resolve_spec_qualifier(imports, options);
+    const value_lines = filtered.map((s) => `\t${s.method}: ${qualify(s)},`).join('\n');
+    const type_lines = filtered.map((s) => `\t${s.method}: typeof ${qualify(s)};`).join('\n');
     return `/**
  * Action specifications indexed by method name.
  * These represent the complete action spec definitions.
@@ -498,8 +510,11 @@ export const action_specs: Array<ActionSpecUnion> = Object.values(ActionSpecs);`
  *
  * Adds `import {z} from 'zod';` and the `* as specs` namespace import.
  *
- * **Single-namespace.** Same caveat as `generate_action_specs_record` —
- * multi-source consumers use the lower-level primitives.
+ * @param options.qualify_spec - per-spec qualified identifier callback for
+ *   multi-source consumers. The helper appends `.input` / `.output` to the
+ *   callback's return value. When set, the helper skips the default
+ *   `* as specs` import — the consumer manages its own namespace imports —
+ *   and `specs_module` is ignored. Single-source consumers omit it.
  */
 export const generate_action_inputs_outputs = (specs, imports, options) => {
     const filtered = filter_composables(specs, options?.include_composables);
@@ -523,19 +538,14 @@ export const ActionOutputs = {} as const;
 export interface ActionOutputs {}`;
     }
     imports.add('zod', 'z');
-    const specs_module = options?.specs_module ?? DEFAULT_SPECS_MODULE;
-    imports.add(specs_module, '* as specs');
-    const inputs_value = filtered
-        .map((s) => `\t${s.method}: specs.${s.method}_action_spec.input,`)
-        .join('\n');
+    const qualify = resolve_spec_qualifier(imports, options);
+    const inputs_value = filtered.map((s) => `\t${s.method}: ${qualify(s)}.input,`).join('\n');
     const inputs_type = filtered
-        .map((s) => `\t${s.method}: z.infer<typeof specs.${s.method}_action_spec.input>;`)
-        .join('\n');
-    const outputs_value = filtered
-        .map((s) => `\t${s.method}: specs.${s.method}_action_spec.output,`)
+        .map((s) => `\t${s.method}: z.infer<typeof ${qualify(s)}.input>;`)
         .join('\n');
+    const outputs_value = filtered.map((s) => `\t${s.method}: ${qualify(s)}.output,`).join('\n');
     const outputs_type = filtered
-        .map((s) => `\t${s.method}: z.infer<typeof specs.${s.method}_action_spec.output>;`)
+        .map((s) => `\t${s.method}: z.infer<typeof ${qualify(s)}.output>;`)
         .join('\n');
     return `/**
  * Action parameter schemas indexed by method name.
@@ -570,12 +580,16 @@ ${outputs_type}
  *
  * Adds the per-kind data type imports (only the kinds that appear in `specs`).
  *
- * @param options.collections_path - when set, adds `ActionInputs` /
- *   `ActionOutputs` type imports from this path. Leave unset (default) when
- *   the producer emits `ActionEventDatas` in the same file as
- *   `ActionInputs` / `ActionOutputs` — same-file scope means no imports
- *   needed (the zzz pattern, where `generate_action_inputs_outputs` and
- *   this helper feed the same `action_collections.ts` output).
+ * @param options.same_file - when `true` (default), assumes `ActionInputs` /
+ *   `ActionOutputs` are in the same module as the emitted `ActionEventDatas`
+ *   and adds no import (the zzz pattern, where `generate_action_inputs_outputs`
+ *   and this helper feed the same `action_collections.ts` output). When
+ *   `false`, adds `ActionInputs` / `ActionOutputs` type imports from
+ *   `collections_path`.
+ * @param options.collections_path - import path used when `same_file: false`.
+ *   Defaults to `'./action_collections.js'`. Ignored when `same_file: true`
+ *   — `same_file` is the file-layout switch; `collections_path` is just the
+ *   path the import resolves to.
  */
 export const generate_action_event_datas = (specs, imports, options) => {
     const filtered = filter_composables(specs, options?.include_composables);
@@ -589,8 +603,10 @@ export const generate_action_event_datas = (specs, imports, options) => {
  */
 export interface ActionEventDatas {}`;
     }
-    if (options?.collections_path) {
-        imports.add_types(options.collections_path, 'ActionInputs', 'ActionOutputs');
+    const same_file = options?.same_file ?? true;
+    if (!same_file) {
+        const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
+        imports.add_types(collections_path, 'ActionInputs', 'ActionOutputs');
     }
     const lines = filtered.map((spec) => {
         const data_type = spec.kind === 'request_response'
@@ -702,8 +718,12 @@ ${lines};
  * `ActionInputs` type import (from `collections_path`), and the
  * `ActionSpecUnion` type import.
  *
- * **Single-namespace.** Same caveat as `generate_action_specs_record` —
- * multi-source consumers use the lower-level primitives.
+ * @param options.qualify_spec - per-spec qualified identifier callback for
+ *   multi-source consumers. When set, the helper emits the callback's return
+ *   value instead of ``specs.${method}_action_spec`` in the broadcast array
+ *   and skips the default `* as specs` import — the consumer manages its own
+ *   namespace imports. `specs_module` is ignored when `qualify_spec` is set.
+ *   Single-source consumers omit it.
  */
 export const generate_backend_actions_api = (specs, imports, options) => {
     const composable_filtered = filter_composables(specs, options?.include_composables);
@@ -722,16 +742,15 @@ export interface BackendActionsApi {}
 
 export const broadcast_action_specs: ReadonlyArray<ActionSpecUnion> = [];`;
     }
-    const specs_module = options?.specs_module ?? DEFAULT_SPECS_MODULE;
     const collections_path = options?.collections_path ?? DEFAULT_COLLECTIONS_PATH;
-    imports.add(specs_module, '* as specs');
     imports.add_type(collections_path, 'ActionInputs');
+    const qualify = resolve_spec_qualifier(imports, options);
     const interface_body = '\n' +
         broadcast
             .map((s) => `\t${s.method}: (input: ActionInputs['${s.method}']) => Promise<void>;`)
             .join('\n') +
         '\n';
-    const array_body = '\n' + broadcast.map((s) => `\tspecs.${s.method}_action_spec,`).join('\n') + '\n';
+    const array_body = '\n' + broadcast.map((s) => `\t${qualify(s)},`).join('\n') + '\n';
     return `${interface_doc}
 export interface BackendActionsApi {${interface_body}}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",