@pgpmjs/core 7.0.0 → 7.2.0

package/rebundle/types.d.ts

@@ -0,0 +1,185 @@
+import { Change } from '@pgpmjs/ast/files/types';
+import { SliceWarning } from '../slice/types';
+/**
+ * Strategy for rebundling a module's changes into fewer, larger chunks.
+ *
+ * Rebundling walks the source plan in order and greedily accumulates
+ * consecutive changes into a chunk until a boundary is hit. Because chunks
+ * are contiguous runs of the source plan, the concatenated deploy/verify/
+ * revert output is byte-identical to the original module — the granularity
+ * dial never reorders statements, it only decides where the chunk seams fall.
+ */
+export interface RebundleStrategy {
+    /**
+     * How chunk boundaries are chosen:
+     * - 'folder' (default): start a new chunk when the folder-derived key
+     *   changes (uses the same path extraction as slice's folder strategy)
+     * - 'none': one chunk for the whole module, subject only to `maxChunkSize`
+     * - 'category': start a new chunk when the caller-supplied `categoryOf` key
+     *   changes — the facts/classifier-driven seam. Lets the seams follow meaning
+     *   (e.g. security, roles, admin) instead of paths. `categoryOf` is required;
+     *   for changes it returns `undefined` for, the folder key is used as a
+     *   fallback so partial classification degrades gracefully.
+     */
+    boundary?: 'folder' | 'none' | 'category';
+    /**
+     * Seam key for a change under `boundary: 'category'`. Consecutive changes
+     * sharing a key merge into one chunk (same greedy, contiguity-preserving rule
+     * as the folder boundary — so the byte-identical invariant is unaffected).
+     * pgpm-core stays classifier-agnostic: callers derive the category however
+     * they like (e.g. from `classifyStatements` facts) and pass it in here.
+     */
+    categoryOf?: (changeName: string) => string | undefined;
+    /** Depth in the change path used to derive the folder key (default: 1) */
+    depth?: number;
+    /** Path prefix stripped before deriving the folder key (default: 'schemas') */
+    prefixToStrip?: string;
+    /**
+     * Maximum number of member changes per chunk. When reached, the current
+     * chunk is sealed and a new one begins even if the boundary key is unchanged.
+     * Undefined or 0 means unlimited.
+     */
+    maxChunkSize?: number;
+}
+/**
+ * A single rebundled chunk: a contiguous run of source-plan changes that will
+ * be merged into one migration. Member ordering is preserved in all three
+ * directions the pgpm engine cares about.
+ */
+export interface Chunk {
+    /** Deterministic chunk identifier */
+    name: string;
+    /** Member change names in deploy order (== source plan order) */
+    deploy: string[];
+    /** Member change names in verify order (same as deploy) */
+    verify: string[];
+    /** Member change names in revert order (reverse of deploy) */
+    revert: string[];
+    /** Other chunk names this chunk depends on (always earlier in deployOrder) */
+    dependencies: string[];
+}
+/**
+ * Result of computing a rebundle plan for a module.
+ */
+export interface RebundleResult {
+    /** Chunks in deploy order */
+    chunks: Chunk[];
+    /** Chunk names in deploy order */
+    deployOrder: string[];
+    /** Warnings encountered while rebundling */
+    warnings: SliceWarning[];
+    /** The source changes (in plan order) that were rebundled */
+    sourceChanges: Change[];
+    /** The source module's project name (from the plan `%project` header) */
+    project: string;
+}
+/**
+ * Options for materializing a rebundled module to disk.
+ */
+export interface RebundleModuleOptions extends RebundleStrategy {
+    /** Directory to write the rebundled module into */
+    outputDir: string;
+    /** Overwrite an existing, non-empty output directory (default: false) */
+    overwrite?: boolean;
+    /** Deparse pretty-printing (default: true) */
+    pretty?: boolean;
+    /** Function body delimiter used during deparse (default: '$EOFCODE$') */
+    functionDelimiter?: string;
+}
+/**
+ * How cross-chunk dependencies are represented when chunks are emitted as
+ * separate modules in a workspace.
+ *
+ * - `change`: also record the fine-grained plan cross-reference (`dep:dep`) in
+ *   addition to the control `requires`.
+ * - `control-only`: carry the dependency solely via the control-file `requires`,
+ *   dropping the per-change plan reference. Extension install ordering deploys
+ *   all of the dependency before any of the dependent, which is strictly
+ *   stronger than the fine edge — the right mode for publishing chunks as
+ *   independent, versioned module forks.
+ */
+export type CrossChunkDepMode = 'change' | 'control-only';
+/**
+ * Options for materializing a rebundled workspace (one module per chunk).
+ */
+export interface RebundleWorkspaceOptions extends RebundleStrategy {
+    /** Directory to write the workspace into (packages land in `packages/<chunk>/`) */
+    outputDir: string;
+    /** Overwrite an existing, non-empty output directory (default: false) */
+    overwrite?: boolean;
+    /** Deparse pretty-printing (default: true) */
+    pretty?: boolean;
+    /** Function body delimiter used during deparse (default: '$EOFCODE$') */
+    functionDelimiter?: string;
+    /** How cross-chunk deps are represented (default: 'control-only') */
+    crossChunkDepMode?: CrossChunkDepMode;
+    /**
+     * When `true`, scaffold each emitted module (and the workspace root) from the
+     * real `pgpm init` boilerplate template (`scaffoldTemplate`) before writing
+     * the merged pgpm files on top — so the output carries the full developer
+     * shell (README/LICENSE/jest/tests, workspace `pnpm-workspace.yaml`/`lerna.json`
+     * /tsconfig/lint/CI) rather than the minimal deployable set.
+     *
+     * Defaults to `false` (the lightweight, network-free minimal writer). Setting
+     * it `true` fetches the boilerplate repo (network), matching `pgpm init`.
+     */
+    initScaffold?: boolean;
+    /** Template repo for `initScaffold` (defaults to the pgpm boilerplates repo) */
+    templateRepo?: string;
+    /** Branch/tag for the `initScaffold` template repo */
+    templateBranch?: string;
+    /**
+     * License for the emitted module package.json (and the `pgpm init` answers
+     * when `initScaffold` is set). Defaults to 'CONSTRUCTIVE'.
+     */
+    license?: string;
+}
+/**
+ * A single emitted chunk-module within a rebundled workspace.
+ */
+export interface RebundlePackage {
+    /** Chunk/module name (also the extension name) */
+    name: string;
+    /** Package directory, relative to the workspace outputDir */
+    dir: string;
+    /** Names of other chunk-modules this one depends on */
+    dependencies: string[];
+}
+/**
+ * Result of materializing a rebundled workspace.
+ */
+export interface RebundleWorkspaceResult extends RebundleResult {
+    /** Directory the workspace was written to */
+    outputDir: string;
+    /** The emitted chunk-modules, in deploy order */
+    packages: RebundlePackage[];
+    /** The dep representation used */
+    crossChunkDepMode: CrossChunkDepMode;
+    /**
+     * Byte-identical gate: the merged concatenation of all package deploy scripts
+     * (in workspace deploy order) equals the merged original module deploy output.
+     */
+    invariant: {
+        ok: boolean;
+    };
+}
+/**
+ * Result of materializing a rebundled module.
+ */
+export interface RebundleModuleResult extends RebundleResult {
+    /** Directory the rebundled module was written to */
+    outputDir: string;
+    /** Per-chunk merged file paths, relative to outputDir */
+    written: {
+        chunk: string;
+        deploy: string;
+        revert: string;
+        verify: string;
+    }[];
+    /** Byte-identical gate result: packageModule(source) === packageModule(output) */
+    invariant: {
+        ok: boolean;
+        sourceDiff: boolean;
+        outputDiff: boolean;
+    };
+}

