pgpm 5.19.1 → 5.20.0

package/commands/slice.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@pgpmjs/core");
 const slice_1 = require("@pgpmjs/slice");
 const types_1 = require("@pgpmjs/types");
-const path_1 = require("path");
 const fs_1 = require("fs");
+const path_1 = require("path");
 const sliceUsageText = `
 Slice Command:
 

package/commands/test-packages.js

@@ -7,8 +7,8 @@ const core_1 = require("@pgpmjs/core");
 const env_1 = require("@pgpmjs/env");
 const logger_1 = require("@pgpmjs/logger");
 const path_1 = __importDefault(require("path"));
-const pg_env_1 = require("pg-env");
 const pg_cache_1 = require("pg-cache");
+const pg_env_1 = require("pg-env");
 const log = new logger_1.Logger('test-packages');
 // ANSI color codes
 const RED = '\x1b[0;31m';

package/commands/transform.d.ts

@@ -0,0 +1,13 @@
+import { PartitionedPackageRows } from '@pgpmjs/transform';
+import { CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
+export { checkOverwrite } from '../utils/emit-package';
+/**
+ * Resolve the base directory package dir(s) are created in. Without --out,
+ * packages are written as siblings of the source module — a plain transform
+ * of `my-mod` at granularity `object` lands in `../my-mod-object`.
+ */
+export declare const resolveOutBase: (modulePath: string, out?: string) => string;
+/** Order partition packages so prerequisites come before dependents. */
+export declare const orderPackages: (packages: PartitionedPackageRows[]) => PartitionedPackageRows[];
+declare const _default: (argv: Partial<ParsedArgs>, prompter: Inquirerer, _options: CLIOptions) => Promise<Partial<ParsedArgs>>;
+export default _default;

package/commands/transform.js

@@ -0,0 +1,275 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orderPackages = exports.resolveOutBase = exports.checkOverwrite = void 0;
+const core_1 = require("@pgpmjs/core");
+const logger_1 = require("@pgpmjs/logger");
+const transform_1 = require("@pgpmjs/transform");
+const fs = __importStar(require("fs"));
+const inquirerer_1 = require("inquirerer");
+const path = __importStar(require("path"));
+const pg_env_1 = require("pg-env");
+const emit_package_1 = require("../utils/emit-package");
+const scratch_db_1 = require("../utils/scratch-db");
+var emit_package_2 = require("../utils/emit-package");
+Object.defineProperty(exports, "checkOverwrite", { enumerable: true, get: function () { return emit_package_2.checkOverwrite; } });
+const log = new logger_1.Logger('transform');
+const transformUsageText = `
+Transform Command:
+
+  pgpm transform --granularity <atomic|object|consolidated> [OPTIONS]
+
+  Re-dial an existing pgpm module (or every module in a workspace) through the
+  dials pipeline: flatten the deploy scripts in plan order, re-project them at
+  the requested granularity with spec-derived change paths, graph-derived
+  requires, and generated revert/verify scripts.
+
+Options:
+  --help, -h              Show this help message
+  --granularity <level>   Target granularity: atomic | object | consolidated (required)
+  --partition <file>      Partition config (JSON: rules/defaultPackage/splitRiders)
+                          splitting the module into multiple pgpm packages with
+                          derived cross-package requires.
+  --naming <style>        Change path naming style: directory | flat (default: directory)
+  --cwd <directory>       Module or workspace directory (default: current directory)
+  --out <dir>             Output directory (default: sibling <module>-<granularity>)
+  --write                 Allow writing over an existing/module directory
+  --check                 Deploy original and transformed output into scratch
+                          databases and assert the catalogs are equivalent
+  --dry-run               Print the resulting plan/paths without writing
+
+Examples:
+  pgpm transform --granularity object
+  pgpm transform --granularity atomic --naming flat --out ./out
+  pgpm transform --granularity object --partition partition.json --check
+`;
+const NAMING_STYLES = ['directory', 'flat'];
+/**
+ * Resolve the base directory package dir(s) are created in. Without --out,
+ * packages are written as siblings of the source module — a plain transform
+ * of `my-mod` at granularity `object` lands in `../my-mod-object`.
+ */
+const resolveOutBase = (modulePath, out) => {
+    if (out)
+        return path.resolve(out);
+    return path.dirname(modulePath);
+};
+exports.resolveOutBase = resolveOutBase;
+/** Order partition packages so prerequisites come before dependents. */
+const orderPackages = (packages) => {
+    const byName = new Map(packages.map(pkg => [pkg.name, pkg]));
+    const ordered = [];
+    const seen = new Set();
+    const visit = (pkg) => {
+        if (seen.has(pkg.name))
+            return;
+        seen.add(pkg.name);
+        for (const req of pkg.requires) {
+            const dep = byName.get(req);
+            if (dep)
+                visit(dep);
+        }
+        ordered.push(pkg);
+    };
+    for (const pkg of packages)
+        visit(pkg);
+    return ordered;
+};
+exports.orderPackages = orderPackages;
+const readControlRequires = (modulePath, name) => {
+    const controlPath = path.join(modulePath, `${name}.control`);
+    if (!fs.existsSync(controlPath))
+        return [];
+    const match = fs.readFileSync(controlPath, 'utf-8').match(/^requires\s*=\s*'([^']*)'\s*$/m);
+    if (!match)
+        return [];
+    return match[1].split(',').map(s => s.trim()).filter(Boolean);
+};
+const deployModules = async (config, modulePaths) => {
+    const client = new core_1.PgpmMigrate(config);
+    for (const modulePath of modulePaths) {
+        const result = await client.deploy({ modulePath });
+        if (result.failed) {
+            throw new Error(`deploy failed at change ${result.failed} (module ${modulePath})`);
+        }
+    }
+};
+/**
+ * Prove the transform is structurally lossless: deploy the original module and
+ * the transformed package(s) into two scratch databases and compare catalogs.
+ */
+const runCheck = async (transformed) => {
+    const config = (0, pg_env_1.getPgEnvOptions)();
+    const stamp = Date.now();
+    const names = [`pgpm_transform_check_a_${stamp}`, `pgpm_transform_check_b_${stamp}`];
+    return (0, scratch_db_1.withScratchDatabases)(config, names, async ([cfgOriginal, cfgTransformed]) => {
+        await deployModules(cfgOriginal, [transformed.modulePath]);
+        const orderedDirs = (0, exports.orderPackages)(transformed.packages).map(pkg => path.join(transformed.outBase, pkg.name));
+        await deployModules(cfgTransformed, orderedDirs);
+        return (0, scratch_db_1.catalogDifferences)(cfgOriginal, cfgTransformed);
+    });
+};
+const transformModule = async (modulePath, granularity, naming, partition, out) => {
+    const source = (0, transform_1.loadModuleSource)(modulePath);
+    const warnings = [...source.warnings];
+    const rows = source.changes.map(change => ({
+        name: change.name,
+        deploy: change.name,
+        deps: change.dependencies,
+        content: change.deploy
+    }));
+    const restructured = await (0, transform_1.restructureExportRows)(rows, granularity, { naming });
+    warnings.push(...restructured.warnings.map(w => `restructure (${granularity}): ${w}`));
+    const outBase = (0, exports.resolveOutBase)(modulePath, out);
+    let packages;
+    if (partition) {
+        const result = await (0, transform_1.partitionExportRows)(restructured.rows, partition);
+        warnings.push(...result.warnings.map(w => `partition: ${w}`));
+        packages = result.packages;
+    }
+    else {
+        // Distinct package name so the output can live beside the source module
+        // in the same workspace without colliding.
+        packages = [{ name: `${source.name}-${granularity}`, requires: [], rows: restructured.rows }];
+    }
+    return { modulePath, name: source.name, outBase, packages, warnings };
+};
+const printDryRun = (transformed) => {
+    console.log(`module ${transformed.name} (${transformed.modulePath})`);
+    for (const pkg of transformed.packages) {
+        console.log(`  package ${pkg.name} -> ${path.join(transformed.outBase, pkg.name)}`);
+        for (const row of pkg.rows) {
+            const deps = row.deps?.length ? ` [${row.deps.join(' ')}]` : '';
+            console.log(`    ${row.deploy}${deps}`);
+        }
+    }
+};
+exports.default = async (argv, prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(transformUsageText);
+        process.exit(0);
+    }
+    const granularityRaw = argv.granularity;
+    if (granularityRaw === undefined) {
+        await (0, inquirerer_1.cliExitWithError)(`--granularity is required. Expected one of: ${transform_1.EXPORT_GRANULARITIES.join(', ')}.`);
+    }
+    if (!(0, transform_1.isExportGranularity)(granularityRaw)) {
+        await (0, inquirerer_1.cliExitWithError)(`Invalid --granularity "${granularityRaw}". Expected one of: ${transform_1.EXPORT_GRANULARITIES.join(', ')}.`);
+    }
+    const granularity = granularityRaw;
+    const namingRaw = argv.naming ?? 'directory';
+    if (!NAMING_STYLES.includes(namingRaw)) {
+        await (0, inquirerer_1.cliExitWithError)(`Invalid --naming "${namingRaw}". Expected one of: ${NAMING_STYLES.join(', ')}.`);
+    }
+    const naming = namingRaw;
+    const cwd = argv.cwd || process.cwd();
+    let partition;
+    if (typeof argv.partition === 'string' && argv.partition) {
+        try {
+            partition = (0, transform_1.parsePartitionConfig)(path.resolve(cwd, argv.partition));
+        }
+        catch (err) {
+            await (0, inquirerer_1.cliExitWithError)(err instanceof Error ? err.message : String(err));
+        }
+    }
+    const out = typeof argv.out === 'string' && argv.out ? path.resolve(cwd, argv.out) : undefined;
+    const write = Boolean(argv.write);
+    const check = Boolean(argv.check);
+    const dryRun = Boolean(argv['dry-run'] ?? argv.dryRun);
+    const pkg = new core_1.PgpmPackage(path.resolve(cwd));
+    let modulePaths;
+    if (pkg.isInModule()) {
+        modulePaths = [pkg.modulePath];
+    }
+    else if (pkg.workspacePath) {
+        const moduleMap = pkg.getModuleMap();
+        modulePaths = Object.values(moduleMap).map(mod => path.resolve(pkg.workspacePath, mod.path));
+        if (modulePaths.length === 0) {
+            await (0, inquirerer_1.cliExitWithError)('No modules found in workspace.');
+        }
+        if (out && modulePaths.length > 1) {
+            await (0, inquirerer_1.cliExitWithError)('--out is not supported when transforming a multi-module workspace.');
+        }
+    }
+    else {
+        await (0, inquirerer_1.cliExitWithError)('Not inside a pgpm module or workspace (pass --cwd <dir>).');
+        return;
+    }
+    for (const modulePath of modulePaths) {
+        let transformed;
+        try {
+            transformed = await transformModule(modulePath, granularity, naming, partition, out);
+        }
+        catch (err) {
+            if (err instanceof transform_1.PartitionCycleError) {
+                await (0, inquirerer_1.cliExitWithError)(`Partition failed: ${err.message}`);
+                return;
+            }
+            throw err;
+        }
+        for (const warning of transformed.warnings) {
+            console.warn(`transform: ${warning}`);
+        }
+        if (dryRun) {
+            printDryRun(transformed);
+            continue;
+        }
+        for (const pkgRows of transformed.packages) {
+            const targetDir = path.join(transformed.outBase, pkgRows.name);
+            const guard = (0, emit_package_1.checkOverwrite)(targetDir, modulePath, write);
+            if (guard) {
+                await (0, inquirerer_1.cliExitWithError)(guard);
+            }
+        }
+        const sourceRequires = readControlRequires(modulePath, transformed.name);
+        for (const pkgRows of transformed.packages) {
+            const dir = (0, emit_package_1.writePackage)(transformed.outBase, pkgRows, sourceRequires);
+            log.success(`wrote ${pkgRows.rows.length} changes to ${dir}`);
+        }
+        if (check) {
+            log.info('running --check: deploying original and transformed output to scratch databases...');
+            const diffs = await runCheck(transformed);
+            if (diffs.length) {
+                console.error(`--check failed: catalogs differ (${diffs.length} differences):`);
+                for (const diff of diffs)
+                    console.error(`  ${diff}`);
+                await (0, inquirerer_1.cliExitWithError)('Transform is not structurally lossless.');
+            }
+            log.success('--check passed: catalogs are structurally equivalent.');
+        }
+    }
+    prompter.close();
+    return argv;
+};

package/commands/update.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("@inquirerer/utils");
 const logger_1 = require("@pgpmjs/logger");
-const inquirerer_1 = require("inquirerer");
 const child_process_1 = require("child_process");
+const inquirerer_1 = require("inquirerer");
 const npm_version_1 = require("../utils/npm-version");
 const log = new logger_1.Logger('update');
 const updateUsageText = `

