@pgpmjs/core 3.0.0

package/resolution/resolve.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolves SQL scripts for deployment or reversion.
+ *
+ * @param pkgDir - The package directory (defaults to the current working directory).
+ * @param scriptType - The type of script to resolve (`deploy` or `revert`).
+ * @returns A single concatenated SQL script as a string.
+ */
+export declare const resolve: (pkgDir?: string, scriptType?: "deploy" | "revert") => string;
+/**
+ * Resolves SQL scripts based on the `pgpm.plan` file.
+ *
+ * @param pkgDir - The package directory (defaults to the current working directory).
+ * @param scriptType - The type of script to resolve (`deploy` or `revert`).
+ * @returns A single concatenated SQL script as a string.
+ */
+export declare const resolveWithPlan: (pkgDir?: string, scriptType?: "deploy" | "revert") => string;
+/**
+ * Resolves a tag reference to its corresponding change name.
+ * Tags provide a way to reference specific points in a package's deployment history.
+ *
+ * @param planPath - Path to the plan file containing tag definitions
+ * @param tagReference - The tag reference to resolve (e.g., "package:@tagName" or "@tagName")
+ * @param currentPackage - The current package name (used when tag doesn't specify package)
+ * @returns The resolved change name
+ * @throws Error if tag format is invalid or tag is not found
+ *
+ * @example
+ * // Resolve a tag in the current package
+ * resolveTagToChangeName('/path/to/pgpm.plan', '@v1.0.0', 'mypackage')
+ * // Returns: 'schema/v1'
+ *
+ * @example
+ * // Resolve a tag from another package
+ * resolveTagToChangeName('/path/to/pgpm.plan', 'auth:@v2.0.0')
+ * // Returns: 'users/table'
+ */
+export declare const resolveTagToChangeName: (planPath: string, tagReference: string, currentProject?: string) => string;

