@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

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

@@ -0,0 +1,97 @@
+import { configureBlindIndexKey, configurePiiSubjectKms, resolveKmsWiringAsync, } from "../crypto/index.js";
+import { createDbConnection, runMigrationsFromDir } from "../db/index.js";
+import { createRegistry } from "../engine/registry.js";
+import { createEventsTable } from "../event-store/index.js";
+import { queueRebuildsFromMarkers, reportPendingRebuildRun, runPendingRebuilds, } from "../migrations/index.js";
+import { createEventConsumerStateTable, createProjectionStateTable } from "../pipeline/index.js";
+import { migrationsDirExistsOrReport, readDatabaseUrlOrReport, } from "./shared.js";
+async function ensureFrameworkInfrastructureTables(db) {
+    // Framework infrastructure tables (event store + pipeline state) are not captured by
+    // `generate`, which handles only entity read tables. Existing databases have them
+    // from the legacy-drizzle foundation; without them, a greenfield database (the
+    // first app without a cutover) would lack kumiko_events and runProdApp would fail
+    // during boot. All three are idempotent (tableExists-gated), so they are no-ops for
+    // existing databases.
+    await createEventsTable(db);
+    await createEventConsumerStateTable(db);
+    await createProjectionStateTable(db);
+}
+function reportAppliedMigrations(out, result) {
+    out.log("");
+    if (result.applied.length === 0) {
+        out.log(`  ✓ All ${result.skipped.length} migrations already applied.`);
+    }
+    else {
+        out.log(`  ✓ Applied ${result.applied.length}:`);
+        for (const id of result.applied)
+            out.log(`    + ${id}`);
+        if (result.skipped.length > 0)
+            out.log(`  (${result.skipped.length} already applied)`);
+    }
+    out.log("");
+}
+function configureRebuildKms(wiring) {
+    if ("kms" in wiring) {
+        configurePiiSubjectKms(wiring.kms);
+        configureBlindIndexKey(wiring.blindIndexKey);
+    }
+}
+async function rebuildQueuedProjections(db, ctx, features, appliedIds) {
+    const thisRunTables = await queueRebuildsFromMarkers(db, {
+        migrationsDir: ctx.migrationsDir,
+        appliedIds,
+    });
+    const registry = createRegistry(features);
+    const rebuildRun = await runPendingRebuilds(db, registry, { thisRunTables });
+    reportPendingRebuildRun(rebuildRun, ctx.out.log);
+}
+export async function runApplyCommand(ctx) {
+    const { out, options, migrationsDir } = ctx;
+    const dbUrl = readDatabaseUrlOrReport(out);
+    if (dbUrl === undefined)
+        return 1;
+    if (!migrationsDirExistsOrReport(ctx))
+        return 1;
+    const { db, close } = createDbConnection({ url: dbUrl });
+    let wiring;
+    try {
+        const result = await runMigrationsFromDir(db, migrationsDir);
+        await ensureFrameworkInfrastructureTables(db);
+        reportAppliedMigrations(out, result);
+        // Projection-rebuild for tables a freshly applied migration changed
+        // (marker NNNN_<name>.rebuild.json from `generate`). Needs the composed
+        // feature set → only when the caller passed `features` (the app bin);
+        // the dev CLI omits it and applies migrations only. Runs unconditionally
+        // (not gated on result.applied.length > 0): a persistent queue
+        // (kumiko_pending_rebuilds) survives a failed/crashed rebuild from an
+        // earlier apply, so a later apply with zero new migrations still must
+        // retry it — otherwise a failed rebuild is silently never retried,
+        // since the migration itself is already tracked applied.
+        if (options.features) {
+            // A rebuild replays applyEntityEvent, which computes bidx columns from
+            // configureBlindIndexKey/configurePiiSubjectKms — both boot-injected by
+            // run{Prod,Dev}App but never by this standalone CLI (the migrate-db
+            // initContainer). Without wiring them here, a rebuild would silently
+            // null out bidx columns and, for ciphertext, throw only once it hits
+            // the row.
+            wiring = await resolveKmsWiringAsync(process.env, {
+                logPrefix: "[kumiko schema apply]",
+                log: out.log,
+                slots: options.kmsSlots,
+            });
+            configureRebuildKms(wiring);
+            await rebuildQueuedProjections(db, ctx, options.features, result.applied);
+        }
+        return 0;
+    }
+    catch (e) {
+        out.err("");
+        out.err(`  ✗ ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`);
+        out.err("");
+        return 1;
+    }
+    finally {
+        await wiring?.close();
+        await close();
+    }
+}

