@promptbook/cli 0.114.0-0 → 0.114.0-10

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

@@ -1,13 +1,16 @@
+import { DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE } from './boilerplateCount';
+
 /**
  * Default npm scripts initialized by `ptbk coder init`.
  */
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
-    'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
-    'coder:add': 'ptbk coder add --template ./prompts/templates/common.md',
+    // Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
+    'coder:generate-boilerplates': `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ./prompts/templates/common.md`,
+    'coder:add': 'npx ptbk coder add --template ./prompts/templates/common.md',
     'coder:run':
-        'ptbk coder run --harness openai-codex --model gpt-5.5 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
+        'npx ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
     // 'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
-    'coder:verify': 'ptbk coder verify',
+    'coder:verify': 'npx ptbk coder verify',
 } as const satisfies Readonly<Record<string, string>>;
 
 /**

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

@@ -3,12 +3,19 @@ import type {
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
+import {
+    addCoderGitSyncOptions,
+    CODER_GIT_SYNC_DESCRIPTION,
+    normalizeCoderGitSyncCliOptions,
+} from '../common/coderGitSyncCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
 import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
+import { DEFAULT_BOILERPLATE_COUNT } from './boilerplateCount';
 import { getDefaultCoderProjectPromptTemplateDefinitions } from './boilerplateTemplates';
 import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
 import { formatDisplayPath } from './formatDisplayPath';
@@ -61,16 +68,36 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
 
                 Checks that the coding harnesses are installed globally and up to date:
                 ${block(listCheckedHarnessLabels())}
+
+                ${block(CODER_GIT_SYNC_DESCRIPTION)}
             `,
         ),
     );
 
+    addCoderGitSyncOptions(command);
+
     command.action(
-        handleActionErrors(async () => {
+        handleActionErrors(async (cliOptions) => {
+            const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
             const projectPath = process.cwd();
+
+            // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
+                '../../../../scripts/run-codex-prompts/git/coderGitSync'
+            );
+
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
+
             const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
-            await generatePromptBoilerplate({ projectPath, filesCount: 5 });
+            await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
+
+            await $commitCoderChanges({
+                gitSync,
+                commitScope,
+                commitMessage: 'Initialize Promptbook Coder',
+            });
+
             await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
         }),
     );

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

@@ -14,7 +14,6 @@ import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';
 import { ensureCoderVscodeSettingsFile } from './ensureCoderVscodeSettingsFile';
 import { ensureDirectory } from './ensureDirectory';
-import { getDefaultCoderPackageJsonScripts } from './getDefaultCoderPackageJsonScripts';
 
 /**
  * Result summary returned after coder configuration initialization.
@@ -57,9 +56,7 @@ export async function initializeCoderProjectConfiguration(projectPath: string):
     const agentCodingFileStatus = await ensureCoderMarkdownFile(
         projectPath,
         AGENT_CODING_FILE_PATH,
-        getDefaultCoderAgentCodingFileContent({
-            packageJsonScripts: getDefaultCoderPackageJsonScripts(),
-        }),
+        getDefaultCoderAgentCodingFileContent(),
     );
     const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
     const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);

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

@@ -0,0 +1,72 @@
+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 { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
+import {
+    addPromptRunnerRuntimeOptions,
+    addPromptRunnerSelectionOptions,
+    normalizePromptRunnerSelectionCliOptions,
+    PROMPT_RUNNER_DESCRIPTION,
+} from '../common/promptRunnerCliOptions';
+
+/**
+ * Initializes `coder ping` 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 $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
+
+            ${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
+            - Leaves the project exactly as it was — nothing is read, written, changed or committed
+            - Use --no-ui to stream the raw harness output instead of only the compact result
+        `),
+    );
+
+    addPromptRunnerSelectionOptions(command);
+    addPromptRunnerRuntimeOptions(command);
+
+    command.action(
+        handleActionErrors(async (cliOptions) => {
+            const runnerOptions = normalizePromptRunnerSelectionCliOptions(
+                cliOptions as PromptRunnerSelectionCliOptions,
+                { isAgentRequired: true },
+            );
+
+            await $ensureHarnessInstallations([runnerOptions.agentName]);
+
+            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
+            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
+            const { printCoderPingResult } = await import(
+                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
+            );
+
+            const result = await pingCoderHarness({
+                agentName: runnerOptions.agentName,
+                model: runnerOptions.model,
+                thinkingLevel: runnerOptions.thinkingLevel,
+                allowCredits: runnerOptions.allowCredits,
+                shouldPrintLiveOutput: runnerOptions.noUi,
+            });
+
+            printCoderPingResult(result);
+        }),
+    );
+}
+
+// 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

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

@@ -1,5 +1,8 @@
 import colors from 'colors';
-import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
+import {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+    Option,
+} from 'commander';
 import { spaceTrim } from 'spacetrim';
 import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
@@ -7,6 +10,7 @@ import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativ
 import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import { $ensurePromptbookCliInstallations } from '../common/promptbook-cli/$ensurePromptbookCliInstallations';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -14,6 +18,11 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import {
+    DEFAULT_CODER_TEST_COMMAND,
+    TEST_BEFORE_MODE_VALUES,
+    type TestBeforeMode,
+} from '../../../../scripts/run-codex-prompts/testing/TestBeforeMode';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 
 /**
@@ -33,13 +42,16 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
             Features:
             - Automatically stages and commits changes with agent identity unless --no-commit is used
+            - Commits only the prompt file and the files the coding agent has changed, leaving unrelated changes alone
             - 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
             - 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 globally and up to date before the first prompt
+            - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
+            - Optional pre-coding test run that can stop or repair pre-existing failures
             - Optional post-prompt verification with test-feedback retries
             - Progress tracking and interactive P/S/X terminal controls
             - Dry-run mode to preview prompts
@@ -60,6 +72,16 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
         '--test <test-command...>',
         'Run a verification command after each prompt; quote it when the command itself contains top-level flags',
     );
+    command.addOption(
+        new Option(
+            '--test-before <mode>',
+            `Run tests before coding: ${TEST_BEFORE_MODE_VALUES.join(
+                ', ',
+            )} (defaults to no; uses npm test when --test is omitted)`,
+        )
+            .choices([...TEST_BEFORE_MODE_VALUES])
+            .default('no'),
+    );
     command.option(
         '--preserve-logs',
         'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics',
@@ -138,6 +160,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 agent,
                 context,
                 test,
+                testBefore,
                 preserveLogs,
                 isolate: isIsolated,
                 priority,
@@ -155,6 +178,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly agent?: string;
                 readonly context?: string;
                 readonly test?: string | string[];
+                readonly testBefore: TestBeforeMode;
                 readonly preserveLogs: boolean;
                 readonly isolate: boolean;
                 readonly priority?: number;
@@ -169,13 +193,12 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly allowDestructiveAutoMigrate: boolean;
             } & PromptRunnerCliOptions;
 
-            const testCommand = normalizeCommandOptionValue(test);
+            const configuredTestCommand = normalizeCommandOptionValue(test);
+            const testCommand = configuredTestCommand ?? (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
-
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
             //   --no-auto: wait for user confirmation before each prompt (interactive mode)
@@ -183,6 +206,13 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             //   --wait-between-prompts: pace from start of one prompt to start of next
             //   --wait-after-error: wait before retrying after an error (default 10m)
             const waitForUser = !auto;
+
+            if (await $ensurePromptbookCliInstallations()) {
+                return process.exit(0);
+            }
+
+            await $ensureHarnessInstallations([runnerOptions.agentName]);
+
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);
@@ -201,6 +231,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 agent,
                 context,
                 testCommand,
+                testBefore,
                 preserveLogs,
                 isIsolated,
                 noUi: runnerOptions.noUi,

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

@@ -1,9 +1,22 @@
 import colors from 'colors';
-import type {
+import {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+    Option,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import type { VerifyPromptsOrder } from '../../../../scripts/verify-prompts/VerifyPromptsOrder';
+import {
+    DEFAULT_VERIFY_PROMPTS_ORDER,
+    VERIFY_PROMPTS_ORDER_DESCRIPTIONS,
+    VERIFY_PROMPTS_ORDER_VALUES,
+} from '../../../../scripts/verify-prompts/VerifyPromptsOrder';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
+import {
+    addCoderGitSyncOptions,
+    CODER_GIT_SYNC_DESCRIPTION,
+    normalizeCoderGitSyncCliOptions,
+} from '../common/coderGitSyncCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -16,39 +29,65 @@ import { handleActionErrors } from '../common/handleActionErrors';
 export function $initializeCoderVerifyCommand(program: Program): $side_effect {
     const command = program.command('verify');
     command.description(
-        spaceTrim(`
-            Interactive verification helper for completed prompts
+        spaceTrim(
+            (block) => `
+                Interactive verification helper for completed prompts
 
-            Features:
-            - Displays list of prompt files with status counts
-            - Guides through verification of completed prompts marked [x]
-            - 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
-        `),
+                Features:
+                - Displays list of prompt files with status counts
+                - Guides through verification of completed prompts marked [x]
+                - 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
+                - Supports processing the prompt files from the earliest, from the latest or in random order
+
+                ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                Note: The git synchronization is applied around each single verification, not once per run.
+            `,
+        ),
     );
 
-    command.option('--reverse', 'Process prompt files in reverse order', false);
+    command.addOption(
+        new Option(
+            '--order <order>',
+            spaceTrim(
+                (block) => `
+                    Order in which the prompt files are processed:
+                    ${block(
+                        VERIFY_PROMPTS_ORDER_VALUES.map(
+                            (order) => `- ${order}: ${VERIFY_PROMPTS_ORDER_DESCRIPTIONS[order]}`,
+                        ).join('\n'),
+                    )}
+                `,
+            ),
+        )
+            .choices([...VERIFY_PROMPTS_ORDER_VALUES])
+            .default(DEFAULT_VERIFY_PROMPTS_ORDER),
+    );
     command.option(
         '--ignore <candidate-text>',
         'Ignore prompt files whose filename or first prompt line contains the given text (repeatable)',
         collectStringOption,
         [],
     );
+    addCoderGitSyncOptions(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const { reverse, ignore } = cliOptions as {
-                readonly reverse: boolean;
+            const { order, ignore } = cliOptions as {
+                readonly order: VerifyPromptsOrder;
                 readonly ignore: ReadonlyArray<string>;
-            };
+            } & CoderGitSyncCliOptions;
+
+            const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
 
             // Note: Import the main function dynamically to avoid loading heavy dependencies until needed
             const { verifyPrompts } = await import('../../../../scripts/verify-prompts/verify-prompts');
 
             try {
-                await verifyPrompts({ reverse, ignore });
+                await verifyPrompts({ order, ignore, gitSync });
             } catch (error) {
                 console.error(colors.bgRed('Prompt verification failed:'), error);
                 return process.exit(1);

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 { $initializeCoderPingCommand } from './coder/ping';
 import { $initializeCoderRunCommand } from './coder/run';
 import { $initializeCoderServerCommand } from './coder/server';
 import { $initializeCoderVerifyCommand } from './coder/verify';
@@ -23,6 +24,7 @@ import { $initializeCoderVerifyCommand } from './coder/verify';
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
  * - run: Run coding prompts with AI agents
+ * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags
  *
@@ -43,6 +45,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             - find-refactor-candidates: Find files that need refactoring
             - find-unwritten: List prompt sections that still need to be authored
             - 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
             - verify: Verify completed prompts
             - find-fresh-emoji-tags: Find unused emoji tags
@@ -56,6 +59,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
+    $initializeCoderPingCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);

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

@@ -0,0 +1,82 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { spaceTrim } from 'spacetrim';
+import type { CoderGitSyncOptions } from '../../../../scripts/run-codex-prompts/git/coderGitSync';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+export type { CoderGitSyncOptions };
+
+/**
+ * Commander option bag for the shared `ptbk coder` git synchronization flags.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type CoderGitSyncCliOptions = {
+    readonly commit: boolean;
+    readonly autoPush: boolean;
+    readonly autoPull: boolean;
+};
+
+/**
+ * Description block shared by the `ptbk coder` commands which can synchronize their changes with git.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
+    Git synchronization:
+    - --auto-pull pulls the latest changes before this command changes anything
+    - --commit commits only the files this command has changed, unrelated changes stay in the working tree
+    - --auto-push pushes the created commit to the remote repository
+`);
+
+/**
+ * Registers the shared `--commit`, `--auto-push` and `--auto-pull` flags on a `ptbk coder` command.
+ *
+ * Note: Unlike `ptbk coder run`, which commits by default and opts out through `--no-commit`,
+ *       these commands never touch git unless the flags are used explicitly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function addCoderGitSyncOptions(command: Program): void {
+    command.option(
+        '--commit',
+        'Commit the files changed by this command with the coding-agent git identity, leaving unrelated changes uncommitted',
+        false,
+    );
+    command.option('--auto-push', 'Automatically git push the created commit, requires --commit', false);
+    command.option(
+        '--auto-pull',
+        'Automatically git pull the latest changes before this command changes anything',
+        false,
+    );
+}
+
+/**
+ * Converts the Commander git synchronization flags into normalized git synchronization options.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function normalizeCoderGitSyncCliOptions(cliOptions: CoderGitSyncCliOptions): CoderGitSyncOptions {
+    if (cliOptions.autoPush && !cliOptions.commit) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Flag \`--auto-push\` can be used only together with \`--commit\`.
+
+                **There is nothing to push when the changes are not committed.**
+
+                Actionable hint:
+                - Add \`--commit\`, for example \`ptbk coder init --commit --auto-push\`.
+            `),
+        );
+    }
+
+    return {
+        isCommitEnabled: cliOptions.commit,
+        isAutoPushEnabled: cliOptions.autoPush,
+        isAutoPullEnabled: cliOptions.autoPull,
+    };
+}
+
+// Note: [🟡] Code for CLI git synchronization options [coderGitSyncCliOptions](src/cli/cli-commands/common/coderGitSyncCliOptions.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/harness/$applyHarnessInstallationStatus.ts

@@ -1,5 +1,5 @@
 import colors from 'colors';
-import { $askForHarnessInstallationApproval } from './$askForHarnessInstallationApproval';
+import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
 import { $installHarness } from './$installHarness';
 import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
@@ -31,7 +31,7 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
 
     console.warn(colors.yellow(formatHarnessInstallationWarning(status)));
 
-    const isInstallationApproved = await $askForHarnessInstallationApproval(
+    const isInstallationApproved = await $askForNpmPackageInstallationApproval(
         installationState === 'not-installed'
             ? `Install ${definition.label} globally now?`
             : `Update ${definition.label} to ${latestVersion} now?`,

package/src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts

@@ -1,8 +1,8 @@
 import { $resolveInstalledHarnessVersion } from './$resolveInstalledHarnessVersion';
-import { $resolveLatestHarnessVersion } from './$resolveLatestHarnessVersion';
+import { $resolveLatestNpmPackageVersion } from '../npm/$resolveLatestNpmPackageVersion';
+import { isNpmPackageVersionOutdated } from '../npm/isNpmPackageVersionOutdated';
 import type { HarnessDefinition } from './HarnessDefinition';
 import type { HarnessInstallationState, HarnessInstallationStatus } from './HarnessInstallationStatus';
-import { isHarnessVersionOutdated } from './isHarnessVersionOutdated';
 
 /**
  * Detects whether one CLI coding harness is installed globally and whether it is up to date.
@@ -14,7 +14,7 @@ import { isHarnessVersionOutdated } from './isHarnessVersionOutdated';
 export async function $checkHarnessInstallation(definition: HarnessDefinition): Promise<HarnessInstallationStatus> {
     const [installedVersion, latestVersion] = await Promise.all([
         $resolveInstalledHarnessVersion(definition),
-        $resolveLatestHarnessVersion(definition),
+        $resolveLatestNpmPackageVersion(definition.npmPackageName),
     ]);
 
     return {
@@ -40,7 +40,9 @@ function resolveHarnessInstallationState(
         return 'unknown';
     }
 
-    return isHarnessVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
+    return isNpmPackageVersionOutdated(installedVersion, latestVersion, { isPrereleaseIgnored: true })
+        ? 'outdated'
+        : 'up-to-date';
 }
 
 // Note: [🟡] Code for CLI harness installation check [$checkHarnessInstallation](src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/$resolveInstalledHarnessVersion.ts

@@ -1,5 +1,5 @@
 import { $execCommand } from '../../../../utils/execCommand/$execCommand';
-import { extractHarnessVersionFromOutput } from './extractHarnessVersionFromOutput';
+import { extractNpmPackageVersionFromOutput } from '../npm/extractNpmPackageVersionFromOutput';
 import type { HarnessDefinition } from './HarnessDefinition';
 
 /**
@@ -23,7 +23,7 @@ export async function $resolveInstalledHarnessVersion(definition: HarnessDefinit
         isVerbose: false,
     }).catch(() => '');
 
-    return extractHarnessVersionFromOutput(output);
+    return extractNpmPackageVersionFromOutput(output);
 }
 
 // Note: [🟡] Code for CLI harness version detection [$resolveInstalledHarnessVersion](src/cli/cli-commands/common/harness/$resolveInstalledHarnessVersion.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/buildHarnessInstallCommand.ts

@@ -1,3 +1,4 @@
+import { buildNpmPackageInstallCommand } from '../npm/buildNpmPackageInstallCommand';
 import type { HarnessDefinition } from './HarnessDefinition';
 
 /**
@@ -9,7 +10,7 @@ import type { HarnessDefinition } from './HarnessDefinition';
  * @private internal utility of `promptbookCli`
  */
 export function buildHarnessInstallCommand(definition: HarnessDefinition): string {
-    return `npm install -g ${definition.npmPackageName}@latest`;
+    return buildNpmPackageInstallCommand(definition.npmPackageName, 'global');
 }
 
 // Note: [🟡] Code for CLI harness install command [buildHarnessInstallCommand](src/cli/cli-commands/common/harness/buildHarnessInstallCommand.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/{harness/$askForHarnessInstallationApproval.ts → npm/$askForNpmPackageInstallationApproval.ts}