package/rebundle/workspace.d.ts

@@ -0,0 +1,15 @@
+import { RebundleWorkspaceOptions, RebundleWorkspaceResult } from './types';
+/**
+ * Materialize a rebundled workspace: emit each chunk as its own tiny module
+ * (one merged change) under `packages/<chunk>/`, carrying cross-chunk deps via
+ * the control-file `requires` (and optionally a plan cross-reference).
+ *
+ * This is the "modular workspace" carve — the same monolith sliced into
+ * independently publishable module forks (e.g. a users module, an admin module).
+ * The emitted directory is a real, discoverable pgpm workspace: it reuses
+ * `writeMinimalWorkspace`/`writeMinimalModule` (the minimal deployable file set
+ * pgpm recognizes — `pgpm.json`, `pgpm.plan`, `<name>.control`, `Makefile`,
+ * `package.json`), `rebundlePlan` for the chunk model, and `mergeChunkScript`
+ * for the per-chunk merge.
+ */
+export declare function rebundleWorkspace(sourceDir: string, options: RebundleWorkspaceOptions): Promise<RebundleWorkspaceResult>;

package/rebundle/workspace.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rebundleWorkspace = rebundleWorkspace;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const template_scaffold_1 = require("../core/template-scaffold");
+const parser_1 = require("@pgpmjs/ast/files/plan/parser");
+const package_1 = require("../packaging/package");
+const resolve_1 = require("../resolution/resolve");
+const minimal_1 = require("../workspace/minimal");
+const module_1 = require("./module");
+const rebundle_1 = require("./rebundle");
+/**
+ * Materialize a rebundled workspace: emit each chunk as its own tiny module
+ * (one merged change) under `packages/<chunk>/`, carrying cross-chunk deps via
+ * the control-file `requires` (and optionally a plan cross-reference).
+ *
+ * This is the "modular workspace" carve — the same monolith sliced into
+ * independently publishable module forks (e.g. a users module, an admin module).
+ * The emitted directory is a real, discoverable pgpm workspace: it reuses
+ * `writeMinimalWorkspace`/`writeMinimalModule` (the minimal deployable file set
+ * pgpm recognizes — `pgpm.json`, `pgpm.plan`, `<name>.control`, `Makefile`,
+ * `package.json`), `rebundlePlan` for the chunk model, and `mergeChunkScript`
+ * for the per-chunk merge.
+ */
+async function rebundleWorkspace(sourceDir, options) {
+    const { outputDir, overwrite = false, pretty = true, functionDelimiter = '$EOFCODE$', crossChunkDepMode = 'control-only', initScaffold = false, templateRepo = template_scaffold_1.DEFAULT_TEMPLATE_REPO, templateBranch, license = 'CONSTRUCTIVE', ...strategy } = options;
+    if ((0, fs_1.existsSync)(outputDir) && (0, fs_1.readdirSync)(outputDir).length > 0 && !overwrite) {
+        throw new Error(`Output directory is not empty: ${outputDir}. Pass overwrite: true to replace.`);
+    }
+    const plan = (0, rebundle_1.rebundlePlan)(sourceDir, strategy);
+    // Remap tags onto their sealing chunk (each tag anchored a chunk boundary).
+    const parsed = (0, parser_1.parsePlanFile)((0, path_1.join)(sourceDir, 'pgpm.plan'));
+    const sourceTags = parsed.data?.tags ?? [];
+    const memberToChunk = new Map();
+    for (const chunk of plan.chunks) {
+        for (const member of chunk.deploy)
+            memberToChunk.set(member, chunk.name);
+    }
+    const remappedTags = sourceTags.map(tag => ({
+        ...tag,
+        change: memberToChunk.get(tag.change) ?? tag.change,
+    }));
+    if (initScaffold) {
+        // Lay down the full `pgpm init` workspace shell (pgpm.json, pnpm-workspace,
+        // lerna.json, tsconfig, lint/format configs, CI); the merged pgpm files are
+        // written on top per module below.
+        await (0, template_scaffold_1.scaffoldTemplate)({
+            fromPath: 'workspace',
+            outputDir,
+            templateRepo,
+            branch: templateBranch,
+            answers: workspaceAnswers(outputDir, license),
+            noTty: true,
+        });
+    }
+    else {
+        (0, minimal_1.writeMinimalWorkspace)(outputDir, { packages: ['packages/*'] });
+    }
+    const byDeployOrder = [...plan.chunks].sort((a, b) => plan.deployOrder.indexOf(a.name) - plan.deployOrder.indexOf(b.name));
+    const packages = [];
+    for (const chunk of byDeployOrder) {
+        const pkgRel = (0, path_1.join)('packages', chunk.name);
+        const pkgDir = (0, path_1.join)(outputDir, pkgRel);
+        if (initScaffold) {
+            // Scaffold the module's developer shell (package.json, jest.config.js,
+            // README, LICENSE, __tests__); writeMinimalModule overwrites the pgpm
+            // files (pgpm.plan, .control, Makefile, deploy/revert/verify) below.
+            await (0, template_scaffold_1.scaffoldTemplate)({
+                fromPath: 'module',
+                outputDir: pkgDir,
+                templateRepo,
+                branch: templateBranch,
+                answers: moduleAnswers(chunk.name, license),
+                noTty: true,
+            });
+        }
+        const scripts = {
+            [chunk.name]: {
+                deploy: await (0, module_1.mergeChunkScript)(sourceDir, chunk, 'deploy', { pretty, functionDelimiter }),
+                revert: await (0, module_1.mergeChunkScript)(sourceDir, chunk, 'revert', { pretty, functionDelimiter }),
+                verify: await (0, module_1.mergeChunkScript)(sourceDir, chunk, 'verify', { pretty, functionDelimiter }),
+            },
+        };
+        // Control `requires` always carries the module-level dependency; in
+        // 'change' mode the plan additionally records the fine-grained cross-ref.
+        const deps = chunk.dependencies;
+        const planChange = {
+            name: chunk.name,
+            dependencies: planChangeDeps(deps, crossChunkDepMode),
+        };
+        (0, minimal_1.writeMinimalModule)(pkgDir, {
+            name: chunk.name,
+            changes: [planChange],
+            scripts,
+            tags: remappedTags.filter(t => t.change === chunk.name),
+            requires: deps,
+            license,
+            overwrite: true,
+            // When scaffolded, keep the boilerplate's richer package.json.
+            writePackageJson: !initScaffold,
+        });
+        packages.push({ name: chunk.name, dir: pkgRel, dependencies: [...deps] });
+    }
+    const invariant = { ok: await checkWorkspaceInvariant(sourceDir, outputDir, packages, { pretty, functionDelimiter }) };
+    return { ...plan, outputDir, packages, crossChunkDepMode, invariant };
+}
+/**
+ * In 'change' mode, express each cross-chunk dep as a plan cross-reference
+ * (`<dep>:<dep>`, since each chunk-module has a single change named after it);
+ * in 'control-only' mode the plan carries no deps — the control `requires`
+ * governs ordering.
+ */
+function planChangeDeps(deps, mode) {
+    if (mode === 'control-only')
+        return [];
+    return deps.map(dep => `${dep}:${dep}`);
+}
+/**
+ * Non-interactive answers for the `pgpm init` workspace template. Values are
+ * deterministic placeholders (the generated pgpm files are the real payload);
+ * the workspace name derives from the output directory.
+ */
+function workspaceAnswers(outputDir, license) {
+    const name = (0, path_1.basename)(outputDir) || 'rebundled-workspace';
+    return {
+        name,
+        fullName: 'Constructive',
+        email: 'noreply@constructive.io',
+        moduleName: name,
+        username: 'constructive-io',
+        repoName: name,
+        license,
+    };
+}
+/** Non-interactive answers for the `pgpm init` module template. */
+function moduleAnswers(name, license) {
+    return {
+        name,
+        moduleName: name,
+        moduleDesc: `${name} module`,
+        description: `${name} module`,
+        repoName: name,
+        fullName: 'Constructive',
+        email: 'noreply@constructive.io',
+        username: 'constructive-io',
+        access: 'public',
+        license,
+    };
+}
+/**
+ * Byte-identical gate for a workspace: concatenate every package's deploy
+ * script in workspace deploy order, merge it, and compare against the merged
+ * original module deploy output. Both go through the same `mergeSqlStatements`
+ * pipeline, so equality proves the carve preserved the deployed statements and
+ * their order.
+ */
+async function checkWorkspaceInvariant(sourceDir, outputDir, packages, opts) {
+    const concatenated = packages
+        .map(p => (0, fs_1.readFileSync)((0, path_1.join)(outputDir, p.dir, 'deploy', `${p.name}.sql`), 'utf-8'))
+        .join('\n');
+    const workspaceMerged = await (0, package_1.mergeSqlStatements)(concatenated, {
+        stripTransactions: true,
+        pretty: opts.pretty,
+        functionDelimiter: opts.functionDelimiter,
+    });
+    const sourceMerged = await (0, package_1.mergeSqlStatements)((0, resolve_1.resolveWithPlan)(sourceDir, 'deploy'), {
+        stripTransactions: true,
+        pretty: opts.pretty,
+        functionDelimiter: opts.functionDelimiter,
+    });
+    return workspaceMerged.sql === sourceMerged.sql;
+}