package/dist/schema-cli/baseline-command.d.ts

@@ -0,0 +1,2 @@
+import { type SchemaCliContext } from "./shared.ts";
+export declare function runBaselineCommand(ctx: SchemaCliContext): Promise<number>;

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

@@ -0,0 +1,33 @@
+import { baselineMigrations, createDbConnection, loadMigrationsFromDir } from "../db/index.js";
+import { describeThrown, migrationsDirExistsOrReport, readDatabaseUrlOrReport, } from "./shared.js";
+export async function runBaselineCommand(ctx) {
+    const { out, migrationsDir } = ctx;
+    // Adopt an existing DB: mark all checked-in migrations as applied WITHOUT
+    // running their SQL (prod tables already exist — cutover from the legacy
+    // drizzle system). Afterwards the boot-gate is drift-free.
+    const dbUrl = readDatabaseUrlOrReport(out);
+    if (dbUrl === undefined)
+        return 1;
+    if (!migrationsDirExistsOrReport(ctx))
+        return 1;
+    const { db, close } = createDbConnection({ url: dbUrl });
+    try {
+        const result = await baselineMigrations(db, loadMigrationsFromDir(migrationsDir));
+        out.log("");
+        out.log(`  ✓ Marked ${result.marked.length} migration(s) as applied (no SQL run):`);
+        for (const id of result.marked)
+            out.log(`    + ${id}`);
+        if (result.alreadyTracked.length > 0) {
+            out.log(`  (${result.alreadyTracked.length} already tracked)`);
+        }
+        out.log("");
+        return 0;
+    }
+    catch (e) {
+        out.err(`  ✗ ${describeThrown(e)}`);
+        return 1;
+    }
+    finally {
+        await close();
+    }
+}

package/dist/schema-cli/generate-command.d.ts

@@ -0,0 +1,2 @@
+import { type SchemaCliContext } from "./shared.ts";
+export declare function runGenerateCommand(ctx: SchemaCliContext): Promise<number>;

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

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertValidMigrationName, generateMigration, readMigrationSqlTexts, rebuildTablesFromDiff, writeRebuildMarker, writeSnapshotJson, } from "../db/index.js";
+import { describeThrown, loadPreviousSnapshot, loadSchemaModOrReport, nextSequenceNumber, SNAPSHOT_FILENAME, } from "./shared.js";
+const GENERATE_USAGE = "  Usage: schema generate <name>";
+function parseGenerateName(ctx) {
+    const { argv, out } = ctx;
+    const name = argv[1];
+    if (name === "--help" || name === "-h") {
+        out.log(GENERATE_USAGE);
+        return { kind: "exit", code: 0 };
+    }
+    if (!name) {
+        out.err(GENERATE_USAGE);
+        return { kind: "exit", code: 1 };
+    }
+    // name lands unescaped in `${seq}_${name}.sql` (generateMigration) —
+    // shared allowlist blocks flag-like names, path traversal, and
+    // ENAMETOOLONG-length names.
+    try {
+        assertValidMigrationName(name);
+    }
+    catch (e) {
+        out.err(`  ${describeThrown(e)}`);
+        out.err(GENERATE_USAGE);
+        return { kind: "exit", code: 1 };
+    }
+    // Trailing args (e.g. a typo'd `--dry-run` — there is no such flag) were
+    // silently ignored and the migration got written anyway. Reject them
+    // before any IO instead of pretending they did something.
+    if (argv.length > 2) {
+        out.err(`  Unrecognized argument(s): ${argv.slice(2).join(" ")}`);
+        out.err(GENERATE_USAGE);
+        return { kind: "exit", code: 1 };
+    }
+    return { kind: "name", name };
+}
+function isEmptyMigration(result) {
+    return (result.diff.newTables.length === 0 &&
+        result.diff.changedTables.length === 0 &&
+        result.diff.droppedTables.length === 0 &&
+        result.retiredDrops.length === 0);
+}
+function writeMigrationFiles(migrationsDir, snapshotPath, result) {
+    if (!existsSync(migrationsDir))
+        mkdirSync(migrationsDir, { recursive: true });
+    writeFileSync(join(migrationsDir, result.filename), result.sqlContent);
+    writeSnapshotJson(snapshotPath, result.snapshot);
+}
+function reportGeneratedMigration(out, result, rebuildTables) {
+    out.log("");
+    out.log(`  ✓ ${result.filename}`);
+    out.log(`    new tables: ${result.diff.newTables.length}, changed: ${result.diff.changedTables.length}, dropped: ${result.diff.droppedTables.length}, retired framework tables dropped: ${result.retiredDrops.length}`);
+    if (rebuildTables.length > 0) {
+        out.log(`    rebuild-marker: ${result.filename.replace(/\.sql$/, ".rebuild.json")} (${rebuildTables.length} table(s))`);
+    }
+    out.log("");
+    out.log("  Review, hand-edit if needed, then git add + commit. Apply via: schema apply");
+    out.log("");
+}
+export async function runGenerateCommand(ctx) {
+    const { out, migrationsDir } = ctx;
+    const parsed = parseGenerateName(ctx);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const schemaMod = await loadSchemaModOrReport(ctx);
+    if (schemaMod === undefined)
+        return 1;
+    const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
+    const prevSnapshot = loadPreviousSnapshot(snapshotPath);
+    const result = generateMigration({
+        metas: schemaMod.entityMetas,
+        prevSnapshot,
+        name: parsed.name,
+        sequenceNumber: nextSequenceNumber(migrationsDir),
+        priorMigrationsSql: readMigrationSqlTexts(migrationsDir),
+    });
+    if (isEmptyMigration(result)) {
+        out.log("  No schema changes detected — no new migration file written.");
+        return 0;
+    }
+    writeMigrationFiles(migrationsDir, snapshotPath, result);
+    // Rebuild markers are written only for incremental migrations — the initial
+    // migration (prevSnapshot===null) only creates tables, so there are no historical
+    // events to replay.
+    const rebuildTables = prevSnapshot === null ? [] : rebuildTablesFromDiff(result.diff);
+    writeRebuildMarker(migrationsDir, result.filename, rebuildTables);
+    reportGeneratedMigration(out, result, rebuildTables);
+    return 0;
+}

