@promptbook/cli 0.114.0-32 → 0.114.0-33

package/esm/index.es.js

@@ -48,7 +48,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-32';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-33';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1812,20 +1812,20 @@ const PROMPT_RUNNER_HARNESS_NAMES = CLI_AGENT_HARNESS_NAMES;
  */
 const PROMPT_RUNNER_DESCRIPTION = spaceTrim$1(`
     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)
 `);
 /**
  * Commander description for the `--harness` option.
  *
  * @private internal utility of `promptbookCli`
  */
-const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = `Select runner: ${PROMPT_RUNNER_HARNESS_NAMES.join(', ')} (required for non-dry-run)`;
+const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = `Select runner: ${PROMPT_RUNNER_HARNESS_NAMES.join(', ')} (required when executing prompts)`;
 /**
  * Runner harness names listed as alternatives of the `--harness` option in error messages.
  *
@@ -1838,7 +1838,7 @@ const PROMPT_RUNNER_HARNESS_OPTION_HINT = `--harness <${PROMPT_RUNNER_HARNESS_NA
  * @private internal utility of `promptbookCli`
  */
 const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION = spaceTrim$1(`
-    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
@@ -42130,19 +42130,19 @@ function normalizeCoderGitSyncCliOptions(cliOptions) {
  *
  * @private internal utility of `ptbk coder`
  */
-const PROMPTS_DIRECTORY_PATH = 'prompts';
+const PROMPTS_DIRECTORY_PATH$1 = 'prompts';
 /**
  * Relative path to the archive directory used by `coder verify`.
  *
  * @private internal utility of `ptbk coder`
  */
-const PROMPTS_DONE_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH, 'done');
+const PROMPTS_DONE_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH$1, 'done');
 /**
  * Relative path to the project-owned boilerplate templates directory.
  *
  * @private internal utility of `ptbk coder`
  */
-const PROMPTS_TEMPLATES_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH, 'templates');
+const PROMPTS_TEMPLATES_DIRECTORY_PATH = join(PROMPTS_DIRECTORY_PATH$1, 'templates');
 /**
  * Built-in boilerplate templates available to `coder generate-boilerplates`.
  *
@@ -42426,7 +42426,7 @@ async function addCoderPrompt({ projectPath, description, priority, templateOpti
     // Note: Import these dynamically to avoid circular dependencies and keep the CLI fast
     const { buildPromptFilename, getPromptNumbering } = await Promise.resolve().then(function () { return getPromptNumbering$1; });
     const { formatPromptEmojiTag, getFreshPromptEmojiTags } = await Promise.resolve().then(function () { return promptEmojiTags; });
-    const promptsDirectory = join(projectPath, PROMPTS_DIRECTORY_PATH);
+    const promptsDirectory = join(projectPath, PROMPTS_DIRECTORY_PATH$1);
     mkdirSync(promptsDirectory, { recursive: true });
     const promptTemplate = await resolveCoderPromptTemplate({ projectPath, templateOption });
     const promptNumbering = await getPromptNumbering({
@@ -42450,7 +42450,7 @@ async function addCoderPrompt({ projectPath, description, priority, templateOpti
     });
     const slug = buildAddPromptSlug(promptTemplate.slugPrefix, title);
     const filename = buildPromptFilename(promptNumbering.datePrefix, promptNumbering.startNumber, slug);
-    const filePath = join(PROMPTS_DIRECTORY_PATH, filename);
+    const filePath = join(PROMPTS_DIRECTORY_PATH$1, filename);
     const absoluteFilePath = join(projectPath, filePath);
     writeFileSync(absoluteFilePath, `${section}\n`, 'utf-8');
     console.info(colors.green(`✓ Added prompt ${emojiTag} in ${filePath}`));
@@ -43042,10 +43042,10 @@ async function generatePromptBoilerplate({ projectPath, boilerplateCount, templa
     const { buildPromptFilename, getPromptNumbering } = await Promise.resolve().then(function () { return getPromptNumbering$1; });
     const { formatPromptEmojiTag, getFreshPromptEmojiTags } = await Promise.resolve().then(function () { return promptEmojiTags; });
     console.info(`🚀  Generate prompt boilerplate files`);
-    mkdirSync(join(projectPath, PROMPTS_DIRECTORY_PATH), { recursive: true });
+    mkdirSync(join(projectPath, PROMPTS_DIRECTORY_PATH$1), { recursive: true });
     const promptTemplate = await resolveCoderPromptTemplate({ projectPath, templateOption });
     const promptNumbering = await getPromptNumbering({
-        promptsDir: join(projectPath, PROMPTS_DIRECTORY_PATH),
+        promptsDir: join(projectPath, PROMPTS_DIRECTORY_PATH$1),
         step: 10,
         ignoreGlobs: ['**/node_modules/**'],
     });
@@ -43069,7 +43069,7 @@ async function generatePromptBoilerplate({ projectPath, boilerplateCount, templa
         const title = titles[i % titles.length];
         const emojiTag = formatPromptEmojiTag(selectedEmojis[i]);
         const filename = buildPromptFilename(promptNumbering.datePrefix, number, buildPromptSlug$1(promptTemplate.slugPrefix, title));
-        const filepath = join(PROMPTS_DIRECTORY_PATH, filename);
+        const filepath = join(PROMPTS_DIRECTORY_PATH$1, filename);
         const absoluteFilepath = join(projectPath, filepath);
         const content = buildBoilerplatePromptFileContent({
             emojiTag,
@@ -44349,7 +44349,7 @@ function resolveDefaultCoderVscodeSettingsEntry() {
  * @private internal utility of `coder init` command
  */
 async function initializeCoderProjectConfiguration(projectPath) {
-    const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH);
+    const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH$1);
     const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
     const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
     const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
@@ -44511,6 +44511,87 @@ function listDefaultCoderProjectPromptTemplateDisplayPaths() {
 // Note: [🟡] Code for CLI command [init](src/cli/cli-commands/coder/init.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Creates a Commander argument parser that accepts only non-negative integers.
+ *
+ * The returned parser is meant to be passed as the coercion callback of `command.option(...)`.
+ * It throws a branded `NotAllowed` error with a clear message referencing the given option name
+ * when the provided value is not a non-negative integer.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function createNonNegativeIntegerOptionParser(optionName) {
+    return (value) => {
+        const parsedValue = Number(value);
+        if (!Number.isInteger(parsedValue) || parsedValue < 0) {
+            throw new NotAllowed(spaceTrim$1(`
+                    Invalid value for \`${optionName}\`: \`${value}\`.
+
+                    Use a non-negative integer.
+                `));
+        }
+        return parsedValue;
+    };
+}
+// Note: [🟡] Code for CLI option parser [createNonNegativeIntegerOptionParser](src/cli/cli-commands/common/createNonNegativeIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`
+
+/**
+ * Registers the shared prompt-priority filter options on a queue-based `ptbk coder` command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function addPromptPriorityOptions(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'));
+}
+// 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
+
+/**
+ * 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`
+ */
+function $initializeCoderListCommand(program) {
+    const command = program.command('list');
+    command.description(spaceTrim$1(`
+            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;
+        const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { 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 Promise.resolve().then(function () { return listCoderPrompts$1; });
+        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
+
 /**
  * Default wait duration applied before retrying a prompt round after an error (10 minutes).
  *
@@ -44651,30 +44732,6 @@ function $initializeCoderPingCommand(program) {
 // Note: [🟡] Code for CLI command [ping](src/cli/cli-commands/coder/ping.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
-/**
- * Creates a Commander argument parser that accepts only non-negative integers.
- *
- * The returned parser is meant to be passed as the coercion callback of `command.option(...)`.
- * It throws a branded `NotAllowed` error with a clear message referencing the given option name
- * when the provided value is not a non-negative integer.
- *
- * @private internal utility of `promptbookCli`
- */
-function createNonNegativeIntegerOptionParser(optionName) {
-    return (value) => {
-        const parsedValue = Number(value);
-        if (!Number.isInteger(parsedValue) || parsedValue < 0) {
-            throw new NotAllowed(spaceTrim$1(`
-                    Invalid value for \`${optionName}\`: \`${value}\`.
-
-                    Use a non-negative integer.
-                `));
-        }
-        return parsedValue;
-    };
-}
-// Note: [🟡] Code for CLI option parser [createNonNegativeIntegerOptionParser](src/cli/cli-commands/common/createNonNegativeIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`
-
 /**
  * Npm packages which directly provide the `ptbk` executable.
  *
@@ -45131,9 +45188,7 @@ function $initializeCoderRunCommand(program) {
             A verified task is merged back into the branch the coder runs on and the worktree is deleted.
             A task that cannot be merged is marked as failed and its worktree is kept for a manual merge.
         `), 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', createPositiveIntegerOptionParser('--limit'));
     command.option('--wait-after-prompt <duration>', spaceTrim$1(`
             Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
@@ -45284,9 +45339,7 @@ function $initializeCoderServerCommand(program) {
     command.option('--test <test-command...>', 'Run a verification command after each prompt; quote it when the command itself contains top-level flags');
     command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', 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$1(`
             Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
             Accepts durations like 1h, 30m, 5s. Defaults to 0 (no wait).
@@ -45501,6 +45554,7 @@ function collectStringOption(value, previousValues) {
  * - 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
@@ -45521,6 +45575,7 @@ function $initializeCoderCommand(program) {
             - 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
@@ -45533,6 +45588,7 @@ function $initializeCoderCommand(program) {
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
+    $initializeCoderListCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
     $initializeCoderPingCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
@@ -74899,6 +74955,88 @@ var findUnwrittenPrompts$1 = /*#__PURE__*/Object.freeze({
     findUnwrittenPrompts: findUnwrittenPrompts
 });
 
