@pgpmjs/core 7.11.1 → 7.14.0

package/apply/apply-spec.d.ts

@@ -0,0 +1,14 @@
+import { ResolvedApplySpec } from './types';
+/** Whether a module directory is an apply-spec proxy module. */
+export declare function hasApplySpec(moduleDir: string): boolean;
+/**
+ * Read, validate, and normalize a proxy module's `pgpm.apply.json`.
+ *
+ * Normalizations: `source` is expanded to its object form and `name` defaults
+ * to the proxy directory's name.
+ *
+ * @throws when the file is missing, unparsable, or structurally invalid.
+ */
+export declare function readApplySpec(moduleDir: string): ResolvedApplySpec;
+/** In-memory core of {@link readApplySpec}. */
+export declare function parseApplySpec(content: string, specPath: string): ResolvedApplySpec;

package/apply/apply-spec.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasApplySpec = hasApplySpec;
+exports.readApplySpec = readApplySpec;
+exports.parseApplySpec = parseApplySpec;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const types_1 = require("./types");
+/** Whether a module directory is an apply-spec proxy module. */
+function hasApplySpec(moduleDir) {
+    return (0, fs_1.existsSync)((0, path_1.join)(moduleDir, types_1.APPLY_SPEC_FILE));
+}
+/**
+ * Read, validate, and normalize a proxy module's `pgpm.apply.json`.
+ *
+ * Normalizations: `source` is expanded to its object form and `name` defaults
+ * to the proxy directory's name.
+ *
+ * @throws when the file is missing, unparsable, or structurally invalid.
+ */
+function readApplySpec(moduleDir) {
+    const specPath = (0, path_1.join)(moduleDir, types_1.APPLY_SPEC_FILE);
+    if (!(0, fs_1.existsSync)(specPath)) {
+        throw new Error(`No ${types_1.APPLY_SPEC_FILE} found in ${moduleDir}`);
+    }
+    return parseApplySpec((0, fs_1.readFileSync)(specPath, 'utf-8'), specPath);
+}
+/** In-memory core of {@link readApplySpec}. */
+function parseApplySpec(content, specPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${specPath}: ${err instanceof Error ? err.message : err}`);
+    }
+    const source = typeof parsed?.source === 'string' ? { module: parsed.source } : parsed?.source;
+    if (!source || typeof source.module !== 'string' || !source.module) {
+        throw new Error(`${specPath}: "source" (source module name, or { "module": ... }) is required`);
+    }
+    const hasSchemas = parsed.schemas !== undefined;
+    if (hasSchemas) {
+        if (typeof parsed.schemas !== 'object' ||
+            Array.isArray(parsed.schemas) ||
+            Object.keys(parsed.schemas).length === 0 ||
+            Object.entries(parsed.schemas).some(([from, to]) => typeof from !== 'string' || typeof to !== 'string' || !from || !to)) {
+            throw new Error(`${specPath}: "schemas" must be a non-empty string → string map`);
+        }
+    }
+    const ROUTE_KINDS = ['table', 'view', 'function', 'procedure', 'type'];
+    const hasRoute = parsed.route !== undefined;
+    if (hasRoute) {
+        if (!Array.isArray(parsed.route) || parsed.route.length === 0) {
+            throw new Error(`${specPath}: "route" must be a non-empty array of route entries`);
+        }
+        for (const entry of parsed.route) {
+            if (!entry ||
+                typeof entry !== 'object' ||
+                typeof entry.fromSchema !== 'string' ||
+                !entry.fromSchema ||
+                typeof entry.name !== 'string' ||
+                !entry.name ||
+                typeof entry.toSchema !== 'string' ||
+                !entry.toSchema ||
+                !ROUTE_KINDS.includes(entry.kind)) {
+                throw new Error(`${specPath}: each "route" entry needs { fromSchema, kind (${ROUTE_KINDS.join('|')}), name, toSchema } as non-empty strings`);
+            }
+        }
+    }
+    if (!hasSchemas && !hasRoute) {
+        throw new Error(`${specPath}: at least one of "schemas" (string → string map) or "route" (object routes) is required`);
+    }
+    const name = parsed.name ?? (0, path_1.basename)((0, path_1.dirname)(specPath));
+    if (typeof name !== 'string' || !name) {
+        throw new Error(`${specPath}: "name" must be a non-empty string`);
+    }
+    if (name === source.module) {
+        throw new Error(`${specPath}: apply module "${name}" cannot apply itself`);
+    }
+    const requires = parsed.requires;
+    if (requires !== undefined &&
+        (!Array.isArray(requires) || requires.some((r) => typeof r !== 'string' || !r))) {
+        throw new Error(`${specPath}: "requires" must be an array of module names`);
+    }
+    if (requires?.includes(source.module)) {
+        throw new Error(`${specPath}: "requires" must not include the source module "${source.module}" — ` +
+            `it is source material, not a runtime dependency`);
+    }
+    return { ...parsed, name, source, requires };
+}

package/apply/index.d.ts

@@ -0,0 +1,3 @@
+export * from './materialize';
+export * from './apply-spec';
+export * from './types';

package/apply/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./materialize"), exports);
+__exportStar(require("./apply-spec"), exports);
+__exportStar(require("./types"), exports);

package/apply/materialize.d.ts

@@ -0,0 +1,40 @@
+import { MigrationBundle } from '@pgpmjs/bundle';
+import { ModuleMap } from '../modules/modules';
+import { ResolvedApplySpec } from './types';
+export interface MaterializeApplyOptions {
+    /** Directory of the source module being applied. */
+    sourceDir: string;
+    /** The apply spec (typically read from the proxy via {@link readApplySpec}). */
+    spec: ResolvedApplySpec;
+    /** Directory to materialize into (default: a fresh temp dir). */
+    outDir?: string;
+}
+export interface MaterializeApplyResult {
+    /** The transpiled, content-addressed bundle that was materialized. */
+    bundle: MigrationBundle;
+    /** The deployable module directory the bundle was written to. */
+    outDir: string;
+}
+/**
+ * Transpile a source module per an apply spec and materialize the result as a
+ * deployable module directory carrying the instance's identity.
+ *
+ * Pure pipeline over existing primitives: `bundleFromModule` →
+ * `transpileBundle(makeSchemaTranspiler)` → `verifyBundle` →
+ * `materializeBundle`. Deterministic — identical source + spec always produce
+ * an identical bundle (and digest), which is what makes verify/revert able to
+ * re-derive the exact deployed artifact.
+ */
+export declare function materializeApplyModule(options: MaterializeApplyOptions): Promise<MaterializeApplyResult>;
+/**
+ * Deploy-path dispatch seam: given a resolved module's directory, return the
+ * directory the migration engine should actually run against.
+ *
+ * Non-proxy modules pass through unchanged. For proxy modules (directories
+ * carrying a `pgpm.apply.json`), the source module is located in the workspace
+ * module map, transpiled per the spec, and materialized to a cached temp dir
+ * carrying the instance's identity.
+ */
+export declare function resolveEffectiveModulePath(moduleName: string, modulePath: string, moduleMap: ModuleMap, workspacePath: string): Promise<string>;
+/** Test seam: clear the per-process materialization cache. */
+export declare function clearApplyMaterializationCache(): void;

package/apply/materialize.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.materializeApplyModule = materializeApplyModule;
+exports.resolveEffectiveModulePath = resolveEffectiveModulePath;
+exports.clearApplyMaterializationCache = clearApplyMaterializationCache;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const bundle_1 = require("@pgpmjs/bundle");
+const transform_1 = require("@pgpmjs/transform");
+const apply_spec_1 = require("./apply-spec");
+// Functions that take a bare schema name as a string-literal first argument.
+// The AST pass only remaps dotted literals ('schema.object'); these helpers
+// (ubiquitous in verify scripts) name the schema alone, so a string-level
+// pre-pass remaps them.
+const SCHEMA_NAME_LITERAL_FUNCS = ['verify_schema', 'has_schema_privilege'];
+const schemaNameLiteralPass = (content, schemaMapping) => {
+    const pattern = new RegExp(`\\b(${SCHEMA_NAME_LITERAL_FUNCS.join('|')})\\s*\\(\\s*'([^']+)'`, 'gi');
+    return content.replace(pattern, (match, _fn, schema) => {
+        const mapped = schemaMapping.get(schema);
+        return mapped ? match.replace(`'${schema}'`, `'${mapped}'`) : match;
+    });
+};
+/**
+ * Transpile a source module per an apply spec and materialize the result as a
+ * deployable module directory carrying the instance's identity.
+ *
+ * Pure pipeline over existing primitives: `bundleFromModule` →
+ * `transpileBundle(makeSchemaTranspiler)` → `verifyBundle` →
+ * `materializeBundle`. Deterministic — identical source + spec always produce
+ * an identical bundle (and digest), which is what makes verify/revert able to
+ * re-derive the exact deployed artifact.
+ */
+async function materializeApplyModule(options) {
+    const { sourceDir, spec } = options;
+    const instanceName = spec.name;
+    // the schema transpiler's SQL/PLpgSQL parser is WASM-backed and needs a
+    // one-time async init (idempotent)
+    await (0, transform_1.loadModule)();
+    const source = (0, bundle_1.bundleFromModule)(sourceDir);
+    if (spec.source.bundleDigest && spec.source.bundleDigest !== source.manifest.digest) {
+        throw new Error(`Apply spec for "${instanceName}" pins source bundle digest ${spec.source.bundleDigest}, ` +
+            `but the installed source "${spec.source.module}" hashes to ${source.manifest.digest}. ` +
+            `Reinstall the pinned version or update the spec.`);
+    }
+    // Every distinct target schema is treated as "may already exist": apply
+    // deploys into consumer-chosen namespaces that can pre-exist (a shared schema,
+    // another tenant), so `CREATE SCHEMA` is emitted idempotently. This is what
+    // lets the same source apply cleanly whether or not the destination exists.
+    const targetSchemas = [
+        ...new Set([
+            ...Object.values(spec.schemas ?? {}),
+            ...(spec.route ?? []).map(r => r.toSchema)
+        ])
+    ];
+    const { renameChange, transformScript, result } = (0, transform_1.makeSchemaTranspiler)({
+        schemaMap: spec.schemas,
+        routes: spec.route,
+        transform: {
+            prePasses: [schemaNameLiteralPass],
+            assumeSchemasExist: targetSchemas
+        }
+    });
+    const transpiled = (0, bundle_1.transpileBundle)(source, {
+        renameChange,
+        transformScript,
+        renameModule: instanceName,
+        provenance: {
+            appliedFrom: spec.source.module,
+            ...(spec.source.package ? { sourcePackage: spec.source.package } : {}),
+            ...(spec.source.version ? { sourceVersion: spec.source.version } : {})
+        }
+    });
+    if (result.errors.length > 0) {
+        const detail = result.errors.map(e => `${e.file}: ${e.error}`).join('; ');
+        throw new Error(`Apply transpile of "${spec.source.module}" as "${instanceName}" failed: ${detail}`);
+    }
+    const issues = (0, bundle_1.verifyBundle)(transpiled);
+    if (issues.length > 0) {
+        throw new Error(`Transpiled bundle for "${instanceName}" failed integrity verification: ` +
+            issues.map(i => i.kind).join(', '));
+    }
+    const outDir = options.outDir ?? (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), `pgpm-apply-${instanceName}-`));
+    (0, bundle_1.materializeBundle)(transpiled, outDir);
+    return { bundle: transpiled, outDir };
+}
+// One materialization per proxy path per process: the pipeline is
+// deterministic, so re-deriving within a process is pure waste.
+const materializedCache = new Map();
+/**
+ * Deploy-path dispatch seam: given a resolved module's directory, return the
+ * directory the migration engine should actually run against.
+ *
+ * Non-proxy modules pass through unchanged. For proxy modules (directories
+ * carrying a `pgpm.apply.json`), the source module is located in the workspace
+ * module map, transpiled per the spec, and materialized to a cached temp dir
+ * carrying the instance's identity.
+ */
+async function resolveEffectiveModulePath(moduleName, modulePath, moduleMap, workspacePath) {
+    if (!(0, apply_spec_1.hasApplySpec)(modulePath))
+        return modulePath;
+    const cached = materializedCache.get(modulePath);
+    if (cached)
+        return cached;
+    const spec = (0, apply_spec_1.readApplySpec)(modulePath);
+    const sourceModule = moduleMap[spec.source.module];
+    if (!sourceModule) {
+        throw new Error(`Apply spec in "${moduleName}" references source module "${spec.source.module}", ` +
+            `which was not found in the workspace. Run \`pgpm install\` to install it` +
+            (spec.source.package ? ` (${spec.source.package})` : '') +
+            `.`);
+    }
+    const sourceDir = (0, path_1.resolve)(workspacePath, sourceModule.path);
+    const { outDir } = await materializeApplyModule({ sourceDir, spec });
+    materializedCache.set(modulePath, outDir);
+    return outDir;
+}
+/** Test seam: clear the per-process materialization cache. */
+function clearApplyMaterializationCache() {
+    materializedCache.clear();
+}

