@pgpmjs/core 7.15.0 → 7.17.0

package/extensions/manifest.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTENSIONS_MANIFEST_FILES = void 0;
+exports.validateExtensionsManifest = validateExtensionsManifest;
+exports.readExtensionsManifest = readExtensionsManifest;
+const fs_1 = require("fs");
+const path_1 = require("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. */
+exports.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.
+ */
+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.
+ */
+function readExtensionsManifest(moduleDir) {
+    for (const file of exports.EXTENSIONS_MANIFEST_FILES) {
+        const p = (0, path_1.join)(moduleDir, file);
+        if ((0, fs_1.existsSync)(p)) {
+            let parsed;
+            try {
+                parsed = JSON.parse((0, fs_1.readFileSync)(p, 'utf-8'));
+            }
+            catch (e) {
+                throw new Error(`Failed to parse ${file} at ${moduleDir}: ${e.message}`);
+            }
+            return validateExtensionsManifest(parsed, file);
+        }
+    }
+    return undefined;
+}

package/extensions/resolve-install.d.ts

@@ -0,0 +1,20 @@
+import { RoleMapping } from '@pgpmjs/types';
+import { CompiledExtensionInstall, CompileExtensionInstallOptions } from './compile';
+/**
+ * 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 declare function roleMapFromRoles(roles?: RoleMapping): Record<string, string> | 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 declare function findExtensionInstall(extname: string, localModules: string[], modules: Record<string, {
+    path: string;
+}>, workspacePath: string, options?: CompileExtensionInstallOptions): CompiledExtensionInstall | undefined;

package/extensions/resolve-install.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.roleMapFromRoles = roleMapFromRoles;
+exports.findExtensionInstall = findExtensionInstall;
+const path_1 = require("path");
+const compile_1 = require("./compile");
+const manifest_1 = require("./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.
+ */
+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.
+ */
+function findExtensionInstall(extname, localModules, modules, workspacePath, options = {}) {
+    let winner;
+    for (const moduleName of localModules) {
+        const mod = modules[moduleName];
+        if (!mod)
+            continue;
+        const manifest = (0, manifest_1.readExtensionsManifest)((0, path_1.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 ? (0, compile_1.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/index.d.ts

@@ -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/index.js

@@ -17,7 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.withTransaction = exports.executeQuery = exports.hashString = exports.hashFile = exports.parseAuthor = exports.PgpmInit = exports.PgpmMigrate = exports.cleanSql = void 0;
 __exportStar(require("./core/class/pgpm"), exports);
 __exportStar(require("./rebundle"), exports);
-__exportStar(require("./extensions/extensions"), exports);
+__exportStar(require("./extensions"), exports);
 __exportStar(require("./modules/modules"), exports);
 __exportStar(require("./packaging/package"), exports);
 __exportStar(require("./packaging/sync-versions"), exports);

package/migrate/clean.js

@@ -5,8 +5,7 @@ const pgsql_parser_1 = require("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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpmjs/core",
-  "version": "7.15.0",
+  "version": "7.17.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PGPM Package and Migration Tools",
   "main": "index.js",
@@ -48,24 +48,24 @@
     "makage": "^0.3.0"
   },
   "dependencies": {
-    "@pgpmjs/ast": "^0.9.2",
-    "@pgpmjs/bundle": "^0.12.0",
-    "@pgpmjs/env": "^2.38.0",
+    "@pgpmjs/ast": "^0.9.4",
+    "@pgpmjs/bundle": "^0.12.2",
+    "@pgpmjs/env": "^2.39.1",
     "@pgpmjs/logger": "^2.22.0",
-    "@pgpmjs/server-utils": "^3.23.1",
-    "@pgpmjs/slice": "^0.10.1",
-    "@pgpmjs/transform": "^0.11.0",
-    "@pgpmjs/types": "^2.46.0",
+    "@pgpmjs/server-utils": "^3.23.3",
+    "@pgpmjs/slice": "^0.11.0",
+    "@pgpmjs/transform": "^0.12.0",
+    "@pgpmjs/types": "^2.48.0",
     "csv-to-pg": "^4.8.0",
     "genomic": "^5.6.2",
     "glob": "^13.0.6",
     "parse-package-name": "^1.0.0",
     "pg": "^8.21.0",
-    "pg-cache": "^3.23.1",
+    "pg-cache": "^3.23.3",
     "pg-env": "^1.26.0",
     "pgsql-deparser": "^18.1.1",
     "pgsql-parser": "^18.1.1",
     "yanse": "^0.2.1"
   },
-  "gitHead": "5ef8341033a8fbd85841b770e996e468dd15333b"
+  "gitHead": "2832d5632d11eb22e1437df773706ac6a99175fe"
 }

package/projects/deploy.js

@@ -44,6 +44,7 @@ const materialize_1 = require("../apply/materialize");
 const apply_spec_1 = require("../apply/apply-spec");
 const deploy_bundled_1 = require("../bundle/deploy-bundled");
 const pgpm_1 = require("../core/class/pgpm");
+const extensions_1 = require("../extensions");
 const client_1 = require("../migrate/client");
 const deps_1 = require("../resolution/deps");
 const log = new logger_1.Logger('deploy');
@@ -63,14 +64,28 @@ const deployProject = async (opts, name, database, pkg, toChange) => {
         ? (0, deps_1.resolveExtensionDependencies)(name, modules)
         : new pgpm_1.PgpmPackage(modulePath, { extensionsDir: pkg.extensionsDir }).getModuleExtensions();
     const pgPool = (0, pg_cache_1.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 = (0, extensions_1.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 = (0, extensions_1.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 = (0, path_1.resolve)(pkg.workspacePath, modules[extension].path);