@cosmicdrift/kumiko-framework 0.363.0 → 0.364.0

package/dist/engine/boot-validator/handler-field-references.js

@@ -1,4 +1,4 @@
-import { handlerFieldReference } from "../handler-field-references.js";
+import { readHandlerFieldReference } from "../handler-field-references.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { getZodObjectShape } from "./zod-shape.js";
 function validateHandlerGroup(feature, featureMap, handlers, handlerNoun) {
@@ -7,15 +7,25 @@ function validateHandlerGroup(feature, featureMap, handlers, handlerNoun) {
         if (shape === undefined)
             continue;
         for (const fieldName of Object.keys(shape)) {
-            const reference = handlerFieldReference(def.schema, fieldName);
-            if (reference === undefined)
+            const where = `Input field "${fieldName}" of ${handlerNoun} "${handlerName}"`;
+            const reading = readHandlerFieldReference(def.schema, fieldName);
+            if (reading.kind === "none")
                 continue;
-            const target = parseRefTarget(reference, feature.name);
-            const targetEntities = featureMap.get(target.featureName)?.entities;
-            if (targetEntities?.[target.entityName] !== undefined)
-                continue;
-            throw new Error(`[Feature ${feature.name}] Input field "${fieldName}" of ${handlerNoun} "${handlerName}" has meta references: "${reference}", ` +
-                `which is not a registered entity. Use "<entity>" for this feature or "<feature>:<entity>" for another one.`);
+            if (reading.kind === "invalid") {
+                throw new Error(`[Feature ${feature.name}] ${where} has an invalid meta references value ${JSON.stringify(reading.raw)}. ` +
+                    `Use "<entity>", "<feature>:<entity>" or { entity, by? }.`);
+            }
+            const { entity, by } = reading.reference;
+            const target = parseRefTarget(entity, feature.name);
+            const targetEntity = featureMap.get(target.featureName)?.entities?.[target.entityName];
+            if (targetEntity === undefined) {
+                throw new Error(`[Feature ${feature.name}] ${where} has meta references: "${entity}", ` +
+                    `which is not a registered entity. Use "<entity>" for this feature or "<feature>:<entity>" for another one.`);
+            }
+            if (by !== undefined && targetEntity.fields[by] === undefined) {
+                throw new Error(`[Feature ${feature.name}] ${where} references entity "${entity}" by "${by}", ` +
+                    `but that entity has no field "${by}". Use an existing field of that entity for "by".`);
+            }
         }
     }
 }

package/dist/engine/boot-validator/i18n-keys.js

@@ -76,13 +76,13 @@ export function validateI18nSurfaceKeys(features) {
             if (isFrameworkOwnedI18nKey(key))
                 continue;
             if (!hasDefinedTranslation(defined, key)) {
-                throw new Error(`[i18n] Feature "${feature.name}": required translation key missing: "${key}"`);
+                throw new Error(`[i18n] Feature "${feature.name}": required translation key missing: "${key}". Add it via r.translations(...) in this feature.`);
             }
         }
     }
     for (const key of requiredKeysFromGeneratedConfigHub(generatedConfigHub)) {
         if (!hasDefinedTranslation(defined, key)) {
-            throw new Error(`[i18n] Settings-Hub: required translation key missing: "${key}"`);
+            throw new Error(`[i18n] Settings-Hub: required translation key missing: "${key}". Add it via r.translations(...) in the owning feature.`);
         }
     }
 }

package/dist/engine/boot-validator/nav.js