+/**
+ * Lists todo prompts that are ready to run (no authoring placeholders).
+ */
+function listRunnablePrompts(files, priorityFilter = {}, promptRunnerIdentity) {
+    return listTodoPrompts(files).filter((prompt) => !isPromptToBeWritten(prompt.file, prompt.section) &&
+        isPromptInPriorityFilter(prompt.section, priorityFilter) &&
+        isPromptCompatibleWithRunner(prompt.file, prompt.section, promptRunnerIdentity));
+}
+
+/**
+ * Lists upcoming tasks that are ready to run (no authoring placeholders).
+ */
+function listUpcomingTasks(files, priorityFilter = {}, promptRunnerIdentity) {
+    return listRunnablePrompts(files, priorityFilter, promptRunnerIdentity).map(({ file, section }) => ({
+        label: buildPromptLabelForDisplay(file, section),
+        summary: buildPromptSummary(file, section),
+        priority: section.priority,
+    }));
+}
+
+/**
+ * Groups upcoming tasks by priority, high to low.
+ */
+function groupUpcomingTasksByPriority(tasks) {
+    const grouped = new Map();
+    for (const task of tasks) {
+        const group = grouped.get(task.priority);
+        if (group) {
+            group.push(task);
+        }
+        else {
+            grouped.set(task.priority, [task]);
+        }
+    }
+    return Array.from(grouped.entries())
+        .sort((a, b) => b[0] - a[0])
+        .map(([priority, groupedTasks]) => ({ priority, tasks: groupedTasks }));
+}
+
+/**
+ * Prints upcoming tasks grouped by priority.
+ */
+function printUpcomingTasks(tasks) {
+    if (tasks.length === 0) {
+        console.info(colors.green('No upcoming tasks.'));
+        return;
+    }
+    console.info(colors.cyan('Upcoming tasks (grouped by priority):'));
+    for (const group of groupUpcomingTasksByPriority(tasks)) {
+        console.info(colors.cyan(`Priority ${group.priority}:`));
+        for (const [index, task] of group.tasks.entries()) {
+            const summary = task.summary ? ` - ${task.summary}` : '';
+            console.info(` ${index + 1}. ${task.label}${summary}`);
+        }
+    }
+}
+
+/**
+ * Directory containing the prompt queue of the current project.
+ *
+ * @private internal constant of `listCoderPrompts`
+ */
+const PROMPTS_DIRECTORY_PATH = join(process.cwd(), 'prompts');
+/**
+ * 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`
+ */
+async function listCoderPrompts(options = {}) {
+    const priorityFilter = normalizePriorityFilter(options);
+    const promptFiles = await loadPromptFiles(PROMPTS_DIRECTORY_PATH);
+    const upcomingTasks = listUpcomingTasks(promptFiles, priorityFilter, options.promptRunnerIdentity);
+    printUpcomingTasks(upcomingTasks);
+    return upcomingTasks.length;
+}
+
+var listCoderPrompts$1 = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    listCoderPrompts: listCoderPrompts
+});
+
 /**
  * Formats one unknown error-like value into its readable message without the stack trace.
  *
@@ -78771,15 +78909,6 @@ function toProjectRelativeGitPath(projectPath, path) {
     return relative(projectPath, path).replace(/\\/gu, '/');
 }
 
-/**
- * Lists todo prompts that are ready to run (no authoring placeholders).
- */
-function listRunnablePrompts(files, priorityFilter = {}, promptRunnerIdentity) {
-    return listTodoPrompts(files).filter((prompt) => !isPromptToBeWritten(prompt.file, prompt.section) &&
-        isPromptInPriorityFilter(prompt.section, priorityFilter) &&
-        isPromptCompatibleWithRunner(prompt.file, prompt.section, promptRunnerIdentity));
-}
-
 /**
  * Selects the next runnable prompt based on priority.
  */
