@cosmicdrift/kumiko-framework 0.388.0 → 0.389.0

package/agents/examples/tenant-isolation.md

@@ -13,6 +13,7 @@ Multi-tenant data isolation by default.
 ## What it shows
 
 - Tenant filter on ordinary handlers
+- `ctx.db.upsert`: insert-or-update on a tenant-scoped, non-event-sourced table. `conflictTarget` must contain `tenantId` and match a declared unique index (here `tenant_id, key`); event-fed tables are rejected
 - What breaks if you forget tenancy (and how the framework prevents it)
 
 ## Source
@@ -37,6 +38,7 @@ bun test
 // Proves: tenant_id scopes all data, cross-tenant access returns nothing
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createTestUser, TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
@@ -45,7 +47,7 @@ import {
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-testing/stack";
-import { noteEntity, noteFeature } from "../feature";
+import { noteEntity, noteFeature, preferenceTable } from "../feature";
 
 let stack: TestStack;
 
@@ -136,12 +138,48 @@ describe("tenant isolation", () => {
     expect(listB.rows.some((r) => r["title"] === "A-Note")).toBe(false);
   });
 });
+
+describe("ctx.db.upsert", () => {
+  const setPreference = (user: typeof tenantBAdmin, key: string, value: string) =>
+    stack.http.writeOk<{ value: string }>("notes:write:preference:set", { key, value }, user);
+
+  test("a second upsert with the same key updates the tenant's row instead of inserting", async () => {
+    await setPreference(tenantAAdmin, "theme", "light");
+    const second = await setPreference(tenantAAdmin, "theme", "dark");
+
+    expect(second.value).toBe("dark");
+    const rows = await selectMany(stack.db, preferenceTable, {
+      tenantId: tenantAAdmin.tenantId,
+      key: "theme",
+    });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["value"]).toBe("dark");
+  });
+
+  test("the same key in another tenant creates a separate row and leaves A's value alone", async () => {
+    await setPreference(tenantAAdmin, "language", "de");
+    await setPreference(tenantBAdmin, "language", "en");
+
+    const rowsA = await selectMany(stack.db, preferenceTable, {
+      tenantId: tenantAAdmin.tenantId,
+      key: "language",
+    });
+    const rowsB = await selectMany(stack.db, preferenceTable, {
+      tenantId: tenantBAdmin.tenantId,
+      key: "language",
+    });
+    expect(rowsA.map((row) => row["value"])).toEqual(["de"]);
+    expect(rowsB.map((row) => row["value"])).toEqual(["en"]);
+  });
+});
 ```
 
 ### src/feature.ts
 
 ```ts
