@promptbook/cli 0.112.0-41 → 0.112.0-42

package/esm/scripts/verify-prompts/verify-prompts.d.ts

@@ -1,8 +1,29 @@
+import type { PromptFile } from '../run-codex-prompts/prompts/types/PromptFile';
+/**
+ * Options supported by the prompt verification helper.
+ */
+export type VerifyPromptsOptions = {
+    /**
+     * Process prompt files in reverse order.
+     */
+    readonly reverse?: boolean;
+    /**
+     * Ignore prompt files whose filename or first prompt line contains one of the provided values.
+     */
+    readonly ignore?: ReadonlyArray<string>;
+};
 /**
  * Starts the verification loop and exits when no `[ ]` prompts remain.
  *
- * @param reverse - Process files in reverse order
+ * @public exported from `@promptbook/cli`
+ */
+export declare function verifyPrompts(options?: VerifyPromptsOptions): Promise<void>;
+/**
+ * Splits prompt files into files that should be verified now and files ignored for this run.
  *
  * @public exported from `@promptbook/cli`
  */
-export declare function verifyPrompts(reverse?: boolean): Promise<void>;
+export declare function partitionPromptFilesByIgnore(promptFiles: ReadonlyArray<PromptFile>, ignoreValues: ReadonlyArray<string>): {
+    promptFiles: PromptFile[];
+    ignoredPromptFiles: PromptFile[];
+};

package/esm/src/cli/cli-commands/coder/verify.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

@@ -4,23 +4,11 @@ import type { string_book } from '../../../../book-2.0/agent-source/string_book'
 import type { string_agent_name, string_agent_permanent_id } from '../../../../types/typeAliases';
 import { AgentCollectionInSupabaseOptions } from './AgentCollectionInSupabaseOptions';
 import type { AgentsDatabaseSchema } from './AgentsDatabaseSchema';
+import { type CreateAgentPersistenceRecordsOptions } from './createAgentPersistenceRecords';
 /**
  * Options for creating a new agent entry.
  */
-type CreateAgentOptions = {
-    /**
-     * Visibility for the new agent.
-     */
-    readonly visibility?: 'PRIVATE' | 'UNLISTED' | 'PUBLIC';
-    /**
-     * Folder identifier to assign the new agent to.
-     */
-    readonly folderId?: number | null;
-    /**
-     * Sort order for the agent within its parent folder.
-     */
-    readonly sortOrder?: number;
-};
+type CreateAgentOptions = CreateAgentPersistenceRecordsOptions;
 /**
  * Optional controls for persisting one source update.
  */

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords.d.ts

@@ -0,0 +1,40 @@
+import type { AgentBasicInformation } from '../../../../book-2.0/agent-source/AgentBasicInformation';
+import type { string_book } from '../../../../book-2.0/agent-source/string_book';
+import type { CreateAgentInput } from '../../CreateAgentInput';
+import type { AgentsDatabaseSchema } from './AgentsDatabaseSchema';
+/**
+ * Optional persistence overrides for one new agent row.
+ *
+ * @private shared persistence helper for `AgentCollectionInSupabase`
+ */
+export type CreateAgentPersistenceRecordsOptions = Omit<CreateAgentInput, 'source'>;
+/**
+ * Prepared insert rows and returned profile for one newly persisted agent.
+ *
+ * @private shared persistence helper for `AgentCollectionInSupabase`
+ */
+export type CreateAgentPersistenceRecordsResult = {
+    /**
+     * Parsed created agent profile including the resolved permanent id.
+     */
+    readonly createdAgent: AgentBasicInformation & Required<Pick<AgentBasicInformation, 'permanentId'>>;
+    /**
+     * Insert row for the `Agent` table.
+     */
+    readonly agentInsertRecord: AgentsDatabaseSchema['public']['Tables']['Agent']['Insert'];
+    /**
+     * Insert row for the `AgentHistory` table.
+     */
+    readonly agentHistoryInsertRecord: AgentsDatabaseSchema['public']['Tables']['AgentHistory']['Insert'];
+};
+/**
+ * Builds normalized insert rows for a newly created persisted agent.
+ *
+ * @param agentSource - Source content of the agent.
+ * @param options - Optional folder placement, ordering, and visibility overrides.
+ * @param createdAt - Shared creation timestamp used across all persisted rows.
+ * @returns Insert rows and the created agent profile.
+ *
+ * @private shared persistence helper for `AgentCollectionInSupabase`
+ */
+export declare function createAgentPersistenceRecords(agentSource: string_book, options?: CreateAgentPersistenceRecordsOptions, createdAt?: string): CreateAgentPersistenceRecordsResult;

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords.test.d.ts

