@promptbook/cli 0.112.0-52 → 0.112.0-54

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-51`).
+ * It follows semantic versioning (e.g., `0.112.0-53`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-52",
+    "version": "0.112.0-54",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

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

@@ -60,7 +60,7 @@
      * @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
@@ -42650,8 +42650,9 @@
             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',
@@ -46309,6 +46310,255 @@
         }
     }
 
+    /**
+     * 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.spaceTrim(`
+        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.spaceTrim(`
+            **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.
      */
@@ -46505,14 +46755,23 @@
      * @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;
@@ -46522,11 +46781,21 @@
             }
             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}`);
@@ -46813,24 +47082,41 @@
      * @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 {
@@ -46841,6 +47127,10 @@
                 };
             }
             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,
@@ -46850,23 +47140,45 @@
                     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.