package/commands.js

@@ -13,12 +13,14 @@ const analyze_1 = __importDefault(require("./commands/analyze"));
 const cache_1 = __importDefault(require("./commands/cache"));
 const clear_1 = __importDefault(require("./commands/clear"));
 const deploy_1 = __importDefault(require("./commands/deploy"));
+const diff_1 = __importDefault(require("./commands/diff"));
 const docker_1 = __importDefault(require("./commands/docker"));
 const doctor_1 = __importDefault(require("./commands/doctor"));
 const dump_1 = __importDefault(require("./commands/dump"));
 const env_1 = __importDefault(require("./commands/env"));
 const export_1 = __importDefault(require("./commands/export"));
 const extension_1 = __importDefault(require("./commands/extension"));
+const import_1 = __importDefault(require("./commands/import"));
 const init_1 = __importDefault(require("./commands/init"));
 const install_1 = __importDefault(require("./commands/install"));
 const kill_1 = __importDefault(require("./commands/kill"));
@@ -34,6 +36,7 @@ const slice_1 = __importDefault(require("./commands/slice"));
 const sync_versions_1 = __importDefault(require("./commands/sync-versions"));
 const tag_1 = __importDefault(require("./commands/tag"));
 const test_packages_1 = __importDefault(require("./commands/test-packages"));
