pgpm 5.19.1 → 5.21.0

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,324 @@
+import { PgpmMigrate } from '@pgpmjs/core';
+import { deltaChangesToRows, loadDiffSideFromDisk, sqlToDiffChanges } from '@pgpmjs/diff';
+import { Logger } from '@pgpmjs/logger';
+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';
+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
+  --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
+                           .bundle.tar.gz archive
+  --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
+                           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 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();
+    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 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))
+        : 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';
+    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;
+    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, changeGranularity, 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);
+    }
+    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) {
+        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;
+};

package/esm/commands/dump.js

@@ -1,10 +1,10 @@
 import { Logger } from '@pgpmjs/logger';
-import { getPgEnvOptions, getSpawnEnvWithPg } from 'pg-env';
-import { getPgPool } from 'pg-cache';
+import { QuoteUtils } from '@pgsql/quotes';
 import { spawn } from 'child_process';
 import fs from 'fs';
 import path from 'path';
-import { QuoteUtils } from '@pgsql/quotes';
+import { getPgPool } from 'pg-cache';
+import { getPgEnvOptions, getSpawnEnvWithPg } from 'pg-env';
 import { getTargetDatabase } from '../utils';
 const log = new Logger('dump');
 const dumpUsageText = `

package/esm/commands/export.js

@@ -1,6 +1,7 @@
 import { PgpmPackage } from '@pgpmjs/core';
-import { exportMigrations, exportGraphQL, GraphQLClient, graphqlRowToPostgresRow, isExportGranularity, EXPORT_GRANULARITIES } from '@pgpmjs/export';
 import { getEnvOptions } from '@pgpmjs/env';
+import { exportGraphQL, exportMigrations, GraphQLClient, graphqlRowToPostgresRow } from '@pgpmjs/export';
+import { EXPORT_GRANULARITIES, isExportGranularity, parsePartitionConfig } from '@pgpmjs/transform';
 import { getGitConfigInfo } from '@pgpmjs/types';
 import { resolve } from 'path';
 import { getPgPool } from 'pg-cache';
@@ -28,12 +29,16 @@ Options:
                           Change paths are derived from the naming spec and
                           requires from the statement graph. When omitted,
                           sql_actions rows are exported unchanged.
+  --partition <file>      Partition config (JSON: rules/defaultPackage/splitRiders)
+                          splitting the exported database module into multiple
+                          pgpm packages with derived cross-package requires.
   --cwd <directory>       Working directory (default: current directory)
 
 Examples:
   pgpm export              Export migrations from selected database (SQL mode)
   pgpm export --exclude-categories security,permissions,auth,memberships
   pgpm export --granularity consolidated
+  pgpm export --granularity object --partition partition.json
   pgpm export --graphql-endpoint 'http://[::1]:3002/graphql' --migrate-endpoint 'http://[::1]:3000/graphql' --migrate-host db_migrate.localhost:3000
 `;
 export default async (argv, prompter, _options) => {
@@ -65,6 +70,18 @@ export default async (argv, prompter, _options) => {
         return;
     }
     const granularity = granularityRaw;
+    const partitionRaw = argv.partition;
+    let partition;
+    if (typeof partitionRaw === 'string' && partitionRaw) {
+        try {
+            partition = parsePartitionConfig(resolve(cwd, partitionRaw));
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            prompter.close();
+            return;
+        }
+    }
     if (graphqlEndpoint) {
         // =========================================================================
         // GraphQL export mode
@@ -162,7 +179,8 @@ export default async (argv, prompter, _options) => {
             argv,
             username,
             excludeCategories,
-            granularity
+            granularity,
+            partition
         });
     }
     else {
@@ -283,7 +301,8 @@ export default async (argv, prompter, _options) => {
             argv,
             username,
             excludeCategories,
-            granularity
+            granularity,
+            partition
         });
     }
     prompter.close();

package/esm/commands/import.js