package/apply/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The apply-spec ("proxy module") types.
+ *
+ * A proxy module is a directory containing a single `pgpm.apply.json` file:
+ * "apply <source module> transpiled with this schema map, under my name". It
+ * needs no `.control`, no `pgpm.plan`, and no deploy/revert/verify scripts —
+ * workspace discovery synthesizes a module entry from the spec, so the proxy
+ * participates in dependency resolution by name exactly like a regular
+ * module. At deploy/verify/revert time the engine transpiles the source
+ * module in memory and runs the normal migration path against the result;
+ * transpiled code is never committed.
+ */
+/** File name of the apply spec inside a proxy module directory. */
+export declare const APPLY_SPEC_FILE = "pgpm.apply.json";
+/** Expanded reference to the source module a proxy module applies. */
+export interface ApplySpecSource {
+    /**
+     * Control/module name of the source module as it appears in the workspace
+     * module map (e.g. `pgpm-totp`). The source is typically installed into the
+     * workspace extensions directory via `pgpm install`; it is source material,
+     * not a runtime dependency, so it must not appear in `requires`.
+     */
+    module: string;
+    /** Optional npm package name the source is installed from (e.g. `@pgpm/totp`). */
+    package?: string;
+    /** Optional exact version pin for the source package. */
+    version?: string;
+    /**
+     * Optional content-addressed pin: the expected `manifest.digest` of the
+     * source bundle. When present, apply refuses to proceed if the installed
+     * source does not hash to exactly this digest.
+     */
+    bundleDigest?: string;
+}
+/**
+ * An object-level route in a `pgpm.apply.json` spec: send one named object out
+ * of a source schema to a target schema, overriding the whole-schema default
+ * for that object only. Kinds are expressed as separate properties (no dotted
+ * identity strings), so a table and a function of the same name route
+ * independently.
+ */
+export interface ApplyRouteEntry {
+    /** Source schema the object is defined in (e.g. `users`). */
+    fromSchema: string;
+    /** Object namespace: `table`/`view` → relation, `procedure` → function. */
+    kind: 'table' | 'view' | 'function' | 'procedure' | 'type';
+    /** Unqualified object name (e.g. `accounts`). */
+    name: string;
+    /** Target schema the object is routed to (e.g. `reporting`). */
+    toSchema: string;
+}
+/** The parsed, normalized `pgpm.apply.json` spec. */
+export interface PgpmApplySpec {
+    /**
+     * Module name this instance is deployed as. Defaults to the proxy
+     * directory's name.
+     */
+    name?: string;
+    /** Source module reference: a module name, or the expanded object form. */
+    source: string | ApplySpecSource;
+    /**
+     * Whole-schema default: source schema → target schema (drives the AST + plan
+     * rewrite). Optional when `route` fully covers the objects being moved.
+     */
+    schemas?: Record<string, string>;
+    /**
+     * Object-level routes. Each entry overrides the `schemas` default for its
+     * specific object, letting one source schema fan out per object (e.g. a
+     * table into a tenant schema and a function into a shared schema).
+     */
+    route?: ApplyRouteEntry[];
+    /**
+     * Runtime requires of the transpiled output (native extensions and other
+     * modules). Defaults to the source module's own requires.
+     */
+    requires?: string[];
+    /** Version reported for this instance (default: the source's version). */
+    version?: string;
+}
+/** {@link PgpmApplySpec} with `source` normalized to the object form. */
+export interface ResolvedApplySpec extends Omit<PgpmApplySpec, 'source'> {
+    source: ApplySpecSource;
+}