package/refactor/rename.d.ts

@@ -1,3 +1,5 @@
+import { renameInPlanContent } from '@pgpmjs/ast/plan-rename';
+export { renameInPlanContent };
 /**
  * Options for {@link renameChanges}.
  */
@@ -29,14 +31,6 @@ export interface RenameChangesResult {
  * @throws on any violation.
  */
 export declare function validateRenames(moduleDir: string, renames: Map<string, string>): void;
-/**
- * Rewrite change names in a pgpm.plan's content according to a rename map.
- * Textual and format-preserving: only the change-name token at the start of a
- * change line, plain (same-package) dependency refs inside `[...]`, and tag
- * lines' change field are rewritten; timestamps, planners, comments,
- * cross-package refs, and tag refs are untouched.
- */
-export declare function renameInPlanContent(content: string, renames: Map<string, string>): string;
 /**
  * Atomically rename/move changes within a pgpm module: the coupled 4-way
  * rewrite of (1) deploy/revert/verify script files on disk, (2) the moved

package/refactor/rename.js

@@ -1,13 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.renameInPlanContent = void 0;
 exports.validateRenames = validateRenames;
-exports.renameInPlanContent = renameInPlanContent;
 exports.renameChanges = renameChanges;
 exports.deriveRenamesFromSchemaMapping = deriveRenamesFromSchemaMapping;
 const fs_1 = require("fs");
 const path_1 = require("path");
-const parser_1 = require("../files/plan/parser");
-const header_1 = require("../files/sql/header");
+const parser_1 = require("@pgpmjs/ast/files/plan/parser");
+const header_1 = require("@pgpmjs/ast/files/sql/header");
+const plan_rename_1 = require("@pgpmjs/ast/plan-rename");
+Object.defineProperty(exports, "renameInPlanContent", { enumerable: true, get: function () { return plan_rename_1.renameInPlanContent; } });
 const SCRIPT_DIRS = ['deploy', 'revert', 'verify'];
 function escapeRe(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -65,31 +67,6 @@ function validateRenames(moduleDir, renames) {
         targets.add(to);
     }
 }
-/**
- * Rewrite change names in a pgpm.plan's content according to a rename map.
- * Textual and format-preserving: only the change-name token at the start of a
- * change line, plain (same-package) dependency refs inside `[...]`, and tag
- * lines' change field are rewritten; timestamps, planners, comments,
- * cross-package refs, and tag refs are untouched.
- */
-function renameInPlanContent(content, renames) {
-    const froms = Array.from(renames.keys()).sort((a, b) => b.length - a.length);
-    return content
-        .split('\n')
-        .map(line => {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('%'))
-            return line;
-        let result = line;
-        for (const from of froms) {
-            const to = renames.get(from);
-            const re = new RegExp(`(^|[\\s\\[])${escapeRe(from)}(?=$|[\\s\\]@])`, 'g');
-            result = result.replace(re, `$1${to}`);
-        }
-        return result;
-    })
-        .join('\n');
-}
 /**
  * Atomically rename/move changes within a pgpm module: the coupled 4-way
  * rewrite of (1) deploy/revert/verify script files on disk, (2) the moved
@@ -163,7 +140,7 @@ function renameChanges(moduleDir, renames, options = {}) {
     // 4. Rewrite pgpm.plan
     const planPath = (0, path_1.join)(moduleDir, 'pgpm.plan');
     const planContent = (0, fs_1.readFileSync)(planPath, 'utf-8');
-    const newPlanContent = renameInPlanContent(planContent, renames);
+    const newPlanContent = (0, plan_rename_1.renameInPlanContent)(planContent, renames);
     if (newPlanContent !== planContent) {
         if (dryRun) {
             result.dryRunReport.push('Would rewrite: pgpm.plan');

package/resolution/deps.d.ts

@@ -1,4 +1,4 @@
-import { ExtendedPlanFile } from '../files/types';
+import { ExtendedPlanFile } from '@pgpmjs/ast/files/types';
 /**
  * Represents a dependency graph where keys are module identifiers
  * and values are arrays of their direct dependencies

package/resolution/deps.js

@@ -5,8 +5,8 @@ const fs_1 = require("fs");
 const glob_1 = require("glob");
 const path_1 = require("path");
 const pgpm_1 = require("../core/class/pgpm");
-const parser_1 = require("../files/plan/parser");
-const header_1 = require("../files/sql/header");
+const parser_1 = require("@pgpmjs/ast/files/plan/parser");
+const header_1 = require("@pgpmjs/ast/files/sql/header");
 const types_1 = require("@pgpmjs/types");
 /**
  * Core dependency resolution algorithm that handles circular dependency detection

package/resolution/resolve.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveTagToChangeName = exports.resolveWithPlan = exports.resolve = void 0;
 const fs_1 = require("fs");
-const files_1 = require("../files");
-const parser_1 = require("../files/plan/parser");
+const files_1 = require("@pgpmjs/ast/files");
+const parser_1 = require("@pgpmjs/ast/files/plan/parser");
 const deps_1 = require("./deps");
 const types_1 = require("@pgpmjs/types");
 /**

package/slice/slice.d.ts

@@ -1,4 +1,4 @@
-import { Change, Tag, ExtendedPlanFile } from '../files/types';
+import { Change, Tag, ExtendedPlanFile } from '@pgpmjs/ast/files/types';
 import { SliceConfig, SliceResult, DependencyGraph, PackageOutput, GroupingStrategy, PatternStrategy, CrossPackageDepMode } from './types';
 /**
  * Build a dependency graph from a parsed plan file

package/slice/slice.js

@@ -14,7 +14,7 @@ exports.generatePlanContent = generatePlanContent;
 exports.generateControlContent = generateControlContent;
 exports.generateSinglePackage = generateSinglePackage;
 exports.slicePlan = slicePlan;
-const parser_1 = require("../files/plan/parser");
+const parser_1 = require("@pgpmjs/ast/files/plan/parser");
 const minimatch_1 = require("minimatch");
 /**
  * Build a dependency graph from a parsed plan file

package/slice/types.d.ts

@@ -1,4 +1,4 @@
-import { Change, Tag, ExtendedPlanFile } from '../files/types';
+import { Change, Tag, ExtendedPlanFile } from '@pgpmjs/ast/files/types';
 /**
  * Configuration for slicing a plan into multiple packages
  */