package/resolution/resolve.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTagToChangeName = exports.resolveWithPlan = exports.resolve = void 0;
+const fs_1 = require("fs");
+const files_1 = require("../files");
+const parser_1 = require("../files/plan/parser");
+const deps_1 = require("./deps");
+const types_1 = require("@pgpmjs/types");
+/**
+ * Resolves SQL scripts for deployment or reversion.
+ *
+ * @param pkgDir - The package directory (defaults to the current working directory).
+ * @param scriptType - The type of script to resolve (`deploy` or `revert`).
+ * @returns A single concatenated SQL script as a string.
+ */
+const resolve = (pkgDir = process.cwd(), scriptType = 'deploy') => {
+    const sqlfile = [];
+    const name = (0, files_1.getExtensionName)(pkgDir);
+    const { resolved, external } = (0, deps_1.resolveDependencies)(pkgDir, name, { tagResolution: 'resolve' });
+    const scripts = scriptType === 'revert' ? [...resolved].reverse() : resolved;
+    for (const script of scripts) {
+        if (external.includes(script))
+            continue;
+        const file = `${pkgDir}/${scriptType}/${script}.sql`;
+        const dscript = (0, fs_1.readFileSync)(file, 'utf-8');
+        sqlfile.push(dscript);
+    }
+    return sqlfile.join('\n');
+};
+exports.resolve = resolve;
+/**
+ * Resolves SQL scripts based on the `pgpm.plan` file.
+ *
+ * @param pkgDir - The package directory (defaults to the current working directory).
+ * @param scriptType - The type of script to resolve (`deploy` or `revert`).
+ * @returns A single concatenated SQL script as a string.
+ */
+const resolveWithPlan = (pkgDir = process.cwd(), scriptType = 'deploy') => {
+    const sqlfile = [];
+    const planPath = `${pkgDir}/pgpm.plan`;
+    let resolved = (0, files_1.getChanges)(planPath);
+    if (scriptType === 'revert') {
+        resolved = resolved.reverse();
+    }
+    for (const script of resolved) {
+        const file = `${pkgDir}/${scriptType}/${script}.sql`;
+        const dscript = (0, fs_1.readFileSync)(file, 'utf-8');
+        sqlfile.push(dscript);
+    }
+    return sqlfile.join('\n');
+};
+exports.resolveWithPlan = resolveWithPlan;
+/**
+ * Resolves a tag reference to its corresponding change name.
+ * Tags provide a way to reference specific points in a package's deployment history.
+ *
+ * @param planPath - Path to the plan file containing tag definitions
+ * @param tagReference - The tag reference to resolve (e.g., "package:@tagName" or "@tagName")
+ * @param currentPackage - The current package name (used when tag doesn't specify package)
+ * @returns The resolved change name
+ * @throws Error if tag format is invalid or tag is not found
+ *
+ * @example
+ * // Resolve a tag in the current package
+ * resolveTagToChangeName('/path/to/pgpm.plan', '@v1.0.0', 'mypackage')
+ * // Returns: 'schema/v1'
+ *
+ * @example
+ * // Resolve a tag from another package
+ * resolveTagToChangeName('/path/to/pgpm.plan', 'auth:@v2.0.0')
+ * // Returns: 'users/table'
+ */
+const resolveTagToChangeName = (planPath, tagReference, currentProject) => {
+    // If not a tag reference, return as-is
+    if (!tagReference.includes('@')) {
+        return tagReference;
+    }
+    // Handle simple tag format (@tagName) by prepending current package
+    if (tagReference.startsWith('@') && !tagReference.includes(':')) {
+        if (!currentProject) {
+            const plan = (0, parser_1.parsePlanFile)(planPath);
+            if (!plan.data) {
+                throw types_1.errors.PLAN_PARSE_ERROR({ planPath, errors: 'Could not parse plan file' });
+            }
+            currentProject = plan.data.package;
+        }
+        tagReference = `${currentProject}:${tagReference}`;
+    }
+    // Parse package:@tagName format
+    const match = tagReference.match(/^([^:]+):@(.+)$/);
+    if (!match) {
+        throw types_1.errors.INVALID_NAME({ name: tagReference, type: 'tag', rules: 'Expected format: package:@tagName or @tagName' });
+    }
+    const [, projectName, tagName] = match;
+    // Parse plan file to find tag
+    const planResult = (0, parser_1.parsePlanFile)(planPath);
+    if (!planResult.data) {
+        throw types_1.errors.PLAN_PARSE_ERROR({ planPath, errors: 'Could not parse plan file' });
+    }
+    // Find the tag in the plan
+    const tag = planResult.data.tags?.find((t) => t.name === tagName);
+    if (!tag) {
+        throw types_1.errors.TAG_NOT_FOUND({ tag: tagName, project: projectName });
+    }
+    return tag.change;
+};
+exports.resolveTagToChangeName = resolveTagToChangeName;

package/utils/debug.d.ts

@@ -0,0 +1,21 @@
+export interface DebugOptions {
+    enabled: boolean;
+    logLevel?: 'info' | 'warn' | 'error' | 'debug';
+    showStackTrace?: boolean;
+    showQueryParams?: boolean;
+    showFullSQL?: boolean;
+}
+export declare class DebugHelper {
+    private options;
+    constructor(options?: DebugOptions);
+    isEnabled(): boolean;
+    logError(message: string, error?: any, context?: Record<string, any>): void;
+    logQuery(query: string, params?: any[], duration?: number): void;
+    logTransactionStart(): void;
+    logTransactionCommit(duration?: number): void;
+    logTransactionRollback(duration?: number): void;
+    static fromEnvironment(): DebugHelper;
+}
+export declare const debugHelper: DebugHelper;
+export declare function enableDebugMode(): void;
+export declare function createDebugSummary(error: any, context?: Record<string, any>): string;

