@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/dist/schema-cli.js

@@ -7,212 +7,39 @@
 // NO-MAGIC-ON-DATA: reads only checked-in artifacts (kumiko/schema.ts →
 // ENTITY_METAS, kumiko/migrations/*.sql). Never auto-generates at runtime,
 // never applies on app-boot — apply/baseline are explicit deploy-steps.
-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, mkdirSync, readdirSync, writeFileSync } from "node:fs";
-import { join, resolve as resolvePath } from "node:path";
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-import { configureBlindIndexKey, configurePiiSubjectKms, resolveKmsWiringAsync, } from "./crypto/index.js";
-import { assertUniqueTableNames, assertValidMigrationName, baselineMigrations, createDbConnection, diffReplayAgainstSnapshot, fetchAppliedMigrations, findCommentedDropTables, generateMigration, isRetiredFrameworkTable, loadMigrationsFromDir, loadSnapshotJson, readMigrationSqlTexts, rebuildTablesFromDiff, replayMigrationsDir, runMigrationsFromDir, tableExists, writeRebuildMarker, writeSnapshotJson, } from "./db/index.js";
-import { isEntityTableMeta } from "./db/table-introspection.js";
-import { validateBoot } from "./engine/boot-validator.js";
-import { FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, } from "./engine/extension-names.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 { resolve as resolvePath } from "node:path";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { runApplyCommand } from "./schema-cli/apply-command.js";
+import { runBaselineCommand } from "./schema-cli/baseline-command.js";
+import { runGenerateCommand } from "./schema-cli/generate-command.js";
+import { runStatusCommand } from "./schema-cli/status-command.js";
+import { runValidateCommand } from "./schema-cli/validate-command.js";
 import { ensureTemporalPolyfill } from "./time/index.js";