+import { defineUnmanagedTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
 
 export const noteEntity = createEntity({
   table: "read_sample_notes",
@@ -151,6 +189,26 @@ export const noteEntity = createEntity({
   },
 });
 
+// Not event-sourced: ctx.db.upsert rejects executor-managed tables.
+export const preferenceTable = defineUnmanagedTable({
+  tableName: "sample_tenant_preferences",
+  columns: [
+    {
+      name: "id",
+      pgType: "uuid",
+      notNull: true,
+      primaryKey: true,
+      defaultSql: "gen_random_uuid()",
+    },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "key", pgType: "text", notNull: true },
+    { name: "value", pgType: "text", notNull: true },
+  ],
+  indexes: [
+    { name: "sample_tenant_preferences_tenant_key", columns: ["tenant_id", "key"], unique: true },
+  ],
+});
+
 const adminWrite = { access: { roles: ["Admin"] } } as const;
 const openRead = {
   access: {
@@ -168,5 +226,19 @@ export const noteFeature = defineFeature("notes", (r) => {
     read: openRead,
     verbs: { update: false, delete: false, restore: false },
   });
+
+  r.storeTable(preferenceTable, { reason: "settings.tenant_preferences" });
+
+  r.writeHandler({
+    name: "preference:set",
+    schema: z.object({ key: z.string().min(1), value: z.string() }),
+    handler: async (event, ctx) => {
+      const row = await ctx.db.upsert<{ value: string }>(preferenceTable, event.payload, {
+        conflictTarget: ["tenantId", "key"],
+      });
+      return { isSuccess: true, data: { value: row?.value } };
+    },
+    ...adminWrite,
+  });
 });
 ```

package/agents/examples.md

@@ -48,6 +48,7 @@
 | `ledger-invoicing` | Accrual invoicing on the ledger primitive — revenue at invoice time, VAT as a liability, receivable cleared on payment. | `examples/ledger-invoicing.md` |
 | `legal-pages` | Auto-rendered Impressum + Datenschutzerklärung pages — template-resolver + legal-pages bundled features wired up with anonymousAccess for DACH-compliance. | `examples/legal-pages.md` |
 | `lifecycle-hooks` | preSave, postSave, and the rest. Your logic, our plumbing. | `examples/lifecycle-hooks.md` |
+| `list-table-options` | Opt-in table behaviour of a list: remembered search/sort/filters, one reset button, column picker with hidden columns, row density, server-side groups with sums, a totals row and a number range facet. | `examples/list-table-options.md` |
 | `managed-config` | Managed config: one declaration provisions storage + masking + settings-hub, across backings (secrets vs config) and scopes (system vs tenant). | `examples/managed-config.md` |
 | `managed-pages` | Tenant-editable, server-rendered public pages with per-tenant branding + tier-gated sanitized custom CSS — managed-pages wired up with config + anonymousAccess. | `examples/managed-pages.md` |
 | `notes-history-basic` | Append-only note history — who wrote what, when — attached to any entity without changing it. | `examples/notes-history-basic.md` |

package/agents/widgets.md

@@ -143,6 +143,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `buildFileUploadFormData` |  |
 | `buildNavRegistrySlice` |  |
 | `buildNavRegistrySliceForApp` |  |
+| `clearRememberedListState` | Forgets all remembered list state and the identity marker. |
 | `cn` | Standard shadcn helper: `clsx` combines conditional classes, while `tailwind-merge` resolves conflicts (for example, `px-2 px-4` → `px-4`). |
 | `createBrowserDraftStorage` | Default DraftStorage when createKumikoApp boots without one. |
 | `createBrowserLocaleResolver` | Default resolver when createKumikoApp is booted without a `locale` option. |

package/dist/api/api-constants.d.ts

@@ -8,6 +8,7 @@ export declare const Routes: {
     readonly command: "/command";
     readonly sse: "/sse";
     readonly stream: "/stream";
+    readonly exportXlsx: "/export/xlsx";
     readonly auth: "/auth";
     readonly authLogin: "/auth/login";
     readonly authMfaVerify: "/auth/mfa/verify";

package/dist/api/api-constants.js

@@ -10,6 +10,7 @@ export const Routes = {
     command: "/command",
     sse: "/sse",
     stream: "/stream",
+    exportXlsx: "/export/xlsx",
     auth: "/auth",
     authLogin: "/auth/login",
     authMfaVerify: "/auth/mfa/verify",
@@ -76,6 +77,7 @@ export const NON_PUBLIC_API_PATHS = new Set([
     `/api${Routes.command}`,
     `/api${Routes.sse}`,
     `/api${Routes.stream}`,
+    `/api${Routes.exportXlsx}`,
     // Namespace prefix used only for body-limit registration
     // (`/api/auth/*` in route-registrars.ts) — never dispatched as its own
     // route, so it carries no auth bypass either way. Classified non-public

package/dist/api/auth-routes-shared.d.ts

@@ -8,6 +8,7 @@ export declare const SignupRequestBody: z.ZodObject<{
         entityType: z.ZodString;
         token: z.ZodString;
     }, z.core.$strip>>;
+    returnTo: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
 export declare function isUnknownHandlerError(e: unknown): boolean;
 export type PendingMfaStep = {
@@ -29,5 +30,6 @@ export declare function registerTokenRequestRoute(opts: {
 }): void;
 declare const RequestTokenBody: z.ZodObject<{
     email: z.ZodEmail;
+    returnTo: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
 export {};

package/dist/api/auth-routes-shared.js

@@ -4,6 +4,9 @@ import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
 import { NotFoundError } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
 const log = createFallbackLogger("kumiko");
+// Content is checked where the mail link is built (bundled-features knows the path rules); a bad
+// value must never void the whole body, or the request would silently send no mail.
+const returnToField = z.string().max(2048).optional().catch(undefined);
 // Cross-device try-first handover: an optional tenant-handover grant the signup-request
 // route forwards to the handler for server-side verification and binding —
 // the grant itself never appears anywhere else (URL, mail, log, response).
@@ -15,6 +18,7 @@ export const SignupRequestBody = z.object({
         token: z.string().min(1).max(4096),
     })
         .optional(),
+    returnTo: returnToField,
 });
 // Shape guard for "handler not registered" — the only legitimate reason to
 // fall back to a single-tenant reply on /auth/tenants or /auth/switch-tenant.
@@ -82,4 +86,5 @@ export function registerTokenRequestRoute(opts) {
 // gains optional fields (locale, deviceId, …).
 const RequestTokenBody = z.object({
     email: z.email(),
+    returnTo: returnToField,
 });

package/dist/api/client-error-route.js

@@ -73,6 +73,8 @@ export function createClientErrorRoute(options) {
     const app = new Hono();
     const logger = createFallbackLogger("client-errors");
     const routePath = `/api${Routes.clientErrors}`;
+    // Always on: the shared limiter fails open when Redis is down, this per-process window is the floor.
+    app.post(Routes.clientErrors, inMemoryIpRateLimit(options.clientIpResolver, options.now ?? Date.now));
     if (options.resolver) {
         app.post(Routes.clientErrors, httpRouteRateLimit({
             resolver: options.resolver,
@@ -82,9 +84,6 @@ export function createClientErrorRoute(options) {
             ...(options.meter && { meter: options.meter }),
         }));
     }
-    else {
-        app.post(Routes.clientErrors, inMemoryIpRateLimit(options.clientIpResolver, options.now ?? Date.now));
-    }
     app.post(Routes.clientErrors, bodyLimit({
         maxSize: MAX_BODY_BYTES,
         onError: (c) => c.json({ error: { code: "payload_too_large" } }, 413),

package/dist/api/entity-read-access.d.ts

@@ -1,2 +1,3 @@
-import type { AccessRule, Registry } from "../engine/types/index.ts";
+import type { AccessRule, OwnershipMap, Registry } from "../engine/types/index.ts";
 export declare function collectEntityReadAccess(registry: Registry): ReadonlyMap<string, readonly AccessRule[]>;
+export declare function collectEntityRowReadMaps(registry: Registry): ReadonlyMap<string, OwnershipMap>;

package/dist/api/entity-read-access.js

@@ -25,3 +25,17 @@ export function collectEntityReadAccess(registry) {
     }
     return rulesByEntity;
 }
+// Entities whose own access.read narrows rows per role (e.g. Driver sees only assigned rows).
+// A signal for such an entity must not name ids to a role that does not read every row.
+export function collectEntityRowReadMaps(registry) {
+    const mapsByEntity = new Map();
+    for (const [entityName, entity] of registry.getAllEntities()) {
+        const readMap = entity.access?.read;
+        if (readMap === undefined || Object.keys(readMap).length === 0)
+            continue;
+        for (const aggregateType of new Set([entityName, toKebabCase(entityName)])) {
+            mapsByEntity.set(aggregateType, readMap);
+        }
+    }
+    return mapsByEntity;
+}

package/dist/api/export/export-cells-reference.d.ts

@@ -0,0 +1,9 @@
+import type { Cell } from "write-excel-file/node";
+import type { ExportRow } from "./export-rows.ts";
+export type ReferenceCellKind = {
+    readonly kind: "reference";
+    readonly labelField: string;
+    readonly multiple: boolean;
+};
+/** Labels come from the list row's eager-loaded `_refs`; a missing target shows its raw id. */
+export declare function referenceCell(cell: ReferenceCellKind, field: string, row: ExportRow): Cell;

package/dist/api/export/export-cells-reference.js

@@ -0,0 +1,21 @@
+import { isPlainObject } from "../../utils/is-plain-object.js";
+function labelOf(ref, labelField) {
+    if (!isPlainObject(ref))
+        return undefined;
+    const label = ref[labelField];
+    return typeof label === "string" ? label : undefined;
+}
+function refsOf(row, field) {
+    const refs = row["_refs"];
+    return isPlainObject(refs) ? refs[field] : undefined;
+}
+/** Labels come from the list row's eager-loaded `_refs`; a missing target shows its raw id. */
+export function referenceCell(cell, field, row) {
+    const ids = cell.multiple && Array.isArray(row[field]) ? row[field] : [row[field]];
+    const ref = refsOf(row, field);
+    const labels = ids.map((id) => {
+        const target = Array.isArray(ref) ? ref.find((r) => isPlainObject(r) && r["id"] === id) : ref;
+        return labelOf(target, cell.labelField) ?? String(id);
+    });
+    return { value: labels.join(", "), type: String };
+}

package/dist/api/export/export-cells.d.ts

@@ -0,0 +1,11 @@
+import type { Cell } from "write-excel-file/node";
+import type { ExportColumn } from "./export-columns.ts";
+import type { ExportRow } from "./export-rows.ts";
+export type Translate = (key: string) => string;
+export type ExportCellContext = {
+    readonly row: ExportRow;
+    readonly translate: Translate;
+    readonly timeZone: string;
+};
+/** Never emits a formula cell and never reinterprets strings: text always stays text. */
+export declare function toExportCell(column: ExportColumn, context: ExportCellContext): Cell;

package/dist/api/export/export-cells.js

@@ -0,0 +1,136 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { referenceCell } from "./export-cells-reference.js";
+const DATE_FORMAT = "yyyy-mm-dd";
+const TIMESTAMP_FORMAT = "yyyy-mm-dd hh:mm";
+const PLAIN_MONEY_FORMAT = "#,##0.00";
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const CURRENCY_CODE = /^[A-Z]{3}$/;
+function isNullish(value) {
+    return value === null || value === undefined;
+}
+function textCell(value) {
+    return { value, type: String };
+}
+function numberCell(value, format) {
+    return { value, type: Number, ...(format !== undefined && { format }) };
+}
+function toFiniteNumber(value) {
+    const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+    return value !== "" && Number.isFinite(n) ? n : undefined;
+}
+function stringify(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object" && value !== null) {
+        // Temporal values stringify to ISO via toString; plain data goes through JSON.
+        const text = String(value);
+        return text === "[object Object]" ? JSON.stringify(value) : text;
+    }
+    return String(value);
+}
+function fromEpochMillis(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? undefined : value;
+    if (typeof value === "object" && value !== null && "epochMilliseconds" in value) {
+        return fromEpochMillis(new Date(Number(value.epochMilliseconds)));
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        return fromEpochMillis(new Date(value));
+    }
+    return undefined;
+}
+// Date-only values are anchored at UTC midnight, never parsed through the local zone.
+function toUtcDate(value) {
+    const text = typeof value === "string" ? value : isNullish(value) ? "" : stringify(value);
+    if (ISO_DATE.test(text))
+        return fromEpochMillis(new Date(`${text}T00:00:00Z`));
+    return undefined;
+}
+function dateCell(value) {
+    const date = toUtcDate(value) ?? fromEpochMillis(value);
+    return date === undefined
+        ? textCell(stringify(value))
+        : { value: date, type: Date, format: DATE_FORMAT };
+}
+// The sheet has no time zone, so the instant is shifted to the wall clock of `timeZone` and
+// stored as if that wall clock were UTC.
+function timestampCell(value, timeZone) {
+    const date = fromEpochMillis(value);
+    if (date === undefined)
+        return textCell(stringify(value));
+    const wall = Temporal.Instant.fromEpochMilliseconds(date.getTime()).toZonedDateTimeISO(timeZone);
+    const shifted = new Date(Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second));
+    return { value: shifted, type: Date, format: TIMESTAMP_FORMAT };
+}
+// `at` is the wall clock in the record's own zone without offset; reading it as UTC keeps the
+// digits the user saw in the list.
+function locatedTimestampCell(value) {
+    const at = typeof value === "object" && value !== null && "at" in value ? String(value.at) : undefined;
+    const date = at === undefined ? undefined : fromEpochMillis(new Date(`${at}Z`));
+    return date === undefined
+        ? textCell(stringify(value))
+        : { value: date, type: Date, format: TIMESTAMP_FORMAT };
+}
+function moneyCell(value) {
+    if (typeof value !== "object" || value === null || !("amount" in value)) {
+        const n = toFiniteNumber(value);
+        return n === undefined ? textCell(stringify(value)) : numberCell(n, PLAIN_MONEY_FORMAT);
+    }
+    const amount = toFiniteNumber(value.amount);
+    if (amount === undefined)
+        return textCell(stringify(value.amount));
+    const currency = "currency" in value ? String(value.currency) : "";
+    const format = CURRENCY_CODE.test(currency)
+        ? `${PLAIN_MONEY_FORMAT} "${currency}"`
+        : PLAIN_MONEY_FORMAT;
+    return numberCell(amount, format);
+}
+function integerCell(value, kind) {
+    const n = toFiniteNumber(value);
+    if (n === undefined)
+        return textCell(stringify(value));
+    // A bigInt beyond 2^53 would lose digits as a spreadsheet number.
+    if (kind === "bigInt" && !Number.isSafeInteger(n))
+        return textCell(stringify(value));
+    return numberCell(n);
+}
+function optionLabel(prefix, raw, translate) {
+    const text = String(raw);
+    const label = translate(`${prefix}${text}`);
+    return label === `${prefix}${text}` ? text : label;
+}
+function autoCell(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return numberCell(value);
+    if (typeof value === "boolean")
+        return { value, type: Boolean };
+    return textCell(stringify(value));
+}
+function optionCell(cell, value, translate) {
+    const values = cell.kind === "multiSelect" && Array.isArray(value) ? value : [value];
+    return textCell(values.map((v) => optionLabel(cell.optionLabelKeyPrefix, v, translate)).join(", "));
+}
+const SIMPLE_CELL_BUILDERS = {
+    number: (value) => integerCell(value, "number"),
+    decimal: (value) => integerCell(value, "decimal"),
+    bigInt: (value) => integerCell(value, "bigInt"),
+    money: (value) => moneyCell(value),
+    date: (value) => dateCell(value),
+    timestamp: timestampCell,
+    locatedTimestamp: (value) => locatedTimestampCell(value),
+    boolean: (value) => typeof value === "boolean" ? { value, type: Boolean } : textCell(stringify(value)),
+    auto: (value) => autoCell(value),
+    text: (value) => textCell(stringify(value)),
+};
+/** Never emits a formula cell and never reinterprets strings: text always stays text. */
+export function toExportCell(column, context) {
+    const { cell, field } = column;
+    const value = context.row[field];
+    if (isNullish(value))
+        return null;
+    if (cell.kind === "reference")
+        return referenceCell(cell, field, context.row);
+    if ("optionLabelKeyPrefix" in cell)
+        return optionCell(cell, value, context.translate);
+    return SIMPLE_CELL_BUILDERS[cell.kind](value, context.timeZone);
+}

