@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/random/generate.js

@@ -1,23 +1,23 @@
-// Random-Generator für human-readable Resource-Identifier:
-//   - Tenant-Keys ("happy-cloud", "swift-river-k8x")
-//   - Webhook-Subscriber-Slugs ("bold-falcon-receiver" mit custom nouns)
-//   - API-Key-Display-Names (3 Vorschläge anbieten beim Create)
-//   - Tenant-Subdomain-Vorschläge im Subdomain-Setup-Screen
-//   - Test-Fixtures mit lesbaren Identifiern
+// Random generator for human-readable resource identifiers:
+//   - Tenant keys ("happy-cloud", "swift-river-k8x")
+//   - Webhook subscriber slugs ("bold-falcon-receiver" with custom nouns)
+//   - API key display names (offer 3 suggestions on creation)
+//   - Tenant subdomain suggestions in the subdomain setup screen
+//   - Test fixtures with readable identifiers
 //
-// NICHT für Security-Token (CSRF, Session, API-Keys, OAuth-State,
-// Reset-Token). Math.random() ist nicht kryptografisch unvorhersagbar.
-// Authority-binding für Tenant-Keys läuft über JWT + DB-Lookup, nicht
-// über Slug-Geheimhaltung — der Slug darf erratbar sein.
+// NOT for security tokens (CSRF, session, API keys, OAuth state,
+// reset tokens). Math.random() is not cryptographically unpredictable.
+// Authority binding for tenant keys uses JWT + DB lookup, not slug secrecy;
+// the slug may be guessable.
 //
-// Universal-safe: Math.random() läuft in Bun, Node, Metro/RN, Expo-Web.
-// Keine node:crypto-Imports.
+// Safe across environments: Math.random() runs in Bun, Node, Metro/RN, and
+// Expo Web. No node:crypto imports.
 import { ADJECTIVES, NOUNS } from "./words.js";
-// Alphabet ohne handgetippt verwechselbare Zeichen:
-//   - keine 0/O (Null vs Großbuchstabe O)
-//   - keine 1/l/I (Eins vs Kleinbuchstabe L vs Großbuchstabe I)
-// Resultat: 32 Zeichen, sicher beim Telefon-Buchstabieren UND beim
-// Mailtext-Copy-Paste in fremde Schriftarten.
+// Alphabet without characters that are easily confused when entered manually:
+//   - no 0/O (zero versus uppercase O)
+//   - no 1/l/I (one versus lowercase L versus uppercase I)
+// Result: 32 characters, safe for spelling over the phone AND for copying
+// from email text in unfamiliar fonts.
 const NO_CONFUSABLE_ALPHABET = "23456789abcdefghjkmnpqrstuvwxyz";
 const NO_CONFUSABLE_CHARS = Object.freeze(NO_CONFUSABLE_ALPHABET.split(""));
 function pickRandom(arr) {
@@ -25,15 +25,15 @@ function pickRandom(arr) {
         throw new Error("pickRandom: cannot pick from empty array");
     }
     const value = arr[Math.floor(Math.random() * arr.length)];
-    // Length-Check oben garantiert dass index in-range ist.
+    // The length check above guarantees that the index is in range.
     if (value === undefined) {
         throw new Error("pickRandom: indexed value undefined (sparse array?)");
     }
     return value;
 }
-/** Sync Generator: produziert "happy-cloud" oder "happy-cloud-k8x"
- *  (mit suffix). Kein Conflict-Check — Caller verantwortlich für
- *  Uniqueness, oder generateUniqueName() für die async Variante. */
+/** Sync generator: produces "happy-cloud" or "happy-cloud-k8x"
+ *  (with suffix). No conflict check — the caller is responsible for
+ *  uniqueness, or can use generateUniqueName() for the async variant. */
 export function generateAdjNounName(options = {}) {
     const sep = options.separator ?? "-";
     const adjs = options.adjectives ?? ADJECTIVES;
@@ -44,9 +44,9 @@ export function generateAdjNounName(options = {}) {
     }
     return name;
 }