package/apply/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * The apply-spec ("proxy module") types.
+ *
+ * A proxy module is a directory containing a single `pgpm.apply.json` file:
+ * "apply <source module> transpiled with this schema map, under my name". It
+ * needs no `.control`, no `pgpm.plan`, and no deploy/revert/verify scripts —
+ * workspace discovery synthesizes a module entry from the spec, so the proxy
+ * participates in dependency resolution by name exactly like a regular
+ * module. At deploy/verify/revert time the engine transpiles the source
+ * module in memory and runs the normal migration path against the result;
+ * transpiled code is never committed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPLY_SPEC_FILE = void 0;
+/** File name of the apply spec inside a proxy module directory. */
+exports.APPLY_SPEC_FILE = 'pgpm.apply.json';

package/core/class/pgpm.d.ts

@@ -97,6 +97,14 @@ export declare class PgpmPackage {
      * Handles naming collisions by preferring the shortest path.
      */
     listModules(): ModuleMap;
+    /**
+     * Discover apply-spec proxy modules (`pgpm.apply.json`) and synthesize
+     * module-map entries for them so they participate in dependency resolution
+     * by name like any other module. A proxy needs no `.control` or `pgpm.plan`;
+     * its `requires` default to the source module's requires. Control-file
+     * modules win name collisions.
+     */
+    private addApplyModules;
     getModuleMap(): ModuleMap;
     getAvailableModules(): Promise<string[]>;
     getModuleProject(name: string): PgpmPackage;
@@ -271,6 +279,18 @@ export declare class PgpmPackage {
         resolved: string[];
         external: string[];
     }>;
+    /**
+     * Dependency closure for a named module. Proxy (apply-spec) modules have no
+     * pgpm.plan, so they resolve straight off the workspace module map instead
+     * of instantiating a module-rooted package.
+     */
+    private getModuleExtensionsFor;
+    /**
+     * Directory the migration engine should run against for a named module:
+     * the module's own directory, or — for proxy (apply-spec) modules — the
+     * materialized transpiled instance.
+     */
+    private getEffectiveModulePathFor;
     private parsePackageTarget;
     deploy(opts: PgpmOptions, target?: string, recursive?: boolean): Promise<void>;
     /**

package/core/class/pgpm.js

@@ -48,6 +48,9 @@ const parse_package_name_1 = require("parse-package-name");
 const path_1 = __importStar(require("path"));
 const pg_cache_1 = require("pg-cache");
 const yanse_1 = __importDefault(require("yanse"));
+const materialize_1 = require("../../apply/materialize");
+const apply_spec_1 = require("../../apply/apply-spec");
+const types_2 = require("../../apply/types");
 const extensions_1 = require("../../extensions/extensions");
 const files_1 = require("@pgpmjs/ast/files");
 const files_2 = require("@pgpmjs/ast/files");
@@ -281,11 +284,44 @@ class PgpmPackage {
             }
         });
         // Parse the selected control files
-        return Array.from(selectedFiles.entries()).reduce((acc, [moduleName, file]) => {
+        const moduleMap = Array.from(selectedFiles.entries()).reduce((acc, [moduleName, file]) => {
             const module = (0, files_2.parseControlFile)(file, this.workspacePath);
             acc[moduleName] = module;
             return acc;
         }, {});
+        return this.addApplyModules(moduleMap, packageDirs);
+    }
+    /**
+     * Discover apply-spec proxy modules (`pgpm.apply.json`) and synthesize
+     * module-map entries for them so they participate in dependency resolution
+     * by name like any other module. A proxy needs no `.control` or `pgpm.plan`;
+     * its `requires` default to the source module's requires. Control-file
+     * modules win name collisions.
+     */
+    addApplyModules(moduleMap, packageDirs) {
+        const specFiles = [...new Set(packageDirs.flatMap(dir => glob.sync((0, glob_1.globPattern)(dir, `**/${types_2.APPLY_SPEC_FILE}`))))].filter((file) => !/node_modules/.test(file)).sort((a, b) => a.localeCompare(b));
+        for (const file of specFiles) {
+            let spec;
+            try {
+                spec = (0, apply_spec_1.readApplySpec)(path_1.default.dirname(file));
+            }
+            catch (err) {
+                console.warn(`Skipping invalid apply spec ${file}: ${err instanceof Error ? err.message : err}`);
+                continue;
+            }
+            const name = spec.name;
+            if (moduleMap[name])
+                continue;
+            const source = moduleMap[spec.source.module];
+            moduleMap[name] = {
+                path: path_1.default
+                    .dirname(path_1.default.relative(this.workspacePath, file))
+                    .replace(/\\/g, '/'),
+                requires: spec.requires ?? source?.requires ?? [],
+                version: spec.version ?? source?.version ?? '0.0.1'
+            };
+        }
+        return moduleMap;
     }
     getModuleMap() {
         if (!this.workspacePath)
@@ -1235,6 +1271,38 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
             external: external
         };
     }
