@promptbook/cli 0.114.0-32 → 0.114.0-33

package/esm/scripts/run-codex-prompts/main/listCoderPrompts.d.ts

@@ -0,0 +1,20 @@
+import { type PriorityFilterInput } from '../prompts/priorityFilter';
+import type { PromptRunnerIdentity } from '../prompts/isPromptCompatibleWithRunner';
+/**
+ * Options which select the ready prompts listed by `ptbk coder list`.
+ *
+ * @public exported from `@promptbook/cli`
+ */
+export type ListCoderPromptsOptions = PriorityFilterInput & {
+    /**
+     * Optional harness and model selection used to omit prompts routed to other runners.
+     */
+    readonly promptRunnerIdentity?: PromptRunnerIdentity;
+};
+/**
+ * Lists ready, fully authored coding prompts in descending priority groups without starting a coding harness.
+ *
+ * @returns The number of prompts printed.
+ * @public exported from `@promptbook/cli`
+ */
+export declare function listCoderPrompts(options?: ListCoderPromptsOptions): Promise<number>;

package/esm/src/cli/cli-commands/coder/list.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder list` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeCoderListCommand(program: Program): $side_effect;

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

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

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

@@ -8,6 +8,7 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * - add: Add one ready-to-run prompt file to the queue
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
+ * - list: List ready prompts in priority order without running them
  * - run: Run coding prompts with AI agents
  * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts

package/esm/src/cli/cli-commands/common/promptPriorityCliOptions.d.ts

@@ -0,0 +1,7 @@
+import type { Command as Program } from 'commander';
+/**
+ * Registers the shared prompt-priority filter options on a queue-based `ptbk coder` command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addPromptPriorityOptions(command: Program): void;

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.114.0-31`).
+ * It follows semantic versioning (e.g., `0.114.0-32`).
  *
  * @generated
  */

package/package.json

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

package/src/cli/cli-commands/coder/list.ts