package/dist/api/export/export-ciphertext-guard.d.ts

@@ -0,0 +1,2 @@
+import type { SheetData } from "write-excel-file/node";
+export declare function guardSheetAgainstCiphertext(sheet: SheetData, isProduction?: boolean): SheetData;

package/dist/api/export/export-ciphertext-guard.js

@@ -0,0 +1,27 @@
+import { InternalError } from "../../errors/index.js";
+import { createFallbackLogger } from "../../logging/utils.js";
+import { CIPHERTEXT_RE, CIPHERTEXT_REDACT_RE, CIPHERTEXT_REDACTION } from "../pii-leak-guard.js";
+const log = createFallbackLogger("kumiko:export-xlsx");
+// The response guard only scans JSON, so a workbook needs its own check: a ciphertext in a cell
+// means a raw DB read reached the export. Same policy as the guard: loud outside production,
+// redacted and logged in production.
+function guardText(text, isProduction) {
+    if (!CIPHERTEXT_RE.test(text))
+        return text;
+    const detail = "XLSX export contains a PII ciphertext — a raw DB read leaked into the sheet. " +
+        "Decrypt before returning (decryptStoredPii / executor read path).";
+    if (!isProduction)
+        throw new InternalError({ message: detail });
+    log.error(detail);
+    return text.replace(CIPHERTEXT_REDACT_RE, CIPHERTEXT_REDACTION);
+}
+function guardCell(cell, isProduction) {
+    if (typeof cell !== "object" || cell === null || !("value" in cell))
+        return cell;
+    if (typeof cell.value !== "string")
+        return cell;
+    return { ...cell, value: guardText(cell.value, isProduction) };
+}
+export function guardSheetAgainstCiphertext(sheet, isProduction = process.env["NODE_ENV"] === "production") {
+    return sheet.map((row) => row.map((cell) => guardCell(cell, isProduction)));
+}