-const SNAPSHOT_FILENAME = ".snapshot.json";
-// `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.
-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.
-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 }),
-    };
-}
-function tableNameHint(entry) {
-    if (isPlainObject(entry) && typeof entry["tableName"] === "string")
-        return entry["tableName"];
-    return "unknown";
-}
-// 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 isFeatureDefinitionShape(entry) {
-    if (!isPlainObject(entry))
-        return false;
-    return (typeof entry["name"] === "string" &&
-        typeof entry["systemScope"] === "boolean" &&
-        FEATURE_ARRAY_KEYS.every((key) => Array.isArray(entry[key])) &&
-        FEATURE_SET_KEYS.every((key) => entry[key] instanceof Set) &&
-        FEATURE_RECORD_KEYS.every((key) => isPlainObject(entry[key])));
-}
-// 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.
-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 (expected an object with a string \`name\`)`);
-        }
-        definitions.push(entry);
-    }
-    return definitions;
-}
-// 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} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`);
-    }
-    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"],
-    };
-}
-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;
-}
-// 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 snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
-    const snapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
-    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`);
-    }
+const SCHEMA_SUBCOMMANDS = ["generate", "validate", "apply", "baseline", "status"];
+const SCHEMA_SUBCOMMAND_HANDLERS = {
+    generate: runGenerateCommand,
+    validate: runValidateCommand,
+    apply: runApplyCommand,
+    baseline: runBaselineCommand,
+    status: runStatusCommand,
+};
+const HELP_ARGS = ["--help", "-h", "help"];
+function printSchemaCliUsage(out) {
+    out.log("");
+    out.log("  Subcommands:");
+    out.log("    generate <name>   Write a new migration from the EntityTableMeta diff");
+    out.log("    validate          Static CI gate (no DB): schema drift + validateBoot");
+    out.log("    apply             Apply pending checked-in SQL files");
+    out.log("    baseline          Mark checked-in migrations as applied (no SQL run)");
+    out.log("    status            List applied vs pending");
     out.log("");
+    return 0;
+}
+function reportUnknownSubcommand(out, sub) {
+    out.err(`  Unknown subcommand: "${sub}"`);
+    out.err(`  Allowed: ${SCHEMA_SUBCOMMANDS.join(" | ")}`);
+    return 1;
 }
-const SCHEMA_SUBCOMMANDS = ["generate", "validate", "apply", "baseline", "status"];
 /**
  * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where
  * `kumiko/schema.ts` + `kumiko/migrations/` live). Returns a process exit code.
@@ -232,406 +59,22 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
     // migration, since the crashed process still records the migration as
     // applied and the rebuild is never retried.
     await ensureTemporalPolyfill();
-    // `--help`/`-h`/`help` fall through to the same "no subcommand" usage
-    // branch below (undefined) — a real request for help, not a typo that
-    // should fail loud like an unrecognized subcommand does.
     const rawSub = argv[0];
-    const sub = rawSub === "--help" || rawSub === "-h" || rawSub === "help" ? undefined : rawSub;
-    const schemaFile = resolvePath(appCwd, "kumiko/schema.ts");
-    const migrationsDir = resolvePath(appCwd, "kumiko/migrations");
-    switch (sub) {
-        case "generate": {
-            const name = argv[1];
-            if (name === "--help" || name === "-h") {
-                out.log("  Usage: schema generate <name>");
-                return 0;
-            }
-            if (!name) {
-                out.err("  Usage: schema generate <name>");
-                return 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) {
-                const msg = e instanceof Error ? e.message : String(e);
-                out.err(`  ${msg}`);
-                out.err("  Usage: schema generate <name>");
-                return 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("  Usage: schema generate <name>");
-                return 1;
-            }
-            if (!existsSync(schemaFile)) {
-                out.err(`  ${schemaFile} fehlt.`);
-                out.err("  App-Convention: kumiko/schema.ts mit");
-                out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
-                return 1;
-            }
-            let metas;
-            try {
-                ({ entityMetas: metas } = await loadSchemaModFromApp(schemaFile));
-            }
-            catch (e) {
-                out.err(`  ${e instanceof Error ? e.message : String(e)}`);
-                return 1;
-            }
-            const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
-            const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
-            const result = generateMigration({
-                metas,
-                prevSnapshot,
-                name,
-                sequenceNumber: nextSequenceNumber(migrationsDir),
-                priorMigrationsSql: readMigrationSqlTexts(migrationsDir),
-            });
-            const isEmpty = result.diff.newTables.length === 0 &&
-                result.diff.changedTables.length === 0 &&
-                result.diff.droppedTables.length === 0 &&
-                result.retiredDrops.length === 0;
-            if (isEmpty) {
-                out.log("  No schema changes detected — kein neues Migration-File geschrieben.");
-                return 0;
-            }
-            if (!existsSync(migrationsDir))
-                mkdirSync(migrationsDir, { recursive: true });
-            writeFileSync(join(migrationsDir, result.filename), result.sqlContent);
-            writeSnapshotJson(snapshotPath, result.snapshot);
-            // 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);
-            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 + ggf. hand-edit + git add + commit. Apply via: schema apply");
-            out.log("");
-            return 0;
-        }
-        case "validate": {
-            // 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.
-            if (!existsSync(schemaFile)) {
-                out.err(`  ${schemaFile} fehlt.`);
-                out.err("  App-Convention: kumiko/schema.ts mit");
-                out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
-                return 1;
-            }
-            let schemaMod;
-            try {
-                schemaMod = await loadSchemaModFromApp(schemaFile);
-            }
-            catch (e) {
-                out.err(`  ${e instanceof Error ? e.message : String(e)}`);
-                return 1;
-            }
-            let ok = true;
-            // 1. Schema drift — compute the diff, never write.
-            const metas = schemaMod.entityMetas;
-            const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
-            const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
-            const drift = generateMigration({
-                metas,
-                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");
-            }
-            else {
-                ok = false;
-                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.");
-            }
-            // 2. Boot validity — needs the composed feature set.
-            let bootFeatures;
-            let bootFeaturesError;
-            try {
-                bootFeatures = featureDefinitionsOf(schemaMod.features);
-            }
-            catch (e) {
-                bootFeaturesError = e instanceof Error ? e.message : String(e);
-            }
-            if (bootFeaturesError !== undefined) {
-                ok = false;
-                out.err(`  ✗ boot: ${bootFeaturesError}`);
-            }
-            else if (bootFeatures) {
-                try {
-                    validateBoot(bootFeatures, {
-                        ...parseValidateBootOptions(schemaMod.validateBootOptions),
-                        env: withFileStoragePresence(process.env),
-                    });
-                    out.log("  ✓ boot: feature configuration is valid");
-                }
-                catch (e) {
-                    ok = false;
-                    out.err(`  ✗ boot: ${e instanceof Error ? e.message : String(e)}`);
-                }
-            }
-            else {
-                out.log("  · boot: skipped — add `export const FEATURES = composeFeatures(APP_FEATURES, { includeBundled: true })` to kumiko/schema.ts to enable validateBoot.");
-            }
-            // 3. Migration-content drift — replay the committed *.sql files and
-            // diff the reconstructed schema against .snapshot.json.
-            if (existsSync(migrationsDir) && prevSnapshot !== null) {
-                try {
-                    const replayed = replayMigrationsDir(migrationsDir);
-                    const mismatches = diffReplayAgainstSnapshot(replayed, prevSnapshot);
-                    if (mismatches.length === 0) {
-                        out.log("  ✓ migrations: table/column names match .snapshot.json");
-                    }
-                    else {
-                        ok = false;
-                        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.");
-                        }
-                    }
-                }
-                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.
-                    ok = false;
-                    out.err(`  ✗ migration-content: ${e instanceof Error ? e.message : String(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 ok ? 0 : 1;
-        }
-        case "apply": {
-            const dbUrl = process.env["DATABASE_URL"];
-            if (!dbUrl) {
-                out.err("  DATABASE_URL not set.");
-                return 1;
-            }
-            if (!existsSync(migrationsDir)) {
-                out.err(`  ${migrationsDir} fehlt — erst schema generate <name>.`);
-                return 1;
-            }
-            const { db, close } = createDbConnection({ url: dbUrl });
-            let wiring;
-            try {
-                const result = await runMigrationsFromDir(db, migrationsDir);
-                // 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);
-                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("");
-                // 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,
-                    });
-                    if ("kms" in wiring) {
-                        configurePiiSubjectKms(wiring.kms);
-                        configureBlindIndexKey(wiring.blindIndexKey);
-                    }
-                    const thisRunTables = await queueRebuildsFromMarkers(db, {
-                        migrationsDir,
-                        appliedIds: result.applied,
-                    });
-                    const registry = createRegistry(options.features);
-                    const rebuildRun = await runPendingRebuilds(db, registry, { thisRunTables });
-                    reportPendingRebuildRun(rebuildRun, out.log);
-                }
-                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();
-            }
-        }
-        case "baseline": {
-            // 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 = process.env["DATABASE_URL"];
-            if (!dbUrl) {
-                out.err("  DATABASE_URL not set.");
-                return 1;
-            }
-            if (!existsSync(migrationsDir)) {
-                out.err(`  ${migrationsDir} fehlt — erst schema generate <name>.`);
-                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(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
-                return 1;
-            }
-            finally {
-                await close();
-            }
-        }
-        case "status": {
-            const dbUrl = process.env["DATABASE_URL"];
-            if (!dbUrl) {
-                out.err("  DATABASE_URL not set.");
-                return 1;
-            }
-            if (!existsSync(migrationsDir)) {
-                out.log("  Kein kumiko/migrations/ — App ist noch auf dem alten drizzle-Pfad.");
-                return 0;
-            }
-            const local = loadMigrationsFromDir(migrationsDir);
-            const { db, close } = createDbConnection({ url: dbUrl });
-            try {
-                // 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");
-                const applied = trackingExists
-                    ? new Set((await fetchAppliedMigrations(db)).map((a) => a.id))
-                    : new Set();
-                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: ${e instanceof Error ? e.message : String(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.
-                }
-            }
-        }
-        default: {
-            // No subcommand (`kumiko schema`) is a help request → usage + exit 0.
-            // An unrecognized one (typo, e.g. `schema cutover`) must fail loud —
-            // silently exiting 0 here let a deploy's migrate step print help and
-            // move on without ever running a migration.
-            if (sub !== undefined) {
-                out.err(`  Unbekanntes Subcommand: "${sub}"`);
-                out.err(`  Erlaubt: ${SCHEMA_SUBCOMMANDS.join(" | ")}`);
-                return 1;
-            }
-            out.log("");
-            out.log("  Subcommands:");
-            out.log("    generate <name>   Schreibe neue Migration aus EntityTableMeta-Diff");
-            out.log("    validate          Static CI-Gate (kein DB): schema-drift + validateBoot");
-            out.log("    apply             Applied pending checked-in SQL-Files");
-            out.log("    baseline          Markiere checked-in Migrations als applied (kein SQL-Run)");
-            out.log("    status            Liste applied vs pending");
-            out.log("");
-            return 0;
-        }
-    }
+    // No subcommand (`kumiko schema`) is a help request → usage + exit 0.
+    // `--help`/`-h`/`help` are the same — a real request for help, not a typo
+    // that should fail loud like an unrecognized subcommand does.
+    if (rawSub === undefined || isOneOf(HELP_ARGS, rawSub))
+        return printSchemaCliUsage(out);
+    // An unrecognized subcommand (typo, e.g. `schema cutover`) must fail loud —
+    // silently exiting 0 here let a deploy's migrate step print help and
+    // move on without ever running a migration.
+    if (!isOneOf(SCHEMA_SUBCOMMANDS, rawSub))
+        return reportUnknownSubcommand(out, rawSub);
+    return SCHEMA_SUBCOMMAND_HANDLERS[rawSub]({
+        argv,
+        out,
+        options,
+        schemaFile: resolvePath(appCwd, "kumiko/schema.ts"),
+        migrationsDir: resolvePath(appCwd, "kumiko/migrations"),
+    });
 }