@cosmicdrift/kumiko-framework 0.154.0 → 0.154.2

package/src/engine/feature-entity-handlers.ts

@@ -3,6 +3,7 @@ import { toTableName } from "../db/table-builder";
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-handler";
 import { type RegisterEntityCrudOptions, registerEntityCrud } from "./entity-handlers";
 import type { FeatureBuilderState } from "./feature-builder-state";
+import { splitNamedDefinition } from "./object-form";
 import type {
   AccessRule,
   EntityDefinition,
@@ -57,13 +58,17 @@ export function buildEntityHandlerMethods<TName extends string>(
 ) {
   return {
     entity(
-      entityName: string,
-      definition: EntityDefinition,
+      nameOrDefinition: string | ({ readonly name: string } & EntityDefinition),
+      definition?: EntityDefinition,
       options?: { readonly table?: unknown },
     ): EntityRef {
-      state.entities[entityName] = definition;
+      const [entityName, entityDefinition] =
+        typeof nameOrDefinition === "string"
+          ? [nameOrDefinition, definition as EntityDefinition]
+          : splitNamedDefinition(nameOrDefinition);
+      state.entities[entityName] = entityDefinition;
       if (options?.table !== undefined) state.entityTables[entityName] = options.table;
-      return { name: entityName, table: definition.table ?? toTableName(entityName) };
+      return { name: entityName, table: entityDefinition.table ?? toTableName(entityName) };
     },
     crud(
       entityName: string,
@@ -73,10 +78,23 @@ export function buildEntityHandlerMethods<TName extends string>(
       registerEntityCrud(getRegistrar(), entityName, definition, options);
       return { name: entityName, table: definition.table ?? toTableName(entityName) };
     },
-    relation(entityRef: NameOrRef, relationName: string, definition: RelationDefinition): void {
+    relation(
+      entityRefOrDefinition:
+        | NameOrRef
+        | ({ readonly entity: NameOrRef; readonly name: string } & RelationDefinition),
+      relationName?: string,
+      definition?: RelationDefinition,
+    ): void {
+      const [entityRef, resolvedRelationName, resolvedDefinition] =
+        typeof entityRefOrDefinition === "object" && "entity" in entityRefOrDefinition
+          ? (() => {
+              const { entity, name: innerName, ...rest } = entityRefOrDefinition;
+              return [entity, innerName, rest as RelationDefinition] as const;
+            })()
+          : [entityRefOrDefinition, relationName as string, definition as RelationDefinition];
       const entityName = resolveName(entityRef);
       if (!state.relations[entityName]) state.relations[entityName] = {};
-      state.relations[entityName][relationName] = definition;
+      state.relations[entityName][resolvedRelationName] = resolvedDefinition;
     },
     writeHandler<TName extends string, TSchema extends ZodType>(
       nameOrDef: string | WriteHandlerDefinition<TName, TSchema>,

package/src/engine/feature-ui-extensions.ts

@@ -31,6 +31,61 @@ import type { WorkspaceDefinition } from "./types/workspace";
 
 // Builds hooks/extensions/projections/screens/nav/workspace/tables/tree-actions
 // registrar methods.
+
+type EntityWideHookType = "postSave" | "preDelete" | "postDelete" | "postQuery";
+
+function isEntityWideHookType(type: LifecycleHookType | "validation"): type is EntityWideHookType {
+  return (
+    type === LifecycleHookTypes.postSave ||
+    type === LifecycleHookTypes.preDelete ||
+    type === LifecycleHookTypes.postDelete ||
+    type === LifecycleHookTypes.postQuery
+  );
+}
+
+// r.hook(type, { allOf: entity }, fn) — "all write/query handlers of this
+// entity", replacing the old r.entityHook(type, entity, fn). Hook-fn casts
+// below: @cast-boundary engine-bridge — typed Dev-API (LifecycleHookFn) →
+// erased Map<entityName, fn>.
+function registerEntityWideHook(
+  state: FeatureBuilderState,
+  featureName: string,
+  type: EntityWideHookType,
+  entityName: string,
+  fn: LifecycleHookFn,
+  options?: { phase?: HookPhase },
+): void {
+  if (type === LifecycleHookTypes.postSave) {
+    const phase = options?.phase ?? HookPhases.afterCommit;
+    if (!state.entityPostSave[entityName]) state.entityPostSave[entityName] = [];
+    state.entityPostSave[entityName].push({
+      fn: fn as PostSaveHookFn,
+      phase,
+      featureName,
+    }); // @cast-boundary engine-bridge
+  } else if (type === LifecycleHookTypes.preDelete) {
+    if (!state.entityPreDelete[entityName]) state.entityPreDelete[entityName] = [];
+    state.entityPreDelete[entityName].push({
+      fn: fn as PreDeleteHookFn, // @cast-boundary engine-bridge
+      phase: HookPhases.inTransaction,
+      featureName,
+    });
+  } else if (type === LifecycleHookTypes.postDelete) {
+    const phase = options?.phase ?? HookPhases.afterCommit;
+    if (!state.entityPostDelete[entityName]) state.entityPostDelete[entityName] = [];
+    state.entityPostDelete[entityName].push({
+      fn: fn as PostDeleteHookFn,
+      phase,
+      featureName,
+    }); // @cast-boundary engine-bridge
+  } else {
+    // postQuery is unphased (no inTransaction/afterCommit semantics — fires
+    // synchronously after query-handler-execute, before field-access-filter)
+    if (!state.entityPostQuery[entityName]) state.entityPostQuery[entityName] = [];
+    state.entityPostQuery[entityName].push({ fn: fn as PostQueryHookFn, featureName }); // @cast-boundary engine-bridge
+  }
+}
+
 export function buildUiExtensionsMethods<TName extends string>(
   state: FeatureBuilderState,
   name: TName,
@@ -38,10 +93,36 @@ export function buildUiExtensionsMethods<TName extends string>(
   return {
     hook(
       type: LifecycleHookType | "validation",
-      target: NameOrRef | readonly NameOrRef[],
+      target: NameOrRef | readonly NameOrRef[] | { readonly allOf: NameOrRef },
       fn: LifecycleHookFn | ValidationHookFn,
       options?: { phase?: HookPhase },
     ): void {
+      // Entity-wide target ("all write/query handlers of this entity") —
+      // replaces the old r.entityHook(type, entity, fn).
+      if (
+        typeof target === "object" &&
+        target !== null &&
+        !Array.isArray(target) &&
+        "allOf" in target
+      ) {
+        if (!isEntityWideHookType(type)) {
+          throw new Error(
+            `[Feature ${name}] r.hook("${type}", { allOf }, ...) only supports ` +
+              `postSave/preDelete/postDelete/postQuery, not "${type}".`,
+          );
+        }
+        registerEntityWideHook(
+          state,
+          name,
+          type,
+          resolveName(target.allOf),
+          fn as LifecycleHookFn,
+          options,
+        );
+        // skip: entity-wide target fully handled above, nothing more to do
+        return;
+      }
+
       const targets = Array.isArray(target) ? target : [target];
       const names = targets.map(resolveName);
 
@@ -81,43 +162,6 @@ export function buildUiExtensionsMethods<TName extends string>(
         bucket[n].push({ fn: fn as LifecycleHookFn, phase, featureName: name }); // @cast-boundary engine-bridge
       }
     },
-    entityHook(
-      type: "postSave" | "preDelete" | "postDelete" | "postQuery",
-      entityRef: NameOrRef,
-      fn: LifecycleHookFn,
-      options?: { phase?: HookPhase },
-    ): void {
-      const entityName = resolveName(entityRef);
-      if (type === LifecycleHookTypes.postSave) {
-        const phase = options?.phase ?? HookPhases.afterCommit;
-        if (!state.entityPostSave[entityName]) state.entityPostSave[entityName] = [];
-        state.entityPostSave[entityName].push({
-          fn: fn as PostSaveHookFn,
-          phase,
-          featureName: name,
-        }); // @cast-boundary engine-bridge
-      } else if (type === LifecycleHookTypes.preDelete) {
-        if (!state.entityPreDelete[entityName]) state.entityPreDelete[entityName] = [];
-        state.entityPreDelete[entityName].push({
-          fn: fn as PreDeleteHookFn, // @cast-boundary engine-bridge
-          phase: HookPhases.inTransaction,
-          featureName: name,
-        });
-      } else if (type === LifecycleHookTypes.postDelete) {
-        const phase = options?.phase ?? HookPhases.afterCommit;
-        if (!state.entityPostDelete[entityName]) state.entityPostDelete[entityName] = [];
-        state.entityPostDelete[entityName].push({
-          fn: fn as PostDeleteHookFn,
-          phase,
-          featureName: name,
-        }); // @cast-boundary engine-bridge
-      } else if (type === LifecycleHookTypes.postQuery) {
-        // postQuery is unphased (no inTransaction/afterCommit semantics — fires
-        // synchronously after query-handler-execute, before field-access-filter)
-        if (!state.entityPostQuery[entityName]) state.entityPostQuery[entityName] = [];
-        state.entityPostQuery[entityName].push({ fn: fn as PostQueryHookFn, featureName: name }); // @cast-boundary engine-bridge
-      }
-    },
     searchPayloadExtension(entityRef: NameOrRef, fn: SearchPayloadContributorFn): void {
       const entityName = resolveName(entityRef);
       if (!state.searchPayloadExtensions[entityName])
@@ -128,11 +172,24 @@ export function buildUiExtensionsMethods<TName extends string>(
       state.registrarExtensions[extensionName] = def;
     },
     useExtension(
-      extensionName: string,
-      entityRef: NameOrRef,
+      extensionNameOrDefinition:
+        | string
+        | ({ readonly name: string; readonly entity: NameOrRef } & Record<string, unknown>),
+      entityRef?: NameOrRef,
       options?: Record<string, unknown>,
     ): void {
-      state.extensionUsages.push({ extensionName, entityName: resolveName(entityRef), options });
+      const [extensionName, resolvedEntityRef, resolvedOptions] =
+        typeof extensionNameOrDefinition === "string"
+          ? [extensionNameOrDefinition, entityRef as NameOrRef, options]
+          : (() => {
+              const { name, entity, ...rest } = extensionNameOrDefinition;
+              return [name, entity, rest] as const;
+            })();
+      state.extensionUsages.push({
+        extensionName,
+        entityName: resolveName(resolvedEntityRef),
+        options: resolvedOptions,
+      });
     },
     extensionSelector(extensionName: string, key: { readonly name: string } | string): void {
       if (state.extensionSelectors.some((s) => s.extensionName === extensionName)) {
@@ -232,14 +289,28 @@ export function buildUiExtensionsMethods<TName extends string>(
       state.entityProjectionExtensions[entityName] = list;
     },
     referenceData(
-      entityRef: NameOrRef,
-      data: readonly Record<string, unknown>[],
+      entityRefOrDefinition:
+        | NameOrRef
+        | {
+            readonly entity: NameOrRef;
+            readonly data: readonly Record<string, unknown>[];
+            readonly upsertKey?: string;
+          },
+      data?: readonly Record<string, unknown>[],
       options?: { upsertKey?: string },
     ): void {
+      const [entityRef, resolvedData, upsertKey] =
+        typeof entityRefOrDefinition === "object" && "entity" in entityRefOrDefinition
+          ? [
+              entityRefOrDefinition.entity,
+              entityRefOrDefinition.data,
+              entityRefOrDefinition.upsertKey,
+            ]
+          : [entityRefOrDefinition, data as readonly Record<string, unknown>[], options?.upsertKey];
       state.referenceData.push({
         entityName: resolveName(entityRef),
-        data,
-        upsertKey: options?.upsertKey,
+        data: resolvedData,
+        upsertKey,
       });
     },
     screen(definition: ScreenDefinition): void {

package/src/engine/object-form.ts

@@ -0,0 +1,12 @@
+// Shared helper for registrar methods that accept an Object-Form call
+// (`r.entity({ name: "item", ... })`) alongside the classic positional form
+// (`r.entity("item", { ... })`). Object-Form is the shape the feature-ast
+// renderer emits for Designer/AI-generated code — a single object argument
+// with named fields is easier to generate correctly than positional args
+// whose count/order vary per method.
+export function splitNamedDefinition<T extends { readonly name: string }>(
+  definition: T,
+): [string, Omit<T, "name">] {
+  const { name, ...rest } = definition;
+  return [name, rest];
+}

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -47,7 +47,6 @@ const ALL_KINDS: FeaturePatternKind[] = [
   "writeHandler",
   "queryHandler",
   "hook",
-  "entityHook",
   "job",
   "notification",
   "authClaims",
@@ -55,7 +54,6 @@ const ALL_KINDS: FeaturePatternKind[] = [
   "projection",
   "multiStreamProjection",
   "defineEvent",
-  "eventMigration",
   "extendsRegistrar",
   "usesApi",
   "exposesApi",
@@ -280,14 +278,6 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
         target: "x",
         fnBody: PLACEHOLDER_BODY_LOC,
       };
-    case "entityHook":
-      return {
-        kind,
-        source: PLACEHOLDER_LOC,
-        hookType: "postSave",
-        entityName: "x",
-        fnBody: PLACEHOLDER_BODY_LOC,
-      };
     case "job":
       return {
         kind,
@@ -332,15 +322,6 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
         eventName: "x",
         schemaSource: PLACEHOLDER_BODY_LOC,
       };
-    case "eventMigration":
-      return {
-        kind,
-        source: PLACEHOLDER_LOC,
-        eventName: "x",
-        fromVersion: 1,
-        toVersion: 2,
-        transformBody: PLACEHOLDER_BODY_LOC,
-      };
     case "extendsRegistrar":
       return {
         kind,

package/src/engine/pattern-library/library.ts

@@ -17,8 +17,6 @@ import type { FeaturePatternKind } from "../feature-ast/patterns";
 import {
   authClaimsSchema,
   defineEventSchema,
-  entityHookSchema,
-  eventMigrationSchema,
   hookSchema,
   httpRouteSchema,
   jobSchema,
@@ -82,7 +80,6 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   writeHandler: writeHandlerSchema,
   queryHandler: queryHandlerSchema,
   hook: hookSchema,
-  entityHook: entityHookSchema,
   job: jobSchema,
   notification: notificationSchema,
   authClaims: authClaimsSchema,
@@ -90,7 +87,6 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   projection: projectionSchema,
   multiStreamProjection: multiStreamProjectionSchema,
   defineEvent: defineEventSchema,
-  eventMigration: eventMigrationSchema,
   extendsRegistrar: extendsRegistrarSchema,
   usesApi: usesApiSchema,
   exposesApi: exposesApiSchema,

package/src/engine/pattern-library/mixed-schemas.ts

@@ -1,11 +1,6 @@
 // Mixed pattern schemas (header form + opaque body source).
 
-import {
-  accessRuleField,
-  ENTITY_HOOK_TYPE_OPTIONS,
-  HOOK_TYPE_OPTIONS,
-  HTTP_METHOD_OPTIONS,
-} from "./shared-fields";
+import { accessRuleField, HOOK_TYPE_OPTIONS, HTTP_METHOD_OPTIONS } from "./shared-fields";
 import type { PatternFormSchema } from "./types";
 
 // --- Mixed patterns (header form + opaque body source) --------------------
@@ -169,45 +164,6 @@ export const hookSchema: PatternFormSchema = {
   ],
 };
 
-export const entityHookSchema: PatternFormSchema = {
-  kind: "entityHook",
-  label: { en: "Entity hook", de: "Entity-Hook" },
-  summary: { en: "Hook scoped to a single entity (no cross-entity targets)." },
-  category: "behaviour",
-  editability: "mixed",
-  fields: [
-    {
-      path: "hookType",
-      label: { en: "Type", de: "Typ" },
-      input: "select",
-      options: ENTITY_HOOK_TYPE_OPTIONS,
-      required: true,
-    },
-    {
-      path: "entityName",
-      label: { en: "Entity", de: "Entität" },
-      input: "entity-ref",
-      required: true,
-    },
-    {
-      path: "fnBody",
-      label: { en: "Hook body (source)", de: "Hook-Body (Source)" },
-      input: "code-block",
-      language: "typescript",
-      readOnly: true,
-    },
-    {
-      path: "phase",
-      label: { en: "Phase", de: "Phase" },
-      input: "select",
-      options: [
-        { value: "inTransaction", label: { en: "In transaction" } },
-        { value: "afterCommit", label: { en: "After commit" } },
-      ],
-    },
-  ],
-};
-
 export const jobSchema: PatternFormSchema = {
   kind: "job",
   label: { en: "Job", de: "Job" },
@@ -443,42 +399,15 @@ export const defineEventSchema: PatternFormSchema = {
       input: "number",
       min: 1,
     },
-  ],
-};
-
-export const eventMigrationSchema: PatternFormSchema = {
-  kind: "eventMigration",
-  label: { en: "Event migration", de: "Event-Migration" },
-  summary: { en: "Step-wise transform between event versions." },
-  category: "data",
-  editability: "mixed",
-  fields: [
-    {
-      path: "eventName",
-      label: { en: "Event", de: "Event" },
-      input: "text",
-      required: true,
-    },
-    {
-      path: "fromVersion",
-      label: { en: "From version", de: "Von Version" },
-      input: "number",
-      min: 1,
-      required: true,
-    },
-    {
-      path: "toVersion",
-      label: { en: "To version", de: "Auf Version" },
-      input: "number",
-      min: 2,
-      required: true,
-    },
     {
-      path: "transformBody",
-      label: { en: "Transform (source)", de: "Transform (Source)" },
-      input: "code-block",
-      language: "typescript",
-      readOnly: true,
+      path: "migrations",
+      label: {
+        en: "Migrations (fromVersion → transform)",
+        de: "Migrationen (fromVersion → Transform)",
+      },
+      input: "key-value-map",
+      keyPlaceholder: "1",
+      valueInput: "code-block",
     },
   ],
 };

package/src/engine/pattern-library/shared-fields.ts

@@ -11,12 +11,7 @@ export const HOOK_TYPE_OPTIONS = [
   { value: "preDelete", label: { en: "Pre-Delete", de: "Vor Löschen" } },
   { value: "postDelete", label: { en: "Post-Delete", de: "Nach Löschen" } },
   { value: "preQuery", label: { en: "Pre-Query", de: "Vor Abfrage" } },
-] as const;
-
-export const ENTITY_HOOK_TYPE_OPTIONS = [
-  { value: "postSave", label: { en: "Post-Save", de: "Nach Speichern" } },
-  { value: "preDelete", label: { en: "Pre-Delete", de: "Vor Löschen" } },
-  { value: "postDelete", label: { en: "Post-Delete", de: "Nach Löschen" } },
+  { value: "postQuery", label: { en: "Post-Query", de: "Nach Abfrage" } },
 ] as const;
 
 export const HTTP_METHOD_OPTIONS = [

package/src/engine/registry-ingest.ts

@@ -147,9 +147,14 @@ export function populateEvents(state: RegistryState, feature: FeatureDefinition)
 
 // Translations prefixed with featureName: (i18next namespace convention).
 export function populateTranslations(state: RegistryState, feature: FeatureDefinition): void {
-  // Translations prefixed with featureName: (i18next namespace convention)
+  // Translations prefixed with featureName: (i18next namespace convention).
+  // Keys that already carry the feature's own namespace prefix (e.g. a nav
+  // label referencing "cap-counter:nav.cap-list" verbatim) must NOT be
+  // re-prefixed, else server-side t() can never resolve them (#1105).
+  const prefix = `${feature.name}:`;
   for (const [key, value] of Object.entries(feature.translations ?? {})) {
-    state.mergedTranslations[`${feature.name}:${key}`] = value;
+    const qualifiedKey = key.startsWith(prefix) ? key : `${prefix}${key}`;
+    state.mergedTranslations[qualifiedKey] = value;
   }
 }
 

package/src/engine/registry-validate.ts

@@ -314,23 +314,23 @@ export function validateEventMigrationVersions(
   features: readonly FeatureDefinition[],
 ): void {
   // Build + validate event upcaster chains. Run AFTER all features are
-  // ingested so r.eventMigration calls can reference events from any
-  // feature (same feature in practice, but the check stays lax for future
-  // cross-feature event packs).
+  // ingested so defineEvent's `migrations` option can reference events from
+  // any feature (same feature in practice, but the check stays lax for
+  // future cross-feature event packs).
   for (const feature of features) {
     for (const [shortName, migrations] of Object.entries(feature.eventMigrations ?? {})) {
       const qualified = qualify(feature.name, "event", shortName);
       const eventDef = state.eventMap.get(qualified);
       if (!eventDef) {
         throw new Error(
-          `Feature "${feature.name}" registered r.eventMigration for "${shortName}" ` +
+          `Feature "${feature.name}" has migrations declared for event "${shortName}" ` +
             `but no r.defineEvent exists for that name. Register the event first.`,
         );
       }
       for (const m of migrations) {
         if (m.toVersion > eventDef.version) {
           throw new Error(
-            `Feature "${feature.name}" has r.eventMigration("${shortName}", ${m.fromVersion}, ${m.toVersion}) ` +
+            `Feature "${feature.name}" declares a migration for event "${shortName}" from v${m.fromVersion} to v${m.toVersion} ` +
               `but r.defineEvent declares only version ${eventDef.version}. ` +
               `Bump the version in defineEvent to at least ${m.toVersion}, or remove the migration.`,
           );
@@ -364,7 +364,7 @@ export function buildEventUpcasterChains(
         if (!chainMap.has(v)) {
           throw new Error(
             `Event "${qualified}" declares version ${eventDef.version} but no migration ` +
-              `covers the step v${v} → v${v + 1}. Register r.eventMigration("${qualified.split(":").pop() ?? qualified}", ${v}, ${v + 1}, transform) ` +
+              `covers the step v${v} → v${v + 1}. Add { fromVersion: ${v}, toVersion: ${v + 1}, transform } to r.defineEvent("${qualified.split(":").pop() ?? qualified}", ...)'s migrations array ` +
               `so stored v${v} payloads can be upcast on read.`,
           );
         }