@pgpmjs/core 7.15.0 → 7.17.0

package/esm/extensions/compile.js

@@ -0,0 +1,109 @@
+const SPECIAL_ROLES = new Set(['public', 'current_user', 'session_user']);
+const quoteIdent = (name) => `"${name.replace(/"/g, '""')}"`;
+const routeRole = (role, roleMap) => {
+    if (!roleMap)
+        return role;
+    if (SPECIAL_ROLES.has(role.toLowerCase()))
+        return role;
+    return roleMap[role] ?? role;
+};
+const grantObjectClause = (on, schema) => {
+    const s = quoteIdent(schema);
+    switch (on) {
+        case 'schema':
+            return `SCHEMA ${s}`;
+        case 'all-tables':
+            return `ALL TABLES IN SCHEMA ${s}`;
+        case 'all-sequences':
+            return `ALL SEQUENCES IN SCHEMA ${s}`;
+        case 'all-functions':
+            return `ALL FUNCTIONS IN SCHEMA ${s}`;
+    }
+};
+const grantSql = (verb, grant, schema, roleMap) => {
+    const roles = (Array.isArray(grant.to) ? grant.to : [grant.to])
+        .map((r) => routeRole(r, roleMap))
+        .join(', ');
+    const obj = grantObjectClause(grant.on, schema);
+    return verb === 'GRANT'
+        ? `GRANT ${grant.privileges} ON ${obj} TO ${roles};`
+        : `REVOKE ${grant.privileges} ON ${obj} FROM ${roles};`;
+};
+/**
+ * Compile a single `provides` declaration into deploy / revert / verify SQL.
+ *
+ * Pure and deterministic: given the same input it returns byte-identical SQL,
+ * with no dynamic `EXECUTE`. This is the nuts-and-bolts primitive; wiring it
+ * into the deploy path (and eventually into real plan changes exempt from
+ * `filterStatements` stripping) composes on top of it.
+ */
+export function compileExtensionInstall(extname, provide, options = {}) {
+    const { roleMap, fixedSchema } = options;
+    const schema = provide.schema === undefined ? null : provide.schema;
+    const relocatable = provide.relocatable ?? true;
+    const ifNotExists = provide.ifNotExists ?? true;
+    const cascade = provide.cascade ?? false;
+    const createSchema = provide.createSchema ?? schema !== null;
+    const dropSchema = provide.dropSchema ?? false;
+    const grants = provide.grants ?? [];
+    // A fixed-schema extension can only be placed at its own fixed schema.
+    if (!relocatable && schema !== null && fixedSchema != null && schema !== fixedSchema) {
+        throw new Error(`Extension "${extname}" is non-relocatable (fixed schema "${fixedSchema}") and cannot be installed into "${schema}".`);
+    }
+    if (grants.length > 0 && schema === null) {
+        throw new Error(`Extension "${extname}" declares grants but no schema; schema-qualified grants require an install schema.`);
+    }
+    const ext = quoteIdent(extname);
+    const deploy = [];
+    const revert = [];
+    const verify = [];
+    if (schema !== null && createSchema) {
+        deploy.push(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)};`);
+    }
+    const createParts = ['CREATE EXTENSION'];
+    if (ifNotExists)
+        createParts.push('IF NOT EXISTS');
+    createParts.push(ext);
+    if (schema !== null)
+        createParts.push(`WITH SCHEMA ${quoteIdent(schema)}`);
+    if (cascade)
+        createParts.push('CASCADE');
+    deploy.push(`${createParts.join(' ')};`);
+    for (const g of grants) {
+        deploy.push(grantSql('GRANT', g, schema, roleMap));
+    }
+    // Revert: drop grants (best-effort), then extension, then optionally schema.
+    for (const g of [...grants].reverse()) {
+        revert.push(grantSql('REVOKE', g, schema, roleMap));
+    }
+    revert.push(`DROP EXTENSION IF EXISTS ${ext};`);
+    if (schema !== null && createSchema && dropSchema) {
+        revert.push(`DROP SCHEMA IF EXISTS ${quoteIdent(schema)};`);
+    }
+    // Verify: assert the extension exists in the expected namespace.
+    if (schema !== null) {
+        verify.push([
+            'SELECT 1 / count(*)::int AS ok',
+            'FROM pg_catalog.pg_extension e',
+            'JOIN pg_catalog.pg_namespace n ON n.oid = e.extnamespace',
+            `WHERE e.extname = ${quoteLiteral(extname)} AND n.nspname = ${quoteLiteral(schema)};`
+        ].join('\n'));
+    }
+    else {
+        verify.push([
+            'SELECT 1 / count(*)::int AS ok',
+            'FROM pg_catalog.pg_extension e',
+            `WHERE e.extname = ${quoteLiteral(extname)};`
+        ].join('\n'));
+    }
+    return { deploy, revert, verify };
+}
+const quoteLiteral = (s) => `'${s.replace(/'/g, "''")}'`;
+/** Compile every `provides` entry in a manifest, keyed by extension name. */
+export function compileExtensionInstalls(provides, options = {}) {
+    const out = {};
+    for (const [extname, provide] of Object.entries(provides)) {
+        out[extname] = compileExtensionInstall(extname, provide, options);
+    }
+    return out;
+}