@@ -0,0 +1,200 @@
+import { dumpCompatibilityWarnings, importDumpRows, linkTextualDeps, loadDumpSource } from '@pgpmjs/import';
+import { Logger } from '@pgpmjs/logger';
+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:
+
+  pgpm import <dump.sql | dir-of-sql-files> --pkg <module-name> [OPTIONS]
+
+  pgpm-itize an arbitrary SQL dump (e.g. pg_dump --schema-only output): parse
+  it, classify every statement, and emit a complete deployable pgpm module —
+  module dir, pgpm.plan, and deploy/revert/verify trees with spec-derived
+  change paths, graph-derived requires, and generated revert/verify scripts.
+
+  Directory inputs concatenate their .sql files in sorted (lexicographic)
+  filename order.
+
+  Dump handling:
+  - pg_dump preamble noise (SET ..., SELECT set_config(...), psql backslash
+    commands) is skipped; COMMENT ON and GRANT statements are kept, attached
+    to their host object's change.
+  - CREATE EXTENSION statements become .control requires (pgpm owns
+    extension creation at deploy time).
+  - COPY ... FROM stdin blocks and INSERTs are skipped with a warning unless
+    --with-data is passed, which emits them as seed fixture changes (COPY
+    data is converted to INSERTs).
+  - Statements that classify to no object land in a misc/statements change
+    with a warning — never dropped silently.
+
+Options:
+  --help, -h              Show this help message
+  --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>
+  --with-data             Import COPY/INSERT data as seed fixture changes
+  --partition <file>      Partition config (JSON: rules/defaultPackage/splitRiders)
+                          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) => {
+    if (argv.help || argv.h) {
+        console.log(importUsageText);
+        process.exit(0);
+    }
+    const cwd = argv.cwd || process.cwd();
+    const input = argv._?.filter(Boolean)[0];
+    if (!input) {
+        await cliExitWithError('Missing input: pgpm import <dump.sql | dir-of-sql-files> --pkg <name>');
+    }
+    const pkgName = argv.pkg;
+    if (!pkgName || typeof pkgName !== 'string') {
+        await cliExitWithError('--pkg <module-name> is required.');
+    }
+    const granularityRaw = argv.granularity ?? 'object';
+    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;
+    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 outBase = typeof argv.out === 'string' && argv.out ? path.resolve(cwd, argv.out) : path.resolve(cwd);
+    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));
+    }
+    catch (err) {
+        await cliExitWithError(err instanceof Error ? err.message : String(err));
+        return;
+    }
+    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, changeGranularity, naming, withData });
+    let packages;
+    if (partition) {
+        try {
+            const partitioned = await partitionExportRows(result.rows, partition);
+            result.warnings.push(...partitioned.warnings.map(w => `partition: ${w}`));
+            packages = partitioned.packages.map(pkg => ({
+                name: pkg.name,
+                requires: [...result.controlRequires, ...pkg.requires],
+                rows: linkTextualDeps(pkg.rows)
+            }));
+        }
+        catch (err) {
+            if (err instanceof PartitionCycleError) {
+                await cliExitWithError(`Partition failed: ${err.message}`);
+                return;
+            }
+            throw err;
+        }
+    }
+    else {
+        packages = [{ name: pkgName, requires: result.controlRequires, rows: result.rows }];
+    }
+    for (const warning of result.warnings) {
+        console.warn(`import: ${warning}`);
+    }
+    if (dryRun) {
+        for (const pkg of packages) {
+            console.log(`package ${pkg.name} -> ${path.join(outBase, pkg.name)}`);
+            if (pkg.requires.length) {
+                console.log(`  requires: ${pkg.requires.join(', ')}`);
+            }
+            for (const row of pkg.rows) {
+                const deps = row.deps?.length ? ` [${row.deps.join(' ')}]` : '';
+                console.log(`  ${row.deploy}${deps}`);
+            }
+        }
+    }
+    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);
+            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;
+    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/init/boilerplate.js

@@ -1,6 +1,6 @@
+import { DEFAULT_TEMPLATE_REPO, PgpmPackage, TEMPLATE_REPOS } from '@pgpmjs/core';
 import fs from 'fs';
 import path from 'path';
-import { DEFAULT_TEMPLATE_REPO, PgpmPackage, TEMPLATE_REPOS } from '@pgpmjs/core';
 /**
  * Resolve the template repo for an `init` invocation from its flags.
  *