jazz-tools 2.0.0-alpha.51 → 2.0.0-alpha.52

package/dist/cli.js

@@ -1,13 +1,10 @@
 #!/usr/bin/env node
 // CLI for jazz-tools schema tooling
 import { existsSync, readFileSync, realpathSync } from "fs";
-import { access, mkdir, readFile, writeFile } from "fs/promises";
+import { readFile } from "fs/promises";
 import { basename, join, resolve } from "path";
 import { fileURLToPath } from "url";
-import { loadCompiledSchema } from "./schema-loader.js";
-import { collectMissingExplicitPolicyDiagnostics } from "./schema-permissions.js";
-import { columnTypeSignature, computeSchemaHash, createSnapshotTimestampFromPublishedAt, createTimestamp, deploy as deployCatalogue, listSnapshotEntries, listSnapshotEntriesForMigrations, normalizeSchemaHashInput, pushMigration as pushCatalogueMigration, resolveKnownSchemaHash, resolveLocalHistoricalSchema, resolveRemoteHistoricalSchema, resolveStoredStructuralSchemaHash, resolveSnapshotEntry, schemaTransitionRequiresRowTransform, shortSchemaHash, snapshotFilename, tableSchemasEqual, writeSnapshotSchemaForMigrations, } from "./dev/catalogue.js";
-import { fetchPermissionsHead, fetchSchemaHashes, fetchStoredWasmSchema, } from "./runtime/schema-fetch.js";
+import { createMigration as createCatalogueMigration, deploy as deployCatalogue, exportSchema as exportCatalogueSchema, getCurrentSchemaHash, getPermissionsStatus, pushMigration as pushCatalogueMigration, shortSchemaHash, validateProject, } from "./dev/catalogue.js";
 const PERMISSIONS_LIFECYCLE_NOTE = "Permission-only changes do not create schema hashes or require migrations.";
 function parseArgs() {
     const args = process.argv.slice(2);
@@ -28,44 +25,27 @@ function parseArgs() {
     }
     return { command, options: { jazzBin, schemaDir } };
 }
