@promptbook/cli 0.114.0-32 → 0.114.0-34

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

@@ -0,0 +1,89 @@
+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';
+import { addCoderAgentOption, type CoderAgentCliOptions } from './agentCliOptions';
+
+/**
+ * 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, --model and --agent filters show only prompts compatible with that selection
+            - Does not start a coding harness or modify prompt files
+        `),
+    );
+
+    addPromptRunnerSelectionOptions(command);
+    addCoderAgentOption(command);
+    addPromptPriorityOptions(command);
+
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const {
+                agent,
+                priority,
+                minPriority: minimumPriority,
+                maxPriority: maximumPriority,
+            } = cliOptions as {
+                readonly agent?: string;
+                readonly priority?: number;
+                readonly minPriority?: number;
+                readonly maxPriority?: number;
+            } & PromptRunnerSelectionCliOptions & CoderAgentCliOptions;
+            const runnerOptions = normalizePromptRunnerSelectionCliOptions(
+                cliOptions as PromptRunnerSelectionCliOptions,
+                { isAgentRequired: false },
+            );
+            const resolvedCoderAgentBook =
+                agent === undefined
+                    ? undefined
+                    : await (await import('../../../../scripts/run-codex-prompts/common/resolveCoderAgent'))
+                          .resolveCoderAgentBook(agent, process.cwd());
+            const promptRunnerIdentity =
+                runnerOptions.agentName === undefined &&
+                runnerOptions.model === undefined &&
+                resolvedCoderAgentBook === undefined
+                    ? undefined
+                    : {
+                          harnessName: runnerOptions.agentName,
+                          modelName: runnerOptions.model,
+                          agentReferences: resolvedCoderAgentBook?.agentReferences,
+                      };
+
+            // 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/mergeStringRecordJsonFile.ts

@@ -30,6 +30,23 @@ type MergeStringRecordJsonFileOptions = {
     readonly ensureParentDirectoryPath?: string;
 };
 
+/**
+ * Result of one additive string-record merge into a JSON file.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type MergedStringRecordJsonFile = {
+    /**
+     * Status describing whether the JSON file had to be created or updated.
+     */
+    readonly status: InitializationStatus;
+
+    /**
+     * Keys which were missing in the JSON file and therefore added by the merge.
+     */
+    readonly addedEntryKeys: ReadonlyArray<string>;
+};
+
 /**
  * Default indentation used when creating new JSON configuration files.
  */
