pgpm 5.20.0 → 5.21.0

package/commands/diff.js

@@ -74,6 +74,10 @@ Options:
                            verify per change, spec-derived paths, graph-derived
                            requires) into <dir>/<pkg>
   --emit-module <dir>      Alias of --emit-migration
+  --append-module <dir>    Append the delta into an EXISTING pgpm module at
+                           <dir> (new changes only; existing changes, scripts,
+                           and .control are left untouched). Standalone: not
+                           combinable with --emit-*/--verify.
   --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
@@ -81,6 +85,9 @@ Options:
   --pkg <name>             Emitted migration package name (default: diff-migration)
   --granularity <level>    Granularity for emitted changes: atomic | object |
                            consolidated (default: object)
+  --change-granularity <level>
+                           Change-level distribution for emitted changes:
+                           alteration | object | single (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
@@ -224,6 +231,11 @@ exports.default = async (argv, prompter, _options) => {
         await (0, inquirerer_1.cliExitWithError)(`Invalid --granularity "${granularityRaw}". Expected one of: ${transform_1.EXPORT_GRANULARITIES.join(', ')}.`);
     }
     const granularity = granularityRaw;
+    const changeGranularityRaw = argv['change-granularity'] ?? argv.changeGranularity ?? 'object';
+    if (!(0, transform_1.isChangeGranularity)(changeGranularityRaw)) {
+        await (0, inquirerer_1.cliExitWithError)(`Invalid --change-granularity "${changeGranularityRaw}". Expected one of: ${transform_1.CHANGE_GRANULARITIES.join(', ')}.`);
+    }
+    const changeGranularity = changeGranularityRaw;
     const namingRaw = argv.naming ?? 'directory';
     if (!NAMING_STYLES.includes(namingRaw)) {
         await (0, inquirerer_1.cliExitWithError)(`Invalid --naming "${namingRaw}". Expected one of: ${NAMING_STYLES.join(', ')}.`);
@@ -236,6 +248,10 @@ exports.default = async (argv, prompter, _options) => {
     const emitModuleDir = typeof emitModuleRaw === 'string' && emitModuleRaw
         ? path.resolve(cwd, emitModuleRaw)
         : undefined;
+    const appendModuleRaw = argv['append-module'] ?? argv.appendModule;
+    const appendModuleDir = typeof appendModuleRaw === 'string' && appendModuleRaw
+        ? path.resolve(cwd, appendModuleRaw)
+        : undefined;
     const emitSqlRaw = argv['emit-sql'] ?? argv.emitSql;
     const emitSql = typeof emitSqlRaw === 'string' && emitSqlRaw
         ? (emitSqlRaw === module_projections_1.STDOUT_TARGET ? module_projections_1.STDOUT_TARGET : path.resolve(cwd, emitSqlRaw))
@@ -246,6 +262,9 @@ exports.default = async (argv, prompter, _options) => {
         : undefined;
     const sqlToStdout = emitSql === module_projections_1.STDOUT_TARGET;
     const pkgName = argv.pkg || 'diff-migration';
+    if (appendModuleDir && (emitModuleDir || emitSql || emitBundle || verify)) {
+        await (0, inquirerer_1.cliExitWithError)('--append-module is standalone; it cannot be combined with --emit-migration/--emit-module/--emit-sql/--emit-bundle/--verify.');
+    }
     await (0, transform_1.loadModule)();
     let sideA;
     let sideB;
@@ -257,7 +276,7 @@ exports.default = async (argv, prompter, _options) => {
         await (0, inquirerer_1.cliExitWithError)(err instanceof Error ? err.message : String(err));
         return;
     }
-    const result = (0, transform_1.diffChangeSets)(sideA.changes, sideB.changes, { granularity, style: naming });
+    const result = (0, transform_1.diffChangeSets)(sideA.changes, sideB.changes, { granularity, changeGranularity, style: naming });
     const warnings = [
         ...sideA.warnings.map(w => `${sideA.label}: ${w}`),
         ...sideB.warnings.map(w => `${sideB.label}: ${w}`),
@@ -284,6 +303,21 @@ exports.default = async (argv, prompter, _options) => {
         if (!sqlToStdout)
             printSummary(result, sideA.label, sideB.label);
     }
+    if (appendModuleDir) {
+        const rows = (0, diff_1.deltaChangesToRows)(result.changes);
+        if (rows.length === 0) {
+            log.info('no migration changes to append (sides are identical).');
+        }
+        else {
+            const appended = (0, transform_1.appendModule)(appendModuleDir, rows);
+            for (const w of appended.warnings)
+                console.warn(`diff: ${w}`);
+            log.success(`appended ${appended.added.length} change(s) to ${appended.dir}` +
+                (appended.skipped.length ? ` (${appended.skipped.length} skipped)` : ''));
+        }
+        prompter.close();
+        return argv;
+    }
     let migrationDir;
     const needModule = Boolean(emitModuleDir || emitSql || emitBundle) || (verify && !result.identical);
     if (needModule) {

package/commands/import.js

@@ -39,6 +39,7 @@ const transform_1 = require("@pgpmjs/transform");
 const inquirerer_1 = require("inquirerer");
 const path = __importStar(require("path"));
 const emit_package_1 = require("../utils/emit-package");
+const module_projections_1 = require("../utils/module-projections");
 const log = new logger_1.Logger('import');
 const importUsageText = `
 Import Command:
@@ -70,6 +71,9 @@ Options:
   --pkg <name>            Module name for the generated package (required)
   --granularity <level>   Granularity dial: atomic | object | consolidated
                           (default: object)
+  --change-granularity <level>
+                          Change-level distribution: alteration | object | single
+                          (default: object)
   --naming <style>        Change path naming style: directory | flat (default: directory)
   --out <dir>             Output base directory (default: current directory);
                           the module is written to <out>/<pkg>
@@ -78,14 +82,24 @@ Options:
                           splitting the import into multiple pgpm packages with
                           derived cross-package requires
   --write                 Allow overwriting an existing module directory
+  --emit-sql <file|->      Also project the imported module into a single linear
+                          SQL script (- for stdout). Requires a single output
+                          package (not supported with --partition).
+  --emit-bundle <file>     Also project the imported module into a
+                          content-addressed .bundle.tar.gz. Same single-package
+                          requirement as --emit-sql.
   --cwd <directory>       Working directory (default: current directory)
   --dry-run               Print the resulting plan/paths without writing
 
+The imported 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 import dump.sql --pkg my-app
   pgpm import dump.sql --pkg my-app --granularity consolidated --naming flat
   pgpm import ./sql-files --pkg my-app --out ./packages --with-data
   pgpm import dump.sql --pkg my-app --partition partition.json
+  pgpm import dump.sql --pkg my-app --emit-sql my-app.sql
 `;
 const NAMING_STYLES = ['directory', 'flat'];
 exports.default = async (argv, prompter, _options) => {
@@ -107,6 +121,11 @@ exports.default = async (argv, prompter, _options) => {
         await (0, inquirerer_1.cliExitWithError)(`Invalid --granularity "${granularityRaw}". Expected one of: ${transform_1.EXPORT_GRANULARITIES.join(', ')}.`);
     }
     const granularity = granularityRaw;
+    const changeGranularityRaw = argv['change-granularity'] ?? argv.changeGranularity ?? 'object';
+    if (!(0, transform_1.isChangeGranularity)(changeGranularityRaw)) {
+        await (0, inquirerer_1.cliExitWithError)(`Invalid --change-granularity "${changeGranularityRaw}". Expected one of: ${transform_1.CHANGE_GRANULARITIES.join(', ')}.`);
+    }
+    const changeGranularity = changeGranularityRaw;
     const namingRaw = argv.naming ?? 'directory';
     if (!NAMING_STYLES.includes(namingRaw)) {
         await (0, inquirerer_1.cliExitWithError)(`Invalid --naming "${namingRaw}". Expected one of: ${NAMING_STYLES.join(', ')}.`);
@@ -125,6 +144,12 @@ exports.default = async (argv, prompter, _options) => {
     const withData = Boolean(argv['with-data'] ?? argv.withData);
     const write = Boolean(argv.write);
     const dryRun = Boolean(argv['dry-run'] ?? argv.dryRun);
+    const emit = (0, module_projections_1.parseEmitProjectionTargets)(argv, cwd);
+    const emitRequested = (0, module_projections_1.hasEmitProjection)(emit);
+    const sqlToStdout = emit.emitSql === module_projections_1.STDOUT_TARGET;
+    if (emitRequested && dryRun) {
+        await (0, inquirerer_1.cliExitWithError)('--emit-sql/--emit-bundle cannot be combined with --dry-run.');
+    }
     let source;
     try {
         source = (0, import_1.loadDumpSource)(path.resolve(cwd, input));
@@ -133,13 +158,13 @@ exports.default = async (argv, prompter, _options) => {
         await (0, inquirerer_1.cliExitWithError)(err instanceof Error ? err.message : String(err));
         return;
     }
-    if (source.files.length > 1) {
+    if (source.files.length > 1 && !sqlToStdout) {
         log.info(`concatenated ${source.files.length} .sql files in sorted order`);
     }
     for (const warning of (0, import_1.dumpCompatibilityWarnings)(source)) {
         console.warn(`\nWARNING: ${warning}\n`);
     }
-    const result = await (0, import_1.importDumpRows)(source, { granularity, naming, withData });
+    const result = await (0, import_1.importDumpRows)(source, { granularity, changeGranularity, naming, withData });
     let packages;
     if (partition) {
         try {
@@ -178,21 +203,33 @@ exports.default = async (argv, prompter, _options) => {
         }
     }
     else {
+        if (emitRequested && packages.length !== 1) {
+            await (0, inquirerer_1.cliExitWithError)('--emit-sql/--emit-bundle require a single output package; a --partition import emits multiple packages.');
+        }
         for (const pkg of packages) {
             const guard = (0, emit_package_1.checkOverwrite)(path.join(outBase, pkg.name), source.files[0], write);
             if (guard) {
                 await (0, inquirerer_1.cliExitWithError)(guard);
             }
         }
+        let firstDir;
         for (const pkg of packages) {
             const dir = (0, emit_package_1.writePackage)(outBase, pkg);
-            log.success(`wrote ${pkg.rows.length} changes to ${dir}`);
+            firstDir ??= dir;
+            if (!sqlToStdout) {
+                log.success(`wrote ${pkg.rows.length} changes to ${dir}`);
+            }
+        }
+        if (emitRequested && firstDir) {
+            await (0, module_projections_1.projectModule)(firstDir, emit, sqlToStdout ? undefined : msg => log.success(msg));
         }
     }
     const { summary } = result;
-    log.success(`import: ${summary.statements} statement(s) -> ${summary.changes} change(s), ` +
-        `${summary.skippedPreamble} preamble skipped, ${summary.skippedData} data skipped, ` +
-        `${summary.misc} in misc, ${result.warnings.length} warning(s)`);
+    if (!sqlToStdout) {
+        log.success(`import: ${summary.statements} statement(s) -> ${summary.changes} change(s), ` +
+            `${summary.skippedPreamble} preamble skipped, ${summary.skippedData} data skipped, ` +
+            `${summary.misc} in misc, ${result.warnings.length} warning(s)`);
+    }
     prompter.close();
     return argv;
 };

package/commands/transform.js

@@ -42,6 +42,7 @@ 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 module_projections_1 = require("../utils/module-projections");
 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; } });
@@ -59,6 +60,12 @@ Transform Command:
 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.
@@ -66,14 +73,25 @@ Options:
   --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'];
 /**
@@ -141,7 +159,7 @@ const runCheck = async (transformed) => {
         return (0, scratch_db_1.catalogDifferences)(cfgOriginal, cfgTransformed);
     });
 };
-const transformModule = async (modulePath, granularity, naming, partition, out) => {
+const transformModule = async (modulePath, granularity, changeGranularity, naming, partition, out) => {
     const source = (0, transform_1.loadModuleSource)(modulePath);
     const warnings = [...source.warnings];
     const rows = source.changes.map(change => ({
@@ -150,7 +168,7 @@ const transformModule = async (modulePath, granularity, naming, partition, out)
         deps: change.dependencies,
         content: change.deploy
     }));
-    const restructured = await (0, transform_1.restructureExportRows)(rows, granularity, { naming });
+    const restructured = await (0, transform_1.restructureExportRows)(rows, granularity, { naming, changeGranularity });
     warnings.push(...restructured.warnings.map(w => `restructure (${granularity}): ${w}`));
     const outBase = (0, exports.resolveOutBase)(modulePath, out);
     let packages;
@@ -189,6 +207,11 @@ exports.default = async (argv, prompter, _options) => {
         await (0, inquirerer_1.cliExitWithError)(`Invalid --granularity "${granularityRaw}". Expected one of: ${transform_1.EXPORT_GRANULARITIES.join(', ')}.`);
     }
     const granularity = granularityRaw;
+    const changeGranularityRaw = argv['change-granularity'] ?? argv.changeGranularity ?? 'object';
+    if (!(0, transform_1.isChangeGranularity)(changeGranularityRaw)) {
+        await (0, inquirerer_1.cliExitWithError)(`Invalid --change-granularity "${changeGranularityRaw}". Expected one of: ${transform_1.CHANGE_GRANULARITIES.join(', ')}.`);
+    }
+    const changeGranularity = changeGranularityRaw;
     const namingRaw = argv.naming ?? 'directory';
     if (!NAMING_STYLES.includes(namingRaw)) {
         await (0, inquirerer_1.cliExitWithError)(`Invalid --naming "${namingRaw}". Expected one of: ${NAMING_STYLES.join(', ')}.`);
@@ -208,6 +231,9 @@ exports.default = async (argv, prompter, _options) => {
     const write = Boolean(argv.write);
     const check = Boolean(argv.check);
     const dryRun = Boolean(argv['dry-run'] ?? argv.dryRun);
+    const emit = (0, module_projections_1.parseEmitProjectionTargets)(argv, cwd);
+    const emitRequested = (0, module_projections_1.hasEmitProjection)(emit);
+    const sqlToStdout = emit.emitSql === module_projections_1.STDOUT_TARGET;
     const pkg = new core_1.PgpmPackage(path.resolve(cwd));
     let modulePaths;
     if (pkg.isInModule()) {
@@ -227,10 +253,16 @@ exports.default = async (argv, prompter, _options) => {
         await (0, inquirerer_1.cliExitWithError)('Not inside a pgpm module or workspace (pass --cwd <dir>).');
         return;
     }
+    if (emitRequested && modulePaths.length > 1) {
+        await (0, inquirerer_1.cliExitWithError)('--emit-sql/--emit-bundle target a single module; they are not supported when transforming a multi-module workspace.');
+    }
+    if (emitRequested && dryRun) {
+        await (0, inquirerer_1.cliExitWithError)('--emit-sql/--emit-bundle cannot be combined with --dry-run.');
+    }
     for (const modulePath of modulePaths) {
         let transformed;
         try {
-            transformed = await transformModule(modulePath, granularity, naming, partition, out);
+            transformed = await transformModule(modulePath, granularity, changeGranularity, naming, partition, out);
         }
         catch (err) {
             if (err instanceof transform_1.PartitionCycleError) {
@@ -253,10 +285,20 @@ exports.default = async (argv, prompter, _options) => {
                 await (0, inquirerer_1.cliExitWithError)(guard);
             }
         }
+        if (emitRequested && transformed.packages.length !== 1) {
+            await (0, inquirerer_1.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 = (0, emit_package_1.writePackage)(transformed.outBase, pkgRows, sourceRequires);
-            log.success(`wrote ${pkgRows.rows.length} changes to ${dir}`);
+            firstDir ??= dir;
+            if (!sqlToStdout) {
+                log.success(`wrote ${pkgRows.rows.length} changes to ${dir}`);
+            }
+        }
+        if (emitRequested && firstDir) {
+            await (0, module_projections_1.projectModule)(firstDir, emit, sqlToStdout ? undefined : msg => log.success(msg));
         }
         if (check) {
             log.info('running --check: deploying original and transformed output to scratch databases...');

package/esm/commands/diff.js

@@ -1,7 +1,7 @@
 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 { appendModule, CHANGE_GRANULARITIES, diffChangeSets, EXPORT_GRANULARITIES, isChangeGranularity, isExportGranularity, loadModule, withoutColumnOrder, writeModule } from '@pgpmjs/transform';
 import { spawn } from 'child_process';
 import * as fs from 'fs';
 import { cliExitWithError, extractFirst } from 'inquirerer';
@@ -39,6 +39,10 @@ Options:
                            verify per change, spec-derived paths, graph-derived
                            requires) into <dir>/<pkg>
   --emit-module <dir>      Alias of --emit-migration
+  --append-module <dir>    Append the delta into an EXISTING pgpm module at
+                           <dir> (new changes only; existing changes, scripts,
+                           and .control are left untouched). Standalone: not
+                           combinable with --emit-*/--verify.
   --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
@@ -46,6 +50,9 @@ Options:
   --pkg <name>             Emitted migration package name (default: diff-migration)
   --granularity <level>    Granularity for emitted changes: atomic | object |
                            consolidated (default: object)
+  --change-granularity <level>
+                           Change-level distribution for emitted changes:
+                           alteration | object | single (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
@@ -189,6 +196,11 @@ export default async (argv, prompter, _options) => {
         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(', ')}.`);
@@ -201,6 +213,10 @@ export default async (argv, prompter, _options) => {
     const emitModuleDir = typeof emitModuleRaw === 'string' && emitModuleRaw
         ? path.resolve(cwd, emitModuleRaw)
         : undefined;
+    const appendModuleRaw = argv['append-module'] ?? argv.appendModule;
+    const appendModuleDir = typeof appendModuleRaw === 'string' && appendModuleRaw
+        ? path.resolve(cwd, appendModuleRaw)
+        : undefined;
     const emitSqlRaw = argv['emit-sql'] ?? argv.emitSql;
     const emitSql = typeof emitSqlRaw === 'string' && emitSqlRaw
         ? (emitSqlRaw === STDOUT_TARGET ? STDOUT_TARGET : path.resolve(cwd, emitSqlRaw))
@@ -211,6 +227,9 @@ export default async (argv, prompter, _options) => {
         : undefined;
     const sqlToStdout = emitSql === STDOUT_TARGET;
     const pkgName = argv.pkg || 'diff-migration';
+    if (appendModuleDir && (emitModuleDir || emitSql || emitBundle || verify)) {
+        await cliExitWithError('--append-module is standalone; it cannot be combined with --emit-migration/--emit-module/--emit-sql/--emit-bundle/--verify.');
+    }
     await loadModule();
     let sideA;
     let sideB;
@@ -222,7 +241,7 @@ export default async (argv, prompter, _options) => {
         await cliExitWithError(err instanceof Error ? err.message : String(err));
         return;
     }
-    const result = diffChangeSets(sideA.changes, sideB.changes, { granularity, style: naming });
+    const result = diffChangeSets(sideA.changes, sideB.changes, { granularity, changeGranularity, style: naming });
     const warnings = [
         ...sideA.warnings.map(w => `${sideA.label}: ${w}`),
         ...sideB.warnings.map(w => `${sideB.label}: ${w}`),
@@ -249,6 +268,21 @@ export default async (argv, prompter, _options) => {
         if (!sqlToStdout)
             printSummary(result, sideA.label, sideB.label);
     }
+    if (appendModuleDir) {
+        const rows = deltaChangesToRows(result.changes);
+        if (rows.length === 0) {
+            log.info('no migration changes to append (sides are identical).');
+        }
+        else {
+            const appended = appendModule(appendModuleDir, rows);
+            for (const w of appended.warnings)
+                console.warn(`diff: ${w}`);
+            log.success(`appended ${appended.added.length} change(s) to ${appended.dir}` +
+                (appended.skipped.length ? ` (${appended.skipped.length} skipped)` : ''));
+        }
+        prompter.close();
+        return argv;
+    }
     let migrationDir;
     const needModule = Boolean(emitModuleDir || emitSql || emitBundle) || (verify && !result.identical);
     if (needModule) {

package/esm/commands/import.js

@@ -1,9 +1,10 @@
 import { dumpCompatibilityWarnings, importDumpRows, linkTextualDeps, loadDumpSource } from '@pgpmjs/import';
 import { Logger } from '@pgpmjs/logger';
-import { EXPORT_GRANULARITIES, isExportGranularity, parsePartitionConfig, PartitionCycleError, partitionExportRows } from '@pgpmjs/transform';
+import { CHANGE_GRANULARITIES, EXPORT_GRANULARITIES, isChangeGranularity, isExportGranularity, parsePartitionConfig, PartitionCycleError, partitionExportRows } from '@pgpmjs/transform';
 import { cliExitWithError } from 'inquirerer';
 import * as path from 'path';
 import { checkOverwrite, writePackage } from '../utils/emit-package';
+import { hasEmitProjection, parseEmitProjectionTargets, projectModule, STDOUT_TARGET } from '../utils/module-projections';
 const log = new Logger('import');
 const importUsageText = `
 Import Command:
@@ -35,6 +36,9 @@ Options:
   --pkg <name>            Module name for the generated package (required)
   --granularity <level>   Granularity dial: atomic | object | consolidated
                           (default: object)
+  --change-granularity <level>
+                          Change-level distribution: alteration | object | single
+                          (default: object)
   --naming <style>        Change path naming style: directory | flat (default: directory)
   --out <dir>             Output base directory (default: current directory);
                           the module is written to <out>/<pkg>
@@ -43,14 +47,24 @@ Options:
                           splitting the import into multiple pgpm packages with
                           derived cross-package requires
   --write                 Allow overwriting an existing module directory
+  --emit-sql <file|->      Also project the imported module into a single linear
+                          SQL script (- for stdout). Requires a single output
+                          package (not supported with --partition).
+  --emit-bundle <file>     Also project the imported module into a
+                          content-addressed .bundle.tar.gz. Same single-package
+                          requirement as --emit-sql.
   --cwd <directory>       Working directory (default: current directory)
   --dry-run               Print the resulting plan/paths without writing
 
+The imported 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 import dump.sql --pkg my-app
   pgpm import dump.sql --pkg my-app --granularity consolidated --naming flat
   pgpm import ./sql-files --pkg my-app --out ./packages --with-data
   pgpm import dump.sql --pkg my-app --partition partition.json
+  pgpm import dump.sql --pkg my-app --emit-sql my-app.sql
 `;
 const NAMING_STYLES = ['directory', 'flat'];
 export default async (argv, prompter, _options) => {
@@ -72,6 +86,11 @@ export default async (argv, prompter, _options) => {
         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(', ')}.`);
@@ -90,6 +109,12 @@ export default async (argv, prompter, _options) => {
     const withData = Boolean(argv['with-data'] ?? argv.withData);
     const write = Boolean(argv.write);
     const dryRun = Boolean(argv['dry-run'] ?? argv.dryRun);
+    const emit = parseEmitProjectionTargets(argv, cwd);
+    const emitRequested = hasEmitProjection(emit);
+    const sqlToStdout = emit.emitSql === STDOUT_TARGET;
+    if (emitRequested && dryRun) {
+        await cliExitWithError('--emit-sql/--emit-bundle cannot be combined with --dry-run.');
+    }
     let source;
     try {
         source = loadDumpSource(path.resolve(cwd, input));
@@ -98,13 +123,13 @@ export default async (argv, prompter, _options) => {
         await cliExitWithError(err instanceof Error ? err.message : String(err));
         return;
     }
-    if (source.files.length > 1) {
+    if (source.files.length > 1 && !sqlToStdout) {
         log.info(`concatenated ${source.files.length} .sql files in sorted order`);
     }
     for (const warning of dumpCompatibilityWarnings(source)) {
         console.warn(`\nWARNING: ${warning}\n`);
     }
-    const result = await importDumpRows(source, { granularity, naming, withData });
+    const result = await importDumpRows(source, { granularity, changeGranularity, naming, withData });
     let packages;
     if (partition) {
         try {
@@ -143,21 +168,33 @@ export default async (argv, prompter, _options) => {
         }
     }
     else {
+        if (emitRequested && packages.length !== 1) {
+            await cliExitWithError('--emit-sql/--emit-bundle require a single output package; a --partition import emits multiple packages.');
+        }
         for (const pkg of packages) {
             const guard = checkOverwrite(path.join(outBase, pkg.name), source.files[0], write);
             if (guard) {
                 await cliExitWithError(guard);
             }
         }
+        let firstDir;
         for (const pkg of packages) {
             const dir = writePackage(outBase, pkg);
-            log.success(`wrote ${pkg.rows.length} changes to ${dir}`);
+            firstDir ??= dir;
+            if (!sqlToStdout) {
+                log.success(`wrote ${pkg.rows.length} changes to ${dir}`);
+            }
+        }
+        if (emitRequested && firstDir) {
+            await projectModule(firstDir, emit, sqlToStdout ? undefined : msg => log.success(msg));
         }
     }
     const { summary } = result;
-    log.success(`import: ${summary.statements} statement(s) -> ${summary.changes} change(s), ` +
-        `${summary.skippedPreamble} preamble skipped, ${summary.skippedData} data skipped, ` +
-        `${summary.misc} in misc, ${result.warnings.length} warning(s)`);
+    if (!sqlToStdout) {
+        log.success(`import: ${summary.statements} statement(s) -> ${summary.changes} change(s), ` +
+            `${summary.skippedPreamble} preamble skipped, ${summary.skippedData} data skipped, ` +
+            `${summary.misc} in misc, ${result.warnings.length} warning(s)`);
+    }
     prompter.close();
     return argv;
 };

package/esm/commands/transform.js

@@ -1,11 +1,12 @@
 import { PgpmMigrate, PgpmPackage } from '@pgpmjs/core';
 import { Logger } from '@pgpmjs/logger';
-import { EXPORT_GRANULARITIES, isExportGranularity, loadModuleSource, parsePartitionConfig, PartitionCycleError, partitionExportRows, restructureExportRows } from '@pgpmjs/transform';
+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');
@@ -22,6 +23,12 @@ Transform Command:
 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.
@@ -29,14 +36,25 @@ Options:
   --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'];
 /**
@@ -102,7 +120,7 @@ const runCheck = async (transformed) => {
         return catalogDifferences(cfgOriginal, cfgTransformed);
     });
 };
-const transformModule = async (modulePath, granularity, naming, partition, out) => {
+const transformModule = async (modulePath, granularity, changeGranularity, naming, partition, out) => {
     const source = loadModuleSource(modulePath);
     const warnings = [...source.warnings];
     const rows = source.changes.map(change => ({
@@ -111,7 +129,7 @@ const transformModule = async (modulePath, granularity, naming, partition, out)
         deps: change.dependencies,
         content: change.deploy
     }));
-    const restructured = await restructureExportRows(rows, granularity, { naming });
+    const restructured = await restructureExportRows(rows, granularity, { naming, changeGranularity });
     warnings.push(...restructured.warnings.map(w => `restructure (${granularity}): ${w}`));
     const outBase = resolveOutBase(modulePath, out);
     let packages;
@@ -150,6 +168,11 @@ export default async (argv, prompter, _options) => {
         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(', ')}.`);
@@ -169,6 +192,9 @@ export default async (argv, prompter, _options) => {
     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()) {
@@ -188,10 +214,16 @@ export default async (argv, prompter, _options) => {
         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, naming, partition, out);
+            transformed = await transformModule(modulePath, granularity, changeGranularity, naming, partition, out);
         }
         catch (err) {
             if (err instanceof PartitionCycleError) {
@@ -214,10 +246,20 @@ export default async (argv, prompter, _options) => {
                 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);
-            log.success(`wrote ${pkgRows.rows.length} changes to ${dir}`);
+            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...');

package/esm/utils/module-projections.js

@@ -45,3 +45,38 @@ export const emitModuleBundle = async (moduleDir, 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

@@ -13,8 +13,8 @@
  * `PgpmMigrate` from `@pgpmjs/core`, and `core` already depends on `transform`
  * — hosting the oracle in `transform` would close that cycle.
  */
-import { diffCatalogSnapshots, snapshotCatalog } from '@pgpmjs/transform';
 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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgpm",
-  "version": "5.20.0",
+  "version": "5.21.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL Package Manager - Database migration and package management CLI",
   "main": "index.js",
@@ -46,14 +46,14 @@
   },
   "dependencies": {
     "@inquirerer/utils": "^3.3.9",
-    "@pgpmjs/core": "^7.21.3",
-    "@pgpmjs/diff": "^0.1.1",
+    "@pgpmjs/core": "^7.21.4",
+    "@pgpmjs/diff": "^0.1.2",
     "@pgpmjs/env": "^2.40.3",
-    "@pgpmjs/export": "^1.15.0",
-    "@pgpmjs/import": "^0.1.1",
+    "@pgpmjs/export": "^1.15.1",
+    "@pgpmjs/import": "^0.2.0",
     "@pgpmjs/logger": "^2.23.3",
-    "@pgpmjs/slice": "^0.13.8",
-    "@pgpmjs/transform": "^0.19.0",
+    "@pgpmjs/slice": "^0.13.9",
+    "@pgpmjs/transform": "^0.20.0",
     "@pgpmjs/types": "^2.49.3",
     "@pgsql/quotes": "^18.2.0",
     "appstash": "^0.7.0",
@@ -80,5 +80,5 @@
     "pg",
     "pgsql"
   ],
-  "gitHead": "c20b6be96b39bf71c0e2df0f4b51e05deacd006b"
+  "gitHead": "e6a7a57f88c9deb2a4acecaba2451320d1be8203"
 }

package/utils/module-projections.d.ts

@@ -13,3 +13,24 @@ export declare const emitModuleSql: (moduleDir: string, target: string) => Promi
  * stores beside the packaged SQL, but written to an arbitrary path.
  */
 export declare const emitModuleBundle: (moduleDir: string, target: string) => Promise<void>;
+/** Resolved `--emit-sql` / `--emit-bundle` projection targets for a command. */
+export interface EmitProjectionTargets {
+    /** Linear SQL target (absolute path, or `-` for stdout). */
+    emitSql?: string;
+    /** Bundle archive target (absolute path). */
+    emitBundle?: string;
+}
+/**
+ * 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 declare const parseEmitProjectionTargets: (argv: Record<string, unknown>, cwd: string) => EmitProjectionTargets;
+/** Whether any projection target was requested. */
+export declare const hasEmitProjection: (targets: EmitProjectionTargets) => boolean;
+/**
+ * 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 declare const projectModule: (moduleDir: string, targets: EmitProjectionTargets, onSuccess?: (message: string) => void) => Promise<void>;

package/utils/module-projections.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.emitModuleBundle = exports.emitModuleSql = exports.STDOUT_TARGET = void 0;
+exports.projectModule = exports.hasEmitProjection = exports.parseEmitProjectionTargets = exports.emitModuleBundle = exports.emitModuleSql = exports.STDOUT_TARGET = void 0;
 /**
  * Projections of an emitted pgpm module directory.
  *
@@ -83,3 +83,41 @@ const emitModuleBundle = async (moduleDir, target) => {
     (0, core_1.writeBundleArchiveFile)(bundle, resolved);
 };
 exports.emitModuleBundle = emitModuleBundle;
+/**
+ * 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.
+ */
+const parseEmitProjectionTargets = (argv, cwd) => {
+    const sqlRaw = argv['emit-sql'] ?? argv.emitSql;
+    const emitSql = typeof sqlRaw === 'string' && sqlRaw
+        ? sqlRaw === exports.STDOUT_TARGET
+            ? exports.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 };
+};
+exports.parseEmitProjectionTargets = parseEmitProjectionTargets;
+/** Whether any projection target was requested. */
+const hasEmitProjection = (targets) => Boolean(targets.emitSql || targets.emitBundle);
+exports.hasEmitProjection = hasEmitProjection;
+/**
+ * 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.
+ */
+const projectModule = async (moduleDir, targets, onSuccess) => {
+    if (targets.emitSql) {
+        await (0, exports.emitModuleSql)(moduleDir, targets.emitSql);
+        if (targets.emitSql !== exports.STDOUT_TARGET) {
+            onSuccess?.(`wrote linear SQL to ${targets.emitSql}`);
+        }
+    }
+    if (targets.emitBundle) {
+        await (0, exports.emitModuleBundle)(moduleDir, targets.emitBundle);
+        onSuccess?.(`wrote bundle to ${targets.emitBundle}`);
+    }
+};
+exports.projectModule = projectModule;

package/utils/scratch-db.d.ts

@@ -1,18 +1,3 @@
-/**
- * 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 { CatalogSnapshot } from '@pgpmjs/transform';
 import type { PgConfig } from 'pg-env';
 /**

package/utils/scratch-db.js

@@ -16,8 +16,8 @@ exports.catalogDifferences = exports.withScratchDatabases = void 0;
  * `PgpmMigrate` from `@pgpmjs/core`, and `core` already depends on `transform`
  * — hosting the oracle in `transform` would close that cycle.
  */
-const transform_1 = require("@pgpmjs/transform");
 const logger_1 = require("@pgpmjs/logger");
+const transform_1 = require("@pgpmjs/transform");
 const pg_cache_1 = require("pg-cache");
 const log = new logger_1.Logger('scratch-db');
 const createScratchDb = async (config, dbName) => {