package/dist/api/export/export-columns.d.ts

@@ -0,0 +1,29 @@
+import type { EntityDefinition, ListColumnSpec, SessionUser } from "../../engine/types/index.ts";
+import type { ReferenceCellKind } from "./export-cells-reference.ts";
+export type SimpleCellKind = "text" | "number" | "decimal" | "bigInt" | "money" | "date" | "timestamp" | "locatedTimestamp" | "boolean" | "auto";
+export type ExportCellKind = {
+    readonly kind: SimpleCellKind;
+} | ReferenceCellKind | {
+    readonly kind: "select" | "multiSelect";
+    /** `<feature>:entity:<entity>:field:<field>:option:` — the option value is appended. */
+    readonly optionLabelKeyPrefix: string;
+};
+export type ExportColumn = {
+    readonly field: string;
+    readonly headerKey: string;
+    readonly headerFallback: string;
+    readonly cell: ExportCellKind;
+};
+export type ExportColumnSource = {
+    readonly featureName: string;
+    readonly columns: readonly ListColumnSpec[];
+    readonly entity: EntityDefinition | undefined;
+    readonly entityName: string | undefined;
+    readonly user: Pick<SessionUser, "roles">;
+};
+/**
+ * Resolves the requested column ids against the screen's declared columns, in client order.
+ * Virtual columns and, on an entityList, encrypted/sensitive fields are dropped without error:
+ * the zip response bypasses the PII-leak guard, so this is the only place that keeps them out.
+ */
+export declare function resolveExportColumns(source: ExportColumnSource, requested: readonly string[]): ExportColumn[];

