@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

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>;

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

@@ -0,0 +1,130 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { diffReplayAgainstSnapshot, generateMigration, readMigrationSqlTexts, replayMigrationsDir, } from "../db/index.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";
+// 1. Schema drift — compute the diff, never write.
+function checkSchemaDrift(ctx, schemaMod, prevSnapshot) {
+    const { out, migrationsDir } = ctx;
+    const drift = generateMigration({
+        metas: schemaMod.entityMetas,
+        prevSnapshot,
+        name: "validate",
+        sequenceNumber: nextSequenceNumber(migrationsDir),
+        priorMigrationsSql: readMigrationSqlTexts(migrationsDir),
+    });
+    const pendingTables = [
+        ...drift.diff.newTables.map((t) => t.tableName),
+        ...drift.diff.changedTables.map((t) => t.tableName),
+        ...drift.diff.droppedTables,
+        ...drift.retiredDrops.map((t) => t.tableName),
+    ];
+    if (pendingTables.length === 0) {
+        out.log("  ✓ schema: migrations match the entity definitions");
+        return true;
+    }
+    out.err("  ✗ schema drift: entity definitions are ahead of kumiko/migrations.");
+    out.err(`    pending — new: ${drift.diff.newTables.length}, changed: ${drift.diff.changedTables.length}, dropped: ${drift.diff.droppedTables.length}`);
+    out.err(`    tables: ${pendingTables.join(", ")}`);
+    out.err("    Fix: `kumiko-schema generate <name>`, then commit the migration.");
+    return false;
+}
+// 2. Boot validity — needs the composed feature set.
+function checkBootValidity(out, schemaMod) {
+    let bootFeatures;
+    try {
+        bootFeatures = featureDefinitionsOf(schemaMod.features);
+    }
+    catch (e) {
+        out.err(`  ✗ boot: ${describeThrown(e)}`);
+        return false;
+    }
+    if (bootFeatures === undefined) {
+        out.log("  · boot: skipped — add `export const FEATURES = composeFeatures(APP_FEATURES, { includeBundled: true })` to kumiko/schema.ts to enable validateBoot.");
+        return true;
+    }
+    try {
+        validateBoot(bootFeatures, {
+            ...parseValidateBootOptions(schemaMod.validateBootOptions),
+            env: withFileStoragePresence(process.env),
+        });
+        out.log("  ✓ boot: feature configuration is valid");
+        return true;
+    }
+    catch (e) {
+        out.err(`  ✗ boot: ${describeThrown(e)}`);
+        return false;
+    }
+}
+function reportMigrationContentMismatches(out, mismatches) {
+    out.err("  ✗ migration-content drift: committed *.sql files don't produce .snapshot.json.");
+    for (const m of mismatches) {
+        out.err(`    ${m.tableName} (${m.kind}): ${m.detail}`);
+    }
+    if (mismatches.some((m) => m.kind === "unexpected-table")) {
+        out.err("    Fix (unexpected-table): build a meta via `defineUnmanagedTable()` " +
+            "from `@cosmicdrift/kumiko-framework/db`, then `r.storeTable(meta, { reason: ... })` " +
+            "inside a feature — this adds it to ENTITY_METAS immediately; the .snapshot.json " +
+            "only picks it up on the NEXT `kumiko-schema generate` run, which you still need " +
+            "to run and commit. `table()` returns a query handle, not a storeTable()-compatible " +
+            "meta — don't pass its result to storeTable(). See the bundled `jobs` feature's " +
+            "job-run-log store table for the pattern.");
+    }
+    if (mismatches.some((m) => m.kind !== "unexpected-table")) {
+        out.err("    Fix (missing-table/column-drift): a migration file's body doesn't match " +
+            "what it (or the snapshot) claims — hand-fix the file, or ship a corrective " +
+            "migration if it's already applied in prod.");
+    }
+}
+// 3. Migration-content drift — replay the committed *.sql files and
+// diff the reconstructed schema against .snapshot.json.
+function checkMigrationContentDrift(ctx, prevSnapshot) {
+    const { out, migrationsDir } = ctx;
+    if (!existsSync(migrationsDir) || prevSnapshot === null)
+        return true;
+    try {
+        const replayed = replayMigrationsDir(migrationsDir);
+        const mismatches = diffReplayAgainstSnapshot(replayed, prevSnapshot);
+        if (mismatches.length === 0) {
+            out.log("  ✓ migrations: table/column names match .snapshot.json");
+            return true;
+        }
+        reportMigrationContentMismatches(out, mismatches);
+        return false;
+    }
+    catch (e) {
+        // replayMigrationsDir fail-loud's on a table-DDL statement it can't
+        // parse — that must surface as a normal ✗ line like every other
+        // check here, not a raw stack trace that kills the process before
+        // any later check (or the Fix: help) ever runs.
+        out.err(`  ✗ migration-content: ${describeThrown(e)}`);
+        out.err("    Fix: a statement in a migration file isn't recognizable to the replay parser — extend the parser's recognized patterns, or reword the migration to one it understands.");
+        return false;
+    }
+}
+// Static, DB-free boot-blocking checks for CI — catches "this won't boot"
+// before deploy. Three layers, no database:
+//   1. schema drift: would `generate` write a migration? (= an entity was
+//      added/changed but never generated → missing table → prod 500)
+//   2. boot validity: validateBoot over the composed FEATURES (QN/screen/
+//      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES;
+//      honours its optional VALIDATE_BOOT_OPTIONS export.
+//   3. migration-content drift: replay every committed *.sql file and
+//      diff the result against .snapshot.json — catches a migration
+//      file whose SQL body doesn't match what its own snapshot entry
+//      claims (e.g. an accidental copy-paste from an earlier file).
+//      Layer 1 alone misses this: it only compares ENTITY_METAS to the
+//      snapshot, never the snapshot to the SQL that's supposed to have
+//      produced it.
+// The DB-level gate (assertKumikoSchemaCurrent) stays at boot/deploy.
+export async function runValidateCommand(ctx) {
+    const schemaMod = await loadSchemaModOrReport(ctx);
+    if (schemaMod === undefined)
+        return 1;
+    const prevSnapshot = loadPreviousSnapshot(join(ctx.migrationsDir, SNAPSHOT_FILENAME));
+    const schemaOk = checkSchemaDrift(ctx, schemaMod, prevSnapshot);
+    const bootOk = checkBootValidity(ctx.out, schemaMod);
+    const migrationsOk = checkMigrationContentDrift(ctx, prevSnapshot);
+    return schemaOk && bootOk && migrationsOk ? 0 : 1;
+}

package/dist/schema-cli.d.ts

@@ -1,21 +1,5 @@
-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[];
-};
+import type { RunSchemaCliOptions, SchemaCliOut } from "./schema-cli/shared.ts";
+export type { RunSchemaCliOptions, SchemaCliOut } from "./schema-cli/shared.ts";
 /**
  * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where
  * `kumiko/schema.ts` + `kumiko/migrations/` live). Returns a process exit code.