jazz-tools 2.0.0-alpha.21 → 2.0.0-alpha.24

package/dist/cli.js

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 // CLI for jazz-tools schema tooling
-import { spawn } from "child_process";
-import { access, readdir, writeFile } from "fs/promises";
-import { join, basename, dirname, resolve } from "path";
+import { access, mkdir, readFile, readdir, writeFile } from "fs/promises";
+import { basename, join, resolve } from "path";
 import { pathToFileURL } from "url";
-import { register as registerCjs } from "tsx/cjs/api";
 import { register as registerEsm } from "tsx/esm/api";
-import { schemaToSql, lensesToSql } from "./sql-gen.js";
-import { getCollectedSchema, getCollectedMigrations, resetCollectedState } from "./dsl.js";
-import { generateClient } from "./codegen/index.js";
+import { schemaDefinitionToAst } from "./migrations.js";
+import { loadCompiledSchema } from "./schema-loader.js";
+import { encodePublishedMigrationValue, fetchPermissionsHead, fetchSchemaHashes, fetchStoredWasmSchema, publishStoredPermissions, publishStoredMigration, } from "./runtime/schema-fetch.js";
+import { toValue } from "./runtime/value-converter.js";
+const PERMISSIONS_LIFECYCLE_NOTE = "Permission-only changes do not create schema hashes or require migrations.";
 function parseArgs() {
     const args = process.argv.slice(2);
     const command = args[0] || "";
-    let jazzBin = "jazz-tools";
-    let schemaDir = join(process.cwd(), "schema");
+    let schemaDir = process.cwd();
+    let jazzBin;
     for (let i = 1; i < args.length; i++) {
         const arg = args[i];
         const nextArg = args[i + 1];
@@ -28,276 +28,612 @@ function parseArgs() {
     }
     return { command, options: { jazzBin, schemaDir } };
 }
-// Allow loading `.ts` schema files when invoked via `node dist/cli.js`.
 registerEsm();
-// Counter for cache-busting module loads.
 let importCounter = 0;
-function requirePermissionsModule(filePath) {
-    const loader = registerCjs({ namespace: `jazz-tools-cli-permissions-${++importCounter}` });
+async function pathExists(path) {
     try {
-        return loader.require(resolve(filePath), import.meta.url);
+        await access(path);
+        return true;
     }
-    finally {
-        loader.unregister();
+    catch {
+        return false;
     }
 }
-async function loadSchemaModule(filePath) {
-    resetCollectedState();
-    const url = pathToFileURL(filePath).href + `?v=${++importCounter}`;
-    await import(url);
+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}.`);
+        console.log(PERMISSIONS_LIFECYCLE_NOTE);
+        console.log("Use `jazz-tools permissions status` or `jazz-tools permissions push` for auth publication.");
+    }
+    console.log(`Validated ${tableCount} table${tableCount === 1 ? "" : "s"} in schema.ts.`);
 }
-async function loadSchema(filePath) {
-    await loadSchemaModule(filePath);
-    return getCollectedSchema();
+export async function exportSchema(options) {
+    if (options.format !== "json") {
+        throw new Error(`Unsupported schema export format: ${options.format}`);
+    }
+    const compiled = await loadCompiledSchema(options.schemaDir);
+    process.stdout.write(`${JSON.stringify(compiled.wasmSchema, null, 2)}\n`);
 }
-async function loadMigrationModule(filePath) {
-    resetCollectedState();
-    const url = pathToFileURL(filePath).href + `?v=${++importCounter}`;
-    await import(url);
-    return getCollectedMigrations();
-}
-async function generateSqlForSchemaFile(tsFile, schema) {
-    const sql = schemaToSql(schema);
-    const sqlFile = tsFile.replace(/\.ts$/, ".sql");
-    await writeFile(sqlFile, sql);
-    console.log(`Generated: ${basename(sqlFile)}`);
-}
-async function generateAppTs(schemaDir, schema) {
-    const output = generateClient(schema);
-    const appTsPath = join(schemaDir, "app.ts");
-    await writeFile(appTsPath, output);
-    console.log(`Generated: app.ts`);
-}
-/**
- * Check if a filename is a migration TypeScript stub.
- *
- * Valid format: `migration_v1_v2_455a1f10a158_357c464c4c43.ts`
- */
-function isMigrationTsStub(filename) {
-    const pattern = /^migration_v\d+_v\d+_[0-9a-f]{12}_[0-9a-f]{12}\.ts$/;
-    return pattern.test(filename);
-}
-/**
- * Generate migration SQL filename with direction before hashes.
- *
- * Input: migration_v1_v2_455a1f10a158_357c464c4c43.ts
- * Output: migration_v1_v2_fwd_455a1f10a158_357c464c4c43.sql
- */
-function migrationSqlFilename(tsFile, direction) {
-    const dir = tsFile.substring(0, tsFile.lastIndexOf("/") + 1);
-    const name = basename(tsFile, ".ts");
-    const match = name.match(/^(migration_v\d+_v\d+)_([0-9a-f]{12})_([0-9a-f]{12})$/);
-    if (!match) {
-        return tsFile.replace(/\.ts$/, `_${direction}.sql`);
+const SHORT_SCHEMA_HASH_LENGTH = 12;
+function getFlagValue(args, flag) {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg) {
+            continue;
+        }
+        if (arg === flag) {
+            return args[i + 1];
+        }
+        const prefix = `${flag}=`;
+        if (arg.startsWith(prefix)) {
+            return arg.slice(prefix.length);
+        }
     }
-    const [, prefix, hash1, hash2] = match;
-    return `${dir}${prefix}_${direction}_${hash1}_${hash2}.sql`;
+    return undefined;
 }
-async function generateSqlForMigrationFile(tsFile) {
-    const lenses = await loadMigrationModule(tsFile);
-    if (lenses.length === 0) {
-        console.error(`No migration found in ${basename(tsFile)}`);
-        return;
+function resolveMigrationOptions(args) {
+    const serverUrl = getFlagValue(args, "--server-url") ?? process.env.JAZZ_SERVER_URL;
+    const adminSecret = getFlagValue(args, "--admin-secret") ?? process.env.JAZZ_ADMIN_SECRET;
+    const migrationsDir = resolve(process.cwd(), getFlagValue(args, "--migrations-dir") ?? join(process.cwd(), "migrations"));
+    if (!serverUrl) {
+        throw new Error("Missing server URL. Pass --server-url <url> or set JAZZ_SERVER_URL.");
+    }
+    if (!adminSecret) {
+        throw new Error("Missing admin secret. Pass --admin-secret <secret> or set JAZZ_ADMIN_SECRET.");
     }
-    const fwdSql = lensesToSql(lenses, "fwd");
-    const bwdSql = lensesToSql(lenses, "bwd");
-    const fwdFile = migrationSqlFilename(tsFile, "fwd");
-    const bwdFile = migrationSqlFilename(tsFile, "bwd");
-    await writeFile(fwdFile, fwdSql);
-    await writeFile(bwdFile, bwdSql);
-    console.log(`Generated: ${basename(fwdFile)}`);
-    console.log(`Generated: ${basename(bwdFile)}`);
-}
-function isOperationPolicyLike(input) {
-    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    return {
+        serverUrl,
+        adminSecret,
+        migrationsDir,
+    };
+}
+function resolvePermissionsOptions(args) {
+    const serverUrl = getFlagValue(args, "--server-url") ?? process.env.JAZZ_SERVER_URL;
+    const adminSecret = getFlagValue(args, "--admin-secret") ?? process.env.JAZZ_ADMIN_SECRET;
+    const schemaDir = resolve(process.cwd(), getFlagValue(args, "--schema-dir") ?? process.cwd());
+    if (!serverUrl) {
+        throw new Error("Missing server URL. Pass --server-url <url> or set JAZZ_SERVER_URL.");
+    }
+    if (!adminSecret) {
+        throw new Error("Missing admin secret. Pass --admin-secret <secret> or set JAZZ_ADMIN_SECRET.");
+    }
+    return {
+        serverUrl,
+        adminSecret,
+        schemaDir,
+    };
+}
+function normalizeSchemaHashInput(hash, label) {
+    const normalized = hash.trim().toLowerCase();
+    if (!/^[0-9a-f]{12,64}$/.test(normalized)) {
+        throw new Error(`${label} must be a 12-64 character lowercase hex schema hash.`);
+    }
+    return normalized;
+}
+function shortSchemaHash(hash) {
+    return normalizeSchemaHashInput(hash, "schema hash").slice(0, SHORT_SCHEMA_HASH_LENGTH);
+}
+function hashMatchesFullSchema(hash, fullHash) {
+    return fullHash.startsWith(normalizeSchemaHashInput(hash, "schema hash"));
+}
+function resolveKnownSchemaHash(hash, label, knownHashes) {
+    const normalized = normalizeSchemaHashInput(hash, label);
+    if (normalized.length === 64) {
+        if (!knownHashes.includes(normalized)) {
+            throw new Error(`No stored schema found for ${label} ${normalized}.`);
+        }
+        return normalized;
+    }
+    const matches = knownHashes.filter((candidate) => candidate.startsWith(normalized));
+    if (matches.length === 0) {
+        throw new Error(`No stored schema found for ${label} prefix ${normalized}.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`${label} prefix ${normalized} is ambiguous: ${matches
+            .map((candidate) => shortSchemaHash(candidate))
+            .join(", ")}`);
+    }
+    return matches[0];
+}
+function columnTypeSignature(columnType) {
+    return JSON.stringify(columnType);
+}
+function columnsEqual(left, right) {
+    return (left.name === right.name &&
+        left.nullable === right.nullable &&
+        left.references === right.references &&
+        columnTypeSignature(left.column_type) === columnTypeSignature(right.column_type));
+}
+function tableSchemasEqual(left, right) {
+    if (!left || !right) {
+        return false;
+    }
+    if (left.columns.length !== right.columns.length) {
         return false;
     }
-    const opPolicy = input;
-    return Object.keys(opPolicy).every((key) => key === "using" || key === "with_check");
+    return left.columns.every((column, index) => columnsEqual(column, right.columns[index]));
 }
