@promptbook/cli 0.114.0-3 → 0.114.0-31

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

@@ -12,9 +12,15 @@ import {
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
+import {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
 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';
@@ -56,7 +62,7 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
                 - ${CODER_DEVELOPER_AGENT_FILE_PATH}
                 - ${AGENTS_FILE_PATH}
                 - ${AGENT_CODING_FILE_PATH}
-                - .gitignore
+                - .gitignore with local artifacts from every supported harness
                 - package.json
                 - .vscode/settings.json
 
@@ -65,7 +71,7 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
                 - CODING_AGENT_GIT_EMAIL
                 - CODING_AGENT_GIT_SIGNING_KEY
 
-                Checks that the coding harnesses are installed globally and up to date:
+                Checks that the coding harnesses are installed and up to date unless \`--no-harness-update\` is used:
                 ${block(listCheckedHarnessLabels())}
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
@@ -74,30 +80,34 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
     );
 
     addCoderGitSyncOptions(command);
+    addHarnessUpdateOption(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
             const projectPath = process.cwd();
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            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,
-                projectPath,
+                commitScope,
                 commitMessage: 'Initialize Promptbook Coder',
             });
 
-            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
+            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, isHarnessUpdateCheckEnabled);
         }),
     );
 }

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

@@ -5,6 +5,11 @@ 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 {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
 import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerRuntimeOptions,
@@ -12,6 +17,8 @@ import {
     normalizePromptRunnerSelectionCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { parseOptionalPeriodDuration } from './waitOptions';
+import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
 
 /**
  * Initializes `coder ping` command for Promptbook CLI utilities
@@ -32,38 +39,69 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
             - 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
+            - 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
         `),
     );
 
     addPromptRunnerSelectionOptions(command);
+    addHarnessUpdateOption(command);
     addPromptRunnerRuntimeOptions(command);
+    command.option(
+        '--period <duration>',
+        spaceTrim(`
+            Keep pinging once per period instead of pinging only once.
+            Accepts durations like 5h, 30m, 1h30m and repeats until it is stopped with CTRL+C.
+        `),
+    );
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const { period: periodValue } = cliOptions as {
+                readonly period?: string;
+            } & PromptRunnerSelectionCliOptions;
+
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
             );
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
+            const periodMs = parseOptionalPeriodDuration('--period', periodValue);
 
-            // 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'
-            );
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
+            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
 
-            const result = await pingCoderHarness({
+            const pingOptions = {
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 thinkingLevel: runnerOptions.thinkingLevel,
                 allowCredits: runnerOptions.allowCredits,
                 shouldPrintLiveOutput: runnerOptions.noUi,
-            });
+            };
+
+            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
+            if (periodMs !== undefined) {
+                const { pingCoderHarnessPeriodically } = await import(
+                    '../../../../scripts/run-codex-prompts/ping/pingCoderHarnessPeriodically'
+                );
+
+                // Note: This never returns - it keeps pinging until the user stops the process
+                await pingCoderHarnessPeriodically({ ...pingOptions, periodMs });
+                return;
+            }
+
+            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
+            const { printCoderPingResult } = await import(
+                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
+            );
 
-            printCoderPingResult(result);
+            printCoderPingResult(await pingCoderHarness(pingOptions));
         }),
     );
 }

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

@@ -10,6 +10,12 @@ import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativ
 import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
+import { $ensurePromptbookCliInstallations } from '../common/promptbook-cli/$ensurePromptbookCliInstallations';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -23,6 +29,7 @@ import {
     type TestBeforeMode,
 } from '../../../../scripts/run-codex-prompts/testing/TestBeforeMode';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
+import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
 
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
@@ -41,12 +48,17 @@ 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
+            - Refuses to start on a dirty working tree unless --git-changes says what should happen with the changes
+            - Optional --git-changes continue resumes the single prompt an interrupted coder left in the [^] status
             - 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
+            - Checks that the selected harness is installed and up to date before the first prompt unless --no-harness-update 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
             - Optional pre-coding test run that can stop or repair pre-existing failures
             - Optional post-prompt verification with test-feedback retries
@@ -57,6 +69,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
     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',