-async function pathExists(path) {
-    try {
-        await access(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 export async function validate(options) {
-    const compiled = await loadCompiledSchema(options.schemaDir);
-    const tableCount = compiled.schema.tables.length;
-    console.log(`Loaded structural schema from ${compiled.schemaFile}.`);
-    if (compiled.permissionsFile) {
-        console.log(`Loaded current permissions from ${compiled.permissionsFile}.`);
+    const result = await validateProject(options);
+    console.log(`Loaded structural schema from ${result.schemaFile}.`);
+    if (result.permissionsFile) {
+        console.log(`Loaded current permissions from ${result.permissionsFile}.`);
         console.log(PERMISSIONS_LIFECYCLE_NOTE);
         console.log("Use `jazz-tools permissions status <appId>` or `jazz-tools deploy <appId>` for auth publication.");
     }
-    for (const diagnostic of collectMissingExplicitPolicyDiagnostics(compiled.schema.tables.map((table) => table.name), compiled.permissions)) {
-        console.warn(`\x1b[33m${diagnostic.message}\x1b[0m`);
+    for (const warning of result.warnings) {
+        console.warn(`\x1b[33m${warning}\x1b[0m`);
     }
-    console.log(`Validated ${tableCount} table${tableCount === 1 ? "" : "s"} in schema.ts.`);
+    console.log(`Validated ${result.tableCount} table${result.tableCount === 1 ? "" : "s"} in schema.ts.`);
 }
 export async function exportSchema(options) {
-    if (options.schemaHash) {
-        const schema = await resolveExportedSchemaByHash(options);
-        process.stdout.write(`${JSON.stringify(schema, null, 2)}\n`);
-        return;
-    }
-    const currentSchema = await loadCurrentSchema(options.schemaDir);
-    await ensureLocalSnapshot(options.schemaDir, options.migrationsDir, currentSchema);
-    process.stdout.write(`${JSON.stringify(currentSchema.schema, null, 2)}\n`);
+    const result = await exportCatalogueSchema(options);
+    process.stdout.write(`${JSON.stringify(result.schema, null, 2)}\n`);
 }
 export async function schemaHash(options) {
-    const compiled = await loadCompiledSchema(options.schemaDir);
-    console.log(`Loaded structural schema from ${compiled.schemaFile}.`);
-    const hash = await computeSchemaHash(compiled.wasmSchema);
-    console.log(`Current schema hash: ${shortSchemaHash(hash)}`);
+    const result = await getCurrentSchemaHash(options);
+    console.log(`Loaded structural schema from ${result.schemaFile}.`);
+    console.log(`Current schema hash: ${shortSchemaHash(result.hash)}`);
 }
 // Framework bundlers (Vite, SvelteKit, Next.js, Expo) expose public env vars
 // under their own prefix so the client bundle can read them. The CLI often
@@ -204,45 +184,6 @@ function resolvePermissionsOptions(args) {
         schemaDir,
     };
 }
-function defaultMigrationsDir(schemaDir) {
-    return join(schemaDir, "migrations");
-}
-function resolvedMigrationsDir(schemaDir, migrationsDir) {
-    return migrationsDir ?? defaultMigrationsDir(schemaDir);
-}
-function snapshotsDir(schemaDir, migrationsDir) {
-    return join(resolvedMigrationsDir(schemaDir, migrationsDir), "snapshots");
-}
-async function listLocalSnapshotEntries(schemaDir, migrationsDir) {
-    return listSnapshotEntries(snapshotsDir(schemaDir, migrationsDir));
-}
-async function resolveLocalSnapshotEntry(schemaDir, migrationsDir, hash, label) {
-    return resolveSnapshotEntry(snapshotsDir(schemaDir, migrationsDir), hash, label);
-}
-async function loadLocalSnapshotSchema(schemaDir, migrationsDir, hash, label) {
-    const entry = await resolveLocalSnapshotEntry(schemaDir, migrationsDir, hash, label);
-    if (!entry) {
-        return null;
-    }
-    return {
-        hash: entry.hash,
-        schema: entry.schema,
-    };
-}
-async function writeSnapshotSchema(schemaDir, migrationsDir, hash, schema, timestamp = createTimestamp()) {
-    const dir = snapshotsDir(schemaDir, migrationsDir);
-    await mkdir(dir, { recursive: true });
-    const filePath = join(dir, snapshotFilename(hash, timestamp));
-    await writeFile(filePath, `${JSON.stringify(schema, null, 2)}\n`);
-    return filePath;
-}
-async function ensureLocalSnapshot(schemaDir, migrationsDir, schema) {
-    const entries = await listLocalSnapshotEntries(schemaDir, migrationsDir);
-    if (entries.some((entry) => entry.hash === schema.hash)) {
-        return null;
-    }
-    return writeSnapshotSchema(schemaDir, migrationsDir, schema.hash, schema.schema);
-}
 function requireSchemaExportServerValue(value, kind) {
     if (value) {
         return value;
@@ -265,473 +206,57 @@ function requireMigrationServerOptions(options) {
         adminSecret: requireSchemaExportServerValue(options.adminSecret, "adminSecret"),
     };
 }
-async function resolveExportedSchemaByHash(options) {
-    const schemaHash = normalizeSchemaHashInput(options.schemaHash, "schema hash");
-    const local = await loadLocalSnapshotSchema(options.schemaDir, options.migrationsDir, schemaHash, "schema hash");
-    if (local) {
-        return local.schema;
-    }
-    const serverUrl = requireSchemaExportServerValue(options.serverUrl ?? resolveEnvVar(SERVER_URL_ENV_VARS), "serverUrl");
-    const adminSecret = requireSchemaExportServerValue(options.adminSecret ?? process.env.JAZZ_ADMIN_SECRET, "adminSecret");
-    const appId = requireAppId(options.appId);
-    const resolvedHash = schemaHash.length === 64
-        ? schemaHash
-        : resolveKnownSchemaHash(schemaHash, "schema hash", (await fetchSchemaHashes(serverUrl, { appId, adminSecret })).hashes);
-    const storedSchema = await fetchStoredWasmSchema(serverUrl, {
-        appId,
-        adminSecret,
-        schemaHash: resolvedHash,
-    });
-    await writeSnapshotSchema(options.schemaDir, options.migrationsDir, resolvedHash, storedSchema.schema, createSnapshotTimestampFromPublishedAt(storedSchema.publishedAt));
-    return storedSchema.schema;
-}
-function changedTableNames(fromSchema, toSchema) {
-    const names = new Set([...Object.keys(fromSchema), ...Object.keys(toSchema)]);
-    return [...names].filter((tableName) => !tableSchemasEqual(fromSchema[tableName], toSchema[tableName]));
-}
-function detectPossibleTableRenames(fromSchema, toSchema) {
-    const removedTables = Object.keys(fromSchema)
-        .filter((tableName) => !toSchema[tableName])
-        .sort();
-    const addedTables = Object.keys(toSchema)
-        .filter((tableName) => !fromSchema[tableName])
-        .sort();
-    const matches = removedTables
-        .map((oldTableName) => {
-        const candidateAddedTables = addedTables.filter((newTableName) => tableSchemasEqual(fromSchema[oldTableName], toSchema[newTableName]));
-        return candidateAddedTables.length === 1
-            ? [oldTableName, candidateAddedTables[0]]
-            : undefined;
-    })
-        .filter((match) => match !== undefined);
-    return matches.flatMap(([oldTableName, newTableName], i) => {
-        const isDuplicateNewTableMatch = matches.some(([_, otherNewTableName], j) => {
-            return i !== j && newTableName === otherNewTableName;
-        });
-        return !isDuplicateNewTableMatch ? [{ oldTableName, newTableName }] : [];
-    });
-}
-function ensurePermissionsProject(compiled) {
-    if (!compiled.permissions || !compiled.permissionsFile) {
-        throw new Error("No permissions found for this app. Create a permissions.ts file before using permissions commands.");
-    }
-    return compiled;
-}
-/**
- * If the provided schema exists in the server, returns its hash. Otherwise, throws an error.
- */
-async function resolveStoredStructuralSchemaHashOrThrow(appId, serverUrl, adminSecret, wasmSchema) {
-    const hash = await resolveStoredStructuralSchemaHash(appId, serverUrl, adminSecret, wasmSchema);
-    if (!hash) {
-        throw new Error("No stored structural schema matches the local schema.ts. Publish the structural schema before pushing permissions.");
-    }
-    return hash;
-}
-function pickWitnessSchema(schema, tableNames) {
-    const uniqueTableNames = [...new Set(tableNames)];
-    return Object.fromEntries(uniqueTableNames
-        .filter((tableName) => schema[tableName])
-        .map((tableName) => [tableName, schema[tableName]]));
-}
-function indentBlock(text, indent) {
-    const prefix = " ".repeat(indent);
-    return text
-        .split("\n")
-        .map((line) => (line.length === 0 ? line : `${prefix}${line}`))
-        .join("\n");
-}
-function baseBuilderExpression(columnType, references) {
-    switch (columnType.type) {
-        case "Text":
-            return "s.string()";
-        case "Boolean":
-            return "s.boolean()";
-        case "Integer":
-            return "s.int()";
-        case "Double":
-            return "s.float()";
-        case "Timestamp":
-            return "s.timestamp()";
-        case "Bytea":
-            return "s.bytes()";
-        case "Json":
-            return columnType.schema ? `s.json(${JSON.stringify(columnType.schema)})` : "s.json()";
-        case "Enum":
-            return `s.enum(${columnType.variants.map((variant) => JSON.stringify(variant)).join(", ")})`;
-        case "Uuid":
-            if (!references) {
-                throw new Error("Migration stub generation does not yet support bare UUID columns.");
-            }
-            return `s.ref(${JSON.stringify(references)})`;
-        case "Array":
-            return `s.array(${baseBuilderExpression(columnType.element, references)})`;
-        case "BigInt":
-            throw new Error("Migration stub generation does not yet support BIGINT columns.");
-        case "Row":
-            throw new Error("Migration stub generation does not yet support row-valued columns.");
-    }
-}
-function builderExpressionForColumn(column) {
-    const base = baseBuilderExpression(column.column_type, column.references);
-    const withOptional = column.nullable ? `${base}.optional()` : base;
-    if (column.merge_strategy === "Counter") {
-        return `${withOptional}.merge("counter")`;
-    }
-    return withOptional;
-}
-function renderSchemaWitness(schema) {
-    const tableEntries = Object.entries(schema)
-        .sort(([left], [right]) => left.localeCompare(right))
-        .map(([tableName, tableSchema]) => {
-        const columnLines = tableSchema.columns.map((column) => `${JSON.stringify(column.name)}: ${builderExpressionForColumn(column)},`);
-        return `${JSON.stringify(tableName)}: s.table({\n${indentBlock(columnLines.join("\n"), 2)}\n})`;
-    });
-    if (tableEntries.length === 0) {
-        return "{}";
-    }
-    return `{\n${indentBlock(tableEntries.join(",\n"), 2)}\n}`;
-}
-function renderArrayElementExpression(columnType, references) {
-    return baseBuilderExpression(columnType, references);
-}
-function renderAddOperationExpression(column, defaultExpression) {
-    switch (column.column_type.type) {
-        case "Text":
-            return `s.add.string({ default: ${defaultExpression} })`;
-        case "Boolean":
-            return `s.add.boolean({ default: ${defaultExpression} })`;
-        case "Integer":
-            return `s.add.int({ default: ${defaultExpression} })`;
-        case "Double":
-            return `s.add.float({ default: ${defaultExpression} })`;
-        case "Timestamp":
-            return `s.add.timestamp({ default: ${defaultExpression} })`;
-        case "Bytea":
-            return `s.add.bytes({ default: ${defaultExpression} })`;
-        case "Json":
-            return column.column_type.schema
-                ? `s.add.json({ default: ${defaultExpression}, schema: ${JSON.stringify(column.column_type.schema)} })`
-                : `s.add.json({ default: ${defaultExpression} })`;
-        case "Enum":
-            return `s.add.enum(${column.column_type.variants
-                .map((variant) => JSON.stringify(variant))
-                .join(", ")}, { default: ${defaultExpression} })`;
-        case "Uuid":
-            if (column.references) {
-                return `s.add.ref(${JSON.stringify(column.references)}, { default: ${defaultExpression} })`;
-            }
-            return `s.add.ref("TODO_TABLE", { default: ${defaultExpression} })`;
-        case "Array":
-            return `s.add.array({ of: ${renderArrayElementExpression(column.column_type.element, column.references)}, default: ${defaultExpression} })`;
-        case "BigInt":
-            throw new Error("Migration stub generation does not yet support BIGINT columns.");
-        case "Row":
-            throw new Error("Migration stub generation does not yet support row-valued columns.");
-    }
-}
-function renderDropOperationExpression(column, defaultExpression) {
-    switch (column.column_type.type) {
-        case "Text":
-            return `s.drop.string({ backwardsDefault: ${defaultExpression} })`;
-        case "Boolean":
-            return `s.drop.boolean({ backwardsDefault: ${defaultExpression} })`;
-        case "Integer":
-            return `s.drop.int({ backwardsDefault: ${defaultExpression} })`;
-        case "Double":
-            return `s.drop.float({ backwardsDefault: ${defaultExpression} })`;
-        case "Timestamp":
-            return `s.drop.timestamp({ backwardsDefault: ${defaultExpression} })`;
-        case "Bytea":
-            return `s.drop.bytes({ backwardsDefault: ${defaultExpression} })`;
-        case "Json":
-            return column.column_type.schema
-                ? `s.drop.json({ backwardsDefault: ${defaultExpression}, schema: ${JSON.stringify(column.column_type.schema)} })`
-                : `s.drop.json({ backwardsDefault: ${defaultExpression} })`;
-        case "Enum":
-            return `s.drop.enum(${column.column_type.variants
-                .map((variant) => JSON.stringify(variant))
-                .join(", ")}, { backwardsDefault: ${defaultExpression} })`;
-        case "Uuid":
-            if (column.references) {
-                return `s.drop.ref(${JSON.stringify(column.references)}, { backwardsDefault: ${defaultExpression} })`;
-            }
-            return `s.drop.ref("TODO_TABLE", { backwardsDefault: ${defaultExpression} })`;
-        case "Array":
-            return `s.drop.array({ of: ${renderArrayElementExpression(column.column_type.element, column.references)}, backwardsDefault: ${defaultExpression} })`;
-        case "BigInt":
-            throw new Error("Migration stub generation does not yet support BIGINT columns.");
-        case "Row":
-            throw new Error("Migration stub generation does not yet support row-valued columns.");
-    }
-}
-function inferTableSuggestions(tableName, fromTable, toTable) {
-    const fromColumns = new Map(fromTable.columns.map((column) => [column.name, column]));
-    const toColumns = new Map(toTable.columns.map((column) => [column.name, column]));
-    const comments = [];
-    const properties = [];
-    const removedColumns = [...fromColumns.keys()].filter((name) => !toColumns.has(name));
-    const addedColumns = [...toColumns.keys()].filter((name) => !fromColumns.has(name));
-    if (removedColumns.length === 1 && addedColumns.length === 1) {
-        const removed = fromColumns.get(removedColumns[0]);
-        const added = toColumns.get(addedColumns[0]);
-        if (removed.nullable === added.nullable &&
-            removed.references === added.references &&
-            columnTypeSignature(removed.column_type) === columnTypeSignature(added.column_type)) {
-            comments.push(`Possible rename detected: ${JSON.stringify(removed.name)} -> ${JSON.stringify(added.name)}.`);
-        }
-    }
-    for (const columnName of addedColumns) {
-        const column = toColumns.get(columnName);
-        if (column.nullable) {
-            properties.push(`${JSON.stringify(columnName)}: ${renderAddOperationExpression(column, "null")},`);
-        }
-        else {
-            comments.push(`Added required column ${JSON.stringify(columnName)} needs an explicit default.`);
-        }
-    }
-    for (const columnName of removedColumns) {
-        const column = fromColumns.get(columnName);
-        if (column.nullable) {
-            properties.push(`${JSON.stringify(columnName)}: ${renderDropOperationExpression(column, "null")},`);
-        }
-        else {
-            comments.push(`Removed required column ${JSON.stringify(columnName)} needs an explicit backwardsDefault.`);
-        }
-    }
-    return {
-        tableName,
-        comments,
-        properties,
-    };
-}
-function renderMigrationBody(fromSchema, toSchema) {
-    const renameSuggestions = detectPossibleTableRenames(fromSchema, toSchema);
-    const renamedOldTables = new Set(renameSuggestions.map((suggestion) => suggestion.oldTableName));
-    const renamedNewTables = new Set(renameSuggestions.map((suggestion) => suggestion.newTableName));
-    const addedTables = Object.keys(toSchema)
-        .filter((tableName) => !fromSchema[tableName])
-        .sort();
-    const removedTables = Object.keys(fromSchema)
-        .filter((tableName) => !toSchema[tableName])
-        .sort();
-    const explicitAddedTables = addedTables.filter((tableName) => !renamedNewTables.has(tableName));
-    const explicitRemovedTables = removedTables.filter((tableName) => !renamedOldTables.has(tableName));
-    const changedTables = changedTableNames(fromSchema, toSchema);
-    const migratableTables = changedTables.filter((tableName) => fromSchema[tableName] !== undefined && toSchema[tableName] !== undefined);
-    const witnessFromTables = [...migratableTables, ...explicitRemovedTables];
-    const witnessToTables = [...migratableTables, ...explicitAddedTables];
-    for (const renameSuggestion of renameSuggestions) {
-        witnessFromTables.push(renameSuggestion.oldTableName);
-        witnessToTables.push(renameSuggestion.newTableName);
-    }
-    const witnessFrom = pickWitnessSchema(fromSchema, witnessFromTables);
-    const witnessTo = pickWitnessSchema(toSchema, witnessToTables);
-    const lines = [];
-    for (const tableName of migratableTables) {
-        const fromTable = fromSchema[tableName];
-        const toTable = toSchema[tableName];
-        const suggestion = inferTableSuggestions(tableName, fromTable, toTable);
-        lines.push(`${JSON.stringify(tableName)}: {`);
-        for (const comment of suggestion.comments) {
-            lines.push(`  // TODO: ${comment}`);
-        }
-        for (const property of suggestion.properties) {
-            lines.push(`  ${property}`);
-        }
-        if (suggestion.comments.length === 0 && suggestion.properties.length === 0) {
-            lines.push("  // TODO: No safe migration steps were inferred automatically.");
-        }
-        lines.push("},");
-        lines.push("");
-    }
-    if (lines.length === 0) {
-        if (renameSuggestions.length === 0 &&
-            explicitAddedTables.length === 0 &&
-            explicitRemovedTables.length === 0) {
-            lines.push(changedTables.length === 0
-                ? "// TODO: No schema differences were detected."
-                : "// TODO: No column-level migration steps were required for the detected schema changes.");
-        }
-    }
-    return {
-        migrateBody: lines.length > 0 ? lines.join("\n").trimEnd() : undefined,
-        createTablesBody: explicitAddedTables.length > 0
-            ? explicitAddedTables.map((tableName) => `${JSON.stringify(tableName)}: true,`).join("\n")
-            : undefined,
-        dropTablesBody: explicitRemovedTables.length > 0
-            ? explicitRemovedTables.map((tableName) => `${JSON.stringify(tableName)}: true,`).join("\n")
-            : undefined,
-        renameTablesBody: renameSuggestions.length > 0
-            ? renameSuggestions
-                .map((renameSuggestion) => `${renameSuggestion.newTableName}: s.renameTableFrom(${JSON.stringify(renameSuggestion.oldTableName)}),`)
-                .join("\n")
-            : undefined,
-        witnessFrom,
-        witnessTo,
-    };
-}
 async function packageVersion() {
     const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
     return packageJson.version ?? "unknown";
 }
-function normalizeMigrationName(name) {
-    const normalized = name
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    if (normalized.length === 0) {
-        throw new Error("Migration name must contain at least one ASCII letter or digit after normalization.");
-    }
-    return normalized;
-}
-function migrationFilename(migrationsDir, fromHash, toHash, name = "unnamed", timestamp = createTimestamp()) {
-    return join(migrationsDir, `${timestamp}-${name}-${shortSchemaHash(fromHash)}-${shortSchemaHash(toHash)}.ts`);
-}
-function renderMigrationStub(input) {
-    const rendered = renderMigrationBody(input.fromSchema, input.toSchema);
-    const sections = [];
-    if (rendered.renameTablesBody) {
-        sections.push(`  renameTables: {\n${indentBlock(rendered.renameTablesBody, 4)}\n  },`);
-    }
-    if (rendered.createTablesBody) {
-        sections.push(`  createTables: {\n${indentBlock(rendered.createTablesBody, 4)}\n  },`);
-    }
-    if (rendered.dropTablesBody) {
-        sections.push(`  dropTables: {\n${indentBlock(rendered.dropTablesBody, 4)}\n  },`);
-    }
-    if (rendered.migrateBody) {
-        sections.push(`  migrate: {\n${indentBlock(rendered.migrateBody, 4)}\n  },`);
-    }
-    sections.push(`  fromHash: ${JSON.stringify(shortSchemaHash(input.fromHash))},`);
-    sections.push(`  toHash: ${JSON.stringify(shortSchemaHash(input.toHash))},`);
-    sections.push(`  from: ${renderSchemaWitness(rendered.witnessFrom)},`);
-    sections.push(`  to: ${renderSchemaWitness(rendered.witnessTo)},`);
-    return `import { schema as s } from "jazz-tools";
-
-export default s.defineMigration({
-${sections.join("\n")}
-});
-`;
-}
-function isCommittedSnapshotFileName(fileName) {
-    return /^\d{8}T\d{6}-[0-9a-f]{12}\.json$/i.test(fileName);
-}
-async function loadLatestCommittedSnapshot(migrationsDir) {
-    const entries = await listSnapshotEntriesForMigrations(migrationsDir);
-    const latest = entries
-        .filter((entry) => isCommittedSnapshotFileName(entry.fileName))
-        .sort((left, right) => left.fileName.localeCompare(right.fileName))
-        .at(-1);
-    if (!latest) {
-        return null;
-    }
-    return {
-        hash: latest.hash,
-        schema: latest.schema,
-    };
-}
-async function ensureCommittedSnapshot(migrationsDir, schema, timestamp) {
-    const entries = await listSnapshotEntriesForMigrations(migrationsDir);
-    if (entries.some((entry) => entry.hash === schema.hash && isCommittedSnapshotFileName(entry.fileName))) {
-        return null;
-    }
-    return writeSnapshotSchemaForMigrations(migrationsDir, snapshotFilename(schema.hash, timestamp), schema.schema);
-}
-async function loadCurrentSchema(schemaDir) {
-    const compiled = await loadCompiledSchema(schemaDir);
-    return {
-        hash: await computeSchemaHash(compiled.wasmSchema),
-        schema: compiled.wasmSchema,
-    };
-}
-async function resolveHistoricalSchemaForCli(migrationsDir, hash, label, appId, serverUrl, adminSecret) {
-    const local = await resolveLocalHistoricalSchema(migrationsDir, hash, label);
-    if (local) {
-        return { hash: local.hash, schema: local.schema };
-    }
-    return resolveRemoteHistoricalSchema(migrationsDir, hash, label, requireAppId(appId), requireSchemaExportServerValue(serverUrl, "serverUrl"), requireSchemaExportServerValue(adminSecret, "adminSecret"));
-}
 export async function createMigration(options) {
-    const explicitHashFlow = Boolean(options.fromHash || options.toHash);
-    await mkdir(options.migrationsDir, { recursive: true });
-    const currentSchema = !explicitHashFlow || !options.toHash ? await loadCurrentSchema(options.schemaDir) : null;
-    let fromSchema;
-    let toSchema;
-    let shouldWriteCommittedSnapshot = false;
-    const timestamp = createTimestamp();
-    if (explicitHashFlow) {
-        if (options.fromHash) {
-            fromSchema = await resolveHistoricalSchemaForCli(options.migrationsDir, options.fromHash, "fromHash", options.appId, options.serverUrl, options.adminSecret);
-        }
-        else {
-            const latest = await loadLatestCommittedSnapshot(options.migrationsDir);
-            if (!latest) {
-                throw new Error("No committed snapshot found. Provide --fromHash or run `jazz-tools migrations create` once to create an initial snapshot.");
-            }
-            fromSchema = latest;
-        }
-        toSchema = options.toHash
-            ? await resolveHistoricalSchemaForCli(options.migrationsDir, options.toHash, "toHash", options.appId, options.serverUrl, options.adminSecret)
-            : currentSchema;
-        shouldWriteCommittedSnapshot = !options.toHash;
-    }
-    else {
-        const latest = await loadLatestCommittedSnapshot(options.migrationsDir);
-        if (!latest) {
-            const snapshotPath = await ensureCommittedSnapshot(options.migrationsDir, currentSchema, timestamp);
-            console.log(`Wrote initial schema snapshot: ${snapshotPath}`);
+    const result = await createCatalogueMigration(options);
+    switch (result.status) {
+        case "initial-snapshot":
+            console.log("Wrote initial schema snapshot: " + result.snapshotPath);
             console.log("No migration created because there was no previous local schema baseline.");
             return null;
-        }
-        if (latest.hash === currentSchema.hash) {
+        case "unchanged":
             console.log("No structural schema changes detected.");
             return null;
+        case "migration-not-required": {
+            const version = await packageVersion();
+            console.log("No reviewed migration file needed because this schema change does not require row transformations.");
+            console.log("Next step: Run npx jazz-tools@" +
+                version +
+                " migrations push " +
+                (options.appId ?? "<appId>") +
+                " " +
+                shortSchemaHash(result.fromHash) +
+                " " +
+                shortSchemaHash(result.toHash));
+            return null;
         }
-        fromSchema = latest;
-        toSchema = currentSchema;
-        shouldWriteCommittedSnapshot = true;
-    }
-    if (fromSchema.hash === toSchema.hash) {
-        console.log("No structural schema changes detected.");
-        return null;
-    }
-    if (!schemaTransitionRequiresRowTransform(fromSchema.schema, toSchema.schema)) {
-        if (shouldWriteCommittedSnapshot) {
-            await ensureCommittedSnapshot(options.migrationsDir, toSchema, timestamp);
+        case "generated": {
+            const version = await packageVersion();
+            console.log("Generated: " + result.filePath);
+            console.log("");
+            console.log("Migration stubs are only for structural schema changes.");
+            console.log(PERMISSIONS_LIFECYCLE_NOTE);
+            console.log("");
+            console.log("Next steps:");
+            console.log("1. Fill in migrate.");
+            if (result.needsRename) {
+                console.log("2. Rename the file by replacing 'unnamed'.");
+            }
+            console.log((result.needsRename ? "3" : "2") +
+                ". Run npx jazz-tools@" +
+                version +
+                " migrations push " +
+                (options.appId ?? "<appId>") +
+                " " +
+                shortSchemaHash(result.fromHash) +
+                " " +
+                shortSchemaHash(result.toHash));
+            return result.filePath;
         }
-        const version = await packageVersion();
-        console.log("No reviewed migration file needed because this schema change does not require row transformations.");
-        console.log(`Next step: Run npx jazz-tools@${version} migrations push ${options.appId ?? "<appId>"} ${shortSchemaHash(fromSchema.hash)} ${shortSchemaHash(toSchema.hash)}`);
-        return null;
-    }
-    const filePath = migrationFilename(options.migrationsDir, fromSchema.hash, toSchema.hash, options.name ? normalizeMigrationName(options.name) : undefined, timestamp);
-    if (await pathExists(filePath)) {
-        throw new Error(`Migration stub already exists: ${filePath}`);
-    }
-    const stub = renderMigrationStub({
-        fromHash: fromSchema.hash,
-        toHash: toSchema.hash,
-        fromSchema: fromSchema.schema,
-        toSchema: toSchema.schema,
-    });
-    await writeFile(filePath, stub);
-    if (shouldWriteCommittedSnapshot) {
-        await ensureCommittedSnapshot(options.migrationsDir, toSchema, timestamp);
-    }
-    const version = await packageVersion();
-    console.log(`Generated: ${filePath}`);
-    console.log("");
-    console.log("Migration stubs are only for structural schema changes.");
-    console.log(PERMISSIONS_LIFECYCLE_NOTE);
-    console.log("");
-    console.log("Next steps:");
-    console.log("1. Fill in migrate.");
-    if (!options.name) {
-        console.log("2. Rename the file by replacing 'unnamed'.");
-    }
-    console.log(`${options.name ? "2" : "3"}. Run npx jazz-tools@${version} migrations push ${options.appId ?? "<appId>"} ${shortSchemaHash(fromSchema.hash)} ${shortSchemaHash(toSchema.hash)}`);
-    return filePath;
+    }
 }
 export async function pushMigration(options) {
     const { appId, serverUrl, adminSecret } = requireMigrationServerOptions(options);
@@ -764,29 +289,24 @@ function logDeployWarning(message) {
     console.warn(`Warning: ${message}`);
 }
 export async function permissionsStatus(options) {
-    const compiled = ensurePermissionsProject(await loadCompiledSchema(options.schemaDir));
-    const localSchemaHash = await resolveStoredStructuralSchemaHashOrThrow(options.appId, options.serverUrl, options.adminSecret, compiled.wasmSchema);
-    const { head } = await fetchPermissionsHead(options.serverUrl, {
-        appId: options.appId,
-        adminSecret: options.adminSecret,
-    });
-    console.log(`Loaded structural schema from ${compiled.schemaFile}.`);
-    console.log(`Loaded current permissions from ${compiled.permissionsFile}.`);
-    console.log(`Local structural schema matches stored hash ${shortSchemaHash(localSchemaHash)}.`);
+    const result = await getPermissionsStatus(options);
+    console.log(`Loaded structural schema from ${result.schemaFile}.`);
+    console.log(`Loaded current permissions from ${result.permissionsFile}.`);
+    console.log(`Local structural schema matches stored hash ${shortSchemaHash(result.localSchemaHash)}.`);
     console.log(PERMISSIONS_LIFECYCLE_NOTE);
-    if (!head) {
+    if (!result.head) {
         console.log("Server has no published permissions head yet.");
         console.log("Next push will publish version 1.");
         return;
     }
-    console.log(`Server permissions head is ${describePermissionsHead(head)}.`);
-    if (head.schemaHash === localSchemaHash) {
+    console.log(`Server permissions head is ${describePermissionsHead(result.head)}.`);
+    if (result.head.schemaHash === result.localSchemaHash) {
         console.log("Current server permissions already target this structural schema.");
     }
     else {
-        console.log(`Current server permissions target ${shortSchemaHash(head.schemaHash)}; pushing will retarget the head to ${shortSchemaHash(localSchemaHash)}.`);
+        console.log(`Current server permissions target ${shortSchemaHash(result.head.schemaHash)}; pushing will retarget the head to ${shortSchemaHash(result.localSchemaHash)}.`);
     }
-    console.log(`Next push will require parent bundle ${head.bundleObjectId}.`);
+    console.log(`Next push will require parent bundle ${result.head.bundleObjectId}.`);
 }
 export async function deploy(options) {
     const result = await deployCatalogue({