@@ -0,0 +1 @@
+export {};

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-40`).
+ * It follows semantic versioning (e.g., `0.112.0-41`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-41",
+    "version": "0.112.0-42",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,

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

@@ -60,7 +60,7 @@
      * @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
@@ -3094,14 +3094,16 @@
             - 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__default["default"].bgRed('Prompt verification failed:'), error);
@@ -3110,6 +3112,14 @@
             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
 
@@ -45392,6 +45402,7 @@
         return value.split('\\').join('/');
     }
 
+    // cspell:ignore hashtext
     /**
      * Cross-process advisory lock key guarding migration execution.
      *
@@ -45403,13 +45414,27 @@
      *
      * @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.
@@ -45933,23 +45958,33 @@
      * @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({
@@ -45960,7 +45995,7 @@
                     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 });
             }
@@ -45973,8 +46008,9 @@
         }
         return {
             processedPrefixes: selectedPrefixes,
-            totalMigrationFiles: migrationFiles.length,
+            totalMigrationFiles,
             perPrefix,
+            isSkippedDueToActiveMigrationLock,
         };
     }
     /**
@@ -48162,24 +48198,26 @@
      */
     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__default["default"].cyan.bold('📋 Prompt verification helper'));
-        if (reverse) {
+        if (normalizedOptions.reverse) {
             console.info(colors__default["default"].gray('Processing files in reverse order'));
         }
-        const initialFiles = await loadPromptFiles(PROMPTS_DIR);
-        if (reverse) {
-            initialFiles.reverse();
+        if (normalizedOptions.ignore.length > 0) {
+            console.info(colors__default["default"].gray(`Ignoring candidates matching: ${normalizedOptions.ignore.join(', ')}`));
+        }
+        const { promptFiles: initialFiles, ignoredPromptFiles } = await loadPromptFilesForVerification(normalizedOptions);
+        if (ignoredPromptFiles.length > 0) {
+            console.info(colors__default["default"].gray(`Ignored ${ignoredPromptFiles.length} prompt file(s) for this run.`));
         }
         displayTopLevelFileList(initialFiles);
         await prepareArchiveDirectory();
@@ -48194,10 +48232,7 @@
                 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
@@ -48207,11 +48242,56 @@
                 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.
@@ -48219,13 +48299,92 @@
     async function prepareArchiveDirectory() {
         await promises.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__default["default"].cyan('\nTop-level prompt files:'));
         if (!promptFiles.length) {
-            console.info(colors__default["default"].gray('  (no markdown files found in prompts/)'));
+            console.info(colors__default["default"].gray('  (no prompt markdown files found for this run in prompts/)'));
             return;
         }
         for (const file of promptFiles) {
@@ -48542,7 +48701,7 @@
     }
     // 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__default["default"].bgRed('Prompt verification failed:'), error);
             process.exit(1);
         });
@@ -48550,7 +48709,8 @@
 
     var verifyPrompts$1 = /*#__PURE__*/Object.freeze({
         __proto__: null,
-        verifyPrompts: verifyPrompts
+        verifyPrompts: verifyPrompts,
+        partitionPromptFilesByIgnore: partitionPromptFilesByIgnore
     });
 
     /**