@@ -195,8 +208,9 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
-
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
@@ -205,6 +219,14 @@ 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], isHarnessUpdateCheckEnabled);
+            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);
@@ -217,7 +239,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 waitBetweenPrompts,
                 waitAfterError,
                 noCommit: runnerOptions.noCommit,
-                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                gitChanges: runnerOptions.gitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 agent,

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

@@ -12,6 +12,11 @@ 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 {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -20,6 +25,7 @@ import {
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
+import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
 
 /**
  * Default port used by `ptbk coder server`.
@@ -48,7 +54,8 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
 
             Features:
             - Runs the same prompt processing as \`ptbk coder run\`
-            - Checks that the selected harness is installed globally and up to date on startup
+            - Checks that the selected harness is installed and up to date on startup unless --no-harness-update is used
+            - Offers to add missing project-local ignore rules for the selected harness
             - Does not exit when all prompts are done; polls for new prompt files instead
             - Serves a kanban board at http://localhost:<port> for visual progress tracking
             - Allows editing prompt files directly from the browser (Trello-style)
@@ -64,6 +71,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
     );
     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',
@@ -173,8 +181,12 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
+            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
 
             // [1] Parse the wait options and --no-auto (same logic as `coder run`)
             const waitForUser = !auto;
@@ -190,7 +202,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 waitBetweenPrompts,
                 waitAfterError,
                 noCommit: runnerOptions.noCommit,
-                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                gitChanges: runnerOptions.gitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 agent,

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

@@ -1,8 +1,15 @@
 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 {
@@ -33,6 +40,7 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
                 - 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)}
 
@@ -41,7 +49,23 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
         ),
     );
 
-    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)',
@@ -52,8 +76,8 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
 
     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;
 
@@ -63,7 +87,7 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
             const { verifyPrompts } = await import('../../../../scripts/verify-prompts/verify-prompts');
 
             try {
-                await verifyPrompts({ reverse, ignore, gitSync });
+                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/waitOptions.ts

@@ -1,4 +1,6 @@
+import { spaceTrim } from 'spacetrim';
 import { parseDuration } from '../../../../scripts/run-codex-prompts/common/parseDuration';
+import { NotAllowed } from '../../../errors/NotAllowed';
 
 /**
  * Default wait duration applied before retrying a prompt round after an error (10 minutes).
@@ -21,4 +23,35 @@ export function parseOptionalWaitDuration(value: string | undefined, defaultMs:
     return parseDuration(value);
 }
 
+/**
+ * Parses an optional Commander period duration string and returns the resolved milliseconds.
+ *
+ * Returns `undefined` when the flag was not provided or was provided without a non-empty value,
+ * which means the command runs only once instead of repeating itself.
+ *
+ * @throws {NotAllowed} When the duration is not a positive one, because a non-positive period
+ *                      would repeat the command without ever pausing between two rounds
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined {
+    if (typeof value !== 'string' || value === '') {
+        return undefined;
+    }
+
+    const periodMs = parseDuration(value);
+
+    if (periodMs <= 0) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${optionName}\`: \`${value}\`.
+
+                Use a **positive** duration like \`5h\`, \`30m\` or \`1h30m\`.
+            `),
+        );
+    }
+
+    return periodMs;
+}
+
 // Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -2,16 +2,16 @@ 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 to confirm one optional change.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin
+ * 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
+ * @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 $askForConfirmation(question: string): Promise<boolean> {
     if (!process.stdin.isTTY) {
-        // Note: In non-interactive environments like CI there is nobody who could confirm the installation
+        // Note: In non-interactive environments like CI there is nobody who could confirm the change.
         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 confirmations [$askForConfirmation](src/cli/cli-commands/common/$askForConfirmation.ts) should never be published outside of `@promptbook/cli`

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

@@ -26,7 +26,7 @@ export type CoderGitSyncCliOptions = {
 export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
     Git synchronization:
     - --auto-pull pulls the latest changes before this command changes anything
-    - --commit commits the changes made by this command
+    - --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
 `);
 
@@ -39,7 +39,11 @@ export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
  * @private internal utility of `promptbookCli`
  */
 export function addCoderGitSyncOptions(command: Program): void {
-    command.option('--commit', 'Commit the changes made by this command with the coding-agent git identity', false);
+    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',

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

@@ -1,25 +1,35 @@
 import colors from 'colors';
-import { $askForHarnessInstallationApproval } from './$askForHarnessInstallationApproval';
-import { $installHarness } from './$installHarness';
+import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
+import { $runHarnessInstallationCommand } from './$runHarnessInstallationCommand';
 import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
+import type { HarnessDefinition } from './HarnessDefinition';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 import { formatHarnessInstallationWarning } from './formatHarnessInstallationWarning';
+import { formatHarnessManualUpdateInstruction } from './formatHarnessManualUpdateInstruction';
+import { resolveHarnessUpdatePlan } from './resolveHarnessUpdatePlan';
 
 /**
  * Reports one detected harness installation status and offers to install or update the harness.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs npm packages
+ * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs software
  *
  * @private internal utility of `promptbookCli`
  */
 export async function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void> {
-    const { definition, installationState, installedVersion, latestVersion } = status;
+    const { definition, installationState, installedVersion } = status;
 
     if (installationState === 'up-to-date') {
         console.info(colors.gray(`✔ ${definition.label} ${installedVersion} is up to date.`));
         return;
     }
 
+    if (installationState === 'installed') {
+        console.info(
+            colors.gray(`✔ ${definition.label} ${installedVersion} is installed. Skipped checking for updates.`),
+        );
+        return;
+    }
+
     if (installationState === 'unknown') {
         console.info(
             colors.gray(
@@ -31,18 +41,64 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
 
     console.warn(colors.yellow(formatHarnessInstallationWarning(status)));
 
-    const isInstallationApproved = await $askForHarnessInstallationApproval(
-        installationState === 'not-installed'
-            ? `Install ${definition.label} globally now?`
-            : `Update ${definition.label} to ${latestVersion} now?`,
+    if (installationState === 'not-installed') {
+        await $applyMissingHarnessInstallation(definition);
+        return;
+    }
+
+    await $applyOutdatedHarnessInstallation(status);
+}
+
+/**
+ * Offers to install a missing harness globally through npm.
+ */
+async function $applyMissingHarnessInstallation(definition: HarnessDefinition): Promise<void> {
+    const installCommand = buildHarnessInstallCommand(definition);
+
+    const isInstallationApproved = await $askForNpmPackageInstallationApproval(
+        `Install ${definition.label} globally now?`,
     );
 
     if (!isInstallationApproved) {
-        console.info(colors.gray(`Skipped, run \`${buildHarnessInstallCommand(definition)}\` to do it manually.`));
+        console.info(colors.gray(`Skipped, run \`${installCommand}\` to do it manually.`));
+        return;
+    }
+
+    await $runHarnessInstallationCommand({
+        definition,
+        operation: 'install',
+        command: installCommand,
+        environment: definition.npmInstallEnvironment,
+    });
+}
+
+/**
+ * Offers to update an outdated harness exactly where it is installed.
+ */
+async function $applyOutdatedHarnessInstallation(status: HarnessInstallationStatus): Promise<void> {
+    const { definition, latestVersion, installationOrigin } = status;
+    const updatePlan = resolveHarnessUpdatePlan(definition, installationOrigin.installationMethod);
+
+    if (updatePlan.command === null || !updatePlan.isRunnableByPromptbook) {
+        console.info(colors.gray(formatHarnessManualUpdateInstruction(status, updatePlan)));
+        return;
+    }
+
+    const isUpdateApproved = await $askForNpmPackageInstallationApproval(
+        `Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`,
+    );
+
+    if (!isUpdateApproved) {
+        console.info(colors.gray(`Skipped, run \`${updatePlan.command}\` to do it manually.`));
         return;
     }
 
-    await $installHarness(definition);
+    await $runHarnessInstallationCommand({
+        definition,
+        operation: 'update',
+        command: updatePlan.command,
+        environment: updatePlan.environment,
+    });
 }
 
 // Note: [🟡] Code for CLI harness installation handling [$applyHarnessInstallationStatus](src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.ts) should never be published outside of `@promptbook/cli`