@promptbook/cli 0.112.0-52 → 0.112.0-54

package/esm/apps/agents-server/src/database/createDatabaseMigrationFailureError.d.ts

@@ -0,0 +1,58 @@
+import { DatabaseError } from '../../../../src/errors/DatabaseError';
+import type { DatabaseMigrationExecutionLockMode } from './acquireMigrationExecutionLock';
+import type { MigratePrefixProgressStage } from './migratePrefix';
+/**
+ * High-level migration stages used to explain where one migration run failed.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+export type DatabaseMigrationFailureStage = 'prepare-migration-plan' | 'connect-to-database' | 'acquire-migration-lock' | 'migrate-prefix';
+/**
+ * Snapshot of migration-run state captured when an error escapes the runner.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+export type DatabaseMigrationFailureContext = {
+    /**
+     * The broad migration phase that was running when the error occurred.
+     */
+    stage: DatabaseMigrationFailureStage;
+    /**
+     * Requested `--only` migration targets before prefix expansion.
+     */
+    onlyTargets: ReadonlyArray<string> | null;
+    /**
+     * Resolved prefixes selected for the current run.
+     */
+    selectedPrefixes: ReadonlyArray<string>;
+    /**
+     * Number of SQL migration files discovered on disk.
+     */
+    totalMigrationFiles: number;
+    /**
+     * Current migration lock mode.
+     */
+    executionLockMode: DatabaseMigrationExecutionLockMode;
+    /**
+     * Current prefix being migrated, when already known.
+     */
+    currentPrefix?: string;
+    /**
+     * More detailed sub-step inside one prefix migration.
+     */
+    currentPrefixStage?: MigratePrefixProgressStage;
+    /**
+     * Current migration filename being applied, when already known.
+     */
+    currentMigrationFile?: string;
+};
+/**
+ * Creates one branded migration failure error enriched with migration context and PostgreSQL details.
+ *
+ * @param error - Original failure thrown by the migration runner.
+ * @param context - Snapshot of migration progress at the time of failure.
+ * @returns Branded migration error with copied PostgreSQL fields for downstream logging.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+export declare function createDatabaseMigrationFailureError(error: unknown, context: DatabaseMigrationFailureContext): DatabaseError;

package/esm/apps/agents-server/src/database/migratePrefix.d.ts

@@ -38,6 +38,35 @@ export type MigratePrefixOptions = {
      * If true, print SQL before execution.
      */
     readonly logSqlStatements: boolean;