@@ -0,0 +1,77 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { handleActionErrors } from '../common/handleActionErrors';
+import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
+import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
+import {
+    addPromptRunnerSelectionOptions,
+    normalizePromptRunnerSelectionCliOptions,
+    PROMPT_RUNNER_DESCRIPTION,
+} from '../common/promptRunnerCliOptions';
+
+/**
+ * Initializes `coder list` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export function $initializeCoderListCommand(program: Program): $side_effect {
+    const command = program.command('list');
+    command.description(
+        spaceTrim(`
+            List ready coding prompts by priority without executing them
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+
+            Features:
+            - Lists only ready, fully authored prompts
+            - Groups prompts from highest to lowest priority
+            - Optional --harness and --model filters show only prompts compatible with that runner
+            - Does not start a coding harness or modify prompt files
+        `),
+    );
+
+    addPromptRunnerSelectionOptions(command);
+    addPromptPriorityOptions(command);
+
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const {
+                priority,
+                minPriority: minimumPriority,
+                maxPriority: maximumPriority,
+            } = cliOptions as {
+                readonly priority?: number;
+                readonly minPriority?: number;
+                readonly maxPriority?: number;
+            } & PromptRunnerSelectionCliOptions;
+            const runnerOptions = normalizePromptRunnerSelectionCliOptions(
+                cliOptions as PromptRunnerSelectionCliOptions,
+                { isAgentRequired: false },
+            );
+            const promptRunnerIdentity =
+                runnerOptions.agentName === undefined && runnerOptions.model === undefined
+                    ? undefined
+                    : {
+                          harnessName: runnerOptions.agentName,
+                          modelName: runnerOptions.model,
+                      };
+
+            // Note: Import dynamically to avoid loading prompt parsing dependencies until this command is used.
+            const { listCoderPrompts } = await import('../../../../scripts/run-codex-prompts/main/listCoderPrompts');
+            await listCoderPrompts({
+                priority,
+                minimumPriority,
+                maximumPriority,
+                promptRunnerIdentity,
+            });
+        }),
+    );
+}
+
+// Note: [🟡] Code for CLI command [list](src/cli/cli-commands/coder/list.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/coder/run.ts

@@ -6,7 +6,6 @@ import {
 import { spaceTrim } from 'spacetrim';
 import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
-import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativeIntegerOptionParser';
 import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
@@ -23,6 +22,7 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import {
     DEFAULT_CODER_TEST_COMMAND,
     TEST_BEFORE_MODE_VALUES,
@@ -107,21 +107,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
         `),
         false,
     );
-    command.option(
-        '--priority <minimum-priority>',
-        'Alias for --min-priority; filter prompts by minimum priority level',
-        createNonNegativeIntegerOptionParser('--priority'),
-    );
-    command.option(
-        '--min-priority <minimum-priority>',
-        'Filter prompts by minimum priority level',
-        createNonNegativeIntegerOptionParser('--min-priority'),
-    );
-    command.option(
-        '--max-priority <maximum-priority>',
-        'Filter prompts by maximum priority level',
-        createNonNegativeIntegerOptionParser('--max-priority'),
-    );
+    addPromptPriorityOptions(command);
     command.option(
         '--limit <run-count>',
         'Stop after processing this many prompt runs',

package/src/cli/cli-commands/coder/server.ts

@@ -9,7 +9,6 @@ import { assertsError } from '../../../errors/assertsError';
 import { NotAllowed } from '../../../errors/NotAllowed';
 import type { number_port } from '../../../types/number_positive';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
-import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativeIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
@@ -24,6 +23,7 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
 
@@ -90,21 +90,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
         false,
     );
     addPromptRunnerExecutionOptions(command);
-    command.option(
-        '--priority <minimum-priority>',
-        'Alias for --min-priority; filter prompts by minimum priority level',
-        createNonNegativeIntegerOptionParser('--priority'),
-    );
-    command.option(
-        '--min-priority <minimum-priority>',
-        'Filter prompts by minimum priority level',
-        createNonNegativeIntegerOptionParser('--min-priority'),
-    );
-    command.option(
-        '--max-priority <maximum-priority>',
-        'Filter prompts by maximum priority level',
-        createNonNegativeIntegerOptionParser('--max-priority'),
-    );
+    addPromptPriorityOptions(command);
     command.option(
         '--wait-after-prompt <duration>',
         spaceTrim(`

package/src/cli/cli-commands/coder.ts

@@ -10,6 +10,7 @@ import { $initializeCoderFindRefactorCandidatesCommand } from './coder/find-refa
 import { $initializeCoderFindUnwrittenCommand } from './coder/find-unwritten';
 import { $initializeCoderGenerateBoilerplatesCommand } from './coder/generate-boilerplates';
 import { $initializeCoderInitCommand } from './coder/init';
+import { $initializeCoderListCommand } from './coder/list';
 import { $initializeCoderPingCommand } from './coder/ping';
 import { $initializeCoderRunCommand } from './coder/run';
 import { $initializeCoderServerCommand } from './coder/server';
@@ -23,6 +24,7 @@ import { $initializeCoderVerifyCommand } from './coder/verify';
  * - add: Add one ready-to-run prompt file to the queue
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
+ * - list: List ready prompts in priority order without running them
  * - run: Run coding prompts with AI agents
  * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
@@ -44,6 +46,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
             - find-unwritten: List prompt sections that still need to be authored
+            - list: List ready prompts in priority order without running them
             - run: Run coding prompts with AI agents
             - ping: Test the connection, response time and quota of one harness and model
             - server: Start a long-running coder server with a kanban web UI
@@ -58,6 +61,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
+    $initializeCoderListCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
     $initializeCoderPingCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);

package/src/cli/cli-commands/common/promptPriorityCliOptions.ts

@@ -0,0 +1,30 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { createNonNegativeIntegerOptionParser } from './createNonNegativeIntegerOptionParser';
+
+/**
+ * Registers the shared prompt-priority filter options on a queue-based `ptbk coder` command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function addPromptPriorityOptions(command: Program): void {
+    command.option(
+        '--priority <minimum-priority>',
+        'Alias for --min-priority; filter prompts by minimum priority level',
+        createNonNegativeIntegerOptionParser('--priority'),
+    );
+    command.option(
+        '--min-priority <minimum-priority>',
+        'Filter prompts by minimum priority level',
+        createNonNegativeIntegerOptionParser('--min-priority'),
+    );
+    command.option(
+        '--max-priority <maximum-priority>',
+        'Filter prompts by maximum priority level',
+        createNonNegativeIntegerOptionParser('--max-priority'),
+    );
+}
+
+// Note: [🟡] Code for CLI prompt priority options [promptPriorityCliOptions](src/cli/cli-commands/common/promptPriorityCliOptions.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

package/src/cli/cli-commands/common/promptRunnerCliOptions.ts

@@ -94,13 +94,13 @@ export type NormalizedPromptRunnerSelectionCliOptions = Pick<
  */
 export const PROMPT_RUNNER_DESCRIPTION = spaceTrim(`
     Runners:
-    - openai-codex: OpenAI Codex integration (requires --model)
+    - openai-codex: OpenAI Codex integration (requires --model when executing)
     - github-copilot: GitHub Copilot CLI integration
     - cline: Cline CLI integration
     - claude-code: Claude Code integration
     - opencode: Opencode integration
-    - gemini: Google Gemini CLI integration (requires --model)
-    - qwen-code: Qwen Code CLI integration (requires --model)
+    - gemini: Google Gemini CLI integration (requires --model when executing)
+    - qwen-code: Qwen Code CLI integration (requires --model when executing)
 `);
 
 /**
@@ -110,7 +110,7 @@ export const PROMPT_RUNNER_DESCRIPTION = spaceTrim(`
  */
 export const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = `Select runner: ${PROMPT_RUNNER_HARNESS_NAMES.join(
     ', ',
-)} (required for non-dry-run)`;
+)} (required when executing prompts)`;
 
 /**
  * Runner harness names listed as alternatives of the `--harness` option in error messages.
@@ -125,7 +125,7 @@ export const PROMPT_RUNNER_HARNESS_OPTION_HINT = `--harness <${PROMPT_RUNNER_HAR
  * @private internal utility of `promptbookCli`
  */
 export const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION = spaceTrim(`
-    Model to use (required for openai-codex, gemini and qwen-code)
+    Model to use or filter by (required when executing with openai-codex, gemini and qwen-code)
 
     OpenAI examples: gpt-5.2-codex, default
     Gemini examples: gemini-3-flash-preview, default