+    /**
+     * Dependency closure for a named module. Proxy (apply-spec) modules have no
+     * pgpm.plan, so they resolve straight off the workspace module map instead
+     * of instantiating a module-rooted package.
+     */
+    getModuleExtensionsFor(name) {
+        const modules = this.getModuleMap();
+        if (!modules[name]) {
+            throw types_1.errors.MODULE_NOT_FOUND({ name });
+        }
+        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[name].path);
+        if ((0, apply_spec_1.hasApplySpec)(modulePath)) {
+            return (0, deps_1.resolveExtensionDependencies)(name, modules);
+        }
+        return this.getModuleProject(name).getModuleExtensions();
+    }
+    /**
+     * Directory the migration engine should run against for a named module:
+     * the module's own directory, or — for proxy (apply-spec) modules — the
+     * materialized transpiled instance.
+     */
+    async getEffectiveModulePathFor(name) {
+        const modules = this.getModuleMap();
+        if (!modules[name]) {
+            throw types_1.errors.MODULE_NOT_FOUND({ name });
+        }
+        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[name].path);
+        if ((0, apply_spec_1.hasApplySpec)(modulePath)) {
+            return (0, materialize_1.resolveEffectiveModulePath)(name, modulePath, modules, this.workspacePath);
+        }
+        return this.getModuleProject(name).getModulePath();
+    }
     parsePackageTarget(target) {
         let name;
         let toChange;
@@ -1279,8 +1347,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                 extensions = await this.resolveWorkspaceExtensionDependencies();
             }
             else {
-                const moduleProject = this.getModuleProject(name);
-                extensions = moduleProject.getModuleExtensions();
+                extensions = this.getModuleExtensionsFor(name);
             }
             const pgPool = (0, pg_cache_1.getPgPool)(opts.pg);
             const targetDescription = name === null ? 'all modules' : name;
