@promptbook/cli 0.112.0-41 → 0.112.0-42

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

@@ -1,14 +1,25 @@
 import type { Client } from 'pg';
 import type { DatabaseMigrationLogger } from './runDatabaseMigrations';
+/**
+ * Lock-acquisition strategies used by the migration runner.
+ *
+ * `wait` is appropriate for explicit/manual migration flows where the caller expects one serialized run.
+ * `skip` is appropriate for background startup checks where waiting would block request handling.
+ *
+ * @private function of runDatabaseMigrations
+ */
+export type DatabaseMigrationExecutionLockMode = 'wait' | 'skip';
 /**
  * Acquires advisory lock preventing concurrent migration execution across processes.
  *
  * @param client Connected PostgreSQL client.
  * @param logger Logger used for progress output.
+ * @param mode Whether the caller should block for the lock or skip when it is already held.
+ * @returns `true` when the lock was acquired and migrations may proceed.
  *
  * @private function of runDatabaseMigrations
  */
-export declare function acquireMigrationExecutionLock(client: Client, logger: DatabaseMigrationLogger): Promise<void>;
+export declare function acquireMigrationExecutionLock(client: Client, logger: DatabaseMigrationLogger, mode?: DatabaseMigrationExecutionLockMode): Promise<boolean>;
 /**
  * Releases advisory lock used for migration execution.
  *

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

@@ -1,4 +1,5 @@
 import { type ServerRecord } from '../utils/serverRegistry';
+import { type DatabaseMigrationExecutionLockMode } from './acquireMigrationExecutionLock';
 /**
  * Allowed values describing who applied a migration record.
  */
@@ -67,6 +68,10 @@ export type RunDatabaseMigrationsOptions = {
      * If true, prints every SQL migration body before execution.
      */
     readonly logSqlStatements?: boolean;
+    /**
+     * Whether migration execution should wait for the advisory lock or skip when another process already owns it.
+     */
+    readonly executionLockMode?: DatabaseMigrationExecutionLockMode;
 };
 /**
  * Result of one prefix migration run.
@@ -97,6 +102,10 @@ export type RunDatabaseMigrationsResult = {
      * Per-prefix summary.
      */
     readonly perPrefix: ReadonlyArray<DatabaseMigrationPrefixResult>;
+    /**
+     * Whether migration execution was skipped because another process already held the advisory lock.
+     */
+    readonly isSkippedDueToActiveMigrationLock: boolean;
 };
 /**
  * Reads migration runtime configuration from environment variables and `_Server`.

package/esm/index.es.js

@@ -57,7 +57,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-41';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-42';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3091,14 +3091,16 @@ function $initializeCoderVerifyCommand(program) {
             - Archives verified prompt files to prompts/done/ directory
             - Auto-appends repair prompts for incomplete work
             - Processes files with all-done prompts first
+            - Supports ignoring matching prompt candidates for one verification run
         `));
     command.option('--reverse', 'Process prompt files in reverse order', false);
+    command.option('--ignore <candidate-text>', 'Ignore prompt files whose filename or first prompt line contains the given text (repeatable)', collectStringOption, []);
     command.action(handleActionErrors(async (cliOptions) => {
-        const { reverse } = cliOptions;
+        const { reverse, ignore } = cliOptions;
         // Note: Import the main function dynamically to avoid loading heavy dependencies until needed
         const { verifyPrompts } = await Promise.resolve().then(function () { return verifyPrompts$1; });
         try {
-            await verifyPrompts(reverse);
+            await verifyPrompts({ reverse, ignore });
         }
         catch (error) {
             console.error(colors.bgRed('Prompt verification failed:'), error);
@@ -3107,6 +3109,14 @@ function $initializeCoderVerifyCommand(program) {
         return process.exit(0);
     }));
 }
+/**
+ * Collects repeatable string options from Commander.
+ *
+ * @private internal utility of `coder verify` command
+ */
+function collectStringOption(value, previousValues) {
+    return [...previousValues, value];
+}
 // Note: [🟡] Code for CLI command [verify](src/cli/cli-commands/coder/verify.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
@@ -45389,6 +45399,7 @@ function normalizePathForLogs(value) {
     return value.split('\\').join('/');
 }
 
