@cosmicdrift/kumiko-framework 0.400.0 → 0.402.0

package/dist/files/rebind-file-ref.js

@@ -0,0 +1,170 @@
+import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
+import { isFrameworkSystemUser } from "../db/lock-guard.js";
+import { selectRowForUpdateById } from "../db/queries/entity-read.js";
+import { asEntityTableMeta } from "../db/table-introspection.js";
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { RecordLockedError } from "../errors/classes.js";
+import { AccessDeniedError, InternalError, NotFoundError, reraiseAsKumikoError, } from "../errors/index.js";
+import { assertRowFitsBindTarget } from "./bind-pending-file-refs.js";
+import { canCallerReadFileRef } from "./can-caller-read-file-ref.js";
+import { getFileRefExecutor } from "./create-file-ref.js";
+import { loadFileRefRows } from "./load-save-file-refs.js";
+import { createRecordReadCheck } from "./record-read-check.js";
+import { createRecordWriteCheck, findImplicitEntityTable, RecordWriteDecisions, } from "./record-write-check.js";
+const CONCURRENT_WRITE_ERROR_CODES = ["version_conflict", "unique_violation"];
+function nullableString(value) {
+    return value === null || typeof value === "string";
+}
+// The file guard (and an app's accessGuard) reads these columns; a row missing one is corrupt.
+async function loadRow(ctx, fileRefId) {
+    if (!isUuid(fileRefId))
+        return undefined;
+    const row = (await loadFileRefRows(ctx.db, [fileRefId], ctx.user.tenantId)).get(fileRefId);
+    if (row === undefined)
+        return undefined;
+    const { tenantId, storageKey, fileName, mimeType, size, entityType, entityId, fieldName } = row;
+    const { insertedById, version } = row;
+    if (typeof tenantId !== "string" ||
+        typeof storageKey !== "string" ||
+        typeof fileName !== "string" ||
+        typeof mimeType !== "string" ||
+        typeof size !== "number" ||
+        typeof version !== "number" ||
+        !nullableString(entityType) ||
+        !nullableString(entityId) ||
+        !nullableString(fieldName) ||
+        !nullableString(insertedById)) {
+        return undefined;
+    }
+    return {
+        fileRef: {
+            id: fileRefId,
+            tenantId,
+            storageKey,
+            fileName,
+            mimeType,
+            size,
+            entityType,
+            entityId,
+            fieldName,
+            insertedById,
+        },
+        version,
+    };
+}
+function isOwnedBy(fileRef, owner) {
+    return (fileRef.entityType === owner.entityType &&
+        fileRef.entityId === owner.entityId &&
+        fileRef.fieldName === owner.fieldName);
+}
+// Holds the source row until commit, so a lock or ownership change committed by another
+// transaction is either seen by the write check below or waits for this rebind to finish.
+async function lockSourceRow(ctx, from) {
+    const table = findImplicitEntityTable(ctx.registry, from.entityType);
+    const tableName = asEntityTableMeta(table)?.tableName;
+    // skip: no stored row to lock; the write check below answers not_found for it
+    if (tableName === undefined)
+        return;
+    await selectRowForUpdateById(tenantDbRunner(ctx.db), tableName, from.entityId);
+}
+// A caller other than the system job must be able to read the file today and must be able to
+// write both records as a save of them would: the source it takes the file from (unlocked, and
+// with an update handler the caller passes; without one only the system job may move the file),
+// and the target field it puts the file into.
+async function assertCallerMayMove(ctx, fileRef, from, to) {
+    if (!(await canCallerReadFileRef(ctx, fileRef))) {
+        throw new AccessDeniedError({ message: `rebindFileRef: file ${fileRef.id} is not readable` });
+    }
+    const canWriteRecord = createRecordWriteCheck({
+        registry: ctx.registry,
+        canReadRecord: createRecordReadCheck(ctx.registry, (qn, payload) => ctx.dispatch.query(qn, payload)),
+        tenantDbFor: () => ctx.db,
+    });
+    await lockSourceRow(ctx, from);
+    const sourceDecision = await canWriteRecord({ ...from, user: ctx.user });
+    if (sourceDecision === RecordWriteDecisions.locked) {
+        throw new RecordLockedError({ entityName: from.entityType, entityId: from.entityId });
+    }
+    if (sourceDecision !== RecordWriteDecisions.writable) {
+        throw new AccessDeniedError({
+            message: `rebindFileRef: source ${from.entityType}.${from.fieldName} of ${from.entityId} is not writable`,
+            details: { decision: sourceDecision },
+        });
+    }
+    const decision = await canWriteRecord({ ...to, user: ctx.user });
+    if (decision !== RecordWriteDecisions.writable) {
+        throw new AccessDeniedError({
+            message: `rebindFileRef: ${to.entityType}.${to.fieldName} of ${to.entityId} is not writable`,
+            details: { decision },
+        });
+    }
+}
+// The caller checks find the target as a side effect; the system path needs its own lookup so a
+// job cannot point a file at a record that does not exist in its tenant.
+async function assertTargetRecordExists(ctx, to) {
+    const entity = ctx.registry.getEntity(to.entityType);
+    const table = findImplicitEntityTable(ctx.registry, to.entityType);
+    const row = entity === undefined || table === undefined
+        ? undefined
+        : await ctx.db.fetchOne(table, {
+            id: to.entityId,
+            ...(entity.softDelete === true && { isDeleted: false }),
+        });
+    if (row === undefined)
+        throw new NotFoundError(to.entityType, to.entityId);
+}
+/**
+ * Moves a bound file from one record's file field to another's, for a record that takes over a
+ * file uploaded elsewhere (an upload record, a mail attachment). Server code only; pending uploads
+ * go through bindPendingFileRef.
+ *
+ * Only files of the caller's tenant are found ("not-found" otherwise, as for unknown ids). The
+ * file must still sit at `from`; "moved" means it does not (any more), for example because a
+ * parallel rebind took it first. A file already at `to` answers "rebound" without a write. The
+ * target must be a registered file field whose accept/maxSize the file fits (InternalError /
+ * UnprocessableError). Unless the caller is the framework system user, the caller must be able
+ * to read the file and to write both the source record and field (it must not be locked, and an
+ * entity without update handler leaves the move to the system user) and the target record and
+ * field (AccessDeniedError, RecordLockedError); the system user skips these checks, and only the
+ * target record has to exist (NotFoundError). The update is checked against the file's stream
+ * version read here, so a bind committing in between returns "version-conflict"; the source row
+ * stays locked until the surrounding transaction commits, so a lock set on `from` in between is
+ * either seen or waits. Rebind first, then save the id into
+ * the target field: the save accepts a file already bound to that record, and the source record
+ * no longer disposes of it when its field is cleared or the record is deleted.
+ * A handler passes its ctx; a job passes `{ db, registry, user: ctx.systemUser }`.
+ */
+export async function rebindFileRef(ctx, args) {
+    const { fileRefId, from, to } = args;
+    const loaded = await loadRow(ctx, fileRefId);
+    if (loaded === undefined)
+        return "not-found";
+    const { fileRef, version } = loaded;
+    if (isOwnedBy(fileRef, to))
+        return "rebound";
+    if (!isOwnedBy(fileRef, from))
+        return "moved";
+    assertRowFitsBindTarget(ctx.registry, { entityName: to.entityType, fieldName: to.fieldName }, fileRef);
+    if (isFrameworkSystemUser(ctx.user)) {
+        await assertTargetRecordExists(ctx, to);
+    }
+    else {
+        const { dispatch } = ctx;
+        if (dispatch === undefined) {
+            throw new InternalError({
+                message: "rebindFileRef: a caller other than the system user needs ctx.dispatch.query",
+            });
+        }
+        await assertCallerMayMove({ ...ctx, dispatch }, fileRef, from, to);
+    }
+    const moved = await getFileRefExecutor().update({
+        id: fileRefId,
+        version,
+        changes: { entityType: to.entityType, entityId: to.entityId, fieldName: to.fieldName },
+    }, ctx.user, ctx.db);
+    if (moved.isSuccess)
+        return "rebound";
+    if (CONCURRENT_WRITE_ERROR_CODES.includes(moved.error.code))
+        return "version-conflict";
+    throw reraiseAsKumikoError(moved.error);
+}

