@pgpmjs/types 2.11.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,89 @@
+# @launchql/types
+
+<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/@launchql/types"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=packages%2Ftypes%2Fpackage.json"/></a>
+</p>
+
+---
+
+## 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
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/packages/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/packages/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/packages/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/packages/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.
+* [pg-ast](https://www.npmjs.com/package/pg-ast): **🔍 Low-level AST tools** and transformations for Postgres query structures.
+
+### 🚀 API & Dev Tools
+
+* [launchql/server](https://github.com/constructive-io/constructive/tree/main/packages/server): **⚡ Express-based API server** powered by PostGraphile to expose a secure, scalable GraphQL API over your Postgres database.
+* [launchql/explorer](https://github.com/constructive-io/constructive/tree/main/packages/explorer): **🔎 Visual API explorer** with GraphiQL for browsing across all databases and schemas—useful for debugging, documentation, and API prototyping.
+
+### 🔁 Streaming & Uploads
+
+* [launchql/s3-streamer](https://github.com/constructive-io/constructive/tree/main/packages/s3-streamer): **📤 Direct S3 streaming** for large files with support for metadata injection and content validation.
+* [launchql/etag-hash](https://github.com/constructive-io/constructive/tree/main/packages/etag-hash): **🏷️ S3-compatible ETags** created by streaming and hashing file uploads in chunks.
+* [launchql/etag-stream](https://github.com/constructive-io/constructive/tree/main/packages/etag-stream): **🔄 ETag computation** via Node stream transformer during upload or transfer.
+* [launchql/uuid-hash](https://github.com/constructive-io/constructive/tree/main/packages/uuid-hash): **🆔 Deterministic UUIDs** generated from hashed content, great for deduplication and asset referencing.
+* [launchql/uuid-stream](https://github.com/constructive-io/constructive/tree/main/packages/uuid-stream): **🌊 Streaming UUID generation** based on piped file content—ideal for upload pipelines.
+* [launchql/upload-names](https://github.com/constructive-io/constructive/tree/main/packages/upload-names): **📂 Collision-resistant filenames** utility for structured and unique file names for uploads.
+
+### 🧰 CLI & Codegen
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/packages/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+* [@launchql/cli](https://github.com/constructive-io/constructive/tree/main/packages/cli): **🖥️ Command-line toolkit** for managing LaunchQL projects—supports database scaffolding, migrations, seeding, code generation, and automation.
+* [constructive-io/constructive-gen](https://github.com/constructive-io/constructive/tree/main/packages/launchql-gen): **✨ Auto-generated GraphQL** mutations and queries dynamically built from introspected schema data.
+* [@launchql/query-builder](https://github.com/constructive-io/constructive/tree/main/packages/query-builder): **🏗️ SQL constructor** providing a robust TypeScript-based query builder for dynamic generation of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and stored procedure calls—supports advanced SQL features like `JOIN`, `GROUP BY`, and schema-qualified queries.
+* [@launchql/query](https://github.com/constructive-io/constructive/tree/main/packages/query): **🧩 Fluent GraphQL builder** for PostGraphile schemas. ⚡ Schema-aware via introspection, 🧩 composable and ergonomic for building deeply nested queries.
+
+## 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/error-factory.d.ts

@@ -0,0 +1,59 @@
+import { PgpmError } from './error';
+type ErrorContext = Record<string, string | number | boolean>;
+export declare const makeError: <T extends ErrorContext>(code: string, messageFn: (context: T) => string, httpCode?: number) => (context: T, overrideMessage?: string) => PgpmError;
+export declare const errors: {
+    NOT_FOUND: (context: ErrorContext, overrideMessage?: string) => PgpmError;
+    MODULE_NOT_FOUND: (context: {
+        name: string;
+    }, overrideMessage?: string) => PgpmError;
+    NO_ACCOUNT_EXISTS: (context: ErrorContext, overrideMessage?: string) => PgpmError;
+    INTERNAL_FAILURE: (context: ErrorContext, overrideMessage?: string) => PgpmError;
+    CONTEXT_MISSING: (context: ErrorContext, overrideMessage?: string) => PgpmError;
+    NOT_IN_WORKSPACE: (context: ErrorContext, overrideMessage?: string) => PgpmError;
+    NOT_IN_WORKSPACE_MODULE: (context: ErrorContext, overrideMessage?: string) => PgpmError;
+    DEPLOYMENT_FAILED: (context: {
+        type: "Deployment" | "Revert" | "Verify";
+        module: string;
+    }, overrideMessage?: string) => PgpmError;
+    UNSUPPORTED_TYPE_HINT: (context: ErrorContext, overrideMessage?: string) => PgpmError;
+    BAD_FILE_NAME: (context: ErrorContext, overrideMessage?: string) => PgpmError;
+    UNKNOWN_COMMAND: (context: ErrorContext, overrideMessage?: string) => PgpmError;
+    CHANGE_NOT_FOUND: (context: {
+        change: string;
+        plan?: string;
+    }, overrideMessage?: string) => PgpmError;
+    TAG_NOT_FOUND: (context: {
+        tag: string;
+        project?: string;
+    }, overrideMessage?: string) => PgpmError;
+    PATH_NOT_FOUND: (context: {
+        path: string;
+        type: "module" | "workspace" | "file";
+    }, overrideMessage?: string) => PgpmError;
+    OPERATION_FAILED: (context: {
+        operation: string;
+        target?: string;
+        reason?: string;
+    }, overrideMessage?: string) => PgpmError;
+    PLAN_PARSE_ERROR: (context: {
+        planPath: string;
+        errors: string;
+    }, overrideMessage?: string) => PgpmError;
+    CIRCULAR_DEPENDENCY: (context: {
+        module: string;
+        dependency: string;
+    }, overrideMessage?: string) => PgpmError;
+    INVALID_NAME: (context: {
+        name: string;
+        type: "tag" | "change" | "module";
+        rules?: string;
+    }, overrideMessage?: string) => PgpmError;
+    WORKSPACE_OPERATION_ERROR: (context: {
+        operation: string;
+    }, overrideMessage?: string) => PgpmError;
+    FILE_NOT_FOUND: (context: {
+        filePath: string;
+        type?: string;
+    }, overrideMessage?: string) => PgpmError;
+};
+export {};

package/error-factory.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errors = exports.makeError = void 0;
+const error_1 = require("./error");
+const makeError = (code, messageFn, httpCode) => {
+    return (context, overrideMessage) => {
+        const message = overrideMessage || messageFn(context);
+        return new error_1.PgpmError(code, message, context, httpCode);
+    };
+};
+exports.makeError = makeError;
+exports.errors = {
+    NOT_FOUND: (0, exports.makeError)('NOT_FOUND', () => `Not found.`, 404),
+    MODULE_NOT_FOUND: (0, exports.makeError)('MODULE_NOT_FOUND', ({ name }) => `Module "${name}" not found in modules list.`, 404),
+    NO_ACCOUNT_EXISTS: (0, exports.makeError)('NO_ACCOUNT_EXISTS', ({ userId }) => `No account exists for user: ${userId}`, 404),
+    INTERNAL_FAILURE: (0, exports.makeError)('INTERNAL_FAILURE', ({ details }) => `Something went wrong: ${details}`, 500),
+    CONTEXT_MISSING: (0, exports.makeError)('CONTEXT_MISSING', () => `Context is not initialized. Did you run setup()?`, 500),
+    NOT_IN_WORKSPACE: (0, exports.makeError)('NOT_IN_WORKSPACE', () => `You must be in a PGPM workspace. Initialize with "pgpm init workspace".`, 400),
+    NOT_IN_WORKSPACE_MODULE: (0, exports.makeError)('NOT_IN_WORKSPACE_MODULE', () => `Error: You must be inside one of the workspace packages.`, 400),
+    DEPLOYMENT_FAILED: (0, exports.makeError)('DEPLOYMENT_FAILED', ({ type, module }) => `${type} failed for module: ${module}`, 500),
+    UNSUPPORTED_TYPE_HINT: (0, exports.makeError)('UNSUPPORTED_TYPE_HINT', ({ typeHint }) => `Unsupported type hint: ${typeHint}`, 400),
+    BAD_FILE_NAME: (0, exports.makeError)('BAD_FILE_NAME', ({ name }) => `Invalid file name: ${name}`, 400),
+    UNKNOWN_COMMAND: (0, exports.makeError)('UNKNOWN_COMMAND', ({ cmd }) => `Unknown command: ${cmd}`, 400),
+    CHANGE_NOT_FOUND: (0, exports.makeError)('CHANGE_NOT_FOUND', ({ change, plan }) => `Change '${change}' not found in plan${plan ? ` file: ${plan}` : ''}`, 404),
+    TAG_NOT_FOUND: (0, exports.makeError)('TAG_NOT_FOUND', ({ tag, project }) => `Tag '${tag}' not found${project ? ` in project ${project}` : ' in plan'}`, 404),
+    PATH_NOT_FOUND: (0, exports.makeError)('PATH_NOT_FOUND', ({ path, type }) => `${type} path not found: ${path}`, 404),
+    OPERATION_FAILED: (0, exports.makeError)('OPERATION_FAILED', ({ operation, target, reason }) => `${operation} failed${target ? ` for ${target}` : ''}${reason ? `: ${reason}` : ''}`, 500),
+    PLAN_PARSE_ERROR: (0, exports.makeError)('PLAN_PARSE_ERROR', ({ planPath, errors }) => `Failed to parse plan file ${planPath}: ${errors}`, 400),
+    CIRCULAR_DEPENDENCY: (0, exports.makeError)('CIRCULAR_DEPENDENCY', ({ module, dependency }) => `Circular reference detected: ${module} → ${dependency}`, 400),
+    INVALID_NAME: (0, exports.makeError)('INVALID_NAME', ({ name, type, rules }) => `Invalid ${type} name: ${name}${rules ? `. ${rules}` : ''}`, 400),
+    WORKSPACE_OPERATION_ERROR: (0, exports.makeError)('WORKSPACE_OPERATION_ERROR', ({ operation }) => `Cannot perform non-recursive ${operation} on workspace. Use recursive=true or specify a target module.`, 400),
+    FILE_NOT_FOUND: (0, exports.makeError)('FILE_NOT_FOUND', ({ filePath, type }) => `${type ? `${type} file` : 'File'} not found: ${filePath}`, 404),
+};
+// throw errors.MODULE_NOT_FOUND({ name: 'auth' });
+// throw errors.INTERNAL_FAILURE({ details: 'Could not connect to DB' });
+// throw errors.UNKNOWN_COMMAND({ cmd: 'foo' }, 'Unsupported command "foo"');
+// throw errors.CONTEXT_MISSING(();

package/error.d.ts

@@ -0,0 +1,7 @@
+export declare class PgpmError extends Error {
+    code: string;
+    context?: any;
+    httpCode?: number;
+    constructor(code: string, message: string, context?: any, httpCode?: number);
+    toString(): string;
+}

package/error.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgpmError = void 0;
+class PgpmError extends Error {
+    code;
+    context;
+    httpCode;
+    constructor(code, message, context, httpCode) {
+        super(message);
+        this.name = 'PgpmError';
+        this.code = code;
+        this.context = context;
+        this.httpCode = httpCode;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, PgpmError);
+        }
+    }
+    toString() {
+        return `[${this.code}] ${this.message}`;
+    }
+}
+exports.PgpmError = PgpmError;

package/esm/error-factory.js

@@ -0,0 +1,33 @@
+import { PgpmError } from './error';
+export const makeError = (code, messageFn, httpCode) => {
+    return (context, overrideMessage) => {
+        const message = overrideMessage || messageFn(context);
+        return new PgpmError(code, message, context, httpCode);
+    };
+};
+export const errors = {
+    NOT_FOUND: makeError('NOT_FOUND', () => `Not found.`, 404),
+    MODULE_NOT_FOUND: makeError('MODULE_NOT_FOUND', ({ name }) => `Module "${name}" not found in modules list.`, 404),
+    NO_ACCOUNT_EXISTS: makeError('NO_ACCOUNT_EXISTS', ({ userId }) => `No account exists for user: ${userId}`, 404),
+    INTERNAL_FAILURE: makeError('INTERNAL_FAILURE', ({ details }) => `Something went wrong: ${details}`, 500),
+    CONTEXT_MISSING: makeError('CONTEXT_MISSING', () => `Context is not initialized. Did you run setup()?`, 500),
+    NOT_IN_WORKSPACE: makeError('NOT_IN_WORKSPACE', () => `You must be in a PGPM workspace. Initialize with "pgpm init workspace".`, 400),
+    NOT_IN_WORKSPACE_MODULE: makeError('NOT_IN_WORKSPACE_MODULE', () => `Error: You must be inside one of the workspace packages.`, 400),
+    DEPLOYMENT_FAILED: makeError('DEPLOYMENT_FAILED', ({ type, module }) => `${type} failed for module: ${module}`, 500),
+    UNSUPPORTED_TYPE_HINT: makeError('UNSUPPORTED_TYPE_HINT', ({ typeHint }) => `Unsupported type hint: ${typeHint}`, 400),
+    BAD_FILE_NAME: makeError('BAD_FILE_NAME', ({ name }) => `Invalid file name: ${name}`, 400),
+    UNKNOWN_COMMAND: makeError('UNKNOWN_COMMAND', ({ cmd }) => `Unknown command: ${cmd}`, 400),
+    CHANGE_NOT_FOUND: makeError('CHANGE_NOT_FOUND', ({ change, plan }) => `Change '${change}' not found in plan${plan ? ` file: ${plan}` : ''}`, 404),
+    TAG_NOT_FOUND: makeError('TAG_NOT_FOUND', ({ tag, project }) => `Tag '${tag}' not found${project ? ` in project ${project}` : ' in plan'}`, 404),
+    PATH_NOT_FOUND: makeError('PATH_NOT_FOUND', ({ path, type }) => `${type} path not found: ${path}`, 404),
+    OPERATION_FAILED: makeError('OPERATION_FAILED', ({ operation, target, reason }) => `${operation} failed${target ? ` for ${target}` : ''}${reason ? `: ${reason}` : ''}`, 500),
+    PLAN_PARSE_ERROR: makeError('PLAN_PARSE_ERROR', ({ planPath, errors }) => `Failed to parse plan file ${planPath}: ${errors}`, 400),
+    CIRCULAR_DEPENDENCY: makeError('CIRCULAR_DEPENDENCY', ({ module, dependency }) => `Circular reference detected: ${module} → ${dependency}`, 400),
+    INVALID_NAME: makeError('INVALID_NAME', ({ name, type, rules }) => `Invalid ${type} name: ${name}${rules ? `. ${rules}` : ''}`, 400),
+    WORKSPACE_OPERATION_ERROR: makeError('WORKSPACE_OPERATION_ERROR', ({ operation }) => `Cannot perform non-recursive ${operation} on workspace. Use recursive=true or specify a target module.`, 400),
+    FILE_NOT_FOUND: makeError('FILE_NOT_FOUND', ({ filePath, type }) => `${type ? `${type} file` : 'File'} not found: ${filePath}`, 404),
+};
+// throw errors.MODULE_NOT_FOUND({ name: 'auth' });
+// throw errors.INTERNAL_FAILURE({ details: 'Could not connect to DB' });
+// throw errors.UNKNOWN_COMMAND({ cmd: 'foo' }, 'Unsupported command "foo"');
+// throw errors.CONTEXT_MISSING(();

package/esm/error.js

@@ -0,0 +1,18 @@
+export class PgpmError extends Error {
+    code;
+    context;
+    httpCode;
+    constructor(code, message, context, httpCode) {
+        super(message);
+        this.name = 'PgpmError';
+        this.code = code;
+        this.context = context;
+        this.httpCode = httpCode;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, PgpmError);
+        }
+    }
+    toString() {
+        return `[${this.code}] ${this.message}`;
+    }
+}

package/esm/index.js

@@ -0,0 +1,5 @@
+export * from './error';
+export * from './error-factory';
+export * from './pgpm';
+export * from './jobs';
+export * from './update';

package/esm/jobs.js

@@ -0,0 +1,53 @@
+/**
+ * Default configuration values for job system
+ */
+export const jobsDefaults = {
+    pg: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'jobs'
+    },
+    schema: {
+        schema: 'app_jobs'
+    },
+    worker: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'jobs',
+        schema: 'app_jobs',
+        hostname: 'worker-0',
+        supportAny: true,
+        supported: [],
+        pollInterval: 1000,
+        gracefulShutdown: true
+    },
+    scheduler: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'jobs',
+        schema: 'app_jobs',
+        hostname: 'scheduler-0',
+        supportAny: true,
+        supported: [],
+        pollInterval: 1000,
+        gracefulShutdown: true
+    },
+    openFaas: {
+        gateway: {
+            gatewayUrl: 'http://gateway:8080',
+            callbackUrl: 'http://callback:12345',
+            callbackPort: 12345
+        },
+        server: {
+            schema: 'app_jobs',
+            port: 3000,
+            host: 'localhost'
+        }
+    }
+};

package/esm/pgpm.js

@@ -0,0 +1,157 @@
+import { execSync } from 'child_process';
+/**
+ * Default configuration values for PGPM framework
+ */
+export const pgpmDefaults = {
+    db: {
+        rootDb: 'postgres',
+        prefix: 'db-',
+        extensions: [],
+        cwd: process.cwd(),
+        connection: {
+            user: 'app_user',
+            password: 'app_password',
+            // TODO: check if this is used vs. roles below...
+            role: 'anonymous'
+        },
+        roles: {
+            anonymous: 'anonymous',
+            authenticated: 'authenticated',
+            administrator: 'administrator',
+            default: 'anonymous'
+        }
+    },
+    pg: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'postgres',
+    },
+    graphile: {
+        schema: [],
+        appendPlugins: [],
+        overrideSettings: {},
+        graphileBuildOptions: {},
+    },
+    server: {
+        host: 'localhost',
+        port: 3000,
+        trustProxy: false,
+        strictAuth: false,
+    },
+    features: {
+        simpleInflection: true,
+        oppositeBaseNames: true,
+        postgis: true
+    },
+    api: {
+        enableMetaApi: true,
+        exposedSchemas: [],
+        anonRole: 'administrator',
+        roleName: 'administrator',
+        defaultDatabaseId: 'hard-coded',
+        isPublic: true,
+        metaSchemas: ['collections_public', 'meta_public']
+    },
+    cdn: {
+        bucketName: 'test-bucket',
+        awsRegion: 'us-east-1',
+        awsAccessKey: 'minioadmin',
+        awsSecretKey: 'minioadmin',
+        minioEndpoint: 'http://localhost:9000'
+    },
+    deployment: {
+        useTx: true,
+        fast: false,
+        usePlan: true,
+        cache: false,
+        logOnly: false,
+        hashMethod: 'content'
+    },
+    migrations: {
+        codegen: {
+            useTx: false
+        }
+    },
+    jobs: {
+        pg: {
+            host: 'localhost',
+            port: 5432,
+            user: 'postgres',
+            password: 'password',
+            database: 'jobs'
+        },
+        schema: {
+            schema: 'app_jobs'
+        },
+        worker: {
+            host: 'localhost',
+            port: 5432,
+            user: 'postgres',
+            password: 'password',
+            database: 'jobs',
+            schema: 'app_jobs',
+            hostname: 'worker-0',
+            supportAny: true,
+            supported: [],
+            pollInterval: 1000,
+            gracefulShutdown: true
+        },
+        scheduler: {
+            host: 'localhost',
+            port: 5432,
+            user: 'postgres',
+            password: 'password',
+            database: 'jobs',
+            schema: 'app_jobs',
+            hostname: 'scheduler-0',
+            supportAny: true,
+            supported: [],
+            pollInterval: 1000,
+            gracefulShutdown: true
+        },
+        openFaas: {
+            gateway: {
+                gatewayUrl: 'http://gateway:8080',
+                callbackUrl: 'http://callback:12345',
+                callbackPort: 12345
+            },
+            server: {
+                schema: 'app_jobs',
+                port: 3000,
+                host: 'localhost'
+            }
+        }
+    }
+};
+export function getGitConfigInfo() {
+    const isTestEnv = process.env.NODE_ENV === 'test' ||
+        process.env.NODE_ENV === 'testing' || // fallback
+        process.env.GITHUB_ACTIONS === 'true'; // GitHub Actions
+    if (isTestEnv) {
+        return {
+            username: 'CI Test User',
+            email: 'ci@example.com'
+        };
+    }
+    let username = '';
+    let email = '';
+    try {
+        username = execSync('git config --global user.name', {
+            encoding: 'utf8'
+        }).trim();
+    }
+    catch {
+        username = '';
+    }
+    try {
+        email = execSync('git config --global user.email', {
+            encoding: 'utf8'
+        }).trim();
+    }
+    catch {
+        email = '';
+    }
+    return { username, email };
+}

package/esm/update.js

@@ -0,0 +1,3 @@
+export const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+export const UPDATE_CHECK_APPSTASH_KEY = 'pgpm-update-check';
+export const UPDATE_PACKAGE_NAME = 'pgpm';

package/index.d.ts

@@ -0,0 +1,5 @@
+export * from './error';
+export * from './error-factory';
+export * from './pgpm';
+export * from './jobs';
+export * from './update';

package/index.js

@@ -0,0 +1,21 @@
+"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("./error"), exports);
+__exportStar(require("./error-factory"), exports);
+__exportStar(require("./pgpm"), exports);
+__exportStar(require("./jobs"), exports);
+__exportStar(require("./update"), exports);

package/jobs.d.ts

@@ -0,0 +1,198 @@
+import { PgConfig } from 'pg-env';
+/**
+ * Job system PostgreSQL configuration
+ * Extends the base PgConfig with job-specific database settings
+ */
+export interface JobPgConfig extends PgConfig {
+    /** Database name for job system (defaults to 'jobs') */
+    database: string;
+}
+/**
+ * Job schema configuration
+ */
+export interface JobSchemaConfig {
+    /** PostgreSQL schema name for job tables and functions (defaults to 'app_jobs') */
+    schema: string;
+}
+/**
+ * Worker/Scheduler hostname configuration
+ */
+export interface JobHostnameConfig {
+    /** Unique identifier for the worker or scheduler instance */
+    hostname: string;
+}
+/**
+ * Job task support configuration
+ */
+export interface JobTaskSupportConfig {
+    /** Whether to support any/all task types (defaults to true) */
+    supportAny: boolean;
+    /** Array of explicitly supported task names */
+    supported: string[];
+}
+/**
+ * OpenFaaS job system gateway configuration
+ */
+export interface JobGatewayConfig {
+    /** Internal gateway URL for OpenFaaS function calls */
+    gatewayUrl: string;
+    /** Callback URL for job completion notifications */
+    callbackUrl: string;
+    /** Port for internal job callback server (defaults to 12345) */
+    callbackPort: number;
+}
+/**
+ * Parameters for failing a job
+ */
+export interface FailJobParams {
+    /** Worker ID that is failing the job */
+    workerId: string;
+    /** Job ID to fail */
+    jobId: number | string;
+    /** Error message or reason for failure */
+    message: string;
+}
+/**
+ * Parameters for completing a job
+ */
+export interface CompleteJobParams {
+    /** Worker ID that completed the job */
+    workerId: string;
+    /** Job ID to mark as complete */
+    jobId: number | string;
+}
+/**
+ * Parameters for getting a job from the queue
+ */
+export interface GetJobParams {
+    /** Worker ID requesting a job */
+    workerId: string;
+    /**
+     * Array of task names this worker supports.
+     * When `null`, the job system will consider any task as supported.
+     */
+    supportedTaskNames: string[] | null;
+}
+/**
+ * Parameters for getting a scheduled job
+ */
+export interface GetScheduledJobParams {
+    /** Worker ID requesting a scheduled job */
+    workerId: string;
+    /**
+     * Array of task names this worker supports.
+     * When `null`, the scheduler will consider any task as supported.
+     */
+    supportedTaskNames: string[] | null;
+}
+/**
+ * Parameters for running a scheduled job
+ */
+export interface RunScheduledJobParams {
+    /** Job ID to run */
+    jobId: number | string;
+}
+/**
+ * Parameters for releasing scheduled jobs
+ */
+export interface ReleaseScheduledJobsParams {
+    /** Worker ID releasing the jobs */
+    workerId: string;
+    /**
+     * Array of job IDs to release.
+     * When omitted, all scheduled jobs for the worker may be released.
+     */
+    ids?: Array<number | string>;
+}
+/**
+ * Parameters for releasing all jobs held by a worker
+ */
+export interface ReleaseJobsParams {
+    /** Worker ID releasing all its jobs */
+    workerId: string;
+}
+/**
+ * Job record structure from database
+ */
+export interface Job {
+    /** Unique job identifier */
+    id: number | string;
+    /** Task name/type for this job */
+    task_name: string;
+    /** JSON payload data for the job */
+    payload?: any;
+    /** Worker ID currently assigned to this job */
+    worker_id?: string;
+    /** Maximum number of retry attempts */
+    max_attempts?: number;
+    /** Current attempt number */
+    attempts?: number;
+    /** Priority level for job execution */
+    priority?: number;
+    /** Timestamp when job was created */
+    created_at?: Date | string;
+    /** Timestamp when job was last updated */
+    updated_at?: Date | string;
+    /** Timestamp when job should run (for scheduled jobs) */
+    run_at?: Date | string;
+    /** Last error message if job failed */
+    last_error?: string;
+}
+/**
+ * Worker configuration options
+ */
+export interface JobWorkerConfig extends JobPgConfig, JobSchemaConfig, JobHostnameConfig, JobTaskSupportConfig {
+    /** Polling interval in milliseconds */
+    pollInterval?: number;
+    /** Whether to enable graceful shutdown */
+    gracefulShutdown?: boolean;
+}
+/**
+ * Scheduler configuration options
+ */
+export interface JobSchedulerConfig extends JobPgConfig, JobSchemaConfig, JobHostnameConfig, JobTaskSupportConfig {
+    /** Polling interval in milliseconds for checking scheduled jobs */
+    pollInterval?: number;
+    /** Whether to enable graceful shutdown */
+    gracefulShutdown?: boolean;
+}
+/**
+ * OpenFaaS worker configuration
+ */
+export interface OpenFaasJobWorkerConfig extends JobWorkerConfig, JobGatewayConfig {
+}
+/**
+ * OpenFaaS server configuration
+ */
+export interface OpenFaasJobServerConfig extends JobSchemaConfig {
+    /** Port for the job server */
+    port: number;
+    /** Host address for the job server */
+    host?: string;
+}
+/**
+ * Complete job system configuration
+ */
+export interface JobsConfig {
+    /** PostgreSQL database configuration */
+    pg?: Partial<JobPgConfig>;
+    /** Job schema configuration */
+    schema?: Partial<JobSchemaConfig>;
+    /** Worker configuration */
+    worker?: Partial<JobWorkerConfig>;
+    /** Scheduler configuration */
+    scheduler?: Partial<JobSchedulerConfig>;
+    /** OpenFaaS specific configuration */
+    openFaas?: {
+        /** OpenFaaS worker config */
+        worker?: Partial<OpenFaasJobWorkerConfig>;
+        /** OpenFaaS server config */
+        server?: Partial<OpenFaasJobServerConfig>;
+        /** Gateway config */
+        gateway?: Partial<JobGatewayConfig>;
+    };
+}
+/**
+ * Default configuration values for job system
+ */
+export declare const jobsDefaults: JobsConfig;

package/jobs.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jobsDefaults = void 0;
+/**
+ * Default configuration values for job system
+ */
+exports.jobsDefaults = {
+    pg: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'jobs'
+    },
+    schema: {
+        schema: 'app_jobs'
+    },
+    worker: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'jobs',
+        schema: 'app_jobs',
+        hostname: 'worker-0',
+        supportAny: true,
+        supported: [],
+        pollInterval: 1000,
+        gracefulShutdown: true
+    },
+    scheduler: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'jobs',
+        schema: 'app_jobs',
+        hostname: 'scheduler-0',
+        supportAny: true,
+        supported: [],
+        pollInterval: 1000,
+        gracefulShutdown: true
+    },
+    openFaas: {
+        gateway: {
+            gatewayUrl: 'http://gateway:8080',
+            callbackUrl: 'http://callback:12345',
+            callbackPort: 12345
+        },
+        server: {
+            schema: 'app_jobs',
+            port: 3000,
+            host: 'localhost'
+        }
+    }
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@pgpmjs/types",
+  "version": "2.11.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "PGPM types",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "deepmerge": "^4.3.1",
+    "graphile-build": "^4.14.1",
+    "pg-env": "^1.2.1",
+    "postgraphile": "^4.14.1"
+  },
+  "keywords": [
+    "graphql",
+    "types",
+    "typescript",
+    "pgpm",
+    "pgpmjs",
+    "schema"
+  ],
+  "devDependencies": {
+    "makage": "^0.1.8"
+  },
+  "gitHead": "e4d5396a5d9154f4886176bb00c2b460b0f320e5"
+}

package/pgpm.d.ts

@@ -0,0 +1,233 @@
+import type { Plugin } from 'graphile-build';
+import { PgConfig } from 'pg-env';
+import { PostGraphileOptions } from 'postgraphile';
+import { JobsConfig } from './jobs';
+/**
+ * Authentication options for test client sessions
+ */
+export interface AuthOptions {
+    /** Role to assume (defaults to 'authenticated' from RoleMapping config) */
+    role?: string;
+    /** User ID to set in session context */
+    userId?: string | number;
+    /** Key name for user ID in session context (defaults to 'jwt.claims.user_id') */
+    userIdKey?: string;
+}
+/**
+ * Configuration options for PostgreSQL test database connections
+ */
+export interface PgTestConnectionOptions {
+    /** The root database to connect to for creating test databases */
+    rootDb?: string;
+    /** Template database to use when creating test databases */
+    template?: string;
+    /** Prefix to add to test database names */
+    prefix?: string;
+    /** PostgreSQL extensions to install in test databases */
+    extensions?: string[];
+    /** Current working directory for database operations */
+    cwd?: string;
+    /** Database connection credentials */
+    connection?: DatabaseConnectionOptions;
+    /** Role mapping configuration */
+    roles?: RoleMapping;
+    /** Default authentication options for db connections */
+    auth?: AuthOptions;
+}
+/**
+ * PostgreSQL session context settings for test clients
+ * Used to set session variables via set_config() for RLS policies, search_path, etc.
+ */
+export interface PgTestClientContext {
+    /** PostgreSQL role to assume */
+    role?: string | null;
+    /** Additional session context variables (e.g., 'jwt.claims.user_id', 'search_path') */
+    [key: string]: string | null | undefined;
+}
+/**
+* @deprecated Use PgTestClientContext instead (typo fix)
+*/
+export type PgTextClientContext = PgTestClientContext;
+/**
+ * Role mapping configuration for database security
+ */
+export interface RoleMapping {
+    /** Anonymous (unauthenticated) role name */
+    anonymous?: string;
+    /** Authenticated user role name */
+    authenticated?: string;
+    /** Administrator role name */
+    administrator?: string;
+    /** Default role for new connections */
+    default?: string;
+}
+/**
+ * Database connection credentials
+ */
+export interface DatabaseConnectionOptions {
+    /** Database user name */
+    user?: string;
+    /** Database password */
+    password?: string;
+    /** Database role to assume */
+    role?: string;
+}
+/**
+ * HTTP server configuration
+ */
+export interface ServerOptions {
+    /** Server host address */
+    host?: string;
+    /** Server port number */
+    port?: number;
+    /** Whether to trust proxy headers */
+    trustProxy?: boolean;
+    /** CORS origin configuration */
+    origin?: string;
+    /** Whether to enforce strict authentication */
+    strictAuth?: boolean;
+}
+/**
+ * Feature flags and toggles
+ */
+export interface FeatureOptions {
+    /** Use simple inflection for GraphQL field names */
+    simpleInflection?: boolean;
+    /** Use opposite base names for relationships */
+    oppositeBaseNames?: boolean;
+    /** Enable PostGIS spatial database support */
+    postgis?: boolean;
+}
+/**
+ * PostGraphile/Graphile configuration
+ */
+export interface GraphileOptions {
+    /** Database schema(s) to expose through GraphQL */
+    schema?: string | string[];
+    /** Additional Graphile plugins to load */
+    appendPlugins?: Plugin[];
+    /** Build options for Graphile */
+    graphileBuildOptions?: PostGraphileOptions['graphileBuildOptions'];
+    /** Override settings for PostGraphile */
+    overrideSettings?: Partial<PostGraphileOptions>;
+}
+/**
+ * CDN and file storage configuration
+ */
+export interface CDNOptions {
+    /** S3 bucket name for file storage */
+    bucketName?: string;
+    /** AWS region for S3 bucket */
+    awsRegion?: string;
+    /** AWS access key for S3 */
+    awsAccessKey?: string;
+    /** AWS secret key for S3 */
+    awsSecretKey?: string;
+    /** MinIO endpoint URL for local development */
+    minioEndpoint?: string;
+}
+/**
+ * Code generation settings
+ */
+export interface CodegenOptions {
+    /** Whether to wrap generated SQL code in transactions */
+    useTx?: boolean;
+}
+/**
+ * Migration and code generation options
+ */
+export interface MigrationOptions {
+    /** Code generation settings */
+    codegen?: CodegenOptions;
+}
+/**
+ * Configuration options for the LaunchQL API
+ */
+export interface ApiOptions {
+    /** Whether to enable the meta API endpoints */
+    enableMetaApi?: boolean;
+    /** Database schemas to expose through the API */
+    exposedSchemas?: string[];
+    /** Anonymous role name for unauthenticated requests */
+    anonRole?: string;
+    /** Default role name for authenticated requests */
+    roleName?: string;
+    /** Default database identifier to use */
+    defaultDatabaseId?: string;
+    /** Whether the API is publicly accessible */
+    isPublic?: boolean;
+    /** Schemas containing metadata tables */
+    metaSchemas?: string[];
+}
+/**
+ * Configuration for PGPM workspace
+ */
+export interface PgpmWorkspaceConfig {
+    /** Glob patterns for package directories */
+    packages: string[];
+    /** Optional workspace metadata */
+    name?: string;
+    version?: string;
+    /** Additional workspace settings */
+    settings?: {
+        [key: string]: any;
+    };
+    /** Deployment configuration for the workspace */
+    deployment?: Omit<DeploymentOptions, 'toChange'>;
+}
+/**
+ * Configuration options for module deployment
+ */
+export interface DeploymentOptions {
+    /** Whether to wrap deployments in database transactions */
+    useTx?: boolean;
+    /** Use fast deployment strategy (skip migration system) */
+    fast?: boolean;
+    /** Whether to use Sqitch plan files for deployments */
+    usePlan?: boolean;
+    /** Enable caching of deployment packages */
+    cache?: boolean;
+    /** Deploy up to a specific change (inclusive) - can be a change name or tag reference (e.g., '@v1.0.0') */
+    toChange?: string;
+    /** Log-only mode - skip script execution and only record deployment metadata */
+    logOnly?: boolean;
+    /**
+     * Hash method for SQL files:
+     * - 'content': Hash the raw file content (fast, but sensitive to formatting changes)
+     * - 'ast': Hash the parsed AST structure (robust, ignores formatting/comments but slower)
+     */
+    hashMethod?: 'content' | 'ast';
+}
+/**
+ * Main configuration options for the PGPM framework
+ */
+export interface PgpmOptions {
+    /** Test database configuration options */
+    db?: Partial<PgTestConnectionOptions>;
+    /** PostgreSQL connection configuration */
+    pg?: Partial<PgConfig>;
+    /** PostGraphile/Graphile configuration */
+    graphile?: GraphileOptions;
+    /** HTTP server configuration */
+    server?: ServerOptions;
+    /** Feature flags and toggles */
+    features?: FeatureOptions;
+    /** API configuration options */
+    api?: ApiOptions;
+    /** CDN and file storage configuration */
+    cdn?: CDNOptions;
+    /** Module deployment configuration */
+    deployment?: DeploymentOptions;
+    /** Migration and code generation options */
+    migrations?: MigrationOptions;
+    /** Job system configuration */
+    jobs?: JobsConfig;
+}
+/**
+ * Default configuration values for PGPM framework
+ */
+export declare const pgpmDefaults: PgpmOptions;
+export declare function getGitConfigInfo(): {
+    username: string;
+    email: string;
+};

package/pgpm.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pgpmDefaults = void 0;
+exports.getGitConfigInfo = getGitConfigInfo;
+const child_process_1 = require("child_process");
+/**
+ * Default configuration values for PGPM framework
+ */
+exports.pgpmDefaults = {
+    db: {
+        rootDb: 'postgres',
+        prefix: 'db-',
+        extensions: [],
+        cwd: process.cwd(),
+        connection: {
+            user: 'app_user',
+            password: 'app_password',
+            // TODO: check if this is used vs. roles below...
+            role: 'anonymous'
+        },
+        roles: {
+            anonymous: 'anonymous',
+            authenticated: 'authenticated',
+            administrator: 'administrator',
+            default: 'anonymous'
+        }
+    },
+    pg: {
+        host: 'localhost',
+        port: 5432,
+        user: 'postgres',
+        password: 'password',
+        database: 'postgres',
+    },
+    graphile: {
+        schema: [],
+        appendPlugins: [],
+        overrideSettings: {},
+        graphileBuildOptions: {},
+    },
+    server: {
+        host: 'localhost',
+        port: 3000,
+        trustProxy: false,
+        strictAuth: false,
+    },
+    features: {
+        simpleInflection: true,
+        oppositeBaseNames: true,
+        postgis: true
+    },
+    api: {
+        enableMetaApi: true,
+        exposedSchemas: [],
+        anonRole: 'administrator',
+        roleName: 'administrator',
+        defaultDatabaseId: 'hard-coded',
+        isPublic: true,
+        metaSchemas: ['collections_public', 'meta_public']
+    },
+    cdn: {
+        bucketName: 'test-bucket',
+        awsRegion: 'us-east-1',
+        awsAccessKey: 'minioadmin',
+        awsSecretKey: 'minioadmin',
+        minioEndpoint: 'http://localhost:9000'
+    },
+    deployment: {
+        useTx: true,
+        fast: false,
+        usePlan: true,
+        cache: false,
+        logOnly: false,
+        hashMethod: 'content'
+    },
+    migrations: {
+        codegen: {
+            useTx: false
+        }
+    },
+    jobs: {
+        pg: {
+            host: 'localhost',
+            port: 5432,
+            user: 'postgres',
+            password: 'password',
+            database: 'jobs'
+        },
+        schema: {
+            schema: 'app_jobs'
+        },
+        worker: {
+            host: 'localhost',
+            port: 5432,
+            user: 'postgres',
+            password: 'password',
+            database: 'jobs',
+            schema: 'app_jobs',
+            hostname: 'worker-0',
+            supportAny: true,
+            supported: [],
+            pollInterval: 1000,
+            gracefulShutdown: true
+        },
+        scheduler: {
+            host: 'localhost',
+            port: 5432,
+            user: 'postgres',
+            password: 'password',
+            database: 'jobs',
+            schema: 'app_jobs',
+            hostname: 'scheduler-0',
+            supportAny: true,
+            supported: [],
+            pollInterval: 1000,
+            gracefulShutdown: true
+        },
+        openFaas: {
+            gateway: {
+                gatewayUrl: 'http://gateway:8080',
+                callbackUrl: 'http://callback:12345',
+                callbackPort: 12345
+            },
+            server: {
+                schema: 'app_jobs',
+                port: 3000,
+                host: 'localhost'
+            }
+        }
+    }
+};
+function getGitConfigInfo() {
+    const isTestEnv = process.env.NODE_ENV === 'test' ||
+        process.env.NODE_ENV === 'testing' || // fallback
+        process.env.GITHUB_ACTIONS === 'true'; // GitHub Actions
+    if (isTestEnv) {
+        return {
+            username: 'CI Test User',
+            email: 'ci@example.com'
+        };
+    }
+    let username = '';
+    let email = '';
+    try {
+        username = (0, child_process_1.execSync)('git config --global user.name', {
+            encoding: 'utf8'
+        }).trim();
+    }
+    catch {
+        username = '';
+    }
+    try {
+        email = (0, child_process_1.execSync)('git config --global user.email', {
+            encoding: 'utf8'
+        }).trim();
+    }
+    catch {
+        email = '';
+    }
+    return { username, email };
+}

package/update.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Metadata stored for npm update checks.
+ */
+export interface UpdateCheckConfig {
+    lastCheckedAt: number;
+    latestKnownVersion: string;
+}
+export declare const UPDATE_CHECK_TTL_MS: number;
+export declare const UPDATE_CHECK_APPSTASH_KEY = "pgpm-update-check";
+export declare const UPDATE_PACKAGE_NAME = "pgpm";

package/update.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPDATE_PACKAGE_NAME = exports.UPDATE_CHECK_APPSTASH_KEY = exports.UPDATE_CHECK_TTL_MS = void 0;
+exports.UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+exports.UPDATE_CHECK_APPSTASH_KEY = 'pgpm-update-check';
+exports.UPDATE_PACKAGE_NAME = 'pgpm';