package/utils/debug.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugHelper = exports.DebugHelper = void 0;
+exports.enableDebugMode = enableDebugMode;
+exports.createDebugSummary = createDebugSummary;
+const logger_1 = require("@pgpmjs/logger");
+const log = new logger_1.Logger('debug');
+class DebugHelper {
+    options;
+    constructor(options = { enabled: false }) {
+        this.options = {
+            logLevel: 'debug',
+            showStackTrace: true,
+            showQueryParams: true,
+            showFullSQL: true,
+            ...options
+        };
+    }
+    isEnabled() {
+        return this.options.enabled;
+    }
+    logError(message, error, context) {
+        if (!this.options.enabled)
+            return;
+        log.error(message);
+        if (context) {
+            log.error('Context:', JSON.stringify(context, null, 2));
+        }
+        if (error) {
+            log.error('Error Details:', {
+                code: error.code,
+                message: error.message,
+                severity: error.severity,
+                detail: error.detail,
+                hint: error.hint,
+                position: error.position,
+                where: error.where,
+                schema: error.schema,
+                table: error.table,
+                column: error.column,
+                dataType: error.dataType,
+                constraint: error.constraint,
+                file: error.file,
+                line: error.line,
+                routine: error.routine
+            });
+            if (this.options.showStackTrace && error.stack) {
+                log.error('Stack Trace:', error.stack);
+            }
+        }
+    }
+    logQuery(query, params, duration) {
+        if (!this.options.enabled)
+            return;
+        log.debug(`Query executed in ${duration || 0}ms:`);
+        if (this.options.showFullSQL) {
+            log.debug('Full SQL:', query);
+        }
+        else {
+            log.debug('SQL Preview:', query.split('\n')[0].trim());
+        }
+        if (this.options.showQueryParams && params && params.length > 0) {
+            log.debug('Parameters:', JSON.stringify(params, null, 2));
+        }
+    }
+    logTransactionStart() {
+        if (!this.options.enabled)
+            return;
+        log.debug('🔄 Transaction started');
+    }
+    logTransactionCommit(duration) {
+        if (!this.options.enabled)
+            return;
+        log.debug(`✅ Transaction committed in ${duration || 0}ms`);
+    }
+    logTransactionRollback(duration) {
+        if (!this.options.enabled)
+            return;
+        log.debug(`❌ Transaction rolled back after ${duration || 0}ms`);
+    }
+    static fromEnvironment() {
+        const enabled = process.env.LAUNCHQL_DEBUG === 'true' || process.env.DEBUG === 'launchql*';
+        const logLevel = process.env.LAUNCHQL_DEBUG_LEVEL || 'debug';
+        const showStackTrace = process.env.LAUNCHQL_DEBUG_STACK !== 'false';
+        const showQueryParams = process.env.LAUNCHQL_DEBUG_PARAMS !== 'false';
+        const showFullSQL = process.env.LAUNCHQL_DEBUG_SQL !== 'false';
+        return new DebugHelper({
+            enabled,
+            logLevel,
+            showStackTrace,
+            showQueryParams,
+            showFullSQL
+        });
+    }
+}
+exports.DebugHelper = DebugHelper;
+// Global debug instance
+exports.debugHelper = DebugHelper.fromEnvironment();
+// Utility functions
+function enableDebugMode() {
+    process.env.LAUNCHQL_DEBUG = 'true';
+    process.env.LOG_LEVEL = 'debug';
+    log.info('🔍 Debug mode enabled');
+    log.info('   Set LAUNCHQL_DEBUG=false to disable');
+    log.info('   Set LAUNCHQL_DEBUG_LEVEL=info|warn|error|debug to change log level');
+    log.info('   Set LAUNCHQL_DEBUG_STACK=false to hide stack traces');
+    log.info('   Set LAUNCHQL_DEBUG_PARAMS=false to hide query parameters');
+    log.info('   Set LAUNCHQL_DEBUG_SQL=false to hide full SQL scripts');
+}
+function createDebugSummary(error, context) {
+    const summary = [];
+    summary.push('=== LaunchQL Debug Summary ===');
+    summary.push('');
+    if (error) {
+        summary.push('Error Information:');
+        summary.push(`  Code: ${error.code || 'N/A'}`);
+        summary.push(`  Message: ${error.message || 'N/A'}`);
+        summary.push(`  Severity: ${error.severity || 'N/A'}`);
+        if (error.detail)
+            summary.push(`  Detail: ${error.detail}`);
+        if (error.hint)
+            summary.push(`  Hint: ${error.hint}`);
+        if (error.position)
+            summary.push(`  Position: ${error.position}`);
+        if (error.where)
+            summary.push(`  Where: ${error.where}`);
+        if (error.schema)
+            summary.push(`  Schema: ${error.schema}`);
+        if (error.table)
+            summary.push(`  Table: ${error.table}`);
+        if (error.column)
+            summary.push(`  Column: ${error.column}`);
+        if (error.constraint)
+            summary.push(`  Constraint: ${error.constraint}`);
+        summary.push('');
+    }
+    if (context) {
+        summary.push('Context:');
+        Object.entries(context).forEach(([key, value]) => {
+            summary.push(`  ${key}: ${JSON.stringify(value)}`);
+        });
+        summary.push('');
+    }
+    summary.push('Debugging Tips:');
+    summary.push('  1. Run with LAUNCHQL_DEBUG=true for more details');
+    summary.push('  2. Check the transaction query history above');
+    summary.push('  3. Verify your SQL scripts for syntax errors');
+    summary.push('  4. Ensure dependencies are applied in correct order');
+    summary.push('  5. Check database permissions and schema existence');
+    summary.push('');
+    summary.push('=== End Debug Summary ===');
+    return summary.join('\n');
+}