package/dist/schema-cli/shared.d.ts

@@ -0,0 +1,39 @@
+import { type renderTablesDdl } from "../db/index.ts";
+import type { FeatureDefinition } from "../engine/types/feature.ts";
+export type SchemaCliOut = {
+    readonly log: (line: string) => void;
+    readonly err: (line: string) => void;
+};
+export type RunSchemaCliOptions = {
+    readonly features?: undefined;
+    readonly kmsSlots?: undefined;
+} | {
+    /** Composed app features. When given, `apply` rebuilds the projections whose
+     *  tables a freshly applied migration changed (via its `.rebuild.json`
+     *  marker). Omitted (dev `kumiko schema`) → no rebuild, migrations only. */
+    readonly features: readonly FeatureDefinition[];
+    /** Schema-declared Key Manager slots, `kmsSlotsOf(composedEnv.schema)`, or
+     *  `[]` when the app wires none. This CLI parses no env schema, so the
+     *  rebuild's KMS wiring cannot derive them itself. */
+    readonly kmsSlots: readonly string[];
+};
+export type SchemaCliContext = {
+    readonly argv: readonly string[];
+    readonly out: SchemaCliOut;
+    readonly options: RunSchemaCliOptions;
+    readonly schemaFile: string;
+    readonly migrationsDir: string;
+};
+export type SchemaSubcommandHandler = (ctx: SchemaCliContext) => Promise<number>;
+export declare const SNAPSHOT_FILENAME = ".snapshot.json";
+export type SchemaMod = {
+    readonly entityMetas: Parameters<typeof renderTablesDdl>[0];
+    readonly features?: unknown;
+    readonly validateBootOptions?: unknown;
+};
+export declare function describeThrown(e: unknown): string;
+export declare function nextSequenceNumber(migrationsDir: string): number;
+export declare function loadPreviousSnapshot(snapshotPath: string): import("../db/migrate-generator.ts").Snapshot | null;
+export declare function loadSchemaModOrReport(ctx: SchemaCliContext): Promise<SchemaMod | undefined>;
+export declare function readDatabaseUrlOrReport(out: SchemaCliOut): string | undefined;
+export declare function migrationsDirExistsOrReport(ctx: SchemaCliContext): boolean;