@@ -43,6 +60,9 @@ const DEFAULT_JSON_FILE_NEWLINE = '\n';
 /**
  * Ensures one JSON object field contains the provided string-record entries.
  *
+ * Entries which the project already defines are **never** overridden - only missing keys are added,
+ * so hand-tuned scripts and settings survive every repeated `ptbk coder init`.
+ *
  * @private function of `initializeCoderProjectConfiguration`
  */
 export async function mergeStringRecordJsonFile({
@@ -51,7 +71,7 @@ export async function mergeStringRecordJsonFile({
     fieldPath,
     nextEntries,
     ensureParentDirectoryPath,
-}: MergeStringRecordJsonFileOptions): Promise<InitializationStatus> {
+}: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile> {
     if (ensureParentDirectoryPath) {
         await mkdir(join(projectPath, ensureParentDirectoryPath), { recursive: true });
     }
@@ -62,23 +82,27 @@ export async function mergeStringRecordJsonFile({
     const jsonObject = fileContent === undefined ? {} : await parseJsonObjectFile(relativeFilePath, fileContent);
     const existingEntries = getStringRecordOrDefault(jsonObject[fieldPath], relativeFilePath, fieldPath);
 
-    let hasChanges = fileContent === undefined;
+    const addedEntryKeys: Array<string> = [];
     const mergedEntries = { ...existingEntries };
     for (const [entryKey, entryValue] of Object.entries(nextEntries)) {
-        if (mergedEntries[entryKey] !== entryValue) {
-            mergedEntries[entryKey] = entryValue;
-            hasChanges = true;
+        if (Object.prototype.hasOwnProperty.call(mergedEntries, entryKey)) {
+            // Note: The project already defines this entry, keep its own value untouched
+            continue;
         }
+
+        mergedEntries[entryKey] = entryValue;
+        addedEntryKeys.push(entryKey);
     }
 
+    const hasChanges = fileContent === undefined || addedEntryKeys.length > 0;
     if (!hasChanges) {
-        return 'unchanged';
+        return { status: 'unchanged', addedEntryKeys };
     }
 
     const nextJsonObject: JsonObject = { ...jsonObject };
     nextJsonObject[fieldPath] = mergedEntries;
     await writeFile(absoluteFilePath, serializeJsonObject(nextJsonObject, formatting), 'utf-8');
-    return fileContent === undefined ? 'created' : 'updated';
+    return { status: fileContent === undefined ? 'created' : 'updated', addedEntryKeys };
 }
 
 /**

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

@@ -6,10 +6,11 @@ import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
-    addHarnessUpdateOption,
-    normalizeHarnessUpdateCliOptions,
-    type HarnessUpdateCliOptions,
-} from '../common/harnessUpdateCliOptions';
+    addQuestionsOption,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerRuntimeOptions,
@@ -30,24 +31,28 @@ import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignor
 export function $initializeCoderPingCommand(program: Program): $side_effect {
     const command = program.command('ping');
     command.description(
-        spaceTrim(`
-            Send one tiny dummy prompt to a harness and model to measure and warm them up
+        spaceTrim(
+            (block) => `
+                Send one tiny dummy prompt to a harness and model to measure and warm them up
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+                ${block(PROMPT_RUNNER_DESCRIPTION)}
 
-            Features:
-            - Verifies that the selected harness, model, thinking level and authentication really work
-            - Reports the answer of the harness, the response time and the reported usage
-            - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
-            - Optional --period keeps the quota window refreshing by pinging once per period until stopped
-            - Makes no coding changes or commits; if the selected harness has missing local ignore rules, offers to add them to .gitignore
-            - Checks that the selected harness is installed and up to date unless --no-harness-update is used
-            - Use --no-ui to stream the raw harness output instead of only the compact result
-        `),
+                ${block(QUESTIONS_DESCRIPTION)}
+
+                Features:
+                - Verifies that the selected harness, model, thinking level and authentication really work
+                - Reports the answer of the harness, the response time and the reported usage
+                - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
+                - Optional --period keeps the quota window refreshing by pinging once per period until stopped
+                - Makes no coding changes or commits; if the selected harness has missing local ignore rules, offers to add them to .gitignore
+                - Checks that the selected harness is installed and up to date unless --no-questions is used
+                - Use --no-ui to stream the raw harness output instead of only the compact result
+            `,
+        ),
     );
 
     addPromptRunnerSelectionOptions(command);
-    addHarnessUpdateOption(command);
+    addQuestionsOption(command);
     addPromptRunnerRuntimeOptions(command);
     command.option(
         '--period <duration>',
@@ -67,15 +72,13 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
             );
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
-                cliOptions as HarnessUpdateCliOptions,
-            );
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
 
             // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
             const periodMs = parseOptionalPeriodDuration('--period', periodValue);
 
-            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+            await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
 
             const pingOptions = {
                 agentName: runnerOptions.agentName,

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

@@ -0,0 +1,14 @@
+import colors from 'colors';
+import { formatUnknownErrorDetails } from '../../../../scripts/run-codex-prompts/common/formatUnknownErrorDetails';
+
+/**
+ * Prints why a coder run has ended to the terminal.
+ *
+ * @private internal utility of `coder run` and `coder server` commands
+ */
+export function printCoderRunFailure(error: Error): void {
+    console.error(colors.bgRed(`${error.name}`));
+    console.error(colors.red(formatUnknownErrorDetails(error)));
+}
+
+// Note: [🟡] Code for coder failure reporting [printCoderRunFailure](src/cli/cli-commands/coder/printCoderRunFailure.ts) should never be published outside of `@promptbook/cli`

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

@@ -1,8 +1,6 @@
 import colors from 'colors';
-import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
-import { AGENTS_FILE_PATH } from './agentsFile';
 import type { InitializationStatus } from './boilerplateTemplates';
-import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import type { CoderReferencedArtifactStatus } from './coderReferencedArtifacts';
 import { formatDisplayPath } from './formatDisplayPath';
 import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
 
@@ -16,23 +14,25 @@ export function printInitializationSummary(summary: CoderInitializationSummary):
     printInitializationStatusLine('prompts/', summary.promptsDirectoryStatus);
     printInitializationStatusLine('prompts/done/', summary.promptsDoneDirectoryStatus);
     printInitializationStatusLine('prompts/templates/', summary.promptsTemplatesDirectoryStatus);
-
-    for (const templateFileStatus of summary.promptTemplateFileStatuses) {
-        printInitializationStatusLine(
-            formatDisplayPath(templateFileStatus.relativeFilePath),
-            templateFileStatus.status,
-        );
-    }
-
     printInitializationStatusLine('agents/', summary.agentsDirectoryStatus);
-    printInitializationStatusLine(CODER_DEVELOPER_AGENT_FILE_PATH, summary.developerAgentFileStatus);
-    printInitializationStatusLine(AGENTS_FILE_PATH, summary.agentsFileStatus);
-    printInitializationStatusLine(AGENT_CODING_FILE_PATH, summary.agentCodingFileStatus);
     printInitializationStatusLine('.env', summary.envFileStatus);
     printInitializationStatusLine('.gitignore', summary.gitignoreFileStatus);
     printInitializationStatusLine('package.json', summary.packageJsonFileStatus);
     printInitializationStatusLine('.vscode/settings.json', summary.vscodeSettingsFileStatus);
 
+    for (const referencedArtifactStatus of summary.referencedArtifactStatuses) {
+        printInitializationStatusLine(
+            formatDisplayPath(referencedArtifactStatus.relativeFilePath),
+            referencedArtifactStatus.status,
+        );
+    }
+
+    if (summary.addedPackageJsonScriptNames.length > 0) {
+        printInitializationNote(`Added npm scripts: ${summary.addedPackageJsonScriptNames.join(', ')}`, colors.cyan);
+    } else {
+        printInitializationNote('All Promptbook coder npm scripts are already present.', colors.gray);
+    }
+
     if (summary.initializedEnvVariableNames.length > 0) {
         printInitializationNote(`Added env variables: ${summary.initializedEnvVariableNames.join(', ')}`, colors.cyan);
     } else {
@@ -43,7 +43,7 @@ export function printInitializationSummary(summary: CoderInitializationSummary):
 /**
  * Formats one initialization status into a human-readable label.
  */
-function formatInitializationStatus(status: InitializationStatus): string {
+function formatInitializationStatus(status: InitializationStatus | CoderReferencedArtifactStatus): string {
     if (status === 'created') {
         return 'created';
     }
@@ -52,13 +52,20 @@ function formatInitializationStatus(status: InitializationStatus): string {
         return 'updated';
     }
 
+    if (status === 'not-referenced') {
+        return 'not referenced by the added scripts, kept as is';
+    }
+
     return 'unchanged';
 }
 
 /**
  * Prints one checked initialization-status line.
  */
-function printInitializationStatusLine(relativePath: string, status: InitializationStatus): void {
+function printInitializationStatusLine(
+    relativePath: string,
+    status: InitializationStatus | CoderReferencedArtifactStatus,
+): void {
     console.info(colors.gray(`✔ ${relativePath}: ${formatInitializationStatus(status)}`));
 }
 

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

@@ -1,4 +1,3 @@
-import colors from 'colors';
 import {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
     Option,
@@ -6,15 +5,17 @@ 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 { $assertSufficientFreeDiskSpace } from '../common/disk-space/$assertSufficientFreeDiskSpace';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
-    addHarnessUpdateOption,
-    normalizeHarnessUpdateCliOptions,
-    type HarnessUpdateCliOptions,
-} from '../common/harnessUpdateCliOptions';
+    addQuestionsOption,
+    assertUserConfirmationIsAllowed,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import { $ensurePromptbookCliInstallations } from '../common/promptbook-cli/$ensurePromptbookCliInstallations';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
@@ -23,6 +24,7 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import {
     DEFAULT_CODER_TEST_COMMAND,
     TEST_BEFORE_MODE_VALUES,
@@ -30,6 +32,8 @@ import {
 } from '../../../../scripts/run-codex-prompts/testing/TestBeforeMode';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
+import { addCoderAgentOption, type CoderAgentCliOptions } from './agentCliOptions';
+import { printCoderRunFailure } from './printCoderRunFailure';
 
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
@@ -41,10 +45,13 @@ import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignor
 export function $initializeCoderRunCommand(program: Program): $side_effect {
     const command = program.command('run');
     command.description(
-        spaceTrim(`
+        spaceTrim(
+            (block) => `
             Execute coding prompts through selected AI agent
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+            ${block(PROMPT_RUNNER_DESCRIPTION)}
+
+            ${block(QUESTIONS_DESCRIPTION)}
 
             Features:
             - Automatically stages and commits changes with agent identity unless --no-commit is used
@@ -54,9 +61,11 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             - Optional post-commit git push with explicit --auto-push opt-in
             - Optional pre-prompt git pull with explicit --auto-pull opt-in
             - Optional --isolate runs every prompt in its own temporary git worktree and merges it back when verified
+            - Saves the run trace of every round into prompts/traces/, named after its prompt file
             - Optional --preserve-logs keeps temp prompt/log artifacts after successful rounds
             - Optional --no-ui keeps plain streaming console output for logging and debugging
-            - Checks that the selected harness is installed and up to date before the first prompt unless --no-harness-update is used
+            - Refuses to start on a nearly full disk and pauses the run when the free disk space becomes critical, unless --no-questions is used
+            - Checks that the selected harness is installed and up to date before the first prompt unless --no-questions is used
             - Offers to add missing project-local ignore rules for the selected harness
             - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
@@ -64,16 +73,14 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             - Optional post-prompt verification with test-feedback retries
             - Progress tracking and interactive P/S/X terminal controls
             - Dry-run mode to preview prompts
-        `),
+        `,
+        ),
     );
 
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
-    addHarnessUpdateOption(command);
-    command.option(
-        '--agent <agent-book-path>',
-        'Path to a .book file whose compiled system message is prepended to each coding prompt',
-    );
+    addQuestionsOption(command);
+    addCoderAgentOption(command);
     command.option(
         '--context <context-or-file>',
         'Append extra instructions either inline or from a file path relative to the current project',
@@ -107,21 +114,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',
@@ -201,16 +194,14 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly auto: boolean;
                 readonly autoMigrate: boolean;
                 readonly allowDestructiveAutoMigrate: boolean;
-            } & PromptRunnerCliOptions;
+            } & PromptRunnerCliOptions & CoderAgentCliOptions;
 
             const configuredTestCommand = normalizeCommandOptionValue(test);
             const testCommand = configuredTestCommand ?? (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
-                cliOptions as HarnessUpdateCliOptions,
-            );
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
 
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
@@ -220,12 +211,18 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             //   --wait-after-error: wait before retrying after an error (default 10m)
             const waitForUser = !auto;
 
-            if (await $ensurePromptbookCliInstallations()) {
+            assertUserConfirmationIsAllowed({ ...questionsOptions, isWaitingForUser: waitForUser });
+
+            // Note: Checked before anything is installed or written, because installing a harness, updating the
+            //       Promptbook CLI and coding itself all need the disk space which is missing
+            await $assertSufficientFreeDiskSpace(process.cwd());
+
+            if (await $ensurePromptbookCliInstallations(questionsOptions)) {
                 return process.exit(0);
             }
 
-            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+            await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
 
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
@@ -260,6 +257,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 allowDestructiveAutoMigrate,
                 autoPush: runnerOptions.autoPush,
                 autoPull: runnerOptions.autoPull,
+                isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled,
             };
 
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
@@ -270,8 +268,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 await runCodexPrompts(runOptions);
             } catch (error) {
                 assertsError(error);
-                console.error(colors.bgRed(`${error.name}`));
-                console.error(colors.red(error.stack || error.message));
+                printCoderRunFailure(error);
                 return process.exit(1);
             }