@cosmicdrift/kumiko-framework 0.399.0 → 0.400.0

package/dist/db/parent-ref-clause.js

@@ -3,24 +3,28 @@ import { SYSTEM_TENANT_ID, UUID_SHAPE_PATTERN } from "../engine/types/identifier
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
 import { schemaTableName } from "./table-introspection.js";
 const candidateStaticsCache = new WeakMap();
-function candidateStaticsFor(candidateName, candidate) {
+function candidateStaticsFor(candidateName, candidate, resolveTable) {
+    if (resolveTable !== undefined)
+        return staticsOf(resolveTable(candidateName));
     const cached = candidateStaticsCache.get(candidate);
     if (cached)
         return cached;
-    const table = buildEntityTable(candidateName, candidate);
+    const statics = staticsOf(buildEntityTable(candidateName, candidate));
+    candidateStaticsCache.set(candidate, statics);
+    return statics;
+}
+function staticsOf(table) {
     const tableName = String(schemaTableName(table));
-    const statics = {
+    return {
         table,
         tableName,
         tenantIdCol: table["tenantId"] !== undefined ? physicalColumnName(table, "tenantId") : undefined,
         isDeletedCol: table["isDeleted"] !== undefined ? physicalColumnName(table, "isDeleted") : undefined,
     };
-    candidateStaticsCache.set(candidate, statics);
-    return statics;
 }
 // Candidate order follows `option.entities` (Registry insertion order) —
 // deterministic given a fixed feature-registration order.
-function selectCandidates(parentRef, option, narrowTypes) {
+function selectCandidates(parentRef, option, narrowTypes, requireReadHandler) {
     const candidates = [];
     for (const [name, candidate] of option.entities) {
         if (parentRef.allowedTypes && !parentRef.allowedTypes.includes(name))
@@ -31,6 +35,11 @@ function selectCandidates(parentRef, option, narrowTypes) {
         // need its own visibility resolved first, which this function doesn't do.
         if (candidate.parentRef !== undefined)
             continue;
+        // A readGate host would need its own gate resolved first; unreadable beats a widened read.
+        if (candidate.readGate !== undefined)
+            continue;
+        if (requireReadHandler && option.canReadEntity?.(name) !== true)
+            continue;
         // event-store-executor-context.ts rejects non-uuid idType at executor
         // build time, so there is no read path to check such a candidate against.
         if (candidate.idType !== undefined && candidate.idType !== "uuid")
@@ -58,7 +67,7 @@ export function buildParentRefClause(entity, table, tableName, user, db, option,
     }
     const typeCol = physicalColumnName(table, parentRef.entityTypeField);
     const idCol = physicalColumnName(table, parentRef.entityIdField);
-    const candidates = selectCandidates(parentRef, option, opts.narrowTypes);
+    const candidates = selectCandidates(parentRef, option, opts.narrowTypes, opts.requireReadHandler === true);
     if (candidates.length === 0)
         return { kind: "empty" };
     // The uuid shape and the tenant ids are bound once and shared by every
@@ -85,6 +94,7 @@ export function buildParentRefClause(entity, table, tableName, user, db, option,
             // kept, so a dropped branch reserves no index and can't shift the
             // positional binding of the branches after it.
             typeParamIdx: params.length + 1,
+            resolveTable: option.resolveTable,
         });
         if (branch === undefined)
             continue;
@@ -99,7 +109,7 @@ export function buildParentRefClause(entity, table, tableName, user, db, option,
 // read ownership can never match — an unsatisfiable arm is dropped rather than
 // emitted, which is what keeps an unreadable host from widening the OR-chain.
 function buildCandidateBranch(candidateName, candidate, user, ctx) {
-    const statics = candidateStaticsFor(candidateName, candidate);
+    const statics = candidateStaticsFor(candidateName, candidate, ctx.resolveTable);
     const ownership = buildOwnershipClause(user, candidate.access?.read, statics.table, ctx.typeParamIdx + 1);
     if (ownership.kind === "empty")
         return undefined;

package/dist/db/read-gate-clause.d.ts

@@ -0,0 +1,7 @@
+import type { ParentVisibilityOption } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import { type OwnershipClause } from "../engine/ownership.ts";
+import type { SessionUser } from "../engine/types/index.ts";
+import type { Table } from "./event-store-executor-context.ts";
+import type { TenantDb } from "./tenant-db.ts";
+export declare function buildReadGateClause(entity: EntityDefinition, table: Table, tableName: string, user: SessionUser, db: TenantDb, option: ParentVisibilityOption | undefined): OwnershipClause;

package/dist/db/read-gate-clause.js

@@ -0,0 +1,188 @@
+import { isFileField } from "../engine/field-helpers.js";
+import { buildOwnershipClause, combineClauses, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
+import { SYSTEM_TENANT_ID, UUID_SHAPE_PATTERN } from "../engine/types/identifiers.js";
+import { FILE_REF_ENTITY_NAME } from "../files/types.js";
+import { isFrameworkSystemUser } from "./lock-guard.js";
+import { buildParentRefClause } from "./parent-ref-clause.js";
+import { buildEntityTable, physicalColumnName } from "./table-builder.js";
+import { schemaTableName } from "./table-introspection.js";
+const PASS = { kind: "pass" };
+const EMPTY = { kind: "empty" };
+const LINK_ALIAS = "gate_link";
+const FILE_ALIAS = "gate_file";
+// Placeholders are numbered from 1 per gate fragment; combineClauses shifts them into the
+// caller's statement, so every embedded fragment is shifted past the params collected so far.
+class GateSql {
+    params = [];
+    bind(value) {
+        this.params.push(value);
+        return `$${this.params.length}`;
+    }
+    embed(clause) {
+        const shifted = shiftParams({ sqlText: clause.sqlText, params: clause.params }, this.params.length);
+        this.params.push(...shifted.params);
+        return shifted.sqlText;
+    }
+}
+function tableOf(option, name, entity) {
+    return option.resolveTable?.(name) ?? buildEntityTable(name, entity);
+}
+function tenantScopeSql(sql, db, table, alias) {
+    if (table["tenantId"] === undefined || db.mode !== "tenant")
+        return [];
+    const first = sql.bind(db.tenantId);
+    const second = sql.bind(SYSTEM_TENANT_ID);
+    return [`"${alias}"."${physicalColumnName(table, "tenantId")}" IN (${first}, ${second})`];
+}
+function liveRowSql(entity, table, alias) {
+    if (entity.softDelete !== true || table["isDeleted"] === undefined)
+        return [];
+    return [`"${alias}"."${physicalColumnName(table, "isDeleted")}" = FALSE`];
+}
+function isRoleExempt(gate, user) {
+    return user.roles.some((role) => gate.linkExemptRoles?.includes(role) === true);
+}
+function anyLinkClause(input, link) {
+    const { option, user, db, tableName } = input;
+    const linkEntity = option.entities.get(link.entity);
+    if (linkEntity?.parentRef === undefined)
+        return EMPTY;
+    const linkTable = tableOf(option, link.entity, linkEntity);
+    const linkTableName = String(schemaTableName(linkTable));
+    const linkOwnership = combineClauses(buildOwnershipClause(user, linkEntity.access?.read, linkTable, 1, LINK_ALIAS), buildParentRefClause(linkEntity, linkTable, LINK_ALIAS, user, db, option, {
+        includeDeleted: false,
+        requireReadHandler: true,
+    }));
+    if (linkOwnership.kind === "empty")
+        return EMPTY;
+    const sql = new GateSql();
+    const conditions = [
+        `"${LINK_ALIAS}"."${physicalColumnName(linkTable, link.field)}"::text = "${tableName}"."${physicalColumnName(input.table, "id")}"::text`,
+        ...tenantScopeSql(sql, db, linkTable, LINK_ALIAS),
+        ...liveRowSql(linkEntity, linkTable, LINK_ALIAS),
+    ];
+    if (linkOwnership.kind === "sql")
+        conditions.push(sql.embed(linkOwnership));
+    return {
+        kind: "sql",
+        sqlText: `EXISTS (SELECT 1 FROM "${linkTableName}" AS "${LINK_ALIAS}" WHERE ${conditions.join(" AND ")})`,
+        params: sql.params,
+    };
+}
+// Every registered entity with a file field can own a file. Join rows and gated entities
+// are left out: their readability is not resolvable without recursion.
+function ownerCandidates(input, selfName) {
+    const { option } = input;
+    const owners = [];
+    for (const [name, entity] of option.entities) {
+        if (name === FILE_REF_ENTITY_NAME || name === selfName)
+            continue;
+        if (entity.parentRef !== undefined || entity.readGate !== undefined)
+            continue;
+        if (entity.idType !== undefined && entity.idType !== "uuid")
+            continue;
+        if (option.canReadEntity?.(name) !== true)
+            continue;
+        const fileFields = Object.entries(entity.fields)
+            .filter(([, field]) => isFileField(field))
+            .map(([fieldName]) => fieldName);
+        if (fileFields.length > 0)
+            owners.push({ name, entity, fileFields });
+    }
+    return owners;
+}
+function ownerBranch(input, owner, refTable, sql) {
+    const { option, user, db } = input;
+    const ownerTable = tableOf(option, owner.name, owner.entity);
+    const ownerTableName = String(schemaTableName(ownerTable));
+    const ownership = buildOwnershipClause(user, owner.entity.access?.read, ownerTable, 1, ownerTableName);
+    if (ownership.kind === "empty")
+        return undefined;
+    const readableAnywhere = [];
+    const fieldArms = [];
+    for (const field of owner.fileFields) {
+        const fieldRead = buildOwnershipClause(user, normalizeAccessEntry(owner.entity.fields[field]?.access?.read), ownerTable, 1, ownerTableName);
+        if (fieldRead.kind === "empty")
+            continue;
+        if (fieldRead.kind === "pass")
+            readableAnywhere.push(field);
+        else
+            fieldArms.push({ field, clause: fieldRead });
+    }
+    if (readableAnywhere.length === 0 && fieldArms.length === 0)
+        return undefined;
+    const typeSql = `"${FILE_ALIAS}"."${physicalColumnName(refTable, "entityType")}" = ${sql.bind(owner.name)}`;
+    const fieldCol = `"${FILE_ALIAS}"."${physicalColumnName(refTable, "fieldName")}"`;
+    const idCol = `"${FILE_ALIAS}"."${physicalColumnName(refTable, "entityId")}"`;
+    const uuidPattern = sql.bind(UUID_SHAPE_PATTERN);
+    const arms = [];
+    if (readableAnywhere.length > 0) {
+        arms.push(`${fieldCol} IN (${readableAnywhere.map((f) => sql.bind(f)).join(", ")})`);
+    }
+    for (const arm of fieldArms) {
+        if (arm.clause.kind !== "sql")
+            continue;
+        arms.push(`(${fieldCol} = ${sql.bind(arm.field)} AND ${sql.embed(arm.clause)})`);
+    }
+    const conditions = [
+        `"${ownerTableName}"."${physicalColumnName(ownerTable, "id")}" = (CASE WHEN ${idCol} ~ ${uuidPattern} THEN ${idCol} END)::uuid`,
+        ...tenantScopeSql(sql, db, ownerTable, ownerTableName),
+        ...liveRowSql(owner.entity, ownerTable, ownerTableName),
+    ];
+    if (ownership.kind === "sql")
+        conditions.push(sql.embed(ownership));
+    conditions.push(`(${arms.join(" OR ")})`);
+    return `(${typeSql} AND EXISTS (SELECT 1 FROM "${ownerTableName}" WHERE ${conditions.join(" AND ")}))`;
+}
+function fileOwnerClause(input, field) {
+    const { option, db, tableName, table, entity } = input;
+    const refEntity = option.entities.get(FILE_REF_ENTITY_NAME);
+    if (refEntity === undefined)
+        return EMPTY;
+    const refTable = tableOf(option, FILE_REF_ENTITY_NAME, refEntity);
+    const refTableName = String(schemaTableName(refTable));
+    // The registry holds a spread copy of the entity, so the table name is the stable identity.
+    const selfName = [...option.entities].find(([, candidate]) => candidate.table === entity.table)?.[0];
+    const sql = new GateSql();
+    const branches = [];
+    if (selfName !== undefined) {
+        const selfType = sql.bind(selfName);
+        branches.push(`("${FILE_ALIAS}"."${physicalColumnName(refTable, "entityType")}" = ${selfType} AND "${FILE_ALIAS}"."${physicalColumnName(refTable, "entityId")}" = "${tableName}"."${physicalColumnName(table, "id")}"::text)`);
+    }
+    for (const owner of ownerCandidates(input, selfName)) {
+        const branch = ownerBranch(input, owner, refTable, sql);
+        if (branch !== undefined)
+            branches.push(branch);
+    }
+    if (branches.length === 0)
+        return EMPTY;
+    const conditions = [
+        `"${FILE_ALIAS}"."${physicalColumnName(refTable, "id")}" = "${tableName}"."${physicalColumnName(table, field)}"`,
+        ...tenantScopeSql(sql, db, refTable, FILE_ALIAS),
+        ...liveRowSql(refEntity, refTable, FILE_ALIAS),
+        `(${branches.join(" OR ")})`,
+    ];
+    return {
+        kind: "sql",
+        sqlText: `EXISTS (SELECT 1 FROM "${refTableName}" AS "${FILE_ALIAS}" WHERE ${conditions.join(" AND ")})`,
+        params: sql.params,
+    };
+}
+// Without the registry the gate cannot be resolved; every caller but the framework system user
+// is denied, which is what forces hand-written handlers to wire parentVisibility.
+export function buildReadGateClause(entity, table, tableName, user, db, option) {
+    const gate = entity.readGate;
+    if (gate === undefined || isFrameworkSystemUser(user))
+        return PASS;
+    if (option === undefined)
+        return EMPTY;
+    const input = { entity, table, tableName, user, db, option };
+    let clause = PASS;
+    if (gate.anyLink !== undefined && !isRoleExempt(gate, user)) {
+        clause = combineClauses(clause, anyLinkClause(input, gate.anyLink));
+    }
+    if (gate.fileOwner !== undefined) {
+        clause = combineClauses(clause, fileOwnerClause(input, gate.fileOwner.field));
+    }
+    return clause;
+}

package/dist/db/read-ownership.d.ts

@@ -0,0 +1,9 @@
+import { type OwnershipClause } from "../engine/ownership.ts";
+import type { SessionUser } from "../engine/types/index.ts";
+import type { ExecutorContext } from "./event-store-executor-context.ts";
+import { type ParentVisibilityOption } from "./parent-ref-clause.ts";
+import type { TenantDb } from "./tenant-db.ts";
+export declare function resolveReadOwnership(ctx: Pick<ExecutorContext, "entity" | "table">, tableName: string, user: SessionUser, db: TenantDb, parentVisibility: ParentVisibilityOption | undefined, gate: {
+    readonly includeDeleted: boolean;
+    readonly narrowTypes: ReadonlySet<string> | undefined;
+}): OwnershipClause;

package/dist/db/read-ownership.js

@@ -0,0 +1,12 @@
+import { buildOwnershipClause, combineClauses } from "../engine/ownership.js";
+import { buildParentRefClause } from "./parent-ref-clause.js";
+import { buildReadGateClause } from "./read-gate-clause.js";
+// H.2 — entity-level read ownership, AND-ed with the parent-ref read-gate
+// (join-row entities derive their visibility from a host row's own read path —
+// see db/parent-ref-clause.ts) and the declarative readGate (db/read-gate-clause.ts). `empty` means there's no row the user could ever see.
+// Lives apart from the list WHERE builder so the reference search and sort can gate their
+// target rows the same way without an import cycle.
+export function resolveReadOwnership(ctx, tableName, user, db, parentVisibility, gate) {
+    const parentClause = buildParentRefClause(ctx.entity, ctx.table, tableName, user, db, parentVisibility, gate);
+    return combineClauses(combineClauses(buildOwnershipClause(user, ctx.entity.access?.read, ctx.table, 1, tableName), parentClause), buildReadGateClause(ctx.entity, ctx.table, tableName, user, db, parentVisibility));
+}

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

@@ -1,2 +1,4 @@
 import type { FeatureDefinition } from "../types/index.ts";
-export declare function validateFeatureBootChecks(features: readonly FeatureDefinition[]): void;
+type FeatureBootCheck = FeatureDefinition["bootChecks"][number];
+export declare function runFeatureBootCheck(feature: FeatureDefinition, check: FeatureBootCheck, features: readonly FeatureDefinition[]): void;
+export {};

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

@@ -4,17 +4,13 @@
 // the full mounted-feature set and throws to fail the boot; we wrap the
 // message with the owning feature's name so the error text points back at
 // the feature that declared the check.
-export function validateFeatureBootChecks(features) {
+export function runFeatureBootCheck(feature, check, features) {
     const ctx = { features };
-    for (const feature of features) {
-        for (const check of feature.bootChecks) {
-            try {
-                check(ctx);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
-            }
-        }
+    try {
+        check(ctx);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
     }
 }

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

@@ -0,0 +1,26 @@
+import type { ConfigKeyDefinition } from "@cosmicdrift/kumiko-types/config";
+import type { FeatureDefinition } from "../types/index.ts";
+import type { ValidateBootOptions } from "./boot-options.ts";
+import { collectKnownRoles, collectNavQns, collectWriteHandlerQns } from "./nav.ts";
+import { collectClaimKeys } from "./ownership.ts";
+import { buildQueryHandlerMap } from "./projection-list-screens.ts";
+import { collectScreenQns, collectScreensByShortId } from "./screens.ts";
+import { collectWorkspaceQns } from "./workspaces.ts";
+export type BootContext = {
+    readonly features: readonly FeatureDefinition[];
+    readonly featureMap: ReadonlyMap<string, FeatureDefinition>;
+    readonly options: ValidateBootOptions | undefined;
+    readonly extensionProviders: ReadonlyMap<string, string>;
+    readonly allConfigKeys: ReadonlySet<string>;
+    readonly configKeyDefsByQn: ReadonlyMap<string, ConfigKeyDefinition>;
+    readonly allClaimKeys: ReturnType<typeof collectClaimKeys>;
+    readonly knownRoles: ReturnType<typeof collectKnownRoles>;
+    readonly allScreenQns: ReturnType<typeof collectScreenQns>;
+    readonly allNavQns: ReturnType<typeof collectNavQns>;
+    readonly allWorkspaceQns: ReturnType<typeof collectWorkspaceQns>;
+    readonly allWriteHandlerQns: ReturnType<typeof collectWriteHandlerQns>;
+    readonly screensByShortId: ReturnType<typeof collectScreensByShortId>;
+    readonly queryHandlerQns: ReturnType<typeof buildQueryHandlerMap>;
+};
+export declare function buildBootContext(features: readonly FeatureDefinition[], options: ValidateBootOptions | undefined): BootContext;
+export declare function collectExposedApis(features: readonly FeatureDefinition[]): Map<string, string>;

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

@@ -0,0 +1,57 @@
+import { QnTypes, qualifyEntityName } from "../qualified-name.js";
+import { collectKnownRoles, collectNavQns, collectWriteHandlerQns } from "./nav.js";
+import { collectClaimKeys } from "./ownership.js";
+import { buildQueryHandlerMap } from "./projection-list-screens.js";
+import { collectScreenQns, collectScreensByShortId } from "./screens.js";
+import { collectWorkspaceQns } from "./workspaces.js";
+export function buildBootContext(features, options) {
+    const featureMap = new Map();
+    const extensionProviders = new Map();
+    const allConfigKeys = new Set();
+    // The raw f.configKeys key is the camelCase object key; the QN is built by
+    // define-feature/registry via qualifyEntityName (kebab-cased), so configEdit
+    // screens with multi-word keys only resolve against the qualified form.
+    // allConfigKeys keeps the older `feature.key` form for validateConfigReads.
+    const configKeyDefsByQn = new Map();
+    for (const f of features) {
+        featureMap.set(f.name, f);
+        for (const extName of Object.keys(f.registrarExtensions)) {
+            extensionProviders.set(extName, f.name);
+        }
+        for (const [key, def] of Object.entries(f.configKeys)) {
+            allConfigKeys.add(`${f.name}.${key}`);
+            configKeyDefsByQn.set(qualifyEntityName(f.name, QnTypes.config, key), def);
+        }
+    }
+    return {
+        features,
+        featureMap,
+        options,
+        extensionProviders,
+        allConfigKeys,
+        configKeyDefsByQn,
+        allClaimKeys: collectClaimKeys(features),
+        // Corpus of "referenced in any handler access rule" (there is no runtime
+        // role registry), so typos like "Admi" fail at boot.
+        knownRoles: collectKnownRoles(features),
+        allScreenQns: collectScreenQns(features),
+        allNavQns: collectNavQns(features),
+        allWorkspaceQns: collectWorkspaceQns(features),
+        allWriteHandlerQns: collectWriteHandlerQns(features),
+        screensByShortId: collectScreensByShortId(features),
+        queryHandlerQns: buildQueryHandlerMap(features),
+    };
+}
+export function collectExposedApis(features) {
+    const allExposedApis = new Map(); // apiName → providerFeature
+    for (const f of features) {
+        for (const apiName of f.exposedApis) {
+            const existing = allExposedApis.get(apiName);
+            if (existing && existing !== f.name) {
+                throw new Error(`Cross-feature API "${apiName}" exposed by both "${existing}" and "${f.name}" — API names must be globally unique.`);
+            }
+            allExposedApis.set(apiName, f.name);
+        }
+    }
+    return allExposedApis;
+}

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

@@ -0,0 +1,33 @@
+import type { EnvelopeCipher } from "../../secrets/envelope-cipher.ts";
+export type ValidateBootOptions = {
+    /** Warn when an access role is used by exactly one handler/config-key/
+     *  field across the whole boot scan — often a typo, but also the normal
+     *  shape of a legitimate fine-grained role (one role scoped to one admin
+     *  endpoint on purpose). Opt-in (default false): a default-on
+     *  prod warning that nobody can silence per-role isn't worth the noise
+     *  it generates on every boot. */
+    readonly warnOnUniqueAccessRoles?: boolean;
+    /** QNs the app's sidebar allowlist admits. When set, every declared nav
+     *  whose screen isn't reachable from any allowlisted nav entry gets a
+     *  boot-time warning — that screen would otherwise be silently
+     *  unreachable via the sidebar. When omitted and the app has
+     *  workspaces, the allowlist is derived from `r.workspace({ nav })` and
+     *  `r.nav({ workspaces })` assignments instead. */
+    readonly navAllowlist?: ReadonlySet<string>;
+    /** Nav QNs deliberately left out of the sidebar allowlist because their
+     *  screen is reachable another way (e.g. as a sub-page of a generated
+     *  settings hub). Suppresses the navAllowlist warning for these QNs. */
+    readonly navAllowlistExempt?: ReadonlySet<string>;
+    /** Env the encrypted-field master-key probe reads. Defaults to
+     *  `process.env`; runners pass their resolved env so a ciphertext-only
+     *  key (already decrypted at boot) is visible to the probe. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** The cipher the runner injects after validation (built from the app's
+     *  `masterKey` or the env keyring). Satisfies the availability check for
+     *  `encrypted: true` fields without an env KEK. */
+    readonly entityFieldCipher?: EnvelopeCipher;
+    /** Locales every translation key must carry across all mounted features
+     *  (locale packages count). Without it a key can ship in one language and
+     *  silently fall back at runtime for users of the others. */
+    readonly requiredLocales?: readonly string[];
+};

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

@@ -0,0 +1 @@
+export {};

package/dist/engine/boot-validator/boot-phases-app.d.ts

@@ -0,0 +1,5 @@
+import type { BootContext } from "./boot-context.ts";
+import type { FeatureFlags } from "./boot-phases.ts";
+import type { BootReport } from "./boot-report.ts";
+export declare function runAppWidePhase(report: BootReport, ctx: BootContext): void;
+export declare function runEnvironmentPhase(report: BootReport, ctx: BootContext, flags: FeatureFlags): void;

package/dist/engine/boot-validator/boot-phases-app.js

@@ -0,0 +1,103 @@
+import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption.js";
+import { FILE_STORAGE_PROVIDER_ENV } from "../extension-names.js";
+import { createRegistry } from "../registry.js";
+import { validateProjectionAllowlist } from "../validate-projection-allowlist.js";
+import { runFeatureBootCheck } from "./boot-check.js";
+import { validateCardMetaOverflow } from "./card-meta-overflow.js";
+import { validateConfigReads } from "./config-deps.js";
+import { validateExtensionPreSaveWiring } from "./entity-handler.js";
+import { validateEntityListScreens } from "./entity-list-screens.js";
+import { validateGdprStoragePersistence } from "./gdpr-storage.js";
+import { validateGlobalTenancyEntities } from "./global-tenancy.js";
+import { validateI18nSurfaceKeys, validateRequiredLocales, validateTranslationLocaleConsistency, } from "./i18n-keys.js";
+import { validateNavCycles } from "./nav.js";
+import { validateProjectionListScreens, validateRelatedListSectionQueries, } from "./projection-list-screens.js";
+import { validateQueryOutputColumns } from "./query-output-columns.js";
+import { validateExtensionSelectorPanels } from "./selector-owner-panels.js";
+import { validateSubmitPrefilledHiddenFields } from "./url-prefill-fields.js";
+import { validateDefaultWorkspaceUniqueness } from "./workspaces.js";
+const APP_CHECKS_AFTER_I18N = [
+    {
+        check: "validateTranslationLocaleConsistency",
+        run: (c) => validateTranslationLocaleConsistency(c.features),
+    },
+    {
+        check: "validateRequiredLocales",
+        run: (c) => validateRequiredLocales(c.features, c.options?.requiredLocales),
+    },
+    { check: "validateEntityListScreens", run: (c) => validateEntityListScreens(c.features) },
+    {
+        check: "validateSubmitPrefilledHiddenFields",
+        run: (c) => validateSubmitPrefilledHiddenFields(c.features),
+    },
+    { check: "validateCardMetaOverflow", run: (c) => validateCardMetaOverflow(c.features) },
+    {
+        check: "validateExtensionSelectorPanels",
+        run: (c) => validateExtensionSelectorPanels(c.features),
+    },
+    // Column/field checks assume every `query` string already resolves (validateQueryRefs, phase 1).
+    { check: "validateQueryOutputColumns", run: (c) => validateQueryOutputColumns(c.features) },
+    {
+        check: "validateProjectionListScreens",
+        run: (c) => validateProjectionListScreens(c.features),
+    },
+    {
+        check: "validateRelatedListSectionQueries",
+        run: (c) => validateRelatedListSectionQueries(c.features),
+    },
+    {
+        check: "validateExtensionPreSaveWiring",
+        run: (c) => validateExtensionPreSaveWiring(c.features),
+    },
+    {
+        check: "validateGdprStoragePersistence",
+        run: (c) => validateGdprStoragePersistence(c.features),
+    },
+    {
+        check: "validateGlobalTenancyEntities",
+        run: (c) => validateGlobalTenancyEntities(c.features),
+    },
+];
+function runFeatureBootChecks(report, ctx) {
+    for (const feature of ctx.features) {
+        for (const check of feature.bootChecks) {
+            report.check("runFeatureBootCheck", feature.name, () => runFeatureBootCheck(feature, check, ctx.features));
+        }
+    }
+}
+export function runAppWidePhase(report, ctx) {
+    const { features } = ctx;
+    report.check("validateNavCycles", undefined, () => validateNavCycles(ctx.allNavQns));
+    report.check("validateDefaultWorkspaceUniqueness", undefined, () => validateDefaultWorkspaceUniqueness(ctx.allWorkspaceQns));
+    const built = {};
+    report.check("createRegistry", undefined, () => {
+        built.registry = createRegistry(features);
+    });
+    const registry = built.registry;
+    if (registry !== undefined) {
+        report.check("validateI18nSurfaceKeys", undefined, () => validateI18nSurfaceKeys(features, registry));
+    }
+    for (const { check, run } of APP_CHECKS_AFTER_I18N) {
+        report.check(check, undefined, () => run(ctx));
+    }
+    runFeatureBootChecks(report, ctx);
+    report.check("validateProjectionAllowlist", undefined, () => validateProjectionAllowlist(features));
+    report.check("validateConfigReads", undefined, () => validateConfigReads(features, ctx.allConfigKeys));
+}
+// Independent of the earlier phases: whether the environment can serve the app is
+// a separate question from whether its definitions are consistent.
+export function runEnvironmentPhase(report, ctx, flags) {
+    const { options } = ctx;
+    if (flags.hasEncryptedFields) {
+        // Availability check, not env-presence: eagerly building the keyring
+        // catches malformed keys (wrong length, bad base64) at boot instead of
+        // on the first encrypted read in prod. An injected cipher (test seam,
+        // custom KMS provider) satisfies the requirement without env keys.
+        report.check("validateEntityFieldEncryptionAvailable", undefined, () => validateEntityFieldEncryptionAvailable(options?.env, options?.entityFieldCipher));
+    }
+    report.check("fileStorageProvider", undefined, () => {
+        if (flags.hasFileFields && !(options?.env ?? process.env)[FILE_STORAGE_PROVIDER_ENV]) {
+            throw new Error(`${FILE_STORAGE_PROVIDER_ENV} environment variable is required (file/image fields in use)`);
+        }
+    });
+}

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

@@ -0,0 +1,11 @@
+import type { BootContext } from "./boot-context.ts";
+import type { BootReport } from "./boot-report.ts";
+import { collectDetailForScreens } from "./detail-screens.ts";
+export type FeatureFlags = {
+    hasEncryptedFields: boolean;
+    hasFileFields: boolean;
+};
+type DetailForScreens = ReturnType<typeof collectDetailForScreens>;
+export declare function runStructurePhase(report: BootReport, ctx: BootContext): DetailForScreens;
+export declare function runFeaturePhase(report: BootReport, ctx: BootContext, detailForScreens: DetailForScreens): FeatureFlags;
+export {};