package/dist/api/export/export-columns.js

@@ -0,0 +1,85 @@
+import { holdsCiphertextOrSecret } from "../../db/entity-field-encryption.js";
+import { userMayReadFieldInBulk } from "../../engine/field-access.js";
+import { normalizeListColumn } from "../../engine/screen-helpers.js";
+import { exportRejection } from "./export-errors.js";
+const PROJECTION_PSEUDO_ENTITY = "__projection__";
+const FIELD_KIND_BY_TYPE = {
+    number: "number",
+    decimal: "decimal",
+    bigInt: "bigInt",
+    money: "money",
+    date: "date",
+    timestamp: "timestamp",
+    locatedTimestamp: "locatedTimestamp",
+    boolean: "boolean",
+};
+function fieldLabelKey(featureName, entityName, field) {
+    return `${featureName}:entity:${entityName}:field:${field}`;
+}
+function entityCellKind(source, entity, field) {
+    const def = entity.fields[field];
+    if (def?.type === "reference") {
+        return {
+            kind: "reference",
+            labelField: def.labelField ?? "id",
+            multiple: def.multiple === true,
+        };
+    }
+    const type = def?.type ?? "text";
+    if (type === "select" || type === "multiSelect") {
+        return {
+            kind: type,
+            optionLabelKeyPrefix: `${fieldLabelKey(source.featureName, source.entityName ?? "", field)}:option:`,
+        };
+    }
+    return { kind: FIELD_KIND_BY_TYPE[type] ?? "text" };
+}
+function projectionCellKind(valueType) {
+    if (valueType === "number" || valueType === "decimal" || valueType === "bigInt") {
+        return { kind: valueType };
+    }
+    return { kind: valueType === "money" ? "money" : "auto" };
+}
+function isExportableOnEntity(source, entity, field, virtual) {
+    if (virtual || !userMayReadFieldInBulk(entity, field, source.user))
+        return false;
+    return !holdsCiphertextOrSecret(entity, field);
+}
+/**
+ * Resolves the requested column ids against the screen's declared columns, in client order.
+ * Virtual columns and, on an entityList, encrypted/sensitive fields are dropped without error:
+ * the zip response bypasses the PII-leak guard, so this is the only place that keeps them out.
+ */
+export function resolveExportColumns(source, requested) {
+    const declared = new Map(source.columns.map((spec) => normalizeListColumn(spec)).map((c) => [c.field, c]));
+    const seen = new Set();
+    const resolved = [];
+    for (const field of requested) {
+        const column = declared.get(field);
+        if (column === undefined) {
+            throw exportRejection("export_unknown_column", "columns", { column: field });
+        }
+        if (seen.has(field))
+            continue;
+        seen.add(field);
+        const virtual = column.virtual === true;
+        const { entity } = source;
+        if (entity !== undefined && !isExportableOnEntity(source, entity, field, virtual))
+            continue;
+        if (entity === undefined && virtual)
+            continue;
+        const cell = entity !== undefined
+            ? entityCellKind(source, entity, field)
+            : projectionCellKind(column.valueType);
+        const headerEntity = source.entityName ?? PROJECTION_PSEUDO_ENTITY;
+        resolved.push({
+            field,
+            headerKey: column.label ?? fieldLabelKey(source.featureName, headerEntity, field),
+            headerFallback: column.label ?? field,
+            cell,
+        });
+    }
+    if (resolved.length === 0)
+        throw exportRejection("export_no_columns", "columns");
+    return resolved;
+}