+// cspell:ignore hashtext
 /**
  * Cross-process advisory lock key guarding migration execution.
  *
@@ -45400,13 +45411,27 @@ const DATABASE_MIGRATION_LOCK_KEY = 'promptbook_agents_server_migrations';
  *
  * @param client Connected PostgreSQL client.
  * @param logger Logger used for progress output.
+ * @param mode Whether the caller should block for the lock or skip when it is already held.
+ * @returns `true` when the lock was acquired and migrations may proceed.
  *
  * @private function of runDatabaseMigrations
  */
-async function acquireMigrationExecutionLock(client, logger) {
+async function acquireMigrationExecutionLock(client, logger, mode = 'wait') {
+    var _a;
+    if (mode === 'skip') {
+        logger.info('🔒 Checking migration lock without waiting');
+        const { rows } = await client.query('SELECT pg_try_advisory_lock(hashtext($1)) AS "isMigrationLockAcquired";', [DATABASE_MIGRATION_LOCK_KEY]);
+        if (!((_a = rows[0]) === null || _a === void 0 ? void 0 : _a.isMigrationLockAcquired)) {
+            logger.info('⏭️ Migration lock is already held by another process. Skipping this migration attempt.');
+            return false;
+        }
+        logger.info('🔒 Migration lock acquired');
+        return true;
+    }
     logger.info('🔒 Waiting for migration lock');
     await client.query('SELECT pg_advisory_lock(hashtext($1));', [DATABASE_MIGRATION_LOCK_KEY]);
     logger.info('🔒 Migration lock acquired');
+    return true;
 }
 /**
  * Releases advisory lock used for migration execution.
@@ -45930,23 +45955,33 @@ async function resolveDatabaseMigrationRuntimeConfiguration(logger = console) {
  * @returns Aggregated migration summary.
  */
 async function runDatabaseMigrations(options) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     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 perPrefix = [];
-    logger.info(`📂 Found ${migrationFiles.length} migration files`);
+    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 hasExecutionLock = false;
+    let isSkippedDueToActiveMigrationLock = false;
     try {
         await client.connect();
         logger.info('🔌 Connected to database');
-        await acquireMigrationExecutionLock(client, logger);
-        hasExecutionLock = true;
+        hasExecutionLock = await acquireMigrationExecutionLock(client, logger, (_d = options.executionLockMode) !== null && _d !== void 0 ? _d : 'wait');
+        if (!hasExecutionLock) {
+            isSkippedDueToActiveMigrationLock = true;
+            return {
+                processedPrefixes: [],
+                totalMigrationFiles,
+                perPrefix,
+                isSkippedDueToActiveMigrationLock,
+            };
+        }
         for (const prefix of selectedPrefixes) {
             logger.info(`\n🏗️ Migrating prefix: "${prefix}"`);
             const appliedCount = await migratePrefix({
@@ -45957,7 +45992,7 @@ async function runDatabaseMigrations(options) {
                 logger,
                 migrationFiles,
                 migrationsDirectory,
-                logSqlStatements: (_d = options.logSqlStatements) !== null && _d !== void 0 ? _d : false,
+                logSqlStatements: (_e = options.logSqlStatements) !== null && _e !== void 0 ? _e : false,
             });
             perPrefix.push({ prefix, appliedCount });
         }
@@ -45970,8 +46005,9 @@ async function runDatabaseMigrations(options) {
     }
     return {
         processedPrefixes: selectedPrefixes,
-        totalMigrationFiles: migrationFiles.length,
+        totalMigrationFiles,
         perPrefix,
+        isSkippedDueToActiveMigrationLock,
     };
 }
 /**
@@ -48159,24 +48195,26 @@ const SNIPPET_CHAR_LIMIT = 900;
  */
 const MAX_PENDING_FILE_NAMES = 8;
 /**
- * Parse command-line arguments
+ * Default verification options parsed from the current process arguments.
  */
-const REVERSE_ORDER = process.argv.includes('--reverse');
+const DEFAULT_VERIFY_PROMPTS_OPTIONS = normalizeVerifyPromptsOptions(parseVerifyPromptsCliOptions(process.argv.slice(2)));
 /**
  * Starts the verification loop and exits when no `[ ]` prompts remain.
  *
- * @param reverse - Process files in reverse order
- *
  * @public exported from `@promptbook/cli`
  */
-async function verifyPrompts(reverse = REVERSE_ORDER) {
+async function verifyPrompts(options = DEFAULT_VERIFY_PROMPTS_OPTIONS) {
+    const normalizedOptions = normalizeVerifyPromptsOptions(options);
     console.info(colors.cyan.bold('📋 Prompt verification helper'));
-    if (reverse) {
+    if (normalizedOptions.reverse) {
         console.info(colors.gray('Processing files in reverse order'));
     }
-    const initialFiles = await loadPromptFiles(PROMPTS_DIR);
-    if (reverse) {
-        initialFiles.reverse();
+    if (normalizedOptions.ignore.length > 0) {
+        console.info(colors.gray(`Ignoring candidates matching: ${normalizedOptions.ignore.join(', ')}`));
+    }
+    const { promptFiles: initialFiles, ignoredPromptFiles } = await loadPromptFilesForVerification(normalizedOptions);
+    if (ignoredPromptFiles.length > 0) {
+        console.info(colors.gray(`Ignored ${ignoredPromptFiles.length} prompt file(s) for this run.`));
     }
     displayTopLevelFileList(initialFiles);
     await prepareArchiveDirectory();
@@ -48191,10 +48229,7 @@ async function verifyPrompts(reverse = REVERSE_ORDER) {
             if (wasSkipped) {
                 skippedFiles.add(fileWithAllDone.path);
             }
-            promptFiles = await loadPromptFiles(PROMPTS_DIR);
-            if (REVERSE_ORDER) {
-                promptFiles.reverse();
-            }
+            promptFiles = (await loadPromptFilesForVerification(normalizedOptions)).promptFiles;
             continue;
         }
         // Second priority: process todo prompts
@@ -48204,11 +48239,56 @@ async function verifyPrompts(reverse = REVERSE_ORDER) {
             break;
         }
         await resolvePrompt(nextPrompt);
-        promptFiles = await loadPromptFiles(PROMPTS_DIR);
-        if (REVERSE_ORDER) {
-            promptFiles.reverse();
+        promptFiles = (await loadPromptFilesForVerification(normalizedOptions)).promptFiles;
+    }
+}
+/**
+ * Parses supported command-line arguments for the standalone verification script.
+ */
+function parseVerifyPromptsCliOptions(args) {
+    return {
+        reverse: args.includes('--reverse'),
+        ignore: readRepeatableStringOption(args, '--ignore'),
+    };
+}
+/**
+ * Loads prompt files and applies ordering plus ignore filters for one verification pass.
+ */
+async function loadPromptFilesForVerification(options) {
+    const loadedPromptFiles = await loadPromptFiles(PROMPTS_DIR);
+    const { promptFiles, ignoredPromptFiles } = partitionPromptFilesByIgnore(loadedPromptFiles, options.ignore);
+    if (options.reverse) {
+        promptFiles.reverse();
+    }
+    return { promptFiles, ignoredPromptFiles };
+}
+/**
+ * Splits prompt files into files that should be verified now and files ignored for this run.
+ *
+ * @public exported from `@promptbook/cli`
+ */
+function partitionPromptFilesByIgnore(promptFiles, ignoreValues) {
+    const normalizedIgnoreValues = normalizeIgnoreValues(ignoreValues);
+    if (normalizedIgnoreValues.length === 0) {
+        return {
+            promptFiles: [...promptFiles],
+            ignoredPromptFiles: [],
+        };
+    }
+    const promptFilesToVerify = [];
+    const ignoredPromptFiles = [];
+    for (const promptFile of promptFiles) {
+        if (matchesIgnoredPromptFile(promptFile, normalizedIgnoreValues)) {
+            ignoredPromptFiles.push(promptFile);
+        }
+        else {
+            promptFilesToVerify.push(promptFile);
         }
     }
+    return {
+        promptFiles: promptFilesToVerify,
+        ignoredPromptFiles,
+    };
 }
 /**
  * Ensures the destination directory for completed prompts exists.
@@ -48216,13 +48296,92 @@ async function verifyPrompts(reverse = REVERSE_ORDER) {
 async function prepareArchiveDirectory() {
     await mkdir(DONE_PROMPTS_DIR, { recursive: true });
 }
+/**
+ * Normalizes verification options so the rest of the flow can assume stable defaults.
+ */
+function normalizeVerifyPromptsOptions(options) {
+    var _a, _b;
+    return {
+        reverse: (_a = options.reverse) !== null && _a !== void 0 ? _a : false,
+        ignore: normalizeIgnoreValues((_b = options.ignore) !== null && _b !== void 0 ? _b : []),
+    };
+}
+/**
+ * Normalizes ignore values and removes empty or duplicate entries case-insensitively.
+ */
+function normalizeIgnoreValues(ignoreValues) {
+    const normalizedIgnoreValues = [];
+    const seenIgnoreValues = new Set();
+    for (const ignoreValue of ignoreValues) {
+        const trimmedIgnoreValue = ignoreValue.trim();
+        if (!trimmedIgnoreValue) {
+            continue;
+        }
+        const lowerCasedIgnoreValue = trimmedIgnoreValue.toLowerCase();
+        if (seenIgnoreValues.has(lowerCasedIgnoreValue)) {
+            continue;
+        }
+        seenIgnoreValues.add(lowerCasedIgnoreValue);
+        normalizedIgnoreValues.push(trimmedIgnoreValue);
+    }
+    return normalizedIgnoreValues;
+}
+/**
+ * Reads one repeatable string option from raw CLI arguments.
+ */
+function readRepeatableStringOption(args, flag) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (!argument) {
+            continue;
+        }
+        if (argument === flag) {
+            const nextValue = args[index + 1];
+            if (nextValue !== undefined && !nextValue.startsWith('--')) {
+                values.push(nextValue);
+                index += 1;
+            }
+            continue;
+        }
+        if (argument.startsWith(`${flag}=`)) {
+            values.push(argument.slice(flag.length + 1));
+        }
+    }
+    return values;
+}
+/**
+ * Resolves whether a prompt file should be ignored for this verification run.
+ */
+function matchesIgnoredPromptFile(promptFile, ignoreValues) {
+    const searchableValues = [promptFile.name, getPromptFileFirstLine(promptFile)].map((value) => value.toLowerCase());
+    return ignoreValues.some((ignoreValue) => {
+        const lowerCasedIgnoreValue = ignoreValue.toLowerCase();
+        return searchableValues.some((searchableValue) => searchableValue.includes(lowerCasedIgnoreValue));
+    });
+}
+/**
+ * Returns the first meaningful line of the prompt file after the status line.
+ */
+function getPromptFileFirstLine(promptFile) {
+    var _a;
+    const firstSection = promptFile.sections[0];
+    const startLineIndex = (firstSection === null || firstSection === void 0 ? void 0 : firstSection.statusLineIndex) !== undefined ? firstSection.statusLineIndex + 1 : ((_a = firstSection === null || firstSection === void 0 ? void 0 : firstSection.startLine) !== null && _a !== void 0 ? _a : 0);
+    for (let index = startLineIndex; index < promptFile.lines.length; index += 1) {
+        const line = promptFile.lines[index];
+        if (line !== undefined && line.trim() !== '') {
+            return line.trim();
+        }
+    }
+    return '';
+}
 /**
  * Displays the list of files that currently live in the prompts root.
  */
 function displayTopLevelFileList(promptFiles) {
     console.info(colors.cyan('\nTop-level prompt files:'));
     if (!promptFiles.length) {
-        console.info(colors.gray('  (no markdown files found in prompts/)'));
+        console.info(colors.gray('  (no prompt markdown files found for this run in prompts/)'));
         return;
     }
     for (const file of promptFiles) {
@@ -48539,7 +48698,7 @@ function isNotFound(error) {
 }
 // Note: When run as a standalone script, call the exported function
 if (require.main === module) {
-    verifyPrompts(REVERSE_ORDER).catch((error) => {
+    verifyPrompts(DEFAULT_VERIFY_PROMPTS_OPTIONS).catch((error) => {
         console.error(colors.bgRed('Prompt verification failed:'), error);
         process.exit(1);
     });
@@ -48547,7 +48706,8 @@ if (require.main === module) {
 
 var verifyPrompts$1 = /*#__PURE__*/Object.freeze({
     __proto__: null,
-    verifyPrompts: verifyPrompts
+    verifyPrompts: verifyPrompts,
+    partitionPromptFilesByIgnore: partitionPromptFilesByIgnore
 });
 
 /**