@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

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

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.