package/workspace/minimal.d.ts

@@ -0,0 +1,64 @@
+import { Change, Tag } from '@pgpmjs/ast/files/types';
+declare const SCRIPT_DIRS: readonly ["deploy", "revert", "verify"];
+export type MinimalScriptDir = (typeof SCRIPT_DIRS)[number];
+/**
+ * A single change's SQL scripts for a minimal module. `verify` is optional.
+ */
+export interface MinimalChangeScripts {
+    deploy: string;
+    revert: string;
+    verify?: string;
+}
+export interface WriteMinimalModuleOptions {
+    /** Module (extension) name */
+    name: string;
+    /** Plan changes, in order. Each must have a matching entry in `scripts`. */
+    changes: Change[];
+    /** SQL scripts keyed by change name */
+    scripts: Record<string, MinimalChangeScripts>;
+    /** Tags to include in the plan */
+    tags?: Tag[];
+    /** Extensions/modules this module requires (control `requires`) */
+    requires?: string[];
+    /** package.json version (default '0.0.1') */
+    version?: string;
+    /** package.json license (default 'CONSTRUCTIVE') */
+    license?: string;
+    /** Overwrite an existing directory (default: false) */
+    overwrite?: boolean;
+    /**
+     * Write a minimal `package.json` (default: true). Set `false` to preserve an
+     * existing one — e.g. when a richer package.json was already scaffolded by
+     * `pgpm init` and only the pgpm files should be written on top.
+     */
+    writePackageJson?: boolean;
+}
+/**
+ * The minimal set of files pgpm needs to recognize and deploy a module:
+ * `pgpm.plan` (module marker + change order), `<name>.control` (extension
+ * metadata), `Makefile` (PGXS packaging), `package.json`, and the
+ * deploy/revert/verify scripts. Mirrors what `pgpm init` scaffolds, minus the
+ * network-fetched boilerplate (README/LICENSE/jest/tests/lint configs).
+ */
+export declare function writeMinimalModule(moduleDir: string, options: WriteMinimalModuleOptions): void;
+export interface WriteMinimalWorkspaceOptions {
+    /** Workspace package globs (default: ['packages/*']) */
+    packages?: string[];
+    /** Overwrite an existing pgpm.json (default: true) */
+    overwrite?: boolean;
+}
+/**
+ * Write the minimal workspace marker (`pgpm.json`) so pgpm discovers the
+ * directory as a workspace. This is what `getWorkspacePath` walks up to find.
+ */
+export declare function writeMinimalWorkspace(workspaceDir: string, options?: WriteMinimalWorkspaceOptions): void;
+/**
+ * Full extension control file, matching the shape `pgpm init` emits (comment,
+ * default_version, module_pathname, requires, relocatable, superuser).
+ */
+export declare function generateModuleControl(name: string, requires?: string[], version?: string): string;
+/**
+ * PGXS Makefile for `pgpm package`/`make install`.
+ */
+export declare function generateModuleMakefile(name: string, version?: string): string;
+export {};