package/utils/target-utils.d.ts

@@ -0,0 +1,5 @@
+export interface ParsedTarget {
+    packageName: string;
+    toChange?: string;
+}
+export declare function parseTarget(target: string): ParsedTarget;

package/utils/target-utils.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTarget = parseTarget;
+const types_1 = require("@pgpmjs/types");
+function parseTarget(target) {
+    if (!target) {
+        throw new Error('Target parameter is required');
+    }
+    if (target.includes(':@')) {
+        const atIndex = target.indexOf(':@');
+        const beforeAt = target.substring(0, atIndex);
+        const afterAt = target.substring(atIndex + 2);
+        if (!afterAt) {
+            throw types_1.errors.INVALID_NAME({ name: target, type: 'tag', rules: 'Expected format: package:@tagName' });
+        }
+        // Check if this is a simple package:@tag format
+        if (!beforeAt.includes(':')) {
+            if (!beforeAt) {
+                throw types_1.errors.INVALID_NAME({ name: target, type: 'tag', rules: 'Expected format: package:@tagName' });
+            }
+            return { packageName: beforeAt, toChange: `@${afterAt}` };
+        }
+        throw types_1.errors.INVALID_NAME({ name: target, type: 'change', rules: 'Expected formats: package, package:changeName, or package:@tagName' });
+    }
+    if (target.includes(':') && !target.includes('@')) {
+        const parts = target.split(':');
+        if (parts.length > 2) {
+            throw types_1.errors.INVALID_NAME({ name: target, type: 'change', rules: 'Expected formats: package, package:changeName, or package:@tagName' });
+        }
+        const [packageName, changeName] = parts;
+        if (!packageName || !changeName) {
+            throw types_1.errors.INVALID_NAME({ name: target, type: 'change', rules: 'Expected format: package:changeName' });
+        }
+        return { packageName, toChange: changeName };
+    }
+    if (!target.includes(':')) {
+        return { packageName: target, toChange: undefined };
+    }
+    throw types_1.errors.INVALID_NAME({ name: target, type: 'change', rules: 'Expected formats: package, package:changeName, or package:@tagName' });
+}