package/dist/schema-cli/shared.js

@@ -0,0 +1,95 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readdirSync } from "node:fs";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { assertUniqueTableNames, loadSnapshotJson } from "../db/index.js";
+import { isEntityTableMeta } from "../db/table-introspection.js";
+export const SNAPSHOT_FILENAME = ".snapshot.json";
+export function describeThrown(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function tableNameHint(entry) {
+    if (isPlainObject(entry) && typeof entry["tableName"] === "string")
+        return entry["tableName"];
+    return "unknown";
+}
+// Single load-path for kumiko/schema.ts (512/3) — `generate` and `validate`
+// both need ENTITY_METAS (and validate additionally wants FEATURES); this is
+// the one place that enforces "ENTITY_METAS must be an array" so the two
+// commands can't drift on the check or its wording. Throws — callers that
+// want a graceful exit code (validate) catch it themselves.
+async function loadSchemaModFromApp(schemaFile) {
+    // bun imports TS directly — no spawn needed.
+    const mod = await import(__rewriteRelativeImportExtension(schemaFile));
+    const entityMetas = mod["ENTITY_METAS"];
+    if (!Array.isArray(entityMetas)) {
+        throw new Error(`Schema file ${schemaFile} must declare \`export const ENTITY_METAS: EntityTableMeta[]\`.`);
+    }
+    const validMetas = [];
+    for (const [index, entry] of entityMetas.entries()) {
+        if (!isEntityTableMeta(entry)) {
+            throw new Error(`Schema file ${schemaFile}: ENTITY_METAS[${index}] is not an EntityTableMeta (table: ${tableNameHint(entry)}).`);
+        }
+        validMetas.push(entry);
+    }
+    assertUniqueTableNames(validMetas);
+    return {
+        entityMetas: validMetas,
+        features: mod["FEATURES"],
+        validateBootOptions: mod["VALIDATE_BOOT_OPTIONS"],
+    };
+}
+export function nextSequenceNumber(migrationsDir) {
+    if (!existsSync(migrationsDir))
+        return 1;
+    const files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql"));
+    let max = 0;
+    for (const f of files) {
+        const m = f.match(/^(\d+)_/);
+        if (m) {
+            const n = Number(m[1]);
+            if (n > max)
+                max = n;
+        }
+    }
+    return max + 1;
+}
+export function loadPreviousSnapshot(snapshotPath) {
+    return existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
+}
+export async function loadSchemaModOrReport(ctx) {
+    const { out, schemaFile } = ctx;
+    if (!existsSync(schemaFile)) {
+        out.err(`  ${schemaFile} is missing.`);
+        out.err("  App convention: kumiko/schema.ts with");
+        out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
+        return undefined;
+    }
+    try {
+        return await loadSchemaModFromApp(schemaFile);
+    }
+    catch (e) {
+        out.err(`  ${describeThrown(e)}`);
+        return undefined;
+    }
+}
+export function readDatabaseUrlOrReport(out) {
+    const dbUrl = process.env["DATABASE_URL"];
+    if (!dbUrl) {
+        out.err("  DATABASE_URL not set.");
+        return undefined;
+    }
+    return dbUrl;
+}
+export function migrationsDirExistsOrReport(ctx) {
+    if (existsSync(ctx.migrationsDir))
+        return true;
+    ctx.out.err(`  ${ctx.migrationsDir} is missing — run schema generate <name> first.`);
+    return false;
+}

package/dist/schema-cli/status-command.d.ts

@@ -0,0 +1,2 @@
+import { type SchemaCliContext } from "./shared.ts";
+export declare function runStatusCommand(ctx: SchemaCliContext): Promise<number>;

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

@@ -0,0 +1,73 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createDbConnection, fetchAppliedMigrations, findCommentedDropTables, isRetiredFrameworkTable, loadMigrationsFromDir, readMigrationSqlTexts, tableExists, } from "../db/index.js";
+import { describeThrown, loadPreviousSnapshot, readDatabaseUrlOrReport, SNAPSHOT_FILENAME, } from "./shared.js";
+// A table that a migration only drops as a commented DESTRUCTIVE marker and
+// that the snapshot no longer has is gone on paper but still in the live DB.
+async function reportLeftoverDroppedTables(db, migrationsDir, out) {
+    const snapshot = loadPreviousSnapshot(join(migrationsDir, SNAPSHOT_FILENAME));
+    const leftovers = [];
+    for (const tableName of findCommentedDropTables(readMigrationSqlTexts(migrationsDir), snapshot)) {
+        if (await tableExists(db, tableName))
+            leftovers.push(tableName);
+    }
+    // skip: nothing left over, nothing to report
+    if (leftovers.length === 0)
+        return;
+    out.log("  Tables dropped only as a commented DESTRUCTIVE marker but still in the database:");
+    for (const tableName of leftovers) {
+        out.log(isRetiredFrameworkTable(tableName)
+            ? `    ! ${tableName} — retired framework table: the next \`schema generate <name>\` creates the drop`
+            : `    ! ${tableName} — app table: after a backup, write a new migration with the drop`);
+    }
+    out.log("");
+}
+async function fetchAppliedMigrationIds(db) {
+    // On a fresh database where `kumiko schema apply` has never run, the tracking table is
+    // absent, which means "nothing applied". Connection and permission errors must not
+    // be swallowed (false pending results would hide the problem) — tableExists checks
+    // only for existence, while all other errors propagate.
+    const trackingExists = await tableExists(db, "_kumiko_migrations");
+    return trackingExists
+        ? new Set((await fetchAppliedMigrations(db)).map((a) => a.id))
+        : new Set();
+}
+export async function runStatusCommand(ctx) {
+    const { out, migrationsDir } = ctx;
+    const dbUrl = readDatabaseUrlOrReport(out);
+    if (dbUrl === undefined)
+        return 1;
+    if (!existsSync(migrationsDir)) {
+        out.log("  No kumiko/migrations/ — the app is still on the legacy drizzle path.");
+        return 0;
+    }
+    const local = loadMigrationsFromDir(migrationsDir);
+    const { db, close } = createDbConnection({ url: dbUrl });
+    try {
+        const applied = await fetchAppliedMigrationIds(db);
+        out.log("");
+        out.log(`  ${local.length} migrations in ${migrationsDir}:`);
+        for (const m of local)
+            out.log(`    ${applied.has(m.id) ? "✓" : " "} ${m.id}`);
+        const pending = local.filter((m) => !applied.has(m.id)).length;
+        out.log("");
+        out.log(`  ${applied.size} applied, ${pending} pending.`);
+        out.log("");
+        await reportLeftoverDroppedTables(db, migrationsDir, out);
+        return pending === 0 ? 0 : 1;
+    }
+    catch (e) {
+        // Message only, never dbUrl: it can carry the password.
+        out.err(`  ✗ schema status failed: ${describeThrown(e)}`);
+        out.err('  Check that DATABASE_URL is reachable and the database exists (the scaffold\'s docker-compose creates "app").');
+        return 1;
+    }
+    finally {
+        try {
+            await close();
+        }
+        catch {
+            // The connection already failed and was reported above; a failing close must not throw again.
+        }
+    }
+}