package/workspace/minimal.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeMinimalModule = writeMinimalModule;
+exports.writeMinimalWorkspace = writeMinimalWorkspace;
+exports.generateModuleControl = generateModuleControl;
+exports.generateModuleMakefile = generateModuleMakefile;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const slice_1 = require("../slice/slice");
+const SCRIPT_DIRS = ['deploy', 'revert', 'verify'];
+/**
+ * The minimal set of files pgpm needs to recognize and deploy a module:
+ * `pgpm.plan` (module marker + change order), `<name>.control` (extension
+ * metadata), `Makefile` (PGXS packaging), `package.json`, and the
+ * deploy/revert/verify scripts. Mirrors what `pgpm init` scaffolds, minus the
+ * network-fetched boilerplate (README/LICENSE/jest/tests/lint configs).
+ */
+function writeMinimalModule(moduleDir, options) {
+    const { name, changes, scripts, tags = [], requires = [], version = '0.0.1', license = 'CONSTRUCTIVE', overwrite = false, writePackageJson = true, } = options;
+    if (fs_1.default.existsSync(moduleDir) && fs_1.default.readdirSync(moduleDir).length > 0 && !overwrite) {
+        throw new Error(`Module directory is not empty: ${moduleDir}. Pass overwrite: true to replace.`);
+    }
+    for (const dir of SCRIPT_DIRS) {
+        fs_1.default.mkdirSync(path_1.default.join(moduleDir, dir), { recursive: true });
+    }
+    for (const change of changes) {
+        const changeScripts = scripts[change.name];
+        if (!changeScripts) {
+            throw new Error(`Missing scripts for change "${change.name}" in module "${name}"`);
+        }
+        fs_1.default.writeFileSync(path_1.default.join(moduleDir, 'deploy', `${change.name}.sql`), changeScripts.deploy);
+        fs_1.default.writeFileSync(path_1.default.join(moduleDir, 'revert', `${change.name}.sql`), changeScripts.revert);
+        fs_1.default.writeFileSync(path_1.default.join(moduleDir, 'verify', `${change.name}.sql`), changeScripts.verify ?? `-- Verify ${change.name}\n\nBEGIN;\n\nSELECT 1;\n\nROLLBACK;\n`);
+    }
+    fs_1.default.writeFileSync(path_1.default.join(moduleDir, 'pgpm.plan'), (0, slice_1.generatePlanContent)(name, changes, tags));
+    fs_1.default.writeFileSync(path_1.default.join(moduleDir, `${name}.control`), generateModuleControl(name, requires, version));
+    fs_1.default.writeFileSync(path_1.default.join(moduleDir, 'Makefile'), generateModuleMakefile(name, version));
+    if (writePackageJson) {
+        fs_1.default.writeFileSync(path_1.default.join(moduleDir, 'package.json'), JSON.stringify({ name, version, description: `${name} module`, license }, null, 2) + '\n');
+    }
+}
+/**
+ * Write the minimal workspace marker (`pgpm.json`) so pgpm discovers the
+ * directory as a workspace. This is what `getWorkspacePath` walks up to find.
+ */
+function writeMinimalWorkspace(workspaceDir, options = {}) {
+    const { packages = ['packages/*'], overwrite = true } = options;
+    const configPath = path_1.default.join(workspaceDir, 'pgpm.json');
+    if (fs_1.default.existsSync(configPath) && !overwrite)
+        return;
+    fs_1.default.mkdirSync(workspaceDir, { recursive: true });
+    fs_1.default.writeFileSync(configPath, JSON.stringify({ packages }, null, 2) + '\n');
+}
+/**
+ * Full extension control file, matching the shape `pgpm init` emits (comment,
+ * default_version, module_pathname, requires, relocatable, superuser).
+ */
+function generateModuleControl(name, requires = [], version = '0.0.1') {
+    let content = `# ${name} extension\n`;
+    content += `comment = '${name} extension'\n`;
+    content += `default_version = '${version}'\n`;
+    content += `module_pathname = '$libdir/${name}'\n`;
+    if (requires.length > 0) {
+        content += `requires = '${requires.join(',')}'\n`;
+    }
+    content += `relocatable = false\n`;
+    content += `superuser = false\n`;
+    return content;
+}
+/**
+ * PGXS Makefile for `pgpm package`/`make install`.
+ */
+function generateModuleMakefile(name, version = '0.0.1') {
+    return (`EXTENSION = ${name}\n` +
+        `DATA = sql/${name}--${version}.sql\n\n` +
+        `PG_CONFIG = pg_config\n` +
+        `PGXS := $(shell $(PG_CONFIG) --pgxs)\n` +
+        `include $(PGXS)\n`);
+}

package/esm/files/extension/index.js

@@ -1,3 +0,0 @@
-// Re-export all extension functionality
-export * from './reader';
-export * from './writer';