package/workspace/paths.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Finds the module path by looking for pgpm.plan.
+ * @param cwd - Current working directory.
+ * @returns A promise that resolves to the directory path containing `pgpm.plan`.
+ */
+export declare const modulePath: (cwd?: string) => string;
+/**
+ * Finds the LaunchQL project path.
+ * @param cwd - Current working directory.
+ * @returns A promise that resolves to the directory path containing `pgpm.json`.
+ */
+export declare const launchqlPath: (cwd?: string) => string;
+export declare const getWorkspacePath: (cwd: string) => string;
+export declare const getModulePath: (cwd: string) => string;

package/workspace/paths.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getModulePath = exports.getWorkspacePath = exports.launchqlPath = exports.modulePath = void 0;
+const utils_1 = require("./utils");
+const PROJECT_FILES = {
+    PLAN: 'pgpm.plan',
+    LAUNCHQL: 'pgpm.json',
+};
+/**
+ * Finds the module path by looking for pgpm.plan.
+ * @param cwd - Current working directory.
+ * @returns A promise that resolves to the directory path containing `pgpm.plan`.
+ */
+const modulePath = (cwd = process.cwd()) => {
+    return (0, utils_1.walkUp)(cwd, PROJECT_FILES.PLAN);
+};
+exports.modulePath = modulePath;
+/**
+ * Finds the LaunchQL project path.
+ * @param cwd - Current working directory.
+ * @returns A promise that resolves to the directory path containing `pgpm.json`.
+ */
+const launchqlPath = (cwd = process.cwd()) => {
+    return (0, utils_1.walkUp)(cwd, PROJECT_FILES.LAUNCHQL);
+};
+exports.launchqlPath = launchqlPath;
+const getWorkspacePath = (cwd) => {
+    let workspacePath;
+    try {
+        workspacePath = (0, exports.launchqlPath)(cwd);
+    }
+    catch (err) {
+        console.error('Error: You must be in a LaunchQL workspace. You can initialize one with `lql init workspace` (or `pgpm init workspace`).');
+        process.exit(1);
+    }
+    return workspacePath;
+};
+exports.getWorkspacePath = getWorkspacePath;
+const getModulePath = (cwd) => {
+    let pkgPath;
+    try {
+        pkgPath = (0, exports.modulePath)(cwd);
+    }
+    catch (err) {
+        console.error('Error: You must be in a LaunchQL module. You can initialize one with the `init` command.');
+        process.exit(1);
+    }
+    return pkgPath;
+};
+exports.getModulePath = getModulePath;

package/workspace/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Recursively walks up directories to find a specific file (sync version).
+ * @param startDir - Starting directory.
+ * @param filename - The target file to search for.
+ * @returns The directory path containing the file.
+ */
+export declare const walkUp: (startDir: string, filename: string) => string;
+export declare const sluggify: (text: string) => string;

package/workspace/utils.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sluggify = exports.walkUp = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const types_1 = require("@pgpmjs/types");
+/**
+ * Recursively walks up directories to find a specific file (sync version).
+ * @param startDir - Starting directory.
+ * @param filename - The target file to search for.
+ * @returns The directory path containing the file.
+ */
+const walkUp = (startDir, filename) => {
+    let currentDir = (0, path_1.resolve)(startDir);
+    while (currentDir) {
+        const targetPath = (0, path_1.resolve)(currentDir, filename);
+        if ((0, fs_1.existsSync)(targetPath)) {
+            return currentDir;
+        }
+        const parentDir = (0, path_1.dirname)(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    throw types_1.errors.FILE_NOT_FOUND({ filePath: filename, type: 'configuration' });
+};
+exports.walkUp = walkUp;
+const sluggify = (text) => {
+    return text.toString().toLowerCase().trim()
+        .replace(/\s+/g, '-') // Replace spaces with -
+        .replace(/&/g, '-and-') // Replace & with 'and'
+        .replace(/[^\w\-]+/g, '') // Remove all non-word chars
+        .replace(/\-\-+/g, '-'); // Replace multiple - with single -
+};
+exports.sluggify = sluggify;