+const transform_1 = __importDefault(require("./commands/transform"));
 const tune_1 = __importDefault(require("./commands/tune"));
 const update_1 = __importDefault(require("./commands/update"));
 const upgrade_1 = __importDefault(require("./commands/upgrade"));
@@ -53,6 +56,7 @@ const ENGINE_EXEMPT_COMMANDS = new Set([
     'doctor',
     'env',
     'extension',
+    'import',
     'init',
     'install',
     'package',
@@ -85,6 +89,7 @@ const createPgpmCommandMap = (skipPgTeardown = false) => {
         'admin-users': pgt(admin_users_1.default),
         clear: pgt(clear_1.default),
         deploy: pgt(deploy_1.default),
+        diff: pgt(diff_1.default),
         docker: docker_1.default,
         doctor: doctor_1.default,
         dump: pgt(dump_1.default),
@@ -97,6 +102,7 @@ const createPgpmCommandMap = (skipPgTeardown = false) => {
         plan: pgt(plan_1.default),
         regen: regen_1.default,
         export: pgt(export_1.default),
+        import: pgt(import_1.default),
         package: pgt(package_1.default),
         tag: pgt(tag_1.default),
         kill: pgt(kill_1.default),
@@ -108,6 +114,7 @@ const createPgpmCommandMap = (skipPgTeardown = false) => {
         slice: slice_1.default,
         'sync-versions': sync_versions_1.default,
         'test-packages': pgt(test_packages_1.default),
+        transform: pgt(transform_1.default),
         tune: pgt(tune_1.default),
         upgrade: pgt(upgrade_1.default),
         up: pgt(upgrade_1.default),

package/esm/commands/cache.js

@@ -1,5 +1,5 @@
-import { cliExitWithError } from 'inquirerer';
 import { CacheManager } from 'genomic';
+import { cliExitWithError } from 'inquirerer';
 const cacheUsageText = `
 Cache Command:
 

package/esm/commands/diff.js

@@ -0,0 +1,290 @@
+import { PgpmMigrate } from '@pgpmjs/core';
+import { deltaChangesToRows, loadDiffSideFromDisk, sqlToDiffChanges } from '@pgpmjs/diff';
+import { Logger } from '@pgpmjs/logger';
+import { diffChangeSets, EXPORT_GRANULARITIES, isExportGranularity, loadModule, withoutColumnOrder, writeModule } from '@pgpmjs/transform';
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import { cliExitWithError, extractFirst } from 'inquirerer';
+import * as os from 'os';
+import * as path from 'path';
+import { getPgPool } from 'pg-cache';
+import { getPgEnvOptions, getSpawnEnvWithPg } from 'pg-env';
+import { emitModuleBundle, emitModuleSql, STDOUT_TARGET } from '../utils/module-projections';
+import { catalogDifferences, withScratchDatabases } from '../utils/scratch-db';
+const log = new Logger('diff');
+const diffUsageText = `
+Diff Command:
+
+  pgpm diff <A> <B> [OPTIONS]
+
+  Identity-keyed semantic diff between two schema sources. Each side is
+  normalized to an object set keyed by identity (kind/schema/name), so the
+  same schema authored at different granularity, naming, or partitioning
+  diffs as empty. Tables are compared column-by-column and
+  constraint-by-constraint, so table changes emit ALTER TABLE, not a rebuild.
+
+Sides:
+  <A> / <B> may each be:
+    - a pgpm module directory (flattened in plan order)
+    - a raw .sql file
+    - a live database: a postgres:// connection string, or db:<name>
+      (uses PG* env for host/port/user; schema is read via pg_dump)
+
+The delta is one model; every --emit-* flag is a projection of it, so they
+compose (a single run can emit a module, a linear SQL file, and a bundle).
+
+Options:
+  --help, -h               Show this help message
+  --emit-migration <dir>   Write the delta as a pgpm module (deploy/revert/
+                           verify per change, spec-derived paths, graph-derived
+                           requires) into <dir>/<pkg>
+  --emit-module <dir>      Alias of --emit-migration
+  --emit-sql <file|->      Also project the delta to a single consolidated SQL
+                           file (deparsed in plan order); - writes to stdout
+  --emit-bundle <file>     Also project the delta to a content-addressed
+                           .bundle.tar.gz archive
+  --pkg <name>             Emitted migration package name (default: diff-migration)
+  --granularity <level>    Granularity for emitted changes: atomic | object |
+                           consolidated (default: object)
+  --naming <style>         Change path naming style: directory | flat (default: directory)
+  --json                   Machine-readable output
+  --verify                 Oracle mode: deploy A plus the emitted migration into
+                           a scratch database and assert catalog equivalence
+                           with B deployed fresh
+  --cwd <directory>        Working directory (default: current directory)
+
+Exit status: 0 when the sides are identical or the diff succeeds; non-zero on
+error or when --verify finds the migrated catalog differs from B.
+
+Examples:
+  pgpm diff ./v1-module ./v2-module
+  pgpm diff ./v1-module ./schema-v2.sql --json
+  pgpm diff db:app_v1 db:app_v2 --emit-migration ./out --verify
+`;
+const NAMING_STYLES = ['directory', 'flat'];
+/** pg_dump a side's schema: `db:<name>` uses PG* env; DSNs pass through. */
+const dumpDatabase = async (spec) => {
+    const args = ['--schema-only', '--no-owner'];
+    let env = process.env;
+    if (spec.startsWith('db:')) {
+        const config = getPgEnvOptions({ database: spec.slice(3) });
+        env = getSpawnEnvWithPg(config);
+    }
+    else {
+        args.push('--dbname', spec);
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn('pg_dump', args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        let err = '';
+        child.stdout.on('data', chunk => { out += chunk; });
+        child.stderr.on('data', chunk => { err += chunk; });
+        child.on('error', (e) => {
+            if (e.code === 'ENOENT') {
+                reject(new Error('pg_dump not found; ensure PostgreSQL client tools are installed and in PATH'));
+                return;
+            }
+            reject(e);
+        });
+        child.on('close', code => {
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(`pg_dump exited with code ${code}: ${err.trim()}`));
+        });
+    });
+};
+/** Resolve one side spec into diff input changes. */
+const loadSide = async (spec, cwd) => {
+    if (resolveDiffSideKindSafe(spec) === 'database') {
+        const label = spec.startsWith('db:') ? spec.slice(3) : spec;
+        return {
+            kind: 'database',
+            label,
+            changes: sqlToDiffChanges(await dumpDatabase(spec), label),
+            warnings: []
+        };
+    }
+    return loadDiffSideFromDisk(path.resolve(cwd, spec));
+};
+/** `resolveDiffSideKind` without throwing on relative on-disk paths. */
+const resolveDiffSideKindSafe = (spec) => /^postgres(ql)?:\/\//.test(spec) || spec.startsWith('db:') ? 'database' : 'disk';
+/** Apply one diff side into a scratch database (module deploy or raw SQL). */
+const applySide = async (config, side, spec, cwd) => {
+    if (side.kind === 'module') {
+        const client = new PgpmMigrate(config);
+        const result = await client.deploy({ modulePath: path.resolve(cwd, spec) });
+        if (result.failed) {
+            throw new Error(`deploy failed at change ${result.failed} (module ${spec})`);
+        }
+        return;
+    }
+    const pool = getPgPool(config);
+    const sql = side.changes.map(c => c.deploy).filter(Boolean).join('\n\n');
+    if (sql.trim())
+        await pool.query(sql);
+};
+/**
+ * Oracle mode: deploy A into a scratch database, deploy the emitted migration
+ * module on top (when there is one), and assert catalog equivalence with B
+ * deployed fresh into a second scratch database. Column order is physical — a
+ * drop+add migration cannot reproduce a fresh deploy's ordinals — so
+ * equivalence is checked order-insensitively via `withoutColumnOrder`.
+ */
+const runVerify = async (sideA, sideB, specA, specB, migrationDir, cwd) => {
+    const config = getPgEnvOptions();
+    const stamp = Date.now();
+    const names = [`pgpm_diff_verify_a_${stamp}`, `pgpm_diff_verify_b_${stamp}`];
+    return withScratchDatabases(config, names, async ([cfgMigrated, cfgTarget]) => {
+        await applySide(cfgMigrated, sideA, specA, cwd);
+        if (migrationDir) {
+            const result = await new PgpmMigrate(cfgMigrated).deploy({ modulePath: migrationDir });
+            if (result.failed) {
+                throw new Error(`migration deploy failed at change ${result.failed}`);
+            }
+        }
+        await applySide(cfgTarget, sideB, specB, cwd);
+        return catalogDifferences(cfgMigrated, cfgTarget, withoutColumnOrder);
+    });
+};
+const printSummary = (result, labelA, labelB) => {
+    if (result.identical) {
+        console.log(`No differences: ${labelA} and ${labelB} describe the same objects.`);
+        return;
+    }
+    const byDelta = (delta) => result.objects.filter(o => o.delta === delta);
+    const section = (title, objects) => {
+        if (objects.length === 0)
+            return;
+        console.log(`${title} (${objects.length}):`);
+        for (const obj of objects) {
+            const detail = [];
+            if (obj.columnsAdded?.length)
+                detail.push(`+cols: ${obj.columnsAdded.join(', ')}`);
+            if (obj.columnsRemoved?.length)
+                detail.push(`-cols: ${obj.columnsRemoved.join(', ')}`);
+            if (obj.columnsModified?.length)
+                detail.push(`~cols: ${obj.columnsModified.join(', ')}`);
+            console.log(`  ${obj.identity.kind} ${obj.path}${detail.length ? ` (${detail.join('; ')})` : ''}`);
+        }
+    };
+    section('Added', byDelta('added'));
+    section('Removed', byDelta('removed'));
+    section('Changed', byDelta('modified'));
+    console.log(`${result.changes.length} migration change(s) derivable.`);
+};
+export default async (argv, prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(diffUsageText);
+        process.exit(0);
+    }
+    const { first: specA, newArgv } = extractFirst(argv);
+    const { first: specB, newArgv: restArgv } = extractFirst(newArgv);
+    argv = restArgv;
+    if (!specA || !specB) {
+        await cliExitWithError('pgpm diff requires two sides: pgpm diff <A> <B> (module dir, .sql file, db:<name>, or connection string).');
+    }
+    const granularityRaw = argv.granularity ?? 'object';
+    if (!isExportGranularity(granularityRaw)) {
+        await cliExitWithError(`Invalid --granularity "${granularityRaw}". Expected one of: ${EXPORT_GRANULARITIES.join(', ')}.`);
+    }
+    const granularity = granularityRaw;
+    const namingRaw = argv.naming ?? 'directory';
+    if (!NAMING_STYLES.includes(namingRaw)) {
+        await cliExitWithError(`Invalid --naming "${namingRaw}". Expected one of: ${NAMING_STYLES.join(', ')}.`);
+    }
+    const naming = namingRaw;
+    const cwd = argv.cwd || process.cwd();
+    const json = Boolean(argv.json);
+    const verify = Boolean(argv.verify);
+    const emitModuleRaw = argv['emit-migration'] ?? argv.emitMigration ?? argv['emit-module'] ?? argv.emitModule;
+    const emitModuleDir = typeof emitModuleRaw === 'string' && emitModuleRaw
+        ? path.resolve(cwd, emitModuleRaw)
+        : undefined;
+    const emitSqlRaw = argv['emit-sql'] ?? argv.emitSql;
+    const emitSql = typeof emitSqlRaw === 'string' && emitSqlRaw
+        ? (emitSqlRaw === STDOUT_TARGET ? STDOUT_TARGET : path.resolve(cwd, emitSqlRaw))
+        : undefined;
+    const emitBundleRaw = argv['emit-bundle'] ?? argv.emitBundle;
+    const emitBundle = typeof emitBundleRaw === 'string' && emitBundleRaw
+        ? path.resolve(cwd, emitBundleRaw)
+        : undefined;
+    const sqlToStdout = emitSql === STDOUT_TARGET;
+    const pkgName = argv.pkg || 'diff-migration';
+    await loadModule();
+    let sideA;
+    let sideB;
+    try {
+        sideA = await loadSide(specA, cwd);
+        sideB = await loadSide(specB, cwd);
+    }
+    catch (err) {
+        await cliExitWithError(err instanceof Error ? err.message : String(err));
+        return;
+    }
+    const result = diffChangeSets(sideA.changes, sideB.changes, { granularity, style: naming });
+    const warnings = [
+        ...sideA.warnings.map(w => `${sideA.label}: ${w}`),
+        ...sideB.warnings.map(w => `${sideB.label}: ${w}`),
+        ...result.warnings
+    ];
+    if (json) {
+        console.log(JSON.stringify({
+            identical: result.identical,
+            objects: result.objects,
+            changes: result.changes.map(c => ({
+                name: c.name,
+                dependencies: c.dependencies,
+                deploy: c.deploy,
+                revert: c.revert,
+                verify: c.verify
+            })),
+            warnings
+        }, null, 2));
+    }
+    else {
+        for (const warning of warnings)
+            console.warn(`diff: ${warning}`);
+        // Keep stdout clean when the SQL projection is piped there.
+        if (!sqlToStdout)
+            printSummary(result, sideA.label, sideB.label);
+    }
+    let migrationDir;
+    const needModule = Boolean(emitModuleDir || emitSql || emitBundle) || (verify && !result.identical);
+    if (needModule) {
+        const outBase = emitModuleDir ?? fs.mkdtempSync(path.join(os.tmpdir(), 'pgpm-diff-'));
+        const rows = deltaChangesToRows(result.changes);
+        if (rows.length === 0) {
+            if (!sqlToStdout)
+                log.info('no migration changes to emit (sides are identical).');
+        }
+        else {
+            migrationDir = writeModule(outBase, { name: pkgName, requires: [], rows });
+            if (emitModuleDir && !sqlToStdout)
+                log.success(`wrote ${rows.length} migration change(s) to ${migrationDir}`);
+            if (emitSql) {
+                await emitModuleSql(migrationDir, emitSql);
+                if (!sqlToStdout)
+                    log.success(`wrote linear SQL to ${emitSql}`);
+            }
+            if (emitBundle) {
+                await emitModuleBundle(migrationDir, emitBundle);
+                if (!sqlToStdout)
+                    log.success(`wrote bundle to ${emitBundle}`);
+            }
+        }
+    }
+    if (verify) {
+        log.info('running --verify: deploying A plus the migration and B into scratch databases...');
+        const diffs = await runVerify(sideA, sideB, specA, specB, migrationDir, cwd);
+        if (diffs.length) {
+            console.error(`--verify failed: catalogs differ (${diffs.length} differences):`);
+            for (const diff of diffs)
+                console.error(`  ${diff}`);
+            await cliExitWithError('Migrated catalog does not match the target.');
+        }
+        log.success('--verify passed: migrated catalog is structurally equivalent to the target.');
+    }
+    prompter.close();
+    return argv;
+};