@@ -78793,54 +78922,6 @@ function findNextTodoPrompt(files, priorityFilter = {}, promptRunnerIdentity) {
     return nextPrompt;
 }
 
-/**
- * Lists upcoming tasks that are ready to run (no authoring placeholders).
- */
-function listUpcomingTasks(files, priorityFilter = {}, promptRunnerIdentity) {
-    return listRunnablePrompts(files, priorityFilter, promptRunnerIdentity).map(({ file, section }) => ({
-        label: buildPromptLabelForDisplay(file, section),
-        summary: buildPromptSummary(file, section),
-        priority: section.priority,
-    }));
-}
-
-/**
- * Groups upcoming tasks by priority, high to low.
- */
-function groupUpcomingTasksByPriority(tasks) {
-    const grouped = new Map();
-    for (const task of tasks) {
-        const group = grouped.get(task.priority);
-        if (group) {
-            group.push(task);
-        }
-        else {
-            grouped.set(task.priority, [task]);
-        }
-    }
-    return Array.from(grouped.entries())
-        .sort((a, b) => b[0] - a[0])
-        .map(([priority, groupedTasks]) => ({ priority, tasks: groupedTasks }));
-}
-
-/**
- * Prints upcoming tasks grouped by priority.
- */
-function printUpcomingTasks(tasks) {
-    if (tasks.length === 0) {
-        console.info(colors.green('No upcoming tasks.'));
-        return;
-    }
-    console.info(colors.cyan('Upcoming tasks (grouped by priority):'));
-    for (const group of groupUpcomingTasksByPriority(tasks)) {
-        console.info(colors.cyan(`Priority ${group.priority}:`));
-        for (const [index, task] of group.tasks.entries()) {
-            const summary = task.summary ? ` - ${task.summary}` : '';
-            console.info(` ${index + 1}. ${task.label}${summary}`);
-        }
-    }
-}
-
 /**
  * Builds a label that identifies the prompt section by index.
  */