+    /**
+     * Optional observer notified about the current prefix migration sub-step.
+     */
+    readonly onProgress?: (progress: MigratePrefixProgress) => void;
+};
+/**
+ * Detailed prefix-migration stages used for richer error reporting.
+ *
+ * @private function of runDatabaseMigrations
+ */
+export type MigratePrefixProgressStage = 'ensure-migrations-table-schema' | 'read-applied-migrations' | 'apply-migration-file' | 'record-applied-migration';
+/**
+ * Progress snapshot emitted while one prefix is being migrated.
+ *
+ * @private function of runDatabaseMigrations
+ */
+export type MigratePrefixProgress = {
+    /**
+     * Prefix currently being migrated.
+     */
+    readonly prefix: string;
+    /**
+     * Detailed migration sub-step.
+     */
+    readonly stage: MigratePrefixProgressStage;
+    /**
+     * Migration file currently being applied, when relevant.
+     */
+    readonly migrationFile?: string;
 };
 /**
  * Applies pending migrations for one prefix inside the current transaction.

package/esm/index.es.js

@@ -58,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-52';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-54';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -42648,8 +42648,9 @@ function createInheritanceCapability(content) {
         iconName = 'SquareArrowUpRight';
     }
     if (isVoidPseudoAgentReference(reference)) {
-        label = VOID_PSEUDO_AGENT_REFERENCE;
+        label = VOID_PSEUDO_AGENT_REFERENCE; // <- {Void} label
         iconName = 'ShieldAlert';
+        return null; // <- Note: Do not show `{Void}` in capabilities, it's only used for internal logic
     }
     return {
         type: 'inheritance',
@@ -46307,6 +46308,255 @@ async function releaseMigrationExecutionLock(client, logger) {
     }
 }
 
+/**
+ * Creates one branded migration failure error enriched with migration context and PostgreSQL details.
+ *
+ * @param error - Original failure thrown by the migration runner.
+ * @param context - Snapshot of migration progress at the time of failure.
+ * @returns Branded migration error with copied PostgreSQL fields for downstream logging.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function createDatabaseMigrationFailureError(error, context) {
+    const postgresLikeError = getPostgresLikeError(error);
+    const message = spaceTrim$1(`
+        Database migration failed while ${describeFailureStage(context.stage)}.
+
+        ${createDatabaseMigrationFailureDetails(context, error, postgresLikeError)}
+        ${createDatabaseMigrationFailureHint(context, postgresLikeError)}
+    `);
+    const migrationError = new DatabaseError(message);
+    if (error instanceof Error) {
+        Object.defineProperty(migrationError, 'cause', {
+            value: error,
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+    }
+    copyPostgresLikeErrorProperties(migrationError, postgresLikeError);
+    return migrationError;
+}
+/**
+ * Creates the detailed markdown block appended to the migration failure summary.
+ *
+ * @param context - Snapshot of migration progress.
+ * @param error - Original failure.
+ * @param postgresLikeError - PostgreSQL-flavored view of the original failure.
+ * @returns Markdown details section.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function createDatabaseMigrationFailureDetails(context, error, postgresLikeError) {
+    const detailLines = [
+        `-   **Stage:** ${formatCode(describeFailureStage(context.stage))}`,
+        `-   **Execution lock mode:** ${formatCode(context.executionLockMode)}`,
+        context.onlyTargets && context.onlyTargets.length > 0
+            ? `-   **Requested targets:** ${formatCodeList(context.onlyTargets)}`
+            : null,
+        context.selectedPrefixes.length > 0
+            ? `-   **Selected prefixes:** ${formatCodeList(context.selectedPrefixes.map(formatPrefixForLogs))}`
+            : '-   **Selected prefixes:** _not resolved yet_',
+        context.totalMigrationFiles > 0
+            ? `-   **Migration files discovered:** ${formatCode(String(context.totalMigrationFiles))}`
+            : null,
+        context.currentPrefix !== undefined
+            ? `-   **Current prefix:** ${formatCode(formatPrefixForLogs(context.currentPrefix))}`
+            : null,
+        context.currentPrefixStage !== undefined
+            ? `-   **Current prefix step:** ${formatCode(describePrefixStage(context.currentPrefixStage))}`
+            : null,
+        context.currentMigrationFile
+            ? `-   **Current migration file:** ${formatCode(context.currentMigrationFile)}`
+            : null,
+        error instanceof Error ? `-   **Original error:** ${formatCode(error.message)}` : `-   **Original error:** ${formatCode(String(error))}`,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.code) ? `-   **PostgreSQL code:** ${formatCode(postgresLikeError.code)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.severity) ? `-   **PostgreSQL severity:** ${formatCode(postgresLikeError.severity)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.detail) ? `-   **PostgreSQL detail:** ${formatCode(postgresLikeError.detail)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.hint) ? `-   **PostgreSQL hint:** ${formatCode(postgresLikeError.hint)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.where) ? `-   **PostgreSQL where:** ${formatCode(postgresLikeError.where)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.schema) ? `-   **PostgreSQL schema:** ${formatCode(postgresLikeError.schema)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.table) ? `-   **PostgreSQL table:** ${formatCode(postgresLikeError.table)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.column) ? `-   **PostgreSQL column:** ${formatCode(postgresLikeError.column)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.constraint) ? `-   **PostgreSQL constraint:** ${formatCode(postgresLikeError.constraint)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.file) ? `-   **PostgreSQL file:** ${formatCode(postgresLikeError.file)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.line) ? `-   **PostgreSQL line:** ${formatCode(postgresLikeError.line)}` : null,
+        (postgresLikeError === null || postgresLikeError === void 0 ? void 0 : postgresLikeError.routine) ? `-   **PostgreSQL routine:** ${formatCode(postgresLikeError.routine)}` : null,
+    ].filter((detailLine) => detailLine !== null);
+    return detailLines.join('\n');
+}
+/**
+ * Creates extra actionable guidance for common migration failures.
+ *
+ * @param context - Snapshot of migration progress.
+ * @param postgresLikeError - PostgreSQL-flavored view of the original failure.
+ * @returns Optional markdown hint block.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function createDatabaseMigrationFailureHint(context, postgresLikeError) {
+    if (isMigrationLockStatementTimeout(context, postgresLikeError)) {
+        return spaceTrim$1(`
+            **Likely cause:** Another process is already running database migrations, so PostgreSQL kept this command blocked inside ${formatCode('pg_advisory_lock(...)')} until ${formatCode('statement_timeout')} canceled the wait.
+
+            **What to check next:**
+            -   Wait for the other migration to finish and rerun this command.
+            -   Inspect active PostgreSQL sessions holding the advisory migration lock.
+            -   Increase ${formatCode('statement_timeout')} for this manual migration session if the wait is expected.
+        `);
+    }
+    return '';
+}
+/**
+ * Detects the specific timeout caused by waiting on the shared migration advisory lock.
+ *
+ * @param context - Snapshot of migration progress.
+ * @param postgresLikeError - PostgreSQL-flavored view of the original failure.
+ * @returns `true` when the failure most likely came from timing out inside `pg_advisory_lock`.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function isMigrationLockStatementTimeout(context, postgresLikeError) {
+    if (context.stage !== 'acquire-migration-lock' || context.executionLockMode !== 'wait' || !postgresLikeError) {
+        return false;
+    }
+    if (postgresLikeError.code === '57014') {
+        return true;
+    }
+    return /statement timeout/i.test(postgresLikeError.message);
+}
+/**
+ * Returns a human-readable description for one failure stage.
+ *
+ * @param stage - Raw failure stage.
+ * @returns Human-readable stage description.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function describeFailureStage(stage) {
+    switch (stage) {
+        case 'prepare-migration-plan':
+            return 'preparing the migration plan';
+        case 'connect-to-database':
+            return 'connecting to the database';
+        case 'acquire-migration-lock':
+            return 'waiting for the migration execution lock';
+        case 'migrate-prefix':
+            return 'migrating one database prefix';
+    }
+}
+/**
+ * Returns a human-readable description for one prefix sub-step.
+ *
+ * @param stage - Raw prefix stage.
+ * @returns Human-readable stage description.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function describePrefixStage(stage) {
+    switch (stage) {
+        case 'ensure-migrations-table-schema':
+            return 'ensuring the migrations table schema';
+        case 'read-applied-migrations':
+            return 'reading already-applied migrations';
+        case 'apply-migration-file':
+            return 'executing a migration file';
+        case 'record-applied-migration':
+            return 'recording an applied migration file';
+    }
+}
+/**
+ * Formats one prefix for logs while keeping the default namespace readable.
+ *
+ * @param prefix - Raw table prefix.
+ * @returns Human-readable prefix label.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function formatPrefixForLogs(prefix) {
+    return prefix === '' ? '<default>' : prefix;
+}
+/**
+ * Wraps one string as inline markdown code.
+ *
+ * @param value - Raw string value.
+ * @returns Inline-code representation.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function formatCode(value) {
+    return `\`${value.replace(/`/g, '\\`')}\``;
+}
+/**
+ * Formats a list of strings as inline-code items separated by commas.
+ *
+ * @param values - Values to format.
+ * @returns Inline-code list.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function formatCodeList(values) {
+    return values.map(formatCode).join(', ');
+}
+/**
+ * Narrows unknown failures to the PostgreSQL error shape when possible.
+ *
+ * @param error - Unknown failure value.
+ * @returns PostgreSQL-like error object or `null`.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function getPostgresLikeError(error) {
+    if (!(error instanceof Error)) {
+        return null;
+    }
+    return error;
+}
+/**
+ * Copies useful PostgreSQL error properties onto the branded migration error.
+ *
+ * This keeps downstream logging compatible with the raw `pg` error shape.
+ *
+ * @param target - Branded migration error.
+ * @param postgresLikeError - Original PostgreSQL-style error, when available.
+ *
+ * @private internal utility of runDatabaseMigrations
+ */
+function copyPostgresLikeErrorProperties(target, postgresLikeError) {
+    if (!postgresLikeError) {
+        return;
+    }
+    const postgresFields = {
+        code: postgresLikeError.code,
+        severity: postgresLikeError.severity,
+        detail: postgresLikeError.detail,
+        hint: postgresLikeError.hint,
+        position: postgresLikeError.position,
+        internalPosition: postgresLikeError.internalPosition,
+        internalQuery: postgresLikeError.internalQuery,
+        where: postgresLikeError.where,
+        schema: postgresLikeError.schema,
+        table: postgresLikeError.table,
+        column: postgresLikeError.column,
+        dataType: postgresLikeError.dataType,
+        constraint: postgresLikeError.constraint,
+        file: postgresLikeError.file,
+        line: postgresLikeError.line,
+        routine: postgresLikeError.routine,
+    };
+    for (const [fieldName, fieldValue] of Object.entries(postgresFields)) {
+        if (fieldValue === undefined) {
+            continue;
+        }
+        Object.defineProperty(target, fieldName, {
+            value: fieldValue,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+}
+
 /**
  * Supported `_Server.environment` values.
  */
@@ -46503,14 +46753,23 @@ function isMissingServerRegistryError(error) {
  * @private function of runDatabaseMigrations
  */
 async function applyPendingMigrationsForPrefix(options) {
+    var _a, _b, _c, _d;
     const { readFile } = await importRuntimeModule('fs/promises');
     const migrationsTableName = `${options.prefix}Migrations`;
     const migrationsTableIdentifier = quoteIdentifier$1(migrationsTableName);
+    (_a = options.onProgress) === null || _a === void 0 ? void 0 : _a.call(options, {
+        prefix: options.prefix,
+        stage: 'ensure-migrations-table-schema',
+    });
     await ensureMigrationsTableSchema({
         client: options.client,
         migrationsTableIdentifier,
         manualAppliedByDefault: options.manualAppliedByDefault,
     });
+    (_b = options.onProgress) === null || _b === void 0 ? void 0 : _b.call(options, {
+        prefix: options.prefix,
+        stage: 'read-applied-migrations',
+    });
     const { rows } = await options.client.query(`SELECT "filename" FROM ${migrationsTableIdentifier}`);
     const appliedMigrations = new Set(rows.map((row) => row.filename));
     let appliedCount = 0;
@@ -46520,11 +46779,21 @@ async function applyPendingMigrationsForPrefix(options) {
         }
         const migrationFilePath = `${options.migrationsDirectory}/${migrationFile}`;
         options.logger.info(`  🔼 Applying ${migrationFilePath.split('\\').join('/')}...`);
+        (_c = options.onProgress) === null || _c === void 0 ? void 0 : _c.call(options, {
+            prefix: options.prefix,
+            stage: 'apply-migration-file',
+            migrationFile,
+        });
         const sql = (await readFile(migrationFilePath, 'utf-8')).replace(/prefix_/g, options.prefix);
         if (options.logSqlStatements) {
             options.logger.info(sql);
         }
         await options.client.query(sql);
+        (_d = options.onProgress) === null || _d === void 0 ? void 0 : _d.call(options, {
+            prefix: options.prefix,
+            stage: 'record-applied-migration',
+            migrationFile,
+        });
         await options.client.query(`INSERT INTO ${migrationsTableIdentifier} ("filename", "appliedBy") VALUES ($1, $2)`, [migrationFile, options.appliedBy]);
         appliedCount++;
         options.logger.info(`  ✅ Applied ${migrationFile}`);
@@ -46811,24 +47080,41 @@ async function resolveDatabaseMigrationRuntimeConfiguration(logger = console) {
  * @returns Aggregated migration summary.
  */
 async function runDatabaseMigrations(options) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g;
     const logger = (_a = options.logger) !== null && _a !== void 0 ? _a : console;
-    const selectedPrefixes = selectPrefixesForMigration(options.prefixes, (_b = options.registeredServers) !== null && _b !== void 0 ? _b : [], options.onlyTargets);
-    const migrationsDirectory = (_c = options.migrationsDirectory) !== null && _c !== void 0 ? _c : (await resolveMigrationsDirectory());
-    const migrationFiles = await readMigrationFiles(migrationsDirectory);
-    const totalMigrationFiles = migrationFiles.length;
+    const failureContext = {
+        stage: 'prepare-migration-plan',
+        onlyTargets: (_b = options.onlyTargets) !== null && _b !== void 0 ? _b : null,
+        selectedPrefixes: [],
+        totalMigrationFiles: 0,
+        executionLockMode: (_c = options.executionLockMode) !== null && _c !== void 0 ? _c : 'wait',
+    };
     const perPrefix = [];
-    logger.info(`📂 Found ${totalMigrationFiles} migration files`);
-    logger.info(`📋 Found ${selectedPrefixes.length} prefixes to migrate: ${selectedPrefixes
-        .map((prefix) => prefix || '<default>')
-        .join(', ')}`);
-    const client = await createPostgresClient(options.connectionString);
+    let client = null;
+    let selectedPrefixes = [];
+    let totalMigrationFiles = 0;
     let hasExecutionLock = false;
     let isSkippedDueToActiveMigrationLock = false;
+    let migrationFailure = null;
+    let migrationsDirectory = '';
+    let migrationFiles = [];
     try {
+        selectedPrefixes = selectPrefixesForMigration(options.prefixes, (_d = options.registeredServers) !== null && _d !== void 0 ? _d : [], options.onlyTargets);
+        failureContext.selectedPrefixes = selectedPrefixes;
+        migrationsDirectory = (_e = options.migrationsDirectory) !== null && _e !== void 0 ? _e : (await resolveMigrationsDirectory());
+        migrationFiles = await readMigrationFiles(migrationsDirectory);
+        totalMigrationFiles = migrationFiles.length;
+        failureContext.totalMigrationFiles = totalMigrationFiles;
+        logger.info(`📂 Found ${totalMigrationFiles} migration files`);
+        logger.info(`📋 Found ${selectedPrefixes.length} prefixes to migrate: ${selectedPrefixes
+            .map((prefix) => prefix || '<default>')
+            .join(', ')}`);
+        failureContext.stage = 'connect-to-database';
+        client = await createPostgresClient(options.connectionString);
         await client.connect();
         logger.info('🔌 Connected to database');
-        hasExecutionLock = await acquireMigrationExecutionLock(client, logger, (_d = options.executionLockMode) !== null && _d !== void 0 ? _d : 'wait');
+        failureContext.stage = 'acquire-migration-lock';
+        hasExecutionLock = await acquireMigrationExecutionLock(client, logger, (_f = options.executionLockMode) !== null && _f !== void 0 ? _f : 'wait');
         if (!hasExecutionLock) {
             isSkippedDueToActiveMigrationLock = true;
             return {
@@ -46839,6 +47125,10 @@ async function runDatabaseMigrations(options) {
             };
         }
         for (const prefix of selectedPrefixes) {
+            failureContext.stage = 'migrate-prefix';
+            failureContext.currentPrefix = prefix;
+            failureContext.currentPrefixStage = undefined;
+            failureContext.currentMigrationFile = undefined;
             logger.info(`\n🏗️ Migrating prefix: "${prefix}"`);
             const appliedCount = await migratePrefix({
                 prefix,
@@ -46848,23 +47138,45 @@ async function runDatabaseMigrations(options) {
                 logger,
                 migrationFiles,
                 migrationsDirectory,
-                logSqlStatements: (_e = options.logSqlStatements) !== null && _e !== void 0 ? _e : false,
+                logSqlStatements: (_g = options.logSqlStatements) !== null && _g !== void 0 ? _g : false,
+                onProgress: ({ prefix, stage, migrationFile }) => {
+                    failureContext.currentPrefix = prefix;
+                    failureContext.currentPrefixStage = stage;
+                    failureContext.currentMigrationFile = migrationFile;
+                },
             });
             perPrefix.push({ prefix, appliedCount });
         }
+        return {
+            processedPrefixes: selectedPrefixes,
+            totalMigrationFiles,
+            perPrefix,
+            isSkippedDueToActiveMigrationLock,
+        };
+    }
+    catch (error) {
+        migrationFailure = createDatabaseMigrationFailureError(error, failureContext);
     }
     finally {
-        if (hasExecutionLock) {
-            await releaseMigrationExecutionLock(client, logger);
+        if (client) {
+            if (hasExecutionLock) {
+                await releaseMigrationExecutionLock(client, logger);
+            }
+            try {
+                await client.end();
+            }
+            catch (clientEndError) {
+                if (migrationFailure === null) {
+                    migrationFailure = clientEndError;
+                }
+                else {
+                    logger.warn('⚠️ Failed to close migration database connection');
+                    logger.warn(String(clientEndError));
+                }
+            }
         }
-        await client.end();
     }
-    return {
-        processedPrefixes: selectedPrefixes,
-        totalMigrationFiles,
-        perPrefix,
-        isSkippedDueToActiveMigrationLock,
-    };
+    throw migrationFailure;
 }
 /**
  * Resolves PostgreSQL connection string from supported environment variables.