@@ -1293,10 +1360,9 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                         await pgPool.query(msg);
                     }
                     else {
-                        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[extension].path);
+                        const modulePath = await (0, materialize_1.resolveEffectiveModulePath)(extension, (0, path_1.resolve)(this.workspacePath, modules[extension].path), modules, this.workspacePath);
                         log.info(`📂 Deploying local module: ${extension}`);
                         if (opts.deployment.fast) {
-                            const localProject = this.getModuleProject(extension);
                             const cacheKey = getCacheKey(opts.pg, extension, opts.pg.database);
                             if (opts.deployment.cache && deployFastCache[cacheKey]) {
                                 log.warn(`⚡ Using cached pkg for ${extension}.`);
@@ -1305,7 +1371,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                             }
                             let pkg;
                             try {
-                                pkg = await (0, package_1.packageModule)(localProject.modulePath, {
+                                pkg = await (0, package_1.packageModule)(modulePath, {
                                     usePlan: opts.deployment.usePlan,
                                     extension: false
                                 });
@@ -1374,8 +1440,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
             if (name === null) {
                 throw types_1.errors.WORKSPACE_OPERATION_ERROR({ operation: 'deployment' });
             }
-            const moduleProject = this.getModuleProject(name);
-            const modulePath = moduleProject.getModulePath();
+            const modulePath = await this.getEffectiveModulePathFor(name);
             if (!modulePath) {
                 throw types_1.errors.PATH_NOT_FOUND({ path: name, type: 'module' });
             }
@@ -1442,7 +1507,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                         }
                     }
                     else {
-                        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[extension].path);
+                        const modulePath = await (0, materialize_1.resolveEffectiveModulePath)(extension, (0, path_1.resolve)(this.workspacePath, modules[extension].path), modules, this.workspacePath);
                         log.info(`📂 Reverting local module: ${extension}`);
                         try {
                             const client = new client_1.PgpmMigrate(opts.pg);
@@ -1475,8 +1540,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
             if (name === null) {
                 throw types_1.errors.WORKSPACE_OPERATION_ERROR({ operation: 'revert' });
             }
-            const moduleProject = this.getModuleProject(name);
-            const modulePath = moduleProject.getModulePath();
+            const modulePath = await this.getEffectiveModulePathFor(name);
             if (!modulePath) {
                 throw types_1.errors.PATH_NOT_FOUND({ path: name, type: 'module' });
             }
@@ -1503,8 +1567,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                 extensions = await this.resolveWorkspaceExtensionDependencies();
             }
             else {
-                const moduleProject = this.getModuleProject(name);
-                extensions = moduleProject.getModuleExtensions();
+                extensions = this.getModuleExtensionsFor(name);
             }
             const pgPool = (0, pg_cache_1.getPgPool)(opts.pg);
             const targetDescription = name === null ? 'all modules' : name;
@@ -1517,7 +1580,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
                         await pgPool.query(query, [extension]);
                     }
                     else {
-                        const modulePath = (0, path_1.resolve)(this.workspacePath, modules[extension].path);
+                        const modulePath = await (0, materialize_1.resolveEffectiveModulePath)(extension, (0, path_1.resolve)(this.workspacePath, modules[extension].path), modules, this.workspacePath);
                         log.info(`📂 Verifying local module: ${extension}`);
                         try {
                             const client = new client_1.PgpmMigrate(opts.pg);
@@ -1549,8 +1612,7 @@ ${dependencies.length > 0 ? dependencies.map(dep => `-- requires: ${dep}`).join(
             if (name === null) {
                 throw types_1.errors.WORKSPACE_OPERATION_ERROR({ operation: 'verification' });
             }
-            const moduleProject = this.getModuleProject(name);
-            const modulePath = moduleProject.getModulePath();
+            const modulePath = await this.getEffectiveModulePathFor(name);
             if (!modulePath) {
                 throw types_1.errors.PATH_NOT_FOUND({ path: name, type: 'module' });
             }