@@ -2,14 +2,14 @@ import colors from 'colors';
 import { createInterface } from 'readline';
 
 /**
- * Asks the user in the terminal whether the harness should be installed or updated right now.
+ * Asks the user in the terminal whether an npm package should be installed or updated now.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin
  *
  * @returns `true` when the user confirms, `false` when the user declines or the terminal is not interactive
  * @private internal utility of `promptbookCli`
  */
-export async function $askForHarnessInstallationApproval(question: string): Promise<boolean> {
+export async function $askForNpmPackageInstallationApproval(question: string): Promise<boolean> {
     if (!process.stdin.isTTY) {
         // Note: In non-interactive environments like CI there is nobody who could confirm the installation
         return false;
@@ -28,4 +28,4 @@ export async function $askForHarnessInstallationApproval(question: string): Prom
     }
 }
 
-// Note: [🟡] Code for CLI harness installation approval [$askForHarnessInstallationApproval](src/cli/cli-commands/common/harness/$askForHarnessInstallationApproval.ts) should never be published outside of `@promptbook/cli`
+// Note: [🟡] Code for CLI npm package installation approval [$askForNpmPackageInstallationApproval](src/cli/cli-commands/common/npm/$askForNpmPackageInstallationApproval.ts) should never be published outside of `@promptbook/cli`