pgpm 5.19.1 → 5.21.0

package/esm/commands/init/index.js

@@ -1,10 +1,10 @@
-import { execSync } from 'child_process';
-import fs from 'fs';
-import path from 'path';
 import { DEFAULT_TEMPLATE_REPO, DEFAULT_TEMPLATE_TOOL_NAME, inspectTemplate, PgpmPackage, resolveBoilerplateBaseDir, scaffoldTemplate, scanBoilerplates, SkillInstaller, sluggify, } from '@pgpmjs/core';
 import { resolveWorkspaceByType } from '@pgpmjs/env';
 import { errors } from '@pgpmjs/types';
+import { execSync } from 'child_process';
+import fs from 'fs';
 import { registerDefaultResolver } from 'inquirerer';
+import path from 'path';
 import { isNoTtyRequested } from '../../utils';
 import { persistBoilerplateSource, readBoilerplateSource, resolveInitTemplateRepo, } from './boilerplate';
 const DEFAULT_MOTD = `

package/esm/commands/package.js

@@ -116,7 +116,6 @@ export default async (argv, prompter, _options) => {
     const project = new PgpmPackage(cwd);
     project.ensureModule();
     const info = project.getModuleInfo();
-    info.version;
     await writePackage({
         version: info.version,
         extension: true,

package/esm/commands/slice.js

@@ -1,8 +1,8 @@
 import { PgpmPackage } from '@pgpmjs/core';
 import { generateDryRunReport, slicePlan, writeSliceResult } from '@pgpmjs/slice';
 import { getGitConfigInfo } from '@pgpmjs/types';
+import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
-import { readFileSync, existsSync } from 'fs';
 const sliceUsageText = `
 Slice Command:
 

package/esm/commands/test-packages.js

@@ -2,8 +2,8 @@ import { PgpmPackage } from '@pgpmjs/core';
 import { getEnvOptions } from '@pgpmjs/env';
 import { Logger } from '@pgpmjs/logger';
 import path from 'path';
-import { getPgEnvOptions } from 'pg-env';
 import { getPgPool } from 'pg-cache';
+import { getPgEnvOptions } from 'pg-env';
 const log = new Logger('test-packages');
 // ANSI color codes
 const RED = '\x1b[0;31m';

package/esm/commands/transform.js