package/esm/extensions/index.js

@@ -0,0 +1,4 @@
+export * from './compile';
+export * from './extensions';
+export * from './manifest';
+export * from './resolve-install';

package/esm/extensions/manifest.js

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+/**
+ * Declarative extension manifest (`extensions.json`) that lives next to a
+ * module's `pgpm.plan` / `.control`. It makes a module self-describing about
+ * the PostgreSQL extensions it relates to:
+ *
+ * - `provides` — the module *is* the extension wrapper: it installs the
+ *   extension into a chosen schema (with grants). This is what replaces the
+ *   dynamic `DO $$ EXECUTE 'CREATE EXTENSION ... SCHEMA x' $$` hack, since a
+ *   literal `CREATE EXTENSION` is stripped at package time.
+ * - `consumes` — the module merely *uses* symbols from an extension installed
+ *   elsewhere (e.g. a bare `crypt()` call) and needs them qualified to wherever
+ *   the extension actually landed. This is the transform/routing side.
+ *
+ * `.control` `requires` still names the extension (dependency ordering is
+ * unchanged); this manifest only adds the *where + grants* that `.control`
+ * cannot express.
+ */
+/** Candidate file names, in precedence order. */
+export const EXTENSIONS_MANIFEST_FILES = ['pgpm.extensions.json', 'extensions.json'];
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const GRANT_TARGETS = new Set([
+    'schema',
+    'all-tables',
+    'all-sequences',
+    'all-functions'
+]);
+/**
+ * Validate + normalize a parsed manifest object. Throws with a precise message
+ * on malformed input so authors get actionable errors rather than silent
+ * misconfiguration.
+ */
+export function validateExtensionsManifest(raw, source = 'extensions.json') {
+    if (!isPlainObject(raw)) {
+        throw new Error(`${source}: manifest must be a JSON object`);
+    }
+    const manifest = {};
+    if (raw.provides !== undefined) {
+        if (!isPlainObject(raw.provides)) {
+            throw new Error(`${source}: "provides" must be an object keyed by extension name`);
+        }
+        const provides = {};
+        for (const [extname, value] of Object.entries(raw.provides)) {
+            provides[extname] = validateProvide(extname, value, source);
+        }
+        manifest.provides = provides;
+    }
+    if (raw.consumes !== undefined) {
+        if (!isPlainObject(raw.consumes)) {
+            throw new Error(`${source}: "consumes" must be an object keyed by extension name`);
+        }
+        const consumes = {};
+        for (const [extname, value] of Object.entries(raw.consumes)) {
+            if (!isPlainObject(value)) {
+                throw new Error(`${source}: consumes."${extname}" must be an object`);
+            }
+            const entry = {};
+            if (value.symbols !== undefined) {
+                if (!Array.isArray(value.symbols) || value.symbols.some((s) => typeof s !== 'string' || !s.trim())) {
+                    throw new Error(`${source}: consumes."${extname}".symbols must be an array of non-empty strings`);
+                }
+                entry.symbols = value.symbols;
+            }
+            consumes[extname] = entry;
+        }
+        manifest.consumes = consumes;
+    }
+    return manifest;
+}
+function validateProvide(extname, value, source) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${source}: provides."${extname}" must be an object`);
+    }
+    const provide = {};
+    if (value.schema !== undefined) {
+        if (value.schema !== null && (typeof value.schema !== 'string' || !value.schema.trim())) {
+            throw new Error(`${source}: provides."${extname}".schema must be a non-empty string or null`);
+        }
+        provide.schema = value.schema;
+    }
+    for (const flag of ['relocatable', 'ifNotExists', 'cascade', 'createSchema', 'dropSchema']) {
+        if (value[flag] !== undefined) {
+            if (typeof value[flag] !== 'boolean') {
+                throw new Error(`${source}: provides."${extname}".${flag} must be a boolean`);
+            }
+            provide[flag] = value[flag];
+        }
+    }
+    if (value.grants !== undefined) {
+        if (!Array.isArray(value.grants)) {
+            throw new Error(`${source}: provides."${extname}".grants must be an array`);
+        }
+        provide.grants = value.grants.map((g, i) => validateGrant(extname, g, i, source));
+    }
+    return provide;
+}
+function validateGrant(extname, value, index, source) {
+    const where = `provides."${extname}".grants[${index}]`;
+    if (!isPlainObject(value)) {
+        throw new Error(`${source}: ${where} must be an object`);
+    }
+    if (typeof value.privileges !== 'string' || !value.privileges.trim()) {
+        throw new Error(`${source}: ${where}.privileges must be a non-empty string`);
+    }
+    if (typeof value.on !== 'string' || !GRANT_TARGETS.has(value.on)) {
+        throw new Error(`${source}: ${where}.on must be one of ${[...GRANT_TARGETS].join(', ')}`);
+    }
+    const toValid = (typeof value.to === 'string' && value.to.trim()) ||
+        (Array.isArray(value.to) && value.to.length > 0 && value.to.every((r) => typeof r === 'string' && r.trim()));
+    if (!toValid) {
+        throw new Error(`${source}: ${where}.to must be a role name or non-empty array of role names`);
+    }
+    return {
+        privileges: value.privileges,
+        on: value.on,
+        to: value.to
+    };
+}
+/**
+ * Read + validate the `extensions.json` (or `pgpm.extensions.json`) manifest for
+ * a module directory. Returns `undefined` when the module declares no manifest.
+ */
+export function readExtensionsManifest(moduleDir) {
+    for (const file of EXTENSIONS_MANIFEST_FILES) {
+        const p = join(moduleDir, file);
+        if (existsSync(p)) {
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(p, 'utf-8'));
+            }
+            catch (e) {
+                throw new Error(`Failed to parse ${file} at ${moduleDir}: ${e.message}`);
+            }
+            return validateExtensionsManifest(parsed, file);
+        }
+    }
+    return undefined;
+}

package/esm/extensions/resolve-install.js

@@ -0,0 +1,70 @@
+import { resolve } from 'path';
+import { compileExtensionInstall } from './compile';
+import { readExtensionsManifest } from './manifest';
+/**
+ * Build a grant role-name map (workspace portability profile) from the
+ * configured {@link RoleMapping}. Keys are the conceptual role names a module
+ * author writes in its manifest (`anonymous`/`authenticated`/`administrator`);
+ * values are the actual role names for this database.
+ */
+export function roleMapFromRoles(roles) {
+    if (!roles)
+        return undefined;
+    const map = {};
+    for (const key of ['anonymous', 'authenticated', 'administrator', 'authenticatedClient']) {
+        const value = roles[key];
+        if (value)
+            map[key] = value;
+    }
+    return Object.keys(map).length > 0 ? map : undefined;
+}
+/**
+ * Find a declarative install for an external extension by scanning the resolved
+ * local modules for an `extensions.json` that `provides` it, and compiling it.
+ *
+ * Returns `undefined` when no module declares the extension — the caller then
+ * falls back to the legacy `CREATE EXTENSION ... CASCADE` (no schema, no grants).
+ * The first declaring module wins; a later contradictory declaration throws.
+ */
+export function findExtensionInstall(extname, localModules, modules, workspacePath, options = {}) {
+    let winner;
+    for (const moduleName of localModules) {
+        const mod = modules[moduleName];
+        if (!mod)
+            continue;
+        const manifest = readExtensionsManifest(resolve(workspacePath, mod.path));
+        const provide = manifest?.provides?.[extname];
+        if (!provide)
+            continue;
+        if (winner && !sameProvide(winner.provide, provide)) {
+            throw new Error(`Conflicting extensions.json "provides" for "${extname}": ` +
+                `module "${winner.moduleName}" and module "${moduleName}" declare incompatible ` +
+                `install schema/grants. Exactly one provider (or identical declarations) is required.`);
+        }
+        if (!winner)
+            winner = { moduleName, provide };
+    }
+    return winner ? compileExtensionInstall(extname, winner.provide, options) : undefined;
+}
+/** Structural equality of two provide declarations (order-insensitive grants). */
+function sameProvide(a, b) {
+    return normalizeProvide(a) === normalizeProvide(b);
+}
+function normalizeProvide(p) {
+    const grants = (p.grants ?? [])
+        .map(g => ({
+        privileges: g.privileges,
+        on: g.on,
+        to: (Array.isArray(g.to) ? [...g.to] : [g.to]).sort()
+    }))
+        .sort((x, y) => JSON.stringify(x).localeCompare(JSON.stringify(y)));
+    return JSON.stringify({
+        schema: p.schema ?? null,
+        relocatable: p.relocatable ?? null,
+        ifNotExists: p.ifNotExists ?? null,
+        cascade: p.cascade ?? null,
+        createSchema: p.createSchema ?? null,
+        dropSchema: p.dropSchema ?? null,
+        grants
+    });
+}

package/esm/index.js

@@ -1,6 +1,6 @@
 export * from './core/class/pgpm';
 export * from './rebundle';
-export * from './extensions/extensions';
+export * from './extensions';
 export * from './modules/modules';
 export * from './packaging/package';
 export * from './packaging/sync-versions';

package/esm/migrate/clean.js

@@ -2,8 +2,7 @@ import { deparse, parse } from 'pgsql-parser';
 const filterStatements = (stmts) => {
     const filteredStmts = stmts.filter(node => {
         const stmt = node.stmt;
-        return stmt && !stmt.hasOwnProperty('TransactionStmt') &&
-            !stmt.hasOwnProperty('CreateExtensionStmt');
+        return stmt && !stmt.hasOwnProperty('TransactionStmt');
     });
     const hasFiltered = filteredStmts.length !== stmts.length;
     return { filteredStmts, hasFiltered };

package/esm/projects/deploy.js

@@ -8,6 +8,7 @@ import { resolveEffectiveModulePath } from '../apply/materialize';
 import { hasApplySpec } from '../apply/apply-spec';
 import { deployModuleFast, isBundledDeployResult } from '../bundle/deploy-bundled';
 import { PgpmPackage } from '../core/class/pgpm';
+import { findExtensionInstall, roleMapFromRoles } from '../extensions';
 import { PgpmMigrate } from '../migrate/client';
 import { resolveExtensionDependencies } from '../resolution/deps';
 const log = new Logger('deploy');
@@ -27,14 +28,28 @@ export const deployProject = async (opts, name, database, pkg, toChange) => {
         ? resolveExtensionDependencies(name, modules)
         : new PgpmPackage(modulePath, { extensionsDir: pkg.extensionsDir }).getModuleExtensions();
     const pgPool = getPgPool({ ...opts.pg, database });
+    // Local modules (in resolve order) that may carry an `extensions.json`
+    // declaring how an external extension should be installed (schema + grants).
+    const localModules = extensions.resolved.filter((m) => !extensions.external.includes(m));
+    const roleMap = roleMapFromRoles(mergedOpts.db?.roles);
     log.success(`🚀 Starting deployment to database ${database}...`);
     for (const extension of extensions.resolved) {
         try {
             if (extensions.external.includes(extension)) {
-                const msg = `CREATE EXTENSION IF NOT EXISTS "${extension}" CASCADE;`;
-                log.info(`📥 Installing external extension: ${extension}`);
-                log.debug(`> ${msg}`);
-                await pgPool.query(msg);
+                const install = findExtensionInstall(extension, localModules, modules, pkg.workspacePath, { roleMap });
+                if (install) {
+                    log.info(`📥 Installing external extension (declarative): ${extension}`);
+                    for (const stmt of install.deploy) {
+                        log.debug(`> ${stmt}`);
+                        await pgPool.query(stmt);
+                    }
+                }
+                else {
+                    const msg = `CREATE EXTENSION IF NOT EXISTS "${extension}" CASCADE;`;
+                    log.info(`📥 Installing external extension: ${extension}`);
+                    log.debug(`> ${msg}`);
+                    await pgPool.query(msg);
+                }
             }
             else {
                 const sourcePath = resolve(pkg.workspacePath, modules[extension].path);

package/extensions/compile.d.ts

@@ -0,0 +1,35 @@
+import { ExtensionProvide } from './manifest';
+/** Result of compiling one `provides` entry into deployable SQL. */
+export interface CompiledExtensionInstall {
+    /** Deploy statements, in order (schema, extension, grants). */
+    deploy: string[];
+    /** Revert statements, in reverse order (drop extension, optionally schema). */
+    revert: string[];
+    /** Verify statements that error when the install is absent. */
+    verify: string[];
+}
+export interface CompileExtensionInstallOptions {
+    /**
+     * Optional role-name map applied to grant targets (workspace portability
+     * profile). Renames identifiers only — never touches privilege semantics.
+     * Special roles (`PUBLIC`, `CURRENT_USER`, `SESSION_USER`) pass through.
+     */
+    roleMap?: Record<string, string>;
+    /**
+     * Control-file schema for a fixed-schema (non-relocatable) extension, when
+     * known. Used to validate that a `false`-relocatable extension is only
+     * "routed" to its own fixed schema.
+     */
+    fixedSchema?: string | null;
+}
+/**
+ * Compile a single `provides` declaration into deploy / revert / verify SQL.
+ *
+ * Pure and deterministic: given the same input it returns byte-identical SQL,
+ * with no dynamic `EXECUTE`. This is the nuts-and-bolts primitive; wiring it
+ * into the deploy path (and eventually into real plan changes exempt from
+ * `filterStatements` stripping) composes on top of it.
+ */
+export declare function compileExtensionInstall(extname: string, provide: ExtensionProvide, options?: CompileExtensionInstallOptions): CompiledExtensionInstall;
+/** Compile every `provides` entry in a manifest, keyed by extension name. */
+export declare function compileExtensionInstalls(provides: Record<string, ExtensionProvide>, options?: CompileExtensionInstallOptions): Record<string, CompiledExtensionInstall>;

package/extensions/compile.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileExtensionInstall = compileExtensionInstall;
+exports.compileExtensionInstalls = compileExtensionInstalls;
+const SPECIAL_ROLES = new Set(['public', 'current_user', 'session_user']);
+const quoteIdent = (name) => `"${name.replace(/"/g, '""')}"`;
+const routeRole = (role, roleMap) => {
+    if (!roleMap)
+        return role;
+    if (SPECIAL_ROLES.has(role.toLowerCase()))
+        return role;
+    return roleMap[role] ?? role;
+};
+const grantObjectClause = (on, schema) => {
+    const s = quoteIdent(schema);
+    switch (on) {
+        case 'schema':
+            return `SCHEMA ${s}`;
+        case 'all-tables':
+            return `ALL TABLES IN SCHEMA ${s}`;
+        case 'all-sequences':
+            return `ALL SEQUENCES IN SCHEMA ${s}`;
+        case 'all-functions':
+            return `ALL FUNCTIONS IN SCHEMA ${s}`;
+    }
+};
+const grantSql = (verb, grant, schema, roleMap) => {
+    const roles = (Array.isArray(grant.to) ? grant.to : [grant.to])
+        .map((r) => routeRole(r, roleMap))
+        .join(', ');
+    const obj = grantObjectClause(grant.on, schema);
+    return verb === 'GRANT'
+        ? `GRANT ${grant.privileges} ON ${obj} TO ${roles};`
+        : `REVOKE ${grant.privileges} ON ${obj} FROM ${roles};`;
+};
+/**
+ * Compile a single `provides` declaration into deploy / revert / verify SQL.
+ *
+ * Pure and deterministic: given the same input it returns byte-identical SQL,
+ * with no dynamic `EXECUTE`. This is the nuts-and-bolts primitive; wiring it
+ * into the deploy path (and eventually into real plan changes exempt from
+ * `filterStatements` stripping) composes on top of it.
+ */
+function compileExtensionInstall(extname, provide, options = {}) {
+    const { roleMap, fixedSchema } = options;
+    const schema = provide.schema === undefined ? null : provide.schema;
+    const relocatable = provide.relocatable ?? true;
+    const ifNotExists = provide.ifNotExists ?? true;
+    const cascade = provide.cascade ?? false;
+    const createSchema = provide.createSchema ?? schema !== null;
+    const dropSchema = provide.dropSchema ?? false;
+    const grants = provide.grants ?? [];
+    // A fixed-schema extension can only be placed at its own fixed schema.
+    if (!relocatable && schema !== null && fixedSchema != null && schema !== fixedSchema) {
+        throw new Error(`Extension "${extname}" is non-relocatable (fixed schema "${fixedSchema}") and cannot be installed into "${schema}".`);
+    }
+    if (grants.length > 0 && schema === null) {
+        throw new Error(`Extension "${extname}" declares grants but no schema; schema-qualified grants require an install schema.`);
+    }
+    const ext = quoteIdent(extname);
+    const deploy = [];
+    const revert = [];
+    const verify = [];
+    if (schema !== null && createSchema) {
+        deploy.push(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)};`);
+    }
+    const createParts = ['CREATE EXTENSION'];
+    if (ifNotExists)
+        createParts.push('IF NOT EXISTS');
+    createParts.push(ext);
+    if (schema !== null)
+        createParts.push(`WITH SCHEMA ${quoteIdent(schema)}`);
+    if (cascade)
+        createParts.push('CASCADE');
+    deploy.push(`${createParts.join(' ')};`);
+    for (const g of grants) {
+        deploy.push(grantSql('GRANT', g, schema, roleMap));
+    }
+    // Revert: drop grants (best-effort), then extension, then optionally schema.
+    for (const g of [...grants].reverse()) {
+        revert.push(grantSql('REVOKE', g, schema, roleMap));
+    }
+    revert.push(`DROP EXTENSION IF EXISTS ${ext};`);
+    if (schema !== null && createSchema && dropSchema) {
+        revert.push(`DROP SCHEMA IF EXISTS ${quoteIdent(schema)};`);
+    }
+    // Verify: assert the extension exists in the expected namespace.
+    if (schema !== null) {
+        verify.push([
+            'SELECT 1 / count(*)::int AS ok',
+            'FROM pg_catalog.pg_extension e',
+            'JOIN pg_catalog.pg_namespace n ON n.oid = e.extnamespace',
+            `WHERE e.extname = ${quoteLiteral(extname)} AND n.nspname = ${quoteLiteral(schema)};`
+        ].join('\n'));
+    }
+    else {
+        verify.push([
+            'SELECT 1 / count(*)::int AS ok',
+            'FROM pg_catalog.pg_extension e',
+            `WHERE e.extname = ${quoteLiteral(extname)};`
+        ].join('\n'));
+    }
+    return { deploy, revert, verify };
+}
+const quoteLiteral = (s) => `'${s.replace(/'/g, "''")}'`;
+/** Compile every `provides` entry in a manifest, keyed by extension name. */
+function compileExtensionInstalls(provides, options = {}) {
+    const out = {};
+    for (const [extname, provide] of Object.entries(provides)) {
+        out[extname] = compileExtensionInstall(extname, provide, options);
+    }
+    return out;
+}