package/dist/api/export/export-errors.d.ts

@@ -0,0 +1,4 @@
+import { ValidationError } from "../../errors/index.ts";
+export declare const EXPORT_TOO_MANY_I18N_KEY = "kumiko.list.export-too-many";
+export type ExportRejectReason = "export_invalid_request" | "export_unknown_screen" | "export_not_enabled" | "export_unknown_column" | "export_no_columns";
+export declare function exportRejection(reason: ExportRejectReason, path: string, params?: Readonly<Record<string, unknown>>): ValidationError;

package/dist/api/export/export-errors.js

@@ -0,0 +1,14 @@
+import { ValidationError } from "../../errors/index.js";
+export const EXPORT_TOO_MANY_I18N_KEY = "kumiko.list.export-too-many";
+export function exportRejection(reason, path, params) {
+    return new ValidationError({
+        fields: [
+            {
+                path,
+                code: reason,
+                i18nKey: `kumiko.list.${reason.replace(/_/g, "-")}`,
+                ...(params !== undefined && { params }),
+            },
+        ],
+    });
+}

package/dist/api/export/export-route.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from "hono";
+import type { Registry } from "../../engine/types/index.ts";
+import type { Dispatcher } from "../../pipeline/dispatcher.ts";
+export declare function createExportRoutes(dispatcher: Dispatcher, registry: Registry): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;