@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/pipeline/system-hooks.js

@@ -552,9 +552,58 @@ function readPatRevokedScope(payload) {
     const tokenIds = readNonEmptyStringArray(payload["tokenIds"]);
     return tokenIds ? { kind: "pat-tokens", tokenIds } : { kind: "user" };
 }
-export function createAccessInvalidationEventConsumer(sseBroker) {
+const ACCESS_INVALIDATION_BACKOFF_INITIAL_MS = 250;
+const ACCESS_INVALIDATION_BACKOFF_MAX_MS = 10_000;
+// Only the publish can fail because Redis is unreachable. The consumer must keep retrying those
+// until Redis is back (dead-lettering would silently stop every later revocation reaching open
+// streams), while any other failure keeps the dispatcher's attempt limit so one poison event
+// cannot hold back every later revocation for good.
+class AccessInvalidationTransportError extends Error {
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.name = "AccessInvalidationTransportError";
+    }
+}
+function isAccessInvalidationTransportError(error) {
+    return error instanceof AccessInvalidationTransportError;
+}
+// The gate rethrows without touching Redis until the backoff elapsed.
+function withTransportBackoff(handle, now) {
+    let delayMs = ACCESS_INVALIDATION_BACKOFF_INITIAL_MS;
+    let retryNotBefore = 0;
+    let transportError = null;
+    return async (event) => {
+        if (transportError !== null && now() < retryNotBefore)
+            throw transportError;
+        try {
+            await handle(event);
+            delayMs = ACCESS_INVALIDATION_BACKOFF_INITIAL_MS;
+            transportError = null;
+        }
+        catch (err) {
+            if (isAccessInvalidationTransportError(err)) {
+                transportError = err;
+                retryNotBefore = now() + delayMs;
+                delayMs = Math.min(delayMs * 2, ACCESS_INVALIDATION_BACKOFF_MAX_MS);
+            }
+            throw err;
+        }
+    };
+}
+export function createAccessInvalidationEventConsumer(sseBroker, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const publish = async (userId, scope) => {
+        try {
+            await sseBroker.publishAccessInvalidation(userId, scope);
+        }
+        catch (cause) {
+            throw new AccessInvalidationTransportError(cause);
+        }
+    };
     return {
         name: ACCESS_INVALIDATION_CONSUMER_NAME,
+        // Count-based dead-lettering would end after a few seconds of Redis downtime.
+        errorPolicy: { isTransientError: isAccessInvalidationTransportError },
         // Shared delivery, same reasoning as SSE broadcast: one
         // cursor reads every event once and calls sseBroker.publishAccessInvalidation
         // below, which a Redis-backed broker republishes to every replica's
@@ -565,7 +614,7 @@ export function createAccessInvalidationEventConsumer(sseBroker) {
         // existed has nothing to invalidate — replaying it would be a no-op at
         // best and a spurious stream-close at worst.
         startFrom: "now",
-        handler: async (event) => {
+        handler: withTransportBackoff(async (event) => {
             if (event.type === SESSION_REVOKED_EVENT_TYPE) {
                 const userId = event.payload["userId"];
                 // skip: malformed session-revoked payload — fail open on this one
@@ -574,7 +623,7 @@ export function createAccessInvalidationEventConsumer(sseBroker) {
                 // every user behind one bad row).
                 if (typeof userId !== "string" || userId.length === 0)
                     return;
-                await sseBroker.publishAccessInvalidation(userId, readSessionRevokedScope(event.payload));
+                await publish(userId, readSessionRevokedScope(event.payload));
             }
             if (event.type === PAT_REVOKED_EVENT_TYPE) {
                 const userId = event.payload["userId"];
@@ -582,7 +631,7 @@ export function createAccessInvalidationEventConsumer(sseBroker) {
                 // session-revoked above.
                 if (typeof userId !== "string" || userId.length === 0)
                     return;
-                await sseBroker.publishAccessInvalidation(userId, readPatRevokedScope(event.payload));
+                await publish(userId, readPatRevokedScope(event.payload));
             }
             if (event.type === TENANT_MEMBERSHIP_UPDATED_EVENT_TYPE ||
                 event.type === TENANT_MEMBERSHIP_DELETED_EVENT_TYPE) {
@@ -591,8 +640,8 @@ export function createAccessInvalidationEventConsumer(sseBroker) {
                 // reasoning as above.
                 if (userId === undefined)
                     return;
-                await sseBroker.publishAccessInvalidation(userId);
+                await publish(userId);
             }
-        },
+        }, now),
     };
 }

package/dist/pipeline/write-result-masking.js

@@ -1,19 +1,24 @@
 import { maskWriteOnlyFields } from "../engine/field-access.js";
 import { isLifecycleResult } from "./dispatcher-utils.js";
+// The echoed event carries plaintext entity data; only hooks and projections may read it.
 function maskLifecycleOrRow(entity, data) {
     if (typeof data !== "object" || data === null || Array.isArray(data))
         return data;
-    if (!isLifecycleResult(data))
-        return maskWriteOnlyFields(entity, data); // @cast-boundary engine-payload
-    if (data.kind === "save") {
+    if (!isLifecycleResult(data)) {
+        return entity ? maskWriteOnlyFields(entity, data) : data; // @cast-boundary engine-payload
+    }
+    const { event: _event, ...lifecycle } = data;
+    if (!entity)
+        return lifecycle;
+    if (lifecycle.kind === "save") {
         return {
-            ...data,
-            data: maskWriteOnlyFields(entity, data.data),
-            changes: maskWriteOnlyFields(entity, data.changes),
-            previous: maskWriteOnlyFields(entity, data.previous),
+            ...lifecycle,
+            data: maskWriteOnlyFields(entity, lifecycle.data),
+            changes: maskWriteOnlyFields(entity, lifecycle.changes),
+            previous: maskWriteOnlyFields(entity, lifecycle.previous),
         };
     }
-    return { ...data, data: maskWriteOnlyFields(entity, data.data) };
+    return { ...lifecycle, data: maskWriteOnlyFields(entity, lifecycle.data) };
 }
 // Copy-on-mask: the original results still feed postSaveBatch hooks, which
 // need the plaintext. Only what leaves the dispatcher is masked.
@@ -22,8 +27,6 @@ export function maskWriteResultForClient(registry, handlerType, result) {
         return result;
     const entityName = registry.getHandlerEntity(handlerType);
     const entity = entityName ? registry.getEntity(entityName) : undefined;
-    if (!entity)
-        return result;
     const data = maskLifecycleOrRow(entity, result.data);
     return data === result.data ? result : { ...result, data };
 }

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

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

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, maxConnections: 1 });
+    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, maxConnections: 1 });
+    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;