-/** Random-String aus dem no-confusable-Alphabet. Für Suffix-bei-Kollision
- *  oder als standalone short-IDs (z.B. Webhook-Verifizierungs-Codes
- *  zum Vorlesen am Telefon). length ≥ 1. */
+/** Random string from the no-confusable alphabet. For suffixes after
+ *  collisions or as standalone short IDs (e.g. webhook verification codes
+ *  to be read aloud over the phone). length ≥ 1. */
 export function generateNoConfusableId(length) {
     if (length < 1) {
         throw new Error(`generateNoConfusableId: length must be ≥ 1 (got ${length})`);
@@ -57,17 +57,17 @@ export function generateNoConfusableId(length) {
     }
     return id;
 }
-/** Generiert einen unique Adj-Noun-Slug indem es bis zu maxCleanAttempts
- *  saubere Wortpaare versucht, danach mit random Suffix bis maxTotal-
- *  Attempts. Wirft wenn auch das nicht hilft (= caller hat ein Bug
- *  mit isAvailable, oder die Wortliste ist defekt).
+/** Generates a unique Adj-Noun slug by trying up to maxCleanAttempts
+ *  clean word pairs, then using a random suffix up to maxTotal-
+ *  Attempts. Throws if that also fails (= the caller has a bug
+ *  in isAvailable, or the word list is defective).
  *
- *  Beispiel:
+ *  Example:
  *    const slug = await generateUniqueName({
  *      isAvailable: async (s) =>
  *        !(await db.select().from(tenants).where(eq(tenants.tenantKey, s)).then(r => r.length > 0)),
  *    });
- *    // → "happy-cloud" oder "happy-cloud-k8x" bei Kollision
+ *    // → "happy-cloud" or "happy-cloud-k8x" on collision
  */
 export async function generateUniqueName(options) {
     const maxClean = options.maxCleanAttempts ?? 3;

package/dist/random/words.js

@@ -1,26 +1,26 @@
-// Wortlisten für human-readable Resource-Slugs (Tenant-Keys, Webhook-
-// Subscribers, API-Key-Display-Names, Test-Fixtures). Heroku/Docker-
-// Style — adjective + noun produzieren aussprechbare, merkbare,
-// PII-freie Identifier.
+// Word lists for human-readable resource slugs (tenant keys, webhook-
+// subscribers, API-key display names, test fixtures). Heroku/Docker-
+// style — adjective + noun produce pronounceable, memorable,
+// PII-free identifiers.
 //
-// Auswahl-Kriterien:
-//   - Emotional-neutral und professionell (kein "fluffy", "sneaky")
-//   - Keine Tiernamen (Heroku-Cliché)
-//   - Keine Personennamen (cultural appropriation, prominenten-collision)
-//   - Keine Themen-Cluster (kein Wetter-only, kein Geographie-only)
-//   - Lowercase, ASCII-only, keine Bindestriche im Wort selbst
-//   - 3-10 Buchstaben pro Wort (kompakter Slug)
-//   - Aussprechbar in Deutsch UND Englisch (User-Telefon-Support)
-//   - Keine Wörter mit ambiguer Bedeutung in Englisch+Deutsch
+// Selection criteria:
+//   - Emotionally neutral and professional (no "fluffy", "sneaky")
+//   - No animal names (Heroku cliché)
+//   - No personal names (cultural appropriation, celebrity collisions)
+//   - No thematic clusters (neither weather-only nor geography-only)
+//   - Lowercase, ASCII-only, with no hyphens within a word
+//   - 3–10 letters per word (compact slug)
+//   - Pronounceable in German AND English (user phone support)
+//   - No words with ambiguous meanings in English and German
 //
-// 191 × 173 = 33.043 saubere Kombinationen. Birthday-Bound: ab ~180
-// Tenants wird kumulativ die erste Kollision wahrscheinlich (~50%);
-// pro Einzel-Draw bleibt p(Kollision) < 1% (vgl. generate.ts). Bei
-// Kollision greift der Suffix-Pfad in generateUniqueName.
+// 191 × 173 = 33,043 clean combinations. Birthday bound: from ~180
+// tenants onward, the first collision becomes likely cumulatively (~50%);
+// for an individual draw, p(collision) remains < 1% (see generate.ts). On
+// collision, the suffix path in generateUniqueName is used.
 //
-// Erweiterung: weitere Wörter unten anhängen reicht (sortiert ist
-// hilfreich für Reviews aber nicht erforderlich). Caller können auch
-// eigene Listen via generateUniqueName({ adjectives, nouns }) reichen.
+// Extension: appending more words below is sufficient (sorting helps with
+// reviews but is not required). Callers can also provide custom lists via
+// generateUniqueName({ adjectives, nouns }).
 export const ADJECTIVES = Object.freeze([
     "agile",
     "amber",

package/dist/rate-limit/middleware.js

@@ -108,21 +108,25 @@ export function createFailOpenReporter(label, meter, now = Date.now) {
         lastWarnAt = nowMs;
         logger.warn("rate limiter unavailable, failing open", {
             label,
-            // ioredis errors can carry the command args, i.e. the bucket key with IP/target.
+            // ioredis errors can carry the command args, i.e. the bucket key. scrubLogText masks an e-mail
+            // address in it; the client IP stays in the line as an operational datum.
             error: scrubLogText(err instanceof Error ? err.message : String(err)),
         });
     };
 }
+const failClosedLogger = createFallbackLogger("rate-limit");
 function defaultOnFailClosed(label) {
     return (err) => {
         // Loud by default — fail-closed for an unknown reason is an ops
         // signal, not something to swallow silently. Production deploys
         // override this with a structured logger; the default keeps the
         // noise visible if no logger is wired.
-        // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-        console.error(`[rate-limit ${label}] fail-closed (refusing request):`, 
-        // ioredis errors can carry the command args, i.e. the bucket key with IP/target.
-        err instanceof Error ? err.message : String(err));
+        failClosedLogger.error("fail-closed (refusing request)", {
+            label,
+            // ioredis errors can carry the command args, i.e. the bucket key. scrubLogText masks an e-mail
+            // address in it; the client IP stays in the line as an operational datum.
+            error: scrubLogText(err instanceof Error ? err.message : String(err)),
+        });
     };
 }
 function setRateLimitHeaders(c, decision) {

package/dist/redis/client.js

@@ -8,8 +8,8 @@
 // production defaults stay consistent and env-var wiring lives in one
 // place. Tests / one-off scripts can still `new Redis()` directly.
 //
-// Split out of index.ts (fw#2625) so pubsub-signal.ts can import this
-// without a same-directory cycle back through the barrel.
+// Split out of index.ts so pubsub-signal.ts can import this without a
+// same-directory cycle back through the barrel.
 import { Redis } from "ioredis";
 import { scrubLogText } from "../logging/scrub.js";
 import { readPositiveIntEnv } from "../utils/env-parse.js";

package/dist/redis/pubsub-signal.js

@@ -1,18 +1,19 @@
+import { createFallbackLogger } from "../logging/utils.js";
 import { createRedisClient } from "./client.js";
 // Redis emits 'error' on connection blips (reconnects transparently); an
-// unhandled listener crashes the process (fw#1805 — job-runner hit the same
-// class with BullMQ's internal client).
-function logConnectionError(label, role) {
+// unhandled listener crashes the process — job-runner hit the same
+// class with BullMQ's internal client.
+function logConnectionError(log, role) {
     return (err) => {
-        // biome-ignore lint/suspicious/noConsole: ops-visible fallback — no logger is threaded through PubSubSignalOptions.
-        console.error(`[kumiko:${label}] ${role} connection error:`, err.message);
+        log.error(`${role} connection error`, { error: err.message });
     };
 }
 export function createRedisPubSubSignal(opts) {
+    const log = createFallbackLogger(`kumiko:${opts.label}`);
     const publisher = createRedisClient(opts.redisUrl, opts.clientOptions);
     const subscriber = createRedisClient(opts.redisUrl, opts.clientOptions);
-    publisher.on("error", logConnectionError(opts.label, "publisher"));
-    subscriber.on("error", logConnectionError(opts.label, "subscriber"));
+    publisher.on("error", logConnectionError(log, "publisher"));
+    subscriber.on("error", logConnectionError(log, "subscriber"));
     const listeners = new Set();
     const reconnectListeners = new Set();
     // Sole purpose: stop close() from racing the initial psubscribe (see
@@ -26,8 +27,7 @@ export function createRedisPubSubSignal(opts) {
             payload = JSON.parse(message);
         }
         catch (err) {
-            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-            console.error(`[kumiko:${opts.label}] dropping unparseable message on "${channel}":`, err);
+            log.error(`dropping unparseable message on "${channel}"`, { err });
             // skip: unparseable payload already logged above, nothing to deliver
             return;
         }
@@ -37,14 +37,14 @@ export function createRedisPubSubSignal(opts) {
     // ponytail: psubscribe on one pattern rather than per-channel
     // subscribe/unsubscribe — every instance receives every message that
     // matches, filtered by the caller. That's strictly no worse than the
-    // pre-fw#2625 per-instance-cursor model (which already read every event
+    // per-instance-cursor model (which already read every event
     // from Postgres in every process) and sidesteps the subscribe-ack/
     // first-publish race a per-channel scheme would have. Revisit with
     // per-channel subscribe only if fanout volume becomes the bottleneck.
     //
     // Awaited by close() below — quitting while this is still in flight (a
     // shutdown landing immediately after construction, e.g. a test closing
-    // right after building the signal) makes ioredis rejects the queued
+    // right after building the signal) makes ioredis reject the queued
     // psubscribe with "Connection is closed" instead of it completing
     // cleanly first. Not caught here or logged when a close is already
     // underway (`closed`), so an intentional shutdown never surfaces this
@@ -54,8 +54,7 @@ export function createRedisPubSubSignal(opts) {
         // this rejection is the expected side effect, not an ops-visible error.
         if (closed)
             return;
-        // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-        console.error(`[kumiko:${opts.label}] psubscribe failed:`, err);
+        log.error("psubscribe failed", { err });
     });
     // ioredis re-sends the psubscribe itself (autoResubscribe) but emits no ack
     // event; repeating it here queues behind that one on the same connection,
@@ -77,8 +76,7 @@ export function createRedisPubSubSignal(opts) {
             // skip: a close() already underway intentionally quit the connection
             if (closed)
                 return;
-            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-            console.error(`[kumiko:${opts.label}] resubscribe failed:`, err);
+            log.error("resubscribe failed", { err });
         });
     });
     return {
@@ -88,8 +86,7 @@ export function createRedisPubSubSignal(opts) {
                 // connections — this rejection is the expected side effect.
                 if (closed)
                     return;
-                // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-                console.error(`[kumiko:${opts.label}] publish failed:`, err);
+                log.error("publish failed", { err });
             });
         },
         async publishConfirmed(channel, payload) {

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 });
+    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;