package/extensions/index.d.ts

@@ -0,0 +1,4 @@
+export * from './compile';
+export * from './extensions';
+export * from './manifest';
+export * from './resolve-install';

package/extensions/index.js

@@ -0,0 +1,20 @@
+"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("./compile"), exports);
+__exportStar(require("./extensions"), exports);
+__exportStar(require("./manifest"), exports);
+__exportStar(require("./resolve-install"), exports);

package/extensions/manifest.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Declarative extension manifest (`extensions.json`) that lives next to a
+ * module's `pgpm.plan` / `.control`. It makes a module self-describing about
+ * the PostgreSQL extensions it relates to:
+ *
+ * - `provides` — the module *is* the extension wrapper: it installs the
+ *   extension into a chosen schema (with grants). This is what replaces the
+ *   dynamic `DO $$ EXECUTE 'CREATE EXTENSION ... SCHEMA x' $$` hack, since a
+ *   literal `CREATE EXTENSION` is stripped at package time.
+ * - `consumes` — the module merely *uses* symbols from an extension installed
+ *   elsewhere (e.g. a bare `crypt()` call) and needs them qualified to wherever
+ *   the extension actually landed. This is the transform/routing side.
+ *
+ * `.control` `requires` still names the extension (dependency ordering is
+ * unchanged); this manifest only adds the *where + grants* that `.control`
+ * cannot express.
+ */
+/** Candidate file names, in precedence order. */
+export declare const EXTENSIONS_MANIFEST_FILES: readonly ["pgpm.extensions.json", "extensions.json"];
+/**
+ * What a declared grant targets. Kept structural (not free-form SQL) so it can
+ * be classified, role-routed, and reverted deterministically.
+ */
+export type ExtensionGrantTarget = 'schema' | 'all-tables' | 'all-sequences' | 'all-functions';
+export interface ExtensionGrant {
+    /** Privilege list, e.g. `USAGE`, `ALL`, `EXECUTE`, `SELECT`. */
+    privileges: string;
+    /** Object class the grant applies to, resolved against the install schema. */
+    on: ExtensionGrantTarget;
+    /** Role name(s). Routed through the workspace role map when one is supplied. */
+    to: string | string[];
+}
+export interface ExtensionProvide {
+    /**
+     * Target schema for the install. A string routes the extension there; `null`
+     * means default/unqualified (control-file location, typically `public`).
+     */
+    schema?: string | null;
+    /**
+     * Author's assertion that the extension is relocatable. Defaults to `true`.
+     * A fixed-schema (`false`) extension must not be routed to a schema that
+     * differs from its control-file schema — {@link compileExtensionInstall}
+     * refuses that combination.
+     */
+    relocatable?: boolean;
+    /** Emit `IF NOT EXISTS` on `CREATE EXTENSION`. Defaults to `true`. */
+    ifNotExists?: boolean;
+    /** Emit `CASCADE` on `CREATE EXTENSION`. Defaults to `false`. */
+    cascade?: boolean;
+    /**
+     * Create `schema` before installing (idempotent). Defaults to `true` when a
+     * schema is given. Set `false` when the schema is owned by another module.
+     */
+    createSchema?: boolean;
+    /** Also `DROP SCHEMA` on revert. Defaults to `false` (only drop the extension). */
+    dropSchema?: boolean;
+    /** Grants applied after install. */
+    grants?: ExtensionGrant[];
+}
+export interface ExtensionConsume {
+    /** Bare symbol names this module references (functions/types/operators). */
+    symbols?: string[];
+}
+export interface ExtensionsManifest {
+    provides?: Record<string, ExtensionProvide>;
+    consumes?: Record<string, ExtensionConsume>;
+}
+/**
+ * Validate + normalize a parsed manifest object. Throws with a precise message
+ * on malformed input so authors get actionable errors rather than silent
+ * misconfiguration.
+ */
+export declare function validateExtensionsManifest(raw: unknown, source?: string): ExtensionsManifest;
+/**
+ * Read + validate the `extensions.json` (or `pgpm.extensions.json`) manifest for
+ * a module directory. Returns `undefined` when the module declares no manifest.
+ */
+export declare function readExtensionsManifest(moduleDir: string): ExtensionsManifest | undefined;