-function isTablePoliciesLike(input) {
-    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+function wasmSchemasEqual(left, right) {
+    const leftTableNames = Object.keys(left).sort();
+    const rightTableNames = Object.keys(right).sort();
+    if (leftTableNames.length !== rightTableNames.length) {
         return false;
     }
-    const tablePolicy = input;
-    const validOperationKeys = ["select", "insert", "update", "delete"];
-    return Object.entries(tablePolicy).every(([key, value]) => {
-        if (!validOperationKeys.includes(key)) {
+    return leftTableNames.every((tableName, index) => {
+        if (tableName !== rightTableNames[index]) {
             return false;
         }
-        return isOperationPolicyLike(value);
+        return tableSchemasEqual(left[tableName], right[tableName]);
     });
 }
-function isPermissionsMap(input) {
-    if (typeof input !== "object" || input === null) {
-        return false;
+function changedTableNames(fromSchema, toSchema) {
+    const names = new Set([...Object.keys(fromSchema), ...Object.keys(toSchema)]);
+    return [...names].filter((tableName) => !tableSchemasEqual(fromSchema[tableName], toSchema[tableName]));
+}
+function ensurePermissionsProject(compiled) {
+    if (!compiled.permissions || !compiled.permissionsFile) {
+        throw new Error("No permissions.ts found for this app. Create permissions.ts before using permissions commands.");
     }
-    return Object.values(input).every((value) => isTablePoliciesLike(value));
+    return compiled;
 }
-async function loadPermissionsModule(filePath) {
-    const module = requirePermissionsModule(filePath);
-    const candidate = module.default ?? module.permissions ?? null;
-    if (!candidate) {
-        throw new Error(`Missing permissions export in ${basename(filePath)}. ` +
-            `Export default definePermissions(...) (or export const permissions = definePermissions(...)).`);
+async function resolveStoredStructuralSchemaHash(serverUrl, adminSecret, wasmSchema) {
+    const { hashes } = await fetchSchemaHashes(serverUrl, { adminSecret });
+    const storedSchemas = await Promise.all(hashes.map(async (hash) => ({
+        hash,
+        schema: (await fetchStoredWasmSchema(serverUrl, { adminSecret, schemaHash: hash })).schema,
+    })));
+    const match = storedSchemas.find(({ schema }) => wasmSchemasEqual(schema, wasmSchema));
+    if (!match) {
+        throw new Error("No stored structural schema matches the local schema.ts. Publish the structural schema before pushing permissions.");
     }
-    if (!isPermissionsMap(candidate)) {
-        throw new Error(`Invalid permissions export in ${basename(filePath)}. Expected default export from definePermissions(...).`);
+    return match.hash;
+}
+function pickWitnessSchema(schema, tableNames) {
+    return Object.fromEntries(tableNames
+        .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.");
     }
-    return candidate;
 }
-function mergePermissionsIntoSchema(schema, compiledPermissions) {
-    const schemaTableNames = new Set(schema.tables.map((table) => table.name));
-    const unknownTables = Object.keys(compiledPermissions).filter((tableName) => !schemaTableNames.has(tableName));
-    if (unknownTables.length > 0) {
-        throw new Error(`permissions.ts defines permissions for unknown table(s): ${unknownTables.join(", ")}.`);
+function builderExpressionForColumn(column) {
+    const base = baseBuilderExpression(column.column_type, column.references);
+    return column.nullable ? `${base}.optional()` : base;
+}
+function sqlTypeToWasmColumnType(sqlType) {
+    if (typeof sqlType === "string") {
+        switch (sqlType) {
+            case "TEXT":
+                return { type: "Text" };
+            case "BOOLEAN":
+                return { type: "Boolean" };
+            case "INTEGER":
+                return { type: "Integer" };
+            case "REAL":
+                return { type: "Double" };
+            case "TIMESTAMP":
+                return { type: "Timestamp" };
+            case "UUID":
+                return { type: "Uuid" };
+            case "BYTEA":
+                return { type: "Bytea" };
+        }
+    }
+    if (sqlType.kind === "ENUM") {
+        return {
+            type: "Enum",
+            variants: [...sqlType.variants],
+        };
+    }
+    if (sqlType.kind === "JSON") {
+        return {
+            type: "Json",
+            schema: sqlType.schema,
+        };
     }
     return {
-        tables: schema.tables.map((table) => {
-            const external = compiledPermissions[table.name];
-            if (!external) {
-                return table;
+        type: "Array",
+        element: sqlTypeToWasmColumnType(sqlType.element),
+    };
+}
+function serializeForwardLenses(forward) {
+    return forward.map((tableLens) => ({
+        table: tableLens.table,
+        operations: tableLens.operations.map((op) => {
+            if (op.type === "rename") {
+                return op;
             }
+            const columnType = sqlTypeToWasmColumnType(op.sqlType);
+            const value = encodePublishedMigrationValue(toValue(op.value, columnType));
             return {
-                ...table,
-                policies: external,
+                type: op.type,
+                column: op.column,
+                columnType,
+                value,
             };
         }),
-    };
+    }));
 }
-/**
- * Check if a path exists
- */
-const pathExists = async (path) => {
-    try {
-        await access(path);
-        return true;
+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 "{}";
     }
-    catch {
-        return false;
+    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.");
     }
-};
-const findMonorepoJazzBinary = async () => {
-    let currentDir = process.cwd();
-    while (true) {
-        const cargoTomlPath = join(currentDir, "Cargo.toml");
-        const monorepoJazzToolsPath = join(currentDir, "target", "debug", "jazz-tools");
-        const monorepoJazzPath = join(currentDir, "target", "debug", "jazz");
-        if ((await pathExists(cargoTomlPath)) && (await pathExists(monorepoJazzToolsPath))) {
-            return monorepoJazzToolsPath;
+}
+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)}.`);
         }
-        // Backward compatibility for older local builds.
-        if ((await pathExists(cargoTomlPath)) && (await pathExists(monorepoJazzPath))) {
-            return monorepoJazzPath;
+    }
+    for (const columnName of addedColumns) {
+        const column = toColumns.get(columnName);
+        if (column.nullable) {
+            properties.push(`${JSON.stringify(columnName)}: ${renderAddOperationExpression(column, "null")},`);
         }
-        const parentDir = dirname(currentDir);
-        if (parentDir === currentDir) {
-            return null;
+        else {
+            comments.push(`Added required column ${JSON.stringify(columnName)} needs an explicit default.`);
         }
-        currentDir = parentDir;
     }
-};
-async function ensurePermissionsTestStub(schemaDir) {
-    const permissionsFile = join(schemaDir, "permissions.ts");
-    if (!(await pathExists(permissionsFile))) {
-        return;
+    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.`);
+        }
     }
-    const testFile = join(schemaDir, "permissions.test.ts");
-    if (await pathExists(testFile)) {
-        return;
+    return {
+        tableName,
+        comments,
+        properties,
+    };
+}
+function renderMigrationBody(fromSchema, toSchema) {
+    const changedTables = changedTableNames(fromSchema, toSchema);
+    const migratableTables = changedTables.filter((tableName) => fromSchema[tableName] !== undefined && toSchema[tableName] !== undefined);
+    const witnessFrom = pickWitnessSchema(fromSchema, migratableTables);
+    const witnessTo = pickWitnessSchema(toSchema, migratableTables);
+    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) {
+        lines.push(changedTables.length === 0
+            ? "// TODO: No schema differences were detected."
+            : "// TODO: No column-level migration steps were required for the detected schema changes.");
     }
-    const template = `/**
- * Permissions test starter.
- *
- * Suggested shape (jazz-tools/testing):
- * - createPolicyTestApp(...) for an isolated test app
- * - testApp.seed(...) to set up synthetic fixtures
- * - testApp.as(...) for request-scoped user clients
- * - testApp.expectAllowed(...) / testApp.expectDenied(...) assertions
- */
-import { describe, it } from "vitest";
+    return {
+        body: lines.join("\n").trimEnd(),
+        witnessFrom,
+        witnessTo,
+    };
+}
+async function packageVersion() {
+    const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    return packageJson.version ?? "unknown";
+}
+function createDateStamp(now = new Date()) {
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, "0");
+    const day = String(now.getDate()).padStart(2, "0");
+    return `${year}${month}${day}`;
+}
+function migrationFilename(migrationsDir, fromHash, toHash) {
+    return join(migrationsDir, `${createDateStamp()}-unnamed-${shortSchemaHash(fromHash)}-${shortSchemaHash(toHash)}.ts`);
+}
+function renderMigrationStub(input) {
+    const rendered = renderMigrationBody(input.fromSchema, input.toSchema);
+    return `import { schema as s } from "jazz-tools";
 
-describe.skip("permissions", () => {
-  it("add policy tests", () => {
-    // Starter file generated by jazz-tools build.
-  });
+export default s.defineMigration({
+  migrate: {
+${indentBlock(rendered.body, 4)}
+  },
+  fromHash: ${JSON.stringify(shortSchemaHash(input.fromHash))},
+  toHash: ${JSON.stringify(shortSchemaHash(input.toHash))},
+  from: ${renderSchemaWitness(rendered.witnessFrom)},
+  to: ${renderSchemaWitness(rendered.witnessTo)},
 });
 `;
-    await writeFile(testFile, template);
-    console.log(`Generated: permissions.test.ts`);
-}
-async function runJazzBuild(jazzBin, schemaDir, searchJazzBinOnError = true) {
-    const result = await new Promise((resolve) => {
-        console.log(`\nRunning: ${jazzBin} build --ts --schema-dir ${schemaDir}`);
-        const child = spawn(jazzBin, ["build", "--ts", "--schema-dir", schemaDir], {
-            stdio: "inherit",
-        });
-        child.on("close", (code) => {
-            resolve({ type: "close", code });
-        });
-        child.on("error", (error) => {
-            resolve({ type: "error", error });
-        });
+}
+function isDefinedMigration(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.fromHash === "string" &&
+        typeof candidate.toHash === "string" &&
+        typeof candidate.from === "object" &&
+        candidate.from !== null &&
+        typeof candidate.to === "object" &&
+        candidate.to !== null &&
+        Array.isArray(candidate.forward));
+}
+async function loadDefinedMigration(filePath) {
+    const url = pathToFileURL(filePath).href + `?v=${++importCounter}`;
+    const loaded = (await import(url));
+    const migration = loaded.default ?? loaded.migration;
+    if (!isDefinedMigration(migration)) {
+        throw new Error(`Invalid migration export in ${basename(filePath)}. Export default defineMigration(...).`);
+    }
+    return migration;
+}
+async function findMigrationFile(migrationsDir, fromHash, toHash) {
+    const fromShortHash = shortSchemaHash(fromHash);
+    const toShortHash = shortSchemaHash(toHash);
+    const files = await readdir(migrationsDir);
+    const matches = files
+        .filter((file) => file.endsWith(".ts"))
+        .filter((file) => file.includes(`-${fromShortHash}-${toShortHash}.ts`) ||
+        file.includes(`-${fromHash}-${toHash}.ts`));
+    if (matches.length === 0) {
+        throw new Error(`No migration file found in ${migrationsDir} for ${fromHash} -> ${toHash}.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Multiple migration files found for ${fromHash} -> ${toHash}: ${matches.join(", ")}`);
+    }
+    return join(migrationsDir, matches[0]);
+}
+export async function createMigration(options) {
+    const { hashes } = await fetchSchemaHashes(options.serverUrl, {
+        adminSecret: options.adminSecret,
     });
-    if (result.type === "close") {
-        if (result.code !== 0) {
-            console.warn(`jazz-tools build exited with code ${result.code} (versioned schemas not generated)`);
-        }
+    const fromHash = resolveKnownSchemaHash(options.fromHash, "fromHash", hashes);
+    const toHash = resolveKnownSchemaHash(options.toHash, "toHash", hashes);
+    await mkdir(options.migrationsDir, { recursive: true });
+    const [{ schema: fromSchema }, { schema: toSchema }] = await Promise.all([
+        fetchStoredWasmSchema(options.serverUrl, {
+            adminSecret: options.adminSecret,
+            schemaHash: fromHash,
+        }),
+        fetchStoredWasmSchema(options.serverUrl, {
+            adminSecret: options.adminSecret,
+            schemaHash: toHash,
+        }),
+    ]);
+    const filePath = migrationFilename(options.migrationsDir, fromHash, toHash);
+    if (await pathExists(filePath)) {
+        throw new Error(`Migration stub already exists: ${filePath}`);
+    }
+    const stub = renderMigrationStub({ fromHash, toHash, fromSchema, toSchema });
+    await writeFile(filePath, stub);
+    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.");
+    console.log("2. Rename the file by replacing 'unnamed'.");
+    console.log(`3. Run npx jazz-tools@${version} migrations push ${shortSchemaHash(fromHash)} ${shortSchemaHash(toHash)}`);
+    return filePath;
+}
+export async function pushMigration(options) {
+    const { hashes } = await fetchSchemaHashes(options.serverUrl, {
+        adminSecret: options.adminSecret,
+    });
+    const fromHash = resolveKnownSchemaHash(options.fromHash, "fromHash", hashes);
+    const toHash = resolveKnownSchemaHash(options.toHash, "toHash", hashes);
+    const filePath = await findMigrationFile(options.migrationsDir, fromHash, toHash);
+    const migration = await loadDefinedMigration(filePath);
+    if (!hashMatchesFullSchema(migration.fromHash, fromHash) ||
+        !hashMatchesFullSchema(migration.toHash, toHash)) {
+        throw new Error(`Migration ${basename(filePath)} exports ${migration.fromHash} -> ${migration.toHash}, expected ${shortSchemaHash(fromHash)} -> ${shortSchemaHash(toHash)}.`);
+    }
+    schemaDefinitionToAst(migration.from);
+    schemaDefinitionToAst(migration.to);
+    if (migration.forward.length === 0) {
+        throw new Error(`Migration ${basename(filePath)} has no steps. Fill in migrate before push.`);
+    }
+    const forward = serializeForwardLenses(migration.forward);
+    await publishStoredMigration(options.serverUrl, {
+        adminSecret: options.adminSecret,
+        fromHash,
+        toHash,
+        forward,
+    });
+    console.log(`Pushed migration ${shortSchemaHash(fromHash)} -> ${shortSchemaHash(toHash)} from ${basename(filePath)}.`);
+}
+function describePermissionsHead(head) {
+    return `v${head.version} on ${shortSchemaHash(head.schemaHash)}`;
+}
+export async function permissionsStatus(options) {
+    const compiled = ensurePermissionsProject(await loadCompiledSchema(options.schemaDir));
+    const localSchemaHash = await resolveStoredStructuralSchemaHash(options.serverUrl, options.adminSecret, compiled.wasmSchema);
+    const { head } = await fetchPermissionsHead(options.serverUrl, {
+        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)}.`);
+    console.log(PERMISSIONS_LIFECYCLE_NOTE);
+    if (!head) {
+        console.log("Server has no published permissions head yet.");
+        console.log("Next push will publish version 1.");
         return;
     }
-    const error = result.error;
-    if (error.code === "ENOENT") {
-        const monorepoJazzPath = searchJazzBinOnError ? await findMonorepoJazzBinary() : null;
-        if (monorepoJazzPath) {
-            console.log(`jazz-tools binary not found at '${jazzBin}'. Using monorepo binary at '${monorepoJazzPath}'`);
-            return runJazzBuild(monorepoJazzPath, schemaDir, false);
-        }
-        else {
-            console.warn(`jazz-tools binary not found at '${jazzBin}'. Use --jazz-bin to specify the path.\n` +
-                `Versioned schemas will not be generated.`);
-        }
+    console.log(`Server permissions head is ${describePermissionsHead(head)}.`);
+    if (head.schemaHash === localSchemaHash) {
+        console.log("Current server permissions already target this structural schema.");
     }
-    console.warn(`jazz-tools build failed: ${error.message}`);
+    else {
+        console.log(`Current server permissions target ${shortSchemaHash(head.schemaHash)}; pushing will retarget the head to ${shortSchemaHash(localSchemaHash)}.`);
+    }
+    console.log(`Next push will require parent bundle ${head.bundleObjectId}.`);
 }
-export async function build(options) {
-    const { jazzBin, schemaDir } = options;
-    let files;
-    try {
-        files = await readdir(schemaDir);
+export async function pushPermissions(options) {
+    const compiled = ensurePermissionsProject(await loadCompiledSchema(options.schemaDir));
+    const localSchemaHash = await resolveStoredStructuralSchemaHash(options.serverUrl, options.adminSecret, compiled.wasmSchema);
+    const { head: currentHead } = await fetchPermissionsHead(options.serverUrl, {
+        adminSecret: options.adminSecret,
+    });
+    const { head: publishedHead } = await publishStoredPermissions(options.serverUrl, {
+        adminSecret: options.adminSecret,
+        schemaHash: localSchemaHash,
+        permissions: compiled.permissions,
+        expectedParentBundleObjectId: currentHead?.bundleObjectId ?? null,
+    });
+    console.log(`Loaded structural schema from ${compiled.schemaFile}.`);
+    console.log(`Loaded current permissions from ${compiled.permissionsFile}.`);
+    console.log(`Resolved structural schema hash ${shortSchemaHash(localSchemaHash)}.`);
+    if (currentHead) {
+        console.log(`Publishing from parent ${describePermissionsHead(currentHead)}.`);
     }
-    catch {
-        console.error(`Schema directory not found: ${schemaDir}`);
-        process.exit(1);
-    }
-    const tsFiles = files.filter((f) => f.endsWith(".ts"));
-    for (const file of tsFiles.filter((name) => isMigrationTsStub(name))) {
-        await generateSqlForMigrationFile(join(schemaDir, file));
-    }
-    const schemaFile = join(schemaDir, "current.ts");
-    if (!(await pathExists(schemaFile))) {
-        console.error(`Schema file not found: ${schemaFile}`);
-        process.exit(1);
-    }
-    let schema = await loadSchema(schemaFile);
-    const tablesWithInlinePolicies = schema.tables
-        .filter((table) => table.policies)
-        .map((t) => t.name);
-    if (tablesWithInlinePolicies.length > 0) {
-        throw new Error("Inline table permissions in current.ts are no longer supported. " +
-            "Move policies to schema/permissions.ts. " +
-            `Tables: ${tablesWithInlinePolicies.join(", ")}.`);
-    }
-    // Generate app.ts before loading permissions.ts so permissions can import it for typing.
-    await generateAppTs(schemaDir, schema);
-    const permissionsFile = join(schemaDir, "permissions.ts");
-    if (await pathExists(permissionsFile)) {
-        const permissions = await loadPermissionsModule(permissionsFile);
-        schema = mergePermissionsIntoSchema(schema, permissions);
-    }
-    await generateSqlForSchemaFile(schemaFile, schema);
-    await generateAppTs(schemaDir, schema);
-    await ensurePermissionsTestStub(schemaDir);
-    await runJazzBuild(jazzBin, schemaDir);
+    else {
+        console.log("Publishing first permissions head for this app.");
+    }
+    const nextHead = publishedHead ?? {
+        schemaHash: localSchemaHash,
+        version: currentHead ? currentHead.version + 1 : 1,
+        parentBundleObjectId: currentHead?.bundleObjectId ?? null,
+        bundleObjectId: currentHead?.bundleObjectId ?? "",
+    };
+    console.log(`Published permissions head ${describePermissionsHead(nextHead)}.`);
+    console.log(PERMISSIONS_LIFECYCLE_NOTE);
 }
 function isMainModule() {
     const entry = process.argv[1];
@@ -307,22 +643,88 @@ function isMainModule() {
     return pathToFileURL(entry).href === import.meta.url;
 }
 if (isMainModule()) {
-    const { command, options } = parseArgs();
-    switch (command) {
-        case "build":
-            build(options).catch((err) => {
-                console.error(err.message);
-                process.exit(1);
-            });
-            break;
-        default:
-            console.log("Usage: node <path-to-jazz-tools>/dist/cli.js build [options]");
-            console.log("\nCommands:");
-            console.log("  build    Generate SQL from TypeScript schemas and run jazz-tools build");
-            console.log("\nOptions:");
-            console.log("  --jazz-bin <path>    Path to jazz binary (default: jazz-tools)");
-            console.log("  --schema-dir <path>  Path to schema directory (default: ./schema)");
-            process.exit(command ? 1 : 0);
+    const command = process.argv[2] ?? "";
+    if (command === "validate") {
+        const { options } = parseArgs();
+        validate(options).catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
+    }
+    else if (command === "schema") {
+        const subcommand = process.argv[3] ?? "";
+        if (subcommand !== "export") {
+            console.error("Usage: node dist/cli.js schema export [--schema-dir <path>] [--format json]");
+            process.exit(1);
+        }
+        const args = process.argv.slice(4);
+        const schemaDir = getFlagValue(args, "--schema-dir") ?? process.cwd();
+        const formatValue = getFlagValue(args, "--format") ?? "json";
+        if (formatValue !== "json") {
+            console.error(`Unsupported schema export format: ${formatValue}`);
+            process.exit(1);
+        }
+        exportSchema({ schemaDir, format: "json" }).catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
+    }
+    else if (command === "migrations") {
+        const subcommand = process.argv[3] ?? "";
+        const fromHash = process.argv[4];
+        const toHash = process.argv[5];
+        const sharedArgs = process.argv.slice(6);
+        if (!fromHash || !toHash) {
+            console.error("Usage: node dist/cli.js migrations <create|push> <fromHash> <toHash> [options]");
+            process.exit(1);
+        }
+        const options = resolveMigrationOptions(sharedArgs);
+        const task = subcommand === "create"
+            ? createMigration({ ...options, fromHash, toHash })
+            : subcommand === "push"
+                ? pushMigration({ ...options, fromHash, toHash })
+                : Promise.reject(new Error("Usage: node dist/cli.js migrations <create|push> <fromHash> <toHash> [options]"));
+        task.catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
+    }
+    else if (command === "permissions") {
+        const subcommand = process.argv[3] ?? "";
+        const options = resolvePermissionsOptions(process.argv.slice(4));
+        const task = subcommand === "status"
+            ? permissionsStatus(options)
+            : subcommand === "push"
+                ? pushPermissions(options)
+                : Promise.reject(new Error("Usage: node dist/cli.js permissions <status|push> [options]"));
+        task.catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
+    }
+    else {
+        console.log("Usage: node <path-to-jazz-tools>/dist/cli.js <command> [options]");
+        console.log("\nCommands:");
+        console.log("  validate              Validate root schema.ts and optional permissions.ts");
+        console.log("  schema export         Print the compiled structural schema as JSON");
+        console.log("  permissions status    Show the current server permissions head for this app");
+        console.log("  permissions push      Publish the current permissions.ts with head-parent checks");
+        console.log("  migrations create     Generate a typed structural migration stub from two known schema hashes");
+        console.log("  migrations push       Push a reviewed migration edge to the server");
+        console.log("\nValidation options:");
+        console.log("  --schema-dir <path>   Path to app root containing schema.ts (default: .)");
+        console.log("\nSchema export options:");
+        console.log("  --schema-dir <path>   Path to app root containing schema.ts (default: .)");
+        console.log("  --format json         Output the compiled schema as JSON");
+        console.log("\nPermissions options:");
+        console.log("  --schema-dir <path>   Path to app root containing schema.ts (default: .)");
+        console.log("  --server-url <url>    Jazz server URL (or set JAZZ_SERVER_URL)");
+        console.log("  --admin-secret <sec>  Admin secret (or set JAZZ_ADMIN_SECRET)");
+        console.log("\nMigration options:");
+        console.log("  --server-url <url>    Jazz server URL (or set JAZZ_SERVER_URL)");
+        console.log("  --admin-secret <sec>  Admin secret (or set JAZZ_ADMIN_SECRET)");
+        console.log("  --migrations-dir <p>  Path to migrations directory (default: ./migrations)");
+        process.exit(command ? 1 : 0);
     }
 }
 //# sourceMappingURL=cli.js.map