package/dist/i18n/required-surface-keys.d.ts

@@ -56,3 +56,9 @@ export type RequiredLocaleGap = {
  * reported as gap owners.
  */
 export declare function findRequiredLocaleGaps(features: readonly FeatureDefinition[], requiredLocales: readonly string[]): readonly RequiredLocaleGap[];
+export declare function embeddedCellLabelKey(featureName: string, entityName: string, fieldName: string, subFieldName: string): string;
+export declare function embeddedCellOptionLabelKey(featureName: string, entityName: string, fieldName: string, subFieldName: string, value: string): string;
+/** Keys for select option labels and embedded-list cells that the screens of one feature
+ *  display. Opt-in via `requireFieldValueTranslations`: without them the renderer falls back
+ *  to the raw option value or sub-field name. */
+export declare function fieldValueTranslationKeysFromFeature(feature: FeatureDefinition): readonly string[];

package/dist/i18n/required-surface-keys.js

@@ -480,6 +480,9 @@ export function requiredKeysFromFeature(feature) {
         for (const key of requiredKeysFromNav(nav))
             out.add(key);
     }
+    for (const collection of Object.values(feature.contentCollections ?? {})) {
+        pushKey(out, collection.nav.entryLabel);
+    }
     for (const ws of Object.values(feature.workspaces)) {
         for (const key of requiredKeysFromWorkspace(ws))
             out.add(key);
@@ -596,3 +599,64 @@ export function findRequiredLocaleGaps(features, requiredLocales) {
     }
     return gaps;
 }
+export function embeddedCellLabelKey(featureName, entityName, fieldName, subFieldName) {
+    return `${fieldLabelKey(featureName, entityName, fieldName)}:cell:${subFieldName}`;
+}
+export function embeddedCellOptionLabelKey(featureName, entityName, fieldName, subFieldName, value) {
+    return `${embeddedCellLabelKey(featureName, entityName, fieldName, subFieldName)}:option:${value}`;
+}
+function pushFieldValueTranslationKeys(out, featureName, entityName, fieldName, def, includeEmbeddedCells) {
+    if (def.type === "select" || def.type === "multiSelect") {
+        for (const value of def.options) {
+            out.add(selectFacetOptionKey(featureName, entityName, fieldName, value));
+        }
+        // skip: option keys are complete, nothing else to collect for select fields
+        return;
+    }
+    // skip: only multi-row embedded fields render cell labels
+    if (!includeEmbeddedCells || def.type !== "embedded" || def.multiple !== true)
+        return;
+    for (const [subName, sub] of Object.entries(def.schema)) {
+        out.add(embeddedCellLabelKey(featureName, entityName, fieldName, subName));
+        if (sub.type !== "select")
+            continue;
+        for (const value of sub.options) {
+            out.add(embeddedCellOptionLabelKey(featureName, entityName, fieldName, subName, value));
+        }
+    }
+}
+/** Keys for select option labels and embedded-list cells that the screens of one feature
+ *  display. Opt-in via `requireFieldValueTranslations`: without them the renderer falls back
+ *  to the raw option value or sub-field name. */
+export function fieldValueTranslationKeysFromFeature(feature) {
+    const out = new Set();
+    for (const screen of Object.values(feature.screens)) {
+        if (screen.type === "entityList") {
+            const entity = feature.entities?.[screen.entity];
+            if (!entity)
+                continue;
+            for (const col of screen.columns) {
+                const { field } = normalizeListColumn(col);
+                const def = entity.fields[field];
+                if (def)
+                    pushFieldValueTranslationKeys(out, feature.name, screen.entity, field, def, false);
+            }
+        }
+        else if (screen.type === "entityEdit") {
+            const entity = feature.entities?.[screen.entity];
+            if (!entity)
+                continue;
+            for (const section of screen.layout.sections) {
+                if (isExtensionEditSection(section) || section.kind === "relatedList")
+                    continue;
+                for (const spec of sectionFieldSpecs(section)) {
+                    const field = editFieldName(spec);
+                    const def = entity.fields[field];
+                    if (def)
+                        pushFieldValueTranslationKeys(out, feature.name, screen.entity, field, def, true);
+                }
+            }
+        }
+    }
+    return [...out];
+}

package/dist/schema-cli/validate-boot-input.js

@@ -41,8 +41,10 @@ export function parseValidateBootOptions(raw) {
     const navAllowlistExempt = readOptionalOption(raw, "navAllowlistExempt", isStringSet, "a Set<string>");
     const warnOnUniqueAccessRoles = readOptionalOption(raw, "warnOnUniqueAccessRoles", isBoolean, "a boolean");
     const requiredLocales = readOptionalOption(raw, "requiredLocales", isNonEmptyStringArray, "an array of non-empty strings");
+    const requireFieldValueTranslations = readOptionalOption(raw, "requireFieldValueTranslations", isBoolean, "a boolean");
     return {
         ...(requiredLocales !== undefined && { requiredLocales }),
+        ...(requireFieldValueTranslations !== undefined && { requireFieldValueTranslations }),
         ...(navAllowlist !== undefined && { navAllowlist }),
         ...(navAllowlistExempt !== undefined && { navAllowlistExempt }),
         ...(warnOnUniqueAccessRoles !== undefined && { warnOnUniqueAccessRoles }),

package/dist/schema-cli/validate-command.js

@@ -4,7 +4,7 @@ import { assertRowLevelSecurityTableState, createDbConnection, generateMigration
 import { isLiveFrameworkTable } from "../db/known-table-names.js";
 import { readMigrationSqlTexts } from "../db/migrate-runner.js";
 import { diffReplayAgainstSnapshot, replayMigrationsDir } from "../db/replay-migration-sql.js";
-import { BootValidationError } from "../engine/boot-validator/boot-rule.js";
+import { BootValidationError, bootRuleDocLink, } from "../engine/boot-validator/boot-rule.js";
 import { validateBoot } from "../engine/boot-validator.js";
 import { describeThrown, loadPreviousSnapshot, loadSchemaModOrReport, nextSequenceNumber, SNAPSHOT_FILENAME, } from "./shared.js";
 import { featureDefinitionsOf, parseValidateBootOptions, withFileStoragePresence, } from "./validate-boot-input.js";
@@ -44,6 +44,9 @@ function reportBootViolations(out, violations) {
         out.err(`  ✗ boot [${v.ruleId}] ${v.message}`);
         if (v.fix !== undefined)
             out.err(`    Fix: ${v.fix}`);
+        const docLink = bootRuleDocLink(v.ruleId);
+        if (docLink !== undefined)
+            out.err(`    Rule: ${docLink}`);
     }
 }
 // 2. Boot validity — needs the composed feature set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.400.0",
+  "version": "0.402.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.400.0",
+    "@cosmicdrift/kumiko-types": "0.402.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.14",
     "i18next": "^26.1.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.400.0",
+    "@cosmicdrift/kumiko-testing": "0.402.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,29 @@
 [
+  {
+    "version": "0.402.0",
+    "type": "improvement",
+    "title": "Boot violations carry rule ids with a fix and a doc link",
+    "detail": "43 boot rules have an id such as `pii/subject-key-sortable` or `entity-list/default-sort-required`. A violation in `BootValidationError.violations` and in `kumiko-schema validate` (text and `--json`) carries that id instead of `unclassified/<check>`, plus a `Fix:` line and `Rule: agents/boot-rules.md#<id>`. PII field rules, entityList screen rules, missing i18n keys, API and extension usages and user-data-rights hooks now report all violations in one run. Message texts are unchanged. `@cosmicdrift/kumiko-framework/engine` exports `bootRuleError`, `BootRuleViolation`, `BootValidationError`, `collectBootRuleViolations` and the types `BootRule`, `BootRuleTable`, `BootViolation`, so a feature's `r.bootCheck` can throw a classified rule."
+  },
+  {
+    "version": "0.402.0",
+    "type": "fix",
+    "title": "Migration replay keeps tables whose name ends in \"as\"",
+    "detail": "`CREATE TABLE IF NOT EXISTS \"read_themas\" (...)` was parsed as `CREATE TABLE read_them AS ...`, so `kumiko-schema validate` reported content drift for `read_them` and `read_themas`. `AS` now needs a column list or whitespace before it."
+  },
+  {
+    "version": "0.401.0",
+    "type": "improvement",
+    "title": "rebindFileRef, readGate allLinks with documents linkReadMode, documents tab entity fix",
+    "detail": "`rebindFileRef(ctx, { fileRefId, from, to })` from `@cosmicdrift/kumiko-framework/files` moves a file that is already bound (for example to an upload record or an inbound mail) onto another record's file field, for server code where a record takes over that file; pending uploads keep using `bindPendingFileRef`. It finds only files of the caller's tenant (\"not-found\" otherwise), answers \"moved\" when the file no longer sits at `from`, \"rebound\" when it was moved or already sits at `to`, and \"version-conflict\" when a parallel bind committed first, because the update is checked against the stream version. The target must be a registered file field whose accept and maxSize the file fits. A caller other than the framework system user must be able to read the file and must be able to write both the source record and field (not locked; an entity without update handler leaves the move to the system user) and the target record and field; the source row stays locked until the transaction commits, so a lock set in between is either seen or waits; a system job (`{ db, registry, user: ctx.systemUser }`) skips these checks, but the target record must exist. Rebind first, then save the id into the target field; clearing or deleting the source record afterwards leaves the file alone. An entity `readGate` takes `allLinks` as an alternative to `anyLink`: a row with links is visible only when the viewer can read every live link, and the boot validator rejects a gate that declares both. `createDocumentsFeature({ linkReadMode: \"allLinks\" })` switches the documents gate to it; the default stays `anyLink`, and the file-owner part is unchanged. `documentsTab()` now references `documents:filed-document`; before, a projection screen using it failed boot after the entity rename. Linking a document to a target entity without an update handler is now allowed for the roles in that entity's `access.write` (plus its row-level write rule); a target with neither stays unlinkable. `documents:write:link` and `documents:write:unlink` have title and field-label translations (de, en), and the documents write handlers carry an explicit `agent.risk` (link, unlink, create, update \"mid\"; import \"high\"). `createDocumentsFeature({ categoryLabels })` takes a de/en label per category (an unlabelled one shows its raw value); a key that is not in `categories` throws."
+  },
+  {
+    "version": "0.401.0",
+    "type": "breaking",
+    "title": "Boot rejects a user reference with personal: false and file accept entries that never match",
+    "detail": "`createReferenceField({ entity, personal?, reason?, required? })` builds a foreign key; a target ending in `:user` defaults to `personal: \"ref\"` and throws on `personal: false`. The boot validator now rejects a reference field to the user entity that carries `personal: false`, and a file, files, image or images field (also inside embedded schemas) whose `accept` has an entry that is not a bare lower-case extension, because the upload check compares the file's extension only. The new boot option `requireFieldValueTranslations: true` (also readable from the schema CLI input) lists every missing translation of select/multiSelect options and embedded cell labels shown by entityList/entityEdit screens in one error. `defineEntityWriteHandler` and the create/update/delete/restore wrappers return a type whose `reserveBeforeTransaction`, `beforeTransaction` and `beforeTransactionWhenNested` are `undefined`, so a handler spread into `defineWriteHandler` can add its own. user-data-rights has the export-job status option labels (de, en, es, fr, it); managed-pages branding accepts `png, jpg, jpeg, webp` instead of MIME types.",
+    "migration": "Replace `personal: false` on a reference to the user entity with `createReferenceField({ entity: \"user:user\" })` or `personal: \"ref\"`. Write `accept` entries as bare extensions (`\"pdf\"`, not `\".pdf\"` or `\"application/pdf\"`)."
+  },
   {
     "version": "0.400.0",
     "type": "improvement",