@@ -0,0 +1,278 @@
+import { PgpmMigrate, PgpmPackage } from '@pgpmjs/core';
+import { Logger } from '@pgpmjs/logger';
+import { CHANGE_GRANULARITIES, EXPORT_GRANULARITIES, isChangeGranularity, isExportGranularity, loadModuleSource, parsePartitionConfig, PartitionCycleError, partitionExportRows, restructureExportRows } from '@pgpmjs/transform';
+import * as fs from 'fs';
+import { cliExitWithError } from 'inquirerer';
+import * as path from 'path';
+import { getPgEnvOptions } from 'pg-env';
+import { checkOverwrite, writePackage } from '../utils/emit-package';
+import { hasEmitProjection, parseEmitProjectionTargets, projectModule, STDOUT_TARGET } from '../utils/module-projections';
+import { catalogDifferences, withScratchDatabases } from '../utils/scratch-db';
+export { checkOverwrite } from '../utils/emit-package';
+const log = new 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)
+  --change-granularity <level>
+                          Change-level distribution: alteration | object | single
+                          (default: object). With alteration, every ADD COLUMN /
+                          ADD CONSTRAINT becomes its own change with its own
+                          deploy/revert/verify and requires. With single, the
+                          whole module becomes one change.
+  --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
+  --emit-sql <file|->      Also project the transformed module into a single
+                          linear SQL script (- for stdout). Requires a single
+                          output package (no workspace/partition fan-out).
+  --emit-bundle <file>     Also project the transformed module into a
+                          content-addressed .bundle.tar.gz. Same single-package
+                          requirement as --emit-sql.
+  --check                 Deploy original and transformed output into scratch
+                          databases and assert the catalogs are equivalent
+  --dry-run               Print the resulting plan/paths without writing
+
+The transformed module is the canonical artifact; --emit-sql and --emit-bundle
+are pure projections of it (the same machinery pgpm package and pgpm diff use).
+
+Examples:
+  pgpm transform --granularity object
+  pgpm transform --granularity atomic --naming flat --out ./out
+  pgpm transform --granularity object --partition partition.json --check
+  pgpm transform --granularity consolidated --emit-sql migration.sql
+  pgpm transform --granularity atomic --change-granularity alteration
+`;
+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`.
+ */
+export const resolveOutBase = (modulePath, out) => {
+    if (out)
+        return path.resolve(out);
+    return path.dirname(modulePath);
+};
+/** Order partition packages so prerequisites come before dependents. */
+export 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;
+};
+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 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 = getPgEnvOptions();
+    const stamp = Date.now();
+    const names = [`pgpm_transform_check_a_${stamp}`, `pgpm_transform_check_b_${stamp}`];
+    return withScratchDatabases(config, names, async ([cfgOriginal, cfgTransformed]) => {
+        await deployModules(cfgOriginal, [transformed.modulePath]);
+        const orderedDirs = orderPackages(transformed.packages).map(pkg => path.join(transformed.outBase, pkg.name));
+        await deployModules(cfgTransformed, orderedDirs);
+        return catalogDifferences(cfgOriginal, cfgTransformed);
+    });
+};
+const transformModule = async (modulePath, granularity, changeGranularity, naming, partition, out) => {
+    const source = 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 restructureExportRows(rows, granularity, { naming, changeGranularity });
+    warnings.push(...restructured.warnings.map(w => `restructure (${granularity}): ${w}`));
+    const outBase = resolveOutBase(modulePath, out);
+    let packages;
+    if (partition) {
+        const result = await 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}`);
+        }
+    }
+};
+export default async (argv, prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(transformUsageText);
+        process.exit(0);
+    }
+    const granularityRaw = argv.granularity;
+    if (granularityRaw === undefined) {
+        await cliExitWithError(`--granularity is required. Expected one of: ${EXPORT_GRANULARITIES.join(', ')}.`);
+    }
+    if (!isExportGranularity(granularityRaw)) {
+        await cliExitWithError(`Invalid --granularity "${granularityRaw}". Expected one of: ${EXPORT_GRANULARITIES.join(', ')}.`);
+    }
+    const granularity = granularityRaw;
+    const changeGranularityRaw = argv['change-granularity'] ?? argv.changeGranularity ?? 'object';
+    if (!isChangeGranularity(changeGranularityRaw)) {
+        await cliExitWithError(`Invalid --change-granularity "${changeGranularityRaw}". Expected one of: ${CHANGE_GRANULARITIES.join(', ')}.`);
+    }
+    const changeGranularity = changeGranularityRaw;
+    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();
+    let partition;
+    if (typeof argv.partition === 'string' && argv.partition) {
+        try {
+            partition = parsePartitionConfig(path.resolve(cwd, argv.partition));
+        }
+        catch (err) {
+            await 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 emit = parseEmitProjectionTargets(argv, cwd);
+    const emitRequested = hasEmitProjection(emit);
+    const sqlToStdout = emit.emitSql === STDOUT_TARGET;
+    const pkg = new 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 cliExitWithError('No modules found in workspace.');
+        }
+        if (out && modulePaths.length > 1) {
+            await cliExitWithError('--out is not supported when transforming a multi-module workspace.');
+        }
+    }
+    else {
+        await cliExitWithError('Not inside a pgpm module or workspace (pass --cwd <dir>).');
+        return;
+    }
+    if (emitRequested && modulePaths.length > 1) {
+        await cliExitWithError('--emit-sql/--emit-bundle target a single module; they are not supported when transforming a multi-module workspace.');
+    }
+    if (emitRequested && dryRun) {
+        await cliExitWithError('--emit-sql/--emit-bundle cannot be combined with --dry-run.');
+    }
+    for (const modulePath of modulePaths) {
+        let transformed;
+        try {
+            transformed = await transformModule(modulePath, granularity, changeGranularity, naming, partition, out);
+        }
+        catch (err) {
+            if (err instanceof PartitionCycleError) {
+                await 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 = checkOverwrite(targetDir, modulePath, write);
+            if (guard) {
+                await cliExitWithError(guard);
+            }
+        }
+        if (emitRequested && transformed.packages.length !== 1) {
+            await cliExitWithError('--emit-sql/--emit-bundle require a single output package; a --partition transform emits multiple packages.');
+        }
+        const sourceRequires = readControlRequires(modulePath, transformed.name);
+        let firstDir;
+        for (const pkgRows of transformed.packages) {
+            const dir = writePackage(transformed.outBase, pkgRows, sourceRequires);
+            firstDir ??= dir;
+            if (!sqlToStdout) {
+                log.success(`wrote ${pkgRows.rows.length} changes to ${dir}`);
+            }
+        }
+        if (emitRequested && firstDir) {
+            await projectModule(firstDir, emit, sqlToStdout ? undefined : msg => log.success(msg));
+        }
+        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 cliExitWithError('Transform is not structurally lossless.');
+            }
+            log.success('--check passed: catalogs are structurally equivalent.');
+        }
+    }
+    prompter.close();
+    return argv;
+};

package/esm/commands/update.js

@@ -1,7 +1,7 @@
 import { suppressUpdateCheck } from '@inquirerer/utils';
 import { Logger } from '@pgpmjs/logger';
-import { cliExitWithError, getPackageJson } from 'inquirerer';
 import { spawn } from 'child_process';
+import { cliExitWithError, getPackageJson } from 'inquirerer';
 import { fetchLatestVersion } from '../utils/npm-version';
 const log = new Logger('update');
 const updateUsageText = `

package/esm/commands.js

@@ -7,12 +7,14 @@ import analyze from './commands/analyze';
 import cache from './commands/cache';
 import clear from './commands/clear';
 import deploy from './commands/deploy';
+import diff from './commands/diff';
 import docker from './commands/docker';
 import doctor from './commands/doctor';
 import dump from './commands/dump';
 import env from './commands/env';
 import _export from './commands/export';
 import extension from './commands/extension';
+import _import from './commands/import';
 import init from './commands/init';
 import install from './commands/install';
 import kill from './commands/kill';
@@ -28,6 +30,7 @@ import slice from './commands/slice';
 import syncVersions from './commands/sync-versions';
 import tag from './commands/tag';
 import testPackages from './commands/test-packages';
+import transform from './commands/transform';
 import tune from './commands/tune';
 import updateCmd from './commands/update';
 import upgrade from './commands/upgrade';
@@ -47,6 +50,7 @@ const ENGINE_EXEMPT_COMMANDS = new Set([
     'doctor',
     'env',
     'extension',
+    'import',
     'init',
     'install',
     'package',
@@ -79,6 +83,7 @@ export const createPgpmCommandMap = (skipPgTeardown = false) => {
         'admin-users': pgt(adminUsers),
         clear: pgt(clear),
         deploy: pgt(deploy),
+        diff: pgt(diff),
         docker,
         doctor,
         dump: pgt(dump),
@@ -91,6 +96,7 @@ export const createPgpmCommandMap = (skipPgTeardown = false) => {
         plan: pgt(plan),
         regen,
         export: pgt(_export),
+        import: pgt(_import),
         package: pgt(_package),
         tag: pgt(tag),
         kill: pgt(kill),
@@ -102,6 +108,7 @@ export const createPgpmCommandMap = (skipPgTeardown = false) => {
         slice,
         'sync-versions': syncVersions,
         'test-packages': pgt(testPackages),
+        transform: pgt(transform),
         tune: pgt(tune),
         upgrade: pgt(upgrade),
         up: pgt(upgrade),

package/esm/utils/display.js

@@ -12,6 +12,9 @@ export const usageText = `
     extension          Manage module dependencies
     plan               Generate module deployment plans
     regen              Generate revert/verify scripts from deploy scripts
+    transform          Re-dial a module through the dials pipeline (granularity/naming/partition)
+    import             pgpm-itize an arbitrary SQL dump into a deployable module
+    diff               Identity-keyed semantic diff between two schema sources (+ migration generation)
     package            Package module for distribution
     materialize        Transpile an apply proxy into a plain, committed module
     sync-versions      Sync .control/Makefile/sql metadata to package.json versions

package/esm/utils/driver.js

@@ -1,6 +1,6 @@
-import { PGPM_DRIVER_EXPORT, } from '@pgpmjs/types';
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
+import { PGPM_DRIVER_EXPORT, } from '@pgpmjs/types';
 /** Package name of the built-in PGlite driver plugin (the `--pglite` alias). */
 export const PGLITE_DRIVER_PLUGIN = '@pgpmjs/pglite-adapter';
 /**

package/esm/utils/emit-package.js

@@ -0,0 +1 @@
+export { checkOverwrite, writeControlFile, writeModule as writePackage } from '@pgpmjs/transform';

package/esm/utils/engine.js

@@ -1,6 +1,6 @@
+import { resolve } from 'node:path';
 import { getEnvOptions } from '@pgpmjs/env';
 import { BUILTIN_ENGINES, DEFAULT_ENGINE, } from '@pgpmjs/types';
-import { resolve } from 'node:path';
 import { activateDriver, driverOverrideFromArgv, PGLITE_DRIVER_PLUGIN } from './driver';
 /** Everything a real Postgres server can do — the built-in `pg` engine. */
 export const SERVER_CAPABILITIES = {

package/esm/utils/module-projections.js

@@ -0,0 +1,82 @@
+/**
+ * Projections of an emitted pgpm module directory.
+ *
+ * A module directory is the canonical artifact the dials pipeline produces
+ * (`writeModule` from `@pgpmjs/transform`). "Linear SQL" and "bundle" are not
+ * separate emitters — they are pure projections of that one module, produced
+ * by the same battle-tested machinery `pgpm package` uses:
+ *
+ *   - {@link emitModuleSql}    -> consolidated single-file SQL (`packageModule`)
+ *   - {@link emitModuleBundle} -> content-addressed bundle (`buildExecutableBundle`)
+ *
+ * They live in the CLI (not `@pgpmjs/transform`) because they reuse packaging
+ * and bundle code from `@pgpmjs/core`, and `core` already depends on
+ * `transform`.
+ */
+import { buildExecutableBundle, packageModule, writeBundleArchiveFile } from '@pgpmjs/core';
+import * as fs from 'fs';
+import * as path from 'path';
+/** Sentinel meaning "write to stdout" for a file-valued emit target. */
+export const STDOUT_TARGET = '-';
+/**
+ * Consolidate an emitted module directory into a single linear SQL script.
+ * Statements are resolved in plan order and deparsed once (comments and
+ * per-change file boundaries collapse away). When `target` is `-` the SQL is
+ * written to stdout; otherwise it is written to the given file path.
+ */
+export const emitModuleSql = async (moduleDir, target) => {
+    const { sql } = await packageModule(moduleDir, { extension: false, usePlan: true, pretty: true });
+    if (target === STDOUT_TARGET) {
+        process.stdout.write(sql.endsWith('\n') ? sql : sql + '\n');
+        return;
+    }
+    const resolved = path.resolve(target);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, sql.endsWith('\n') ? sql : sql + '\n');
+};
+/**
+ * Project an emitted module directory into a content-addressed bundle archive
+ * (`.bundle.tar.gz`) at `target` — the same executable bundle `pgpm package`
+ * stores beside the packaged SQL, but written to an arbitrary path.
+ */
+export const emitModuleBundle = async (moduleDir, target) => {
+    const bundle = await buildExecutableBundle(moduleDir, { createdWith: '@pgpmjs/cli' });
+    const resolved = path.resolve(target);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    writeBundleArchiveFile(bundle, resolved);
+};
+/**
+ * Parse the shared `--emit-sql` / `--emit-bundle` projection flags off a parsed
+ * argv, resolving file targets against `cwd` (the `-` stdout sentinel for SQL is
+ * preserved). Keeps every command's projection flags identical.
+ */
+export const parseEmitProjectionTargets = (argv, cwd) => {
+    const sqlRaw = argv['emit-sql'] ?? argv.emitSql;
+    const emitSql = typeof sqlRaw === 'string' && sqlRaw
+        ? sqlRaw === STDOUT_TARGET
+            ? STDOUT_TARGET
+            : path.resolve(cwd, sqlRaw)
+        : undefined;
+    const bundleRaw = argv['emit-bundle'] ?? argv.emitBundle;
+    const emitBundle = typeof bundleRaw === 'string' && bundleRaw ? path.resolve(cwd, bundleRaw) : undefined;
+    return { emitSql, emitBundle };
+};
+/** Whether any projection target was requested. */
+export const hasEmitProjection = (targets) => Boolean(targets.emitSql || targets.emitBundle);
+/**
+ * Run the requested SQL/bundle projections against a written module directory.
+ * `onSuccess` (when provided) is invoked with a human-readable line per emitted
+ * artifact; it is skipped for stdout SQL so the stream stays valid SQL.
+ */
+export const projectModule = async (moduleDir, targets, onSuccess) => {
+    if (targets.emitSql) {
+        await emitModuleSql(moduleDir, targets.emitSql);
+        if (targets.emitSql !== STDOUT_TARGET) {
+            onSuccess?.(`wrote linear SQL to ${targets.emitSql}`);
+        }
+    }
+    if (targets.emitBundle) {
+        await emitModuleBundle(moduleDir, targets.emitBundle);
+        onSuccess?.(`wrote bundle to ${targets.emitBundle}`);
+    }
+};

package/esm/utils/scratch-db.js

@@ -0,0 +1,61 @@
+/**
+ * Scratch-database catalog oracle shared by the dials commands that prove
+ * structural equivalence (`pgpm transform --check`, `pgpm diff --verify`).
+ *
+ * Both commands do the same dance: create throwaway databases, deploy a
+ * schema into each, snapshot the catalogs, and diff them — always dropping the
+ * scratch databases afterwards even on failure. This centralizes the lifecycle
+ * (`withScratchDatabases`) and the snapshot/compare step (`catalogDifferences`)
+ * so each command only supplies what is genuinely command-specific: how it
+ * deploys a side.
+ *
+ * It lives in the CLI (not `@pgpmjs/transform`) because deploying touches
+ * `PgpmMigrate` from `@pgpmjs/core`, and `core` already depends on `transform`
+ * — hosting the oracle in `transform` would close that cycle.
+ */
+import { Logger } from '@pgpmjs/logger';
+import { diffCatalogSnapshots, snapshotCatalog } from '@pgpmjs/transform';
+import { getPgPool } from 'pg-cache';
+const log = new Logger('scratch-db');
+const createScratchDb = async (config, dbName) => {
+    const adminPool = getPgPool({ ...config, database: 'postgres' });
+    await adminPool.query(`DROP DATABASE IF EXISTS "${dbName}"`);
+    await adminPool.query(`CREATE DATABASE "${dbName}"`);
+};
+const dropScratchDb = async (config, dbName) => {
+    const adminPool = getPgPool({ ...config, database: 'postgres' });
+    await adminPool.query(`DROP DATABASE IF EXISTS "${dbName}" WITH (FORCE)`);
+};
+/**
+ * Create the named scratch databases, run `fn` with a per-database `PgConfig`
+ * for each (in the same order as `names`), and drop them all afterwards —
+ * even if `fn` throws. Drop failures are logged, never thrown, so they can't
+ * mask the original error.
+ */
+export const withScratchDatabases = async (config, names, fn) => {
+    try {
+        for (const name of names)
+            await createScratchDb(config, name);
+        return await fn(names.map(name => ({ ...config, database: name })));
+    }
+    finally {
+        try {
+            for (const name of names)
+                await dropScratchDb(config, name);
+        }
+        catch (err) {
+            log.warn(`failed to drop scratch databases: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+};
+/**
+ * Snapshot the catalogs of two databases and return their differences. An
+ * optional `normalize` transform is applied to both snapshots first (e.g.
+ * `withoutColumnOrder` when a drop+add migration cannot reproduce a fresh
+ * deploy's physical column ordinals). Empty result means equivalent.
+ */
+export const catalogDifferences = async (configA, configB, normalize = snap => snap) => {
+    const snapA = await snapshotCatalog(getPgPool(configA));
+    const snapB = await snapshotCatalog(getPgPool(configB));
+    return diffCatalogSnapshots(normalize(snapA), normalize(snapB));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgpm",
-  "version": "5.19.1",
+  "version": "5.21.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL Package Manager - Database migration and package management CLI",
   "main": "index.js",
@@ -46,22 +46,24 @@
   },
   "dependencies": {
     "@inquirerer/utils": "^3.3.9",
-    "@pgpmjs/core": "^7.21.2",
-    "@pgpmjs/env": "^2.40.2",
-    "@pgpmjs/export": "^1.14.2",
-    "@pgpmjs/logger": "^2.23.2",
-    "@pgpmjs/slice": "^0.13.7",
-    "@pgpmjs/transform": "^0.18.0",
-    "@pgpmjs/types": "^2.49.2",
-    "@pgsql/quotes": "^18.1.0",
+    "@pgpmjs/core": "^7.21.4",
+    "@pgpmjs/diff": "^0.1.2",
+    "@pgpmjs/env": "^2.40.3",
+    "@pgpmjs/export": "^1.15.1",
+    "@pgpmjs/import": "^0.2.0",
+    "@pgpmjs/logger": "^2.23.3",
+    "@pgpmjs/slice": "^0.13.9",
+    "@pgpmjs/transform": "^0.20.0",
+    "@pgpmjs/types": "^2.49.3",
+    "@pgsql/quotes": "^18.2.0",
     "appstash": "^0.7.0",
     "find-and-require-package-json": "^0.9.1",
     "genomic": "^5.6.2",
     "inquirerer": "^4.9.1",
     "js-yaml": "^4.1.0",
-    "pg-cache": "^3.24.2",
+    "pg-cache": "^3.24.3",
     "pg-env": "^1.27.2",
-    "pgsql-deparser": "^18.2.0",
+    "pgsql-deparser": "^18.3.1",
     "semver": "^7.8.1",
     "shelljs": "^0.10.0",
     "yanse": "^0.2.1"
@@ -78,5 +80,5 @@
     "pg",
     "pgsql"
   ],
-  "gitHead": "6d3e25dc5c9f93421dba49ddedf93239f87213a8"
+  "gitHead": "e6a7a57f88c9deb2a4acecaba2451320d1be8203"
 }

package/utils/display.d.ts

@@ -1 +1 @@
-export declare const usageText = "\n  Usage: pgpm <command> [options]\n\n  Core Database Operations:\n    add                Add database changes to plans and create SQL files\n    deploy             Deploy database changes and migrations\n    verify             Verify database state and migrations\n    revert             Revert database changes and migrations\n\n  Project Management:\n    init               Initialize workspace or module\n    extension          Manage module dependencies\n    plan               Generate module deployment plans\n    regen              Generate revert/verify scripts from deploy scripts\n    package            Package module for distribution\n    materialize        Transpile an apply proxy into a plain, committed module\n    sync-versions      Sync .control/Makefile/sql metadata to package.json versions\n    export             Export database migrations from existing databases\n    update             Update pgpm to the latest version\n    cache              Manage cached templates (clean)\n    upgrade            Upgrade installed pgpm modules to latest versions (alias: up)\n\n  Database Administration:\n    dump               Dump a database to a sql file\n    kill               Terminate database connections and optionally drop databases\n    install            Install database modules\n    tag                Add tags to changes for versioning\n    clear              Clear database state\n    remove             Remove database changes\n    analyze            Analyze database structure\n    rename             Rename database changes\n    admin-users        Manage admin users\n    tune               Tune PostgreSQL for throwaway environments (CI/test)\n\n  Testing:\n    test-packages      Run integration tests on all workspace packages\n\n  Migration Tools:\n    migrate            Migration management subcommands\n      init             Initialize migration tracking\n      status           Show migration status\n      list             List all changes\n      deps             Show change dependencies\n  \n  Development Tools:\n    docker             Manage Docker containers (start/stop/ls, --minio)\n    doctor             Check local dependencies (node, docker, psql) with install guidance\n    env                Manage environment variables (--supabase, --minio)\n    test-packages      Run integration tests on workspace packages\n  \n  Global Options:\n    -h, --help         Display this help information\n    -v, --version      Display version information\n    --cwd <directory>  Working directory (default: current directory)\n    --engine <name>    Migration backend: pg (default, Postgres server) or\n                       pglite (in-process WASM Postgres, no server). Also set by\n                       the \"engine\" key of pgpm.json or PGPM_ENGINE.\n    --driver <pkg>     Driver plugin package backing the engine (escape hatch)\n    --pglite[=dataDir] Sugar for --engine pglite, persisted to <dataDir> if given\n\n  Individual Command Help:\n    pgpm <command> --help    Display detailed help for specific command\n    pgpm <command> -h        Display detailed help for specific command\n\n  Examples:\n    pgpm deploy --help       Show deploy command options\n    pgpm init workspace      Initialize new workspace\n    pgpm install @pgpm/base32  Install a database module\n  ";
+export declare const usageText = "\n  Usage: pgpm <command> [options]\n\n  Core Database Operations:\n    add                Add database changes to plans and create SQL files\n    deploy             Deploy database changes and migrations\n    verify             Verify database state and migrations\n    revert             Revert database changes and migrations\n\n  Project Management:\n    init               Initialize workspace or module\n    extension          Manage module dependencies\n    plan               Generate module deployment plans\n    regen              Generate revert/verify scripts from deploy scripts\n    transform          Re-dial a module through the dials pipeline (granularity/naming/partition)\n    import             pgpm-itize an arbitrary SQL dump into a deployable module\n    diff               Identity-keyed semantic diff between two schema sources (+ migration generation)\n    package            Package module for distribution\n    materialize        Transpile an apply proxy into a plain, committed module\n    sync-versions      Sync .control/Makefile/sql metadata to package.json versions\n    export             Export database migrations from existing databases\n    update             Update pgpm to the latest version\n    cache              Manage cached templates (clean)\n    upgrade            Upgrade installed pgpm modules to latest versions (alias: up)\n\n  Database Administration:\n    dump               Dump a database to a sql file\n    kill               Terminate database connections and optionally drop databases\n    install            Install database modules\n    tag                Add tags to changes for versioning\n    clear              Clear database state\n    remove             Remove database changes\n    analyze            Analyze database structure\n    rename             Rename database changes\n    admin-users        Manage admin users\n    tune               Tune PostgreSQL for throwaway environments (CI/test)\n\n  Testing:\n    test-packages      Run integration tests on all workspace packages\n\n  Migration Tools:\n    migrate            Migration management subcommands\n      init             Initialize migration tracking\n      status           Show migration status\n      list             List all changes\n      deps             Show change dependencies\n  \n  Development Tools:\n    docker             Manage Docker containers (start/stop/ls, --minio)\n    doctor             Check local dependencies (node, docker, psql) with install guidance\n    env                Manage environment variables (--supabase, --minio)\n    test-packages      Run integration tests on workspace packages\n  \n  Global Options:\n    -h, --help         Display this help information\n    -v, --version      Display version information\n    --cwd <directory>  Working directory (default: current directory)\n    --engine <name>    Migration backend: pg (default, Postgres server) or\n                       pglite (in-process WASM Postgres, no server). Also set by\n                       the \"engine\" key of pgpm.json or PGPM_ENGINE.\n    --driver <pkg>     Driver plugin package backing the engine (escape hatch)\n    --pglite[=dataDir] Sugar for --engine pglite, persisted to <dataDir> if given\n\n  Individual Command Help:\n    pgpm <command> --help    Display detailed help for specific command\n    pgpm <command> -h        Display detailed help for specific command\n\n  Examples:\n    pgpm deploy --help       Show deploy command options\n    pgpm init workspace      Initialize new workspace\n    pgpm install @pgpm/base32  Install a database module\n  ";

package/utils/display.js

@@ -15,6 +15,9 @@ exports.usageText = `
     extension          Manage module dependencies
     plan               Generate module deployment plans
     regen              Generate revert/verify scripts from deploy scripts
+    transform          Re-dial a module through the dials pipeline (granularity/naming/partition)
+    import             pgpm-itize an arbitrary SQL dump into a deployable module
+    diff               Identity-keyed semantic diff between two schema sources (+ migration generation)
     package            Package module for distribution
     materialize        Transpile an apply proxy into a plain, committed module
     sync-versions      Sync .control/Makefile/sql metadata to package.json versions

package/utils/driver.js

@@ -4,9 +4,9 @@ exports.PGLITE_DRIVER_PLUGIN = void 0;
 exports.resolveDriverConfig = resolveDriverConfig;
 exports.driverOverrideFromArgv = driverOverrideFromArgv;
 exports.activateDriver = activateDriver;
-const types_1 = require("@pgpmjs/types");
 const node_module_1 = require("node:module");
 const node_path_1 = require("node:path");
+const types_1 = require("@pgpmjs/types");
 /** Package name of the built-in PGlite driver plugin (the `--pglite` alias). */
 exports.PGLITE_DRIVER_PLUGIN = '@pgpmjs/pglite-adapter';
 /**