@@ -83,7 +83,7 @@ export function validateNavCycles(allNavQns) {
     const stack = new Set();
     function visit(qualified, path) {
         if (stack.has(qualified)) {
-            throw new Error(`[Kumiko Nav] Nav entry parent cycle detected: ${[...path, qualified].join(" → ")}`);
+            throw new Error(`[Kumiko Nav] Nav entry parent cycle detected: ${[...path, qualified].join(" → ")}. Change or remove the parent of one entry in the cycle.`);
         }
         // skip: already visited — cycle-detection only needs to traverse each
         // node once, and the `stack` check above catches any actual cycles

package/dist/engine/boot-validator/pii-retention.js

@@ -50,7 +50,7 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
         for (const [subName, subField] of Object.entries(field.schema)) {
             if ("writeOnly" in subField && subField.writeOnly === true) {
                 // @cast-boundary schema-walk
-                throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields.`);
+                throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields. Remove writeOnly from the sub-field or declare it on a top-level text field.`);
             }
         }
         // skip: embedded fields carry no writeOnly of their own; sub-fields are checked above
@@ -61,7 +61,7 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
     if (flags.writeOnly !== true)
         return;
     if (field.type !== "text") {
-        throw new Error(`${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields.`);
+        throw new Error(`${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields. Use a text field or remove writeOnly.`);
     }
     if (field.sensitive !== true) {
         throw new Error(`${where} declares { writeOnly: true } without { sensitive: true } — add find: "secret" (ciphertext at rest, stripped from event echoes).`);
@@ -69,7 +69,7 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
     for (const flag of WRITE_ONLY_FORBIDDEN_FLAGS) {
         const value = flags[flag];
         if (value !== undefined && value !== false) {
-            throw new Error(`${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up.`);
+            throw new Error(`${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up. Remove either writeOnly or the conflicting flag.`);
         }
     }
 }
@@ -89,7 +89,7 @@ function validatePersonalJsonbField(featureName, entityName, entity, fieldName,
     const flags = field; // @cast-boundary schema-walk
     for (const flag of JSONB_PERSONAL_FORBIDDEN_FLAGS) {
         if (flags[flag] !== undefined && flags[flag] !== false) {
-            throw new Error(`${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}.`);
+            throw new Error(`${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}. Remove the ${flag} flag or the personal annotation.`);
         }
     }
     const index = entity.indexes?.find((def) => def.columns.includes(fieldName));
@@ -151,7 +151,7 @@ export function validatePiiAndRetention(feature) {
             // zweite (deterministische!) Kopie ohne Nutzen.
             if (annot.lookupable === true) {
                 if (field.type !== "text") {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") but has type "${field.type}" — blind-index equality lookups only apply to text fields.`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") but has type "${field.type}" — blind-index equality lookups only apply to text fields. Use a text field or set find: "none".`);
                 }
                 if (annotCount === 0) {
                     throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares find: "exact" (or "fuzzy") without a subject annotation (personal: "self" / "tenant" / { of: "<field>" }). Plaintext fields don't need a blind index — add personal or set find: "none".`);
@@ -188,7 +188,7 @@ export function validatePiiAndRetention(feature) {
             if (annot.userOwned) {
                 const ownerName = annot.userOwned.ownerField;
                 if (!ownerName || typeof ownerName !== "string") {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has personal: { of: ... } without an owner field name`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has personal: { of: ... } without an owner field name. Pass the name of the owner field: personal: { of: "<ownerField>" }.`);
                 }
                 const ownerField = fieldsByName[ownerName];
                 if (!ownerField) {
@@ -205,7 +205,7 @@ export function validatePiiAndRetention(feature) {
                 }
                 const { whenAbsent } = annot.userOwned;
                 if (whenAbsent !== undefined && whenAbsent !== "tenant") {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" (no plaintext fallback for stored PII).`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant".`);
                 }
                 if (ownerField.required !== true && whenAbsent === undefined) {
                     throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" is personal: { of: "${ownerName}" }, but "${ownerName}" is not required — rows without an owner would fail to encrypt (SubjectResolutionError, HTTP 500) on update, delete and forget. Declare { personal: { of: "${ownerName}", whenAbsent: "tenant" } } to encrypt those rows under the tenant key, or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`);
@@ -259,7 +259,7 @@ export function validatePiiAndRetention(feature) {
         if (retention) {
             if (!KEEP_FOR_PATTERN.test(retention.keepFor)) {
                 // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-                console.warn(`[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.keepFor="${retention.keepFor}" hat ungueltiges Format. Erwartet: <Zahl><h|d|w|m|y> (z.B. "30d", "10y", "6m"). Cleanup-Job (Sprint 2) wird das nicht parsen koennen.`);
+                console.warn(`[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.keepFor="${retention.keepFor}" has an invalid format. Expected: <number><h|d|w|m|y> (e.g. "30d", "10y", "6m"). The cleanup job cannot parse anything else; fix keepFor.`);
             }
             if (retention.reference !== undefined) {
                 const refName = retention.reference;

package/dist/engine/boot-validator/projection-list-screens.js

@@ -32,7 +32,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers) {
     const prefix = `[projectionList] Feature "${feature.name}" screen "${screen.id}"`;
     const schema = queryHandlers.get(screen.query)?.schema;
     if (screen.searchable === true && !schemaAccepts(schema, "search")) {
-        throw new Error(`${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema`);
+        throw new Error(`${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema. Add a "search" field to the query schema or remove searchable: true.`);
     }
     if (screen.searchable === false &&
         schemaAccepts(schema, "search") &&
@@ -52,7 +52,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers) {
     const searchActive = screen.searchable !== false && schemaAccepts(schema, "search");
     const sortActive = schemaAccepts(schema, "sort");
     if ((searchActive || sortActive) && screen.defaultSort === undefined) {
-        throw new Error(`${prefix}: defaultSort required when search or sort is active`);
+        throw new Error(`${prefix}: defaultSort required when search or sort is active. Set defaultSort: { field, direction }.`);
     }
     validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
     validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
@@ -97,7 +97,7 @@ function validateProjectionListDateRangeFacets(prefix, screen, schema) {
             continue;
         if (facet.params.from === facet.params.to) {
             throw new Error(`${prefix}: dateRange facet on "${facet.field}" names the same param ` +
-                `"${facet.params.from}" for both bounds.`);
+                `"${facet.params.from}" for both bounds. Use two different param names for from and to.`);
         }
         for (const param of [facet.params.from, facet.params.to]) {
             if (RESERVED_LIST_PAYLOAD_KEYS.has(param)) {
@@ -106,7 +106,7 @@ function validateProjectionListDateRangeFacets(prefix, screen, schema) {
             }
             if (usedParams.has(param)) {
                 throw new Error(`${prefix}: dateRange facet on "${facet.field}" names "${param}" which another dateRange ` +
-                    `facet on this screen already uses — the facets would overwrite each other's bound.`);
+                    `facet on this screen already uses — the facets would overwrite each other's bound. Give each dateRange facet its own param names.`);
             }
             usedParams.add(param);
             if (schemaAccepts(schema, param))
@@ -144,7 +144,7 @@ function validateRelatedListSearchable(prefix, section, schema) {
     // skip: not searchable, or the schema already accepts search — nothing to reject.
     if (section.searchable !== true || schemaAccepts(schema, "search"))
         return;
-    throw new Error(`${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema`);
+    throw new Error(`${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema. Add a "search" field to the query schema or remove searchable: true.`);
 }
 function validateRelatedListFacets(prefix, section, schema) {
     // skip: no facets declared — nothing to reject.

package/dist/engine/boot-validator/query-output-columns.js

@@ -73,7 +73,7 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
     const prefix = `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`;
     // @wrapper-known semantic-alias
     const checkHeaderField = (part, field) => {
-        checkFieldExists(recordShape, field, () => `${prefix} header.${part} references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+        checkFieldExists(recordShape, field, () => `${prefix} header.${part} references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     };
     if (screen.header !== undefined) {
         checkHeaderField("title", screen.header.title);
@@ -103,11 +103,11 @@ function checkProjectionDetailOutputFields(queryHandlers, featureName, screenId,
     }
     if (screen.recordTitleField !== undefined) {
         const field = screen.recordTitleField;
-        checkFieldExists(recordShape, field, () => `${prefix} recordTitleField references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+        checkFieldExists(recordShape, field, () => `${prefix} recordTitleField references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     }
     for (const metric of screen.metrics ?? []) {
         const field = metricField(metric);
-        checkFieldExists(recordShape, field, () => `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+        checkFieldExists(recordShape, field, () => `${prefix} metrics references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     }
     checkDetailSectionFields(recordShape, prefix, screen);
     checkRelatedListToolbarActionFields(recordShape, featureName, screenId, screen);
@@ -119,13 +119,13 @@ function checkDetailSectionFields(recordShape, prefix, screen) {
     for (const section of screen.layout.sections) {
         const countField = "countField" in section ? section.countField : undefined;
         if (countField !== undefined) {
-            checkFieldExists(recordShape, countField, () => `${prefix} section "${section.title ?? "(untitled)"}" countField references field "${countField}" which is not present in query "${screen.query}"'s outputSchema.`);
+            checkFieldExists(recordShape, countField, () => `${prefix} section "${section.title ?? "(untitled)"}" countField references field "${countField}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
         }
         if (section.kind !== undefined && section.kind !== "fields")
             continue;
         for (const entry of sectionFieldSpecs(section)) {
             const field = typeof entry === "string" ? entry : entry.field;
-            checkFieldExists(recordShape, field, () => `${prefix} section "${section.title ?? section.id ?? "(untitled)"}" references field "${field}" which is not present in query "${screen.query}"'s outputSchema.`);
+            checkFieldExists(recordShape, field, () => `${prefix} section "${section.title ?? section.id ?? "(untitled)"}" references field "${field}" which is not present in query "${screen.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
         }
     }
 }
@@ -158,7 +158,7 @@ function checkDashboardStatPanelFields(queryHandlers, featureName, screenId, pan
         // skip: this stat-panel field slot is optional and wasn't declared — nothing to validate
         if (field === undefined)
             return;
-        checkFieldExists(recordShape, field, () => `${prefix} ${part} references field "${field}" which is not present in query "${panel.query}"'s outputSchema.`);
+        checkFieldExists(recordShape, field, () => `${prefix} ${part} references field "${field}" which is not present in query "${panel.query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
     };
     checkPanelField("valueField", panel.valueField);
     checkPanelField("subField", panel.subField);
@@ -174,7 +174,7 @@ function checkVisibleWhenField(queryHandlers, visibleWhen, owner) {
     if (visibleWhen === undefined)
         return;
     const { query, field } = visibleWhen;
-    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `${owner} visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema.`);
+    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `${owner} visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema. Check the field name for a typo or add the field to the outputSchema.`);
 }
 function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen) {
     for (const panel of screen.panels) {

package/dist/engine/boot-validator/screens.d.ts

@@ -1,6 +1,6 @@
 import type { IconKey } from "@cosmicdrift/kumiko-types/nav-icon";
 import type { ConfigKeyDefinition, FeatureDefinition } from "../types/index.js";
-import type { DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, ToolbarAction } from "../types/screen.js";
+import type { ActionFormScreenDefinition, DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction } from "../types/screen.js";
 export declare function rowFieldExtractorKeys(params: RowFieldExtractor): readonly string[];
 export declare function readsNavigateParamsAsFormPrefill(target: ScreenDefinition, explicitEntityId: string | undefined, sourceScreenEntity: string | undefined): boolean;
 export declare function validateActionHasIcon(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit" | "entityList" | "projectionList", context: string, action: {
@@ -13,6 +13,7 @@ export declare function validateScreenShortIdCollisions(screensByShortId: Readon
     readonly screen: ScreenDefinition;
 }>>): void;
 export declare function resolveScreenTargetQn(featureName: string, target: string): string;
+export declare function validateDrawerPrefillKeys(where: string, targetLabel: "drawer-target" | "navigate-target", targetScreenId: string, target: ActionFormScreenDefinition | SecretMintScreenDefinition, params: RowFieldExtractor): void;
 export declare function validateScreens(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>, allWriteHandlerQns: ReadonlySet<string>, allScreenQns: ReadonlySet<string>, configKeyDefsByQn: ReadonlyMap<string, ConfigKeyDefinition>, screensByShortId: ReadonlyMap<string, ReadonlyArray<{
     readonly featureName: string;
     readonly screen: ScreenDefinition;