@pgpmjs/ast 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @pgpmjs/ast
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/@pgpmjs/ast"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=pgpm%2Fast%2Fpackage.json"/></a>
+</p>
+
+The pgpm **module AST** — the plan/control/SQL-header parsers (`files/*`) and the
+lossless module read/write layer (`module/*`) that composes them into a single typed
+`PgpmModuleAst`.
+
+- `readModule(dir)` / `parseModule(dir)` — parse a pgpm module directory into a typed AST.
+- `writeModule(ast, { outDir })` / `deparseModule(ast)` — serialize the AST back to a
+  module (byte-lossless for modules read via `readModule`).
+- `files/*` — the low-level parsers/writers everything else composes; no re-implementation.
+
+This package is a pure leaf (no database, no deploy engine). `@pgpmjs/core` and the
+migration-bundle artifact layer build on top of it. See the `pgpm-migration-bundle` skill
+for how the bundle layer uses this AST.
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/files/extension/index.js

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

package/esm/files/extension/reader.js

@@ -0,0 +1,79 @@
+import { readFileSync } from 'fs';
+import { basename, dirname, relative } from 'path';
+import { parsePlanFileSimple } from '../plan';
+/**
+ * Parse a .control file and extract its metadata.
+ * https://www.postgresql.org/docs/current/extend-extensions.html
+ */
+export function parseControlFile(filePath, basePath) {
+    const contents = readFileSync(filePath, 'utf-8');
+    const key = basename(filePath).split('.control')[0];
+    const requires = contents
+        .split('\n')
+        .find((line) => /^requires/.test(line))
+        ?.split('=')[1]
+        .split(',')
+        .map((req) => req.replace(/[\'\s]*/g, '').trim()) || [];
+    const version = contents
+        .split('\n')
+        .find((line) => /^default_version/.test(line))
+        ?.split('=')[1]
+        .replace(/[\']*/g, '')
+        .trim() || '';
+    return {
+        path: dirname(relative(basePath, filePath)),
+        requires,
+        version,
+    };
+}
+/**
+ * Parse the pgpm.plan file to get the extension name.
+ */
+export const getExtensionName = (packageDir) => {
+    const planPath = `${packageDir}/pgpm.plan`;
+    const plan = parsePlanFileSimple(planPath);
+    if (!plan.package) {
+        throw new Error('No package name found in pgpm.plan!');
+    }
+    return plan.package;
+};
+/**
+ * Get detailed information about an extension in the specified directory.
+ */
+export const getExtensionInfo = (packageDir) => {
+    const pkgPath = `${packageDir}/package.json`;
+    const pkg = require(pkgPath);
+    const extname = getExtensionName(packageDir);
+    const version = pkg.version;
+    const Makefile = `${packageDir}/Makefile`;
+    const controlFile = `${packageDir}/${extname}.control`;
+    const sqlFile = `sql/${extname}--${version}.sql`;
+    return { extname, packageDir, version, Makefile, controlFile, sqlFile };
+};
+/**
+ * Get a list of extensions required by an extension from its control file.
+ * Returns an empty array if the file doesn't exist or has no requires line.
+ */
+export const getInstalledExtensions = (controlFilePath) => {
+    try {
+        const contents = readFileSync(controlFilePath, 'utf-8');
+        const match = contents.match(/^\s*requires\s*=\s*'([^']*)'/m);
+        if (!match) {
+            return [];
+        }
+        const requiresValue = match[1];
+        if (!requiresValue || requiresValue.trim() === '') {
+            return [];
+        }
+        return requiresValue
+            .split(',')
+            .map((ext) => ext.trim())
+            .filter((ext) => ext.length > 0);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            return [];
+        }
+        throw new Error(`Error reading control file at ${controlFilePath}: ${e.message}`);
+    }
+};

package/esm/files/extension/writer.js

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { getExtensionInfo } from './reader';
+/**
+ * Write the Makefile for the extension.
+ */
+export const writeExtensionMakefile = (outputPath, extname, version) => {
+    const content = `EXTENSION = ${extname}
+DATA = sql/${extname}--${version}.sql
+
+PG_CONFIG = pg_config
+PGXS := $(shell $(PG_CONFIG) --pgxs)
+include $(PGXS)
+  `;
+    writeFileSync(outputPath, content);
+};
+/**
+ * Generate content for a .control file
+ * https://www.postgresql.org/docs/current/extend-extensions.html
+ */
+export function generateControlFileContent(options) {
+    const { name, version, comment = `${name} extension`, requires = [], default_version = version, relocatable = false, superuser = false, schema, module_pathname } = options;
+    let content = `# ${name} extension
+comment = '${comment}'
+default_version = '${default_version}'
+`;
+    if (module_pathname) {
+        content += `module_pathname = '${module_pathname}'\n`;
+    }
+    else {
+        content += `module_pathname = '$libdir/${name}'\n`;
+    }
+    if (requires.length > 0) {
+        content += `requires = '${requires.join(',')}'\n`;
+    }
+    content += `relocatable = ${relocatable}
+superuser = ${superuser}\n`;
+    if (schema) {
+        content += `schema = ${schema}\n`;
+    }
+    return content;
+}
+/**
+ * Update (or insert/remove) the `requires =` line of an existing .control file
+ * in place, preserving every other field and the file's formatting. Used when
+ * changing a module's dependencies after init (e.g. via `pgpm extension`) so
+ * hand-tuned fields (comment, schema, relocatable, module_pathname) survive.
+ */
+export function upsertRequiresLine(content, requires) {
+    const lines = content.split('\n');
+    const idx = lines.findIndex((line) => /^\s*requires\s*=/.test(line));
+    if (requires.length === 0) {
+        if (idx !== -1)
+            lines.splice(idx, 1);
+        return lines.join('\n');
+    }
+    const requiresLine = `requires = '${requires.join(',')}'`;
+    if (idx !== -1) {
+        lines[idx] = requiresLine;
+        return lines.join('\n');
+    }
+    // Insert to match generated ordering (before relocatable/superuser/schema).
+    const insertAt = lines.findIndex((line) => /^\s*(relocatable|superuser|schema)\s*=/.test(line));
+    if (insertAt !== -1) {
+        lines.splice(insertAt, 0, requiresLine);
+    }
+    else {
+        lines.push(requiresLine);
+    }
+    return lines.join('\n');
+}
+/**
+ * Write the control file for the extension.
+ * If the file already exists, only its `requires` line is updated so that any
+ * custom fields are preserved; otherwise a fresh file is generated.
+ */
+export const writeExtensionControlFile = (outputPath, extname, extensions, version) => {
+    if (existsSync(outputPath)) {
+        const existing = readFileSync(outputPath, 'utf-8');
+        writeFileSync(outputPath, upsertRequiresLine(existing, extensions));
+        return;
+    }
+    const content = generateControlFileContent({
+        name: extname,
+        version,
+        requires: extensions
+    });
+    writeFileSync(outputPath, content);
+};
+/**
+ * Write control and Makefile for the extension with given data.
+ * If extInfo is not provided, it will be generated from packageDir.
+ */
+export const writeExtensions = (packageDir, extensions, extInfo) => {
+    // If extInfo is not provided, get it from packageDir
+    const info = extInfo || getExtensionInfo(packageDir);
+    const { controlFile, Makefile, extname, version } = info;
+    writeExtensionControlFile(controlFile, extname, extensions, version);
+    writeExtensionMakefile(Makefile, extname, version);
+};

package/esm/files/index.js

@@ -0,0 +1,6 @@
+// Re-export all functionality from package-files
+export * from './extension';
+export * from './plan';
+export * from './sql';
+export * from './sql-scripts';
+export * from './types';

package/esm/files/plan/generator.js

@@ -0,0 +1,82 @@
+import fs from 'fs';
+/**
+ * Fixed epoch timestamp used for deterministic plan generation.
+ * Can be overridden with the PGPM_FROZEN_TIME environment variable.
+ */
+const DEFAULT_FROZEN_TIME = '2017-08-11T08:11:51Z';
+/**
+ * Get a UTC timestamp string from a Date object.
+ */
+function getUTCTimestamp(d) {
+    return (d.getUTCFullYear() +
+        '-' + String(d.getUTCMonth() + 1).padStart(2, '0') +
+        '-' + String(d.getUTCDate()).padStart(2, '0') +
+        'T' + String(d.getUTCHours()).padStart(2, '0') +
+        ':' + String(d.getUTCMinutes()).padStart(2, '0') +
+        ':' + String(d.getUTCSeconds()).padStart(2, '0') +
+        'Z');
+}
+/**
+ * Get a timestamp for the plan file.
+ * Uses the PGPM_FROZEN_TIME env var if present, otherwise the fixed epoch.
+ */
+export function getNow() {
+    const frozen = process.env.PGPM_FROZEN_TIME;
+    if (frozen) {
+        return getUTCTimestamp(new Date(frozen));
+    }
+    return DEFAULT_FROZEN_TIME;
+}
+/**
+ * Sort dependencies by their order in the supplied plan, so prerequisites
+ * (parent migrations) appear before their dependents in the bracket.
+ * Internal dependencies are sorted by their plan index, and external
+ * dependencies (not in the plan) preserve their original order.
+ */
+const sortDependencies = (deps, order) => {
+    const originalOrder = new Map(deps.map((dep, index) => [dep, index]));
+    return [...deps].sort((a, b) => {
+        const aIndex = order.get(a);
+        const bIndex = order.get(b);
+        const aOriginal = originalOrder.get(a);
+        const bOriginal = originalOrder.get(b);
+        if (aIndex !== undefined && bIndex !== undefined)
+            return aIndex - bIndex || aOriginal - bOriginal;
+        if (aIndex !== undefined)
+            return -1;
+        if (bIndex !== undefined)
+            return 1;
+        return aOriginal - bOriginal;
+    });
+};
+/**
+ * Generate a plan file content from structured data
+ */
+export function generatePlan(options) {
+    const { moduleName, uri, entries } = options;
+    const now = getNow();
+    const planfile = [
+        `%syntax-version=1.0.0`,
+        `%project=${moduleName}`,
+        `%uri=${uri || moduleName}`
+    ];
+    // Build an order map from the entry list so brackets can be sorted by plan order
+    const entryOrder = new Map(entries.map((entry, index) => [entry.change, index]));
+    // Generate the plan entries
+    entries.forEach(entry => {
+        const deps = sortDependencies(entry.dependencies || [], entryOrder);
+        if (deps.length > 0) {
+            planfile.push(`${entry.change} [${deps.join(' ')}] ${now} constructive <constructive@5b0c196eeb62>${entry.comment ? ` # ${entry.comment}` : ''}`);
+        }
+        else {
+            planfile.push(`${entry.change} ${now} constructive <constructive@5b0c196eeb62>${entry.comment ? ` # ${entry.comment}` : ''}`);
+        }
+    });
+    return planfile.join('\n');
+}
+/**
+ * Write a generated plan file to disk
+ */
+export function writePlan(planPath, plan) {
+    fs.writeFileSync(planPath, plan);
+}

package/esm/files/plan/index.js

@@ -0,0 +1,5 @@
+// Re-export all plan functionality
+export * from './generator';
+export * from './parser';
+export * from './validators';
+export * from './writer';