package/dist/schema-cli/validate-boot-input.d.ts

@@ -0,0 +1,5 @@
+import type { ValidateBootOptions } from "../engine/boot-validator.ts";
+import type { FeatureDefinition } from "../engine/types/feature.ts";
+export declare function withFileStoragePresence(env: Readonly<Record<string, string | undefined>>): Record<string, string | undefined>;
+export declare function parseValidateBootOptions(raw: unknown): ValidateBootOptions;
+export declare function featureDefinitionsOf(value: unknown): readonly FeatureDefinition[] | undefined;

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

@@ -0,0 +1,130 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, } from "../engine/extension-names.js";
+// `validate` only sees the composed FEATURES. The file provider normally comes from
+// runProdApp's `fileStorage` option, which defaults FILE_STORAGE_PROVIDER at boot, so
+// an unset variable here is no misconfiguration. The deploy env is checked by the real boot.
+export function withFileStoragePresence(env) {
+    return env[FILE_STORAGE_PROVIDER_ENV] === undefined
+        ? { ...env, [FILE_STORAGE_PROVIDER_ENV]: FILE_STORAGE_PROVIDER_BOOT_SENTINEL }
+        : { ...env };
+}
+function isStringSet(value) {
+    return value instanceof Set && [...value].every((entry) => typeof entry === "string");
+}
+function isNonEmptyStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry !== "");
+}
+function isBoolean(value) {
+    return typeof value === "boolean";
+}
+function validateBootOptionsError(detail) {
+    return new Error(`kumiko/schema.ts: \`VALIDATE_BOOT_OPTIONS\` ${detail}`);
+}
+function readOptionalOption(raw, key, isValid, expected) {
+    const value = Reflect.get(raw, key);
+    if (value === undefined)
+        return undefined;
+    if (!isValid(value))
+        throw validateBootOptionsError(`\`${key}\` must be ${expected}.`);
+    return value;
+}
+// Boundary check for `export const VALIDATE_BOOT_OPTIONS` in kumiko/schema.ts.
+// Only the options that change what validateBoot reports are honoured; `env` and
+// `entityFieldCipher` are runner-injected and deliberately ignored here.
+export function parseValidateBootOptions(raw) {
+    if (raw === undefined)
+        return {};
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw validateBootOptionsError("must be an object (ValidateBootOptions).");
+    }
+    const navAllowlist = readOptionalOption(raw, "navAllowlist", isStringSet, "a Set<string>");
+    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");
+    return {
+        ...(requiredLocales !== undefined && { requiredLocales }),
+        ...(navAllowlist !== undefined && { navAllowlist }),
+        ...(navAllowlistExempt !== undefined && { navAllowlistExempt }),
+        ...(warnOnUniqueAccessRoles !== undefined && { warnOnUniqueAccessRoles }),
+    };
+}
+// Every non-optional top-level property of FeatureDefinition, grouped by the runtime shape the
+// boot validators rely on; a hand-built entry missing one would crash far from the cause.
+const FEATURE_ARRAY_KEYS = [
+    "requires",
+    "optionalRequires",
+    "configSeeds",
+    "extensionUsages",
+    "extensionSelectors",
+    "bootChecks",
+    "referenceData",
+    "configReads",
+    "authClaimsHooks",
+];
+const FEATURE_SET_KEYS = [
+    "requiredProjections",
+    "requiredSteps",
+    "exposedApis",
+    "usedApis",
+];
+const FEATURE_RECORD_KEYS = [
+    "relations",
+    "writeHandlers",
+    "queryHandlers",
+    "streamHandlers",
+    "translations",
+    "configKeys",
+    "jobs",
+    "registrarExtensions",
+    "notifications",
+    "events",
+    "eventMigrations",
+    "handlerEntityMappings",
+    "metrics",
+    "secretKeys",
+    "secretNamespaces",
+    "projections",
+    "multiStreamProjections",
+    "claimKeys",
+    "screens",
+    "navs",
+    "workspaces",
+    "httpRoutes",
+    "webSocketRoutes",
+    "storeTables",
+];
+function firstFeatureShapeViolation(entry) {
+    if (!isPlainObject(entry))
+        return "entry must be an object";
+    if (typeof entry["name"] !== "string")
+        return "`name` must be a string";
+    if (typeof entry["systemScope"] !== "boolean")
+        return "`systemScope` must be a boolean";
+    const arrayKey = FEATURE_ARRAY_KEYS.find((key) => !Array.isArray(entry[key]));
+    if (arrayKey)
+        return `\`${arrayKey}\` must be an array`;
+    const setKey = FEATURE_SET_KEYS.find((key) => !(entry[key] instanceof Set));
+    if (setKey)
+        return `\`${setKey}\` must be a Set`;
+    const recordKey = FEATURE_RECORD_KEYS.find((key) => !isPlainObject(entry[key]));
+    if (recordKey)
+        return `\`${recordKey}\` must be an object`;
+    return undefined;
+}
+function isFeatureDefinitionShape(entry) {
+    return firstFeatureShapeViolation(entry) === undefined;
+}
+// FEATURES comes from the app's schema module; one malformed entry would make
+// validateBoot fail with an unrelated error far from the cause, so name the index here.
+export function featureDefinitionsOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const definitions = [];
+    for (const [index, entry] of value.entries()) {
+        if (!isFeatureDefinitionShape(entry)) {
+            throw new Error(`FEATURES[${index}] is not a FeatureDefinition: ${firstFeatureShapeViolation(entry)}`);
+        }
+        definitions.push(entry);
+    }
+    return definitions;
+}

package/dist/schema-cli/validate-command.d.ts

@@ -0,0 +1,2 @@
+import { type SchemaCliContext } from "./shared.ts";
+export declare function runValidateCommand(ctx: SchemaCliContext): Promise<number>;