@promptbook/cli 0.113.0-8 → 0.114.0-0

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

@@ -1,13 +1,17 @@
 import colors from 'colors';
-import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
-import { Option } from 'commander';
+import {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+    Option,
+} from 'commander';
 import { spaceTrim } from 'spacetrim';
 import { NETWORK_LIMITS } from '../../../constants';
 import { assertsError } from '../../../errors/assertsError';
 import { NotAllowed } from '../../../errors/NotAllowed';
 import type { number_port } from '../../../types/number_positive';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativeIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
+import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -44,11 +48,12 @@ 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
             - 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)
             - Play / pause button in the browser stays in sync with the CLI pause state
-            - Press "p" in the terminal to pause / resume (same as \`ptbk coder run\`)
+            - Terminal controls match \`ptbk coder run\`: P pause/resume, S skip waiting, X end after current prompt
         `),
     );
 
@@ -77,7 +82,21 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
         false,
     );
     addPromptRunnerExecutionOptions(command);
-    command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
+    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'),
+    );
     command.option(
         '--wait-after-prompt <duration>',
         spaceTrim(`
@@ -123,6 +142,8 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 test,
                 preserveLogs,
                 priority,
+                minPriority: minimumPriority,
+                maxPriority: maximumPriority,
                 waitAfterPrompt: waitAfterPromptValue,
                 waitBetweenPrompts: waitBetweenPromptsValue,
                 waitAfterError: waitAfterErrorValue,
@@ -136,7 +157,9 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 readonly context?: string;
                 readonly test?: string | string[];
                 readonly preserveLogs: boolean;
-                readonly priority: number;
+                readonly priority?: number;
+                readonly minPriority?: number;
+                readonly maxPriority?: number;
                 readonly waitAfterPrompt?: string;
                 readonly waitBetweenPrompts?: string;
                 readonly waitAfterError?: string;
@@ -151,6 +174,8 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 isAgentRequired: !dryRun,
             });
 
+            await $ensureHarnessInstallations([runnerOptions.agentName]);
+
             // [1] Parse the wait options and --no-auto (same logic as `coder run`)
             const waitForUser = !auto;
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
@@ -174,7 +199,9 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 preserveLogs,
                 noUi: runnerOptions.noUi,
                 thinkingLevel: runnerOptions.thinkingLevel,
-                priority,
+                priority: priority ?? 0,
+                minimumPriority,
+                maximumPriority,
                 normalizeLineEndings: runnerOptions.normalizeLineEndings,
                 allowCredits: runnerOptions.allowCredits,
                 autoMigrate,
@@ -223,19 +250,6 @@ function parseCoderServerPort(rawPort: string): number_port {
     return port as number_port;
 }
 
-/**
- * Parses an integer option value.
- *
- * @private internal utility of `coder server` command
- */
-function parseIntOption(value: string): number {
-    const parsed = parseInt(value, 10);
-    if (isNaN(parsed)) {
-        throw new Error(`Invalid number: ${value}`);
-    }
-    return parsed;
-}
-
 /**
  * Joins one Commander option that may be parsed either as a single string or a variadic token array.
  *

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

@@ -4,6 +4,7 @@ import type {
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $initializeCoderAddCommand } from './coder/add';
 import { $initializeCoderFindFreshEmojiTagCommand } from './coder/find-fresh-emoji-tags';
 import { $initializeCoderFindRefactorCandidatesCommand } from './coder/find-refactor-candidates';
 import { $initializeCoderFindUnwrittenCommand } from './coder/find-unwritten';
@@ -18,6 +19,7 @@ import { $initializeCoderVerifyCommand } from './coder/verify';
  *
  * The coder command provides utilities for automated coding:
  * - init: Initialize coder configuration in current project
+ * - 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
  * - run: Run coding prompts with AI agents
@@ -36,6 +38,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
 
             Subcommands:
             - init: Initialize coder configuration in current project
+            - 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
             - find-unwritten: List prompt sections that still need to be authored
@@ -48,6 +51,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
 
     // Register all subcommands
     $initializeCoderInitCommand(coderCommand);
+    $initializeCoderAddCommand(coderCommand);
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);

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

@@ -0,0 +1,31 @@
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/**
+ * 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`
+ */
+export function createNonNegativeIntegerOptionParser(optionName: string): (value: string) => number {
+    return (value: string): number => {
+        const parsedValue = Number(value);
+
+        if (!Number.isInteger(parsedValue) || parsedValue < 0) {
+            throw new NotAllowed(
+                spaceTrim(`
+                    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`

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

@@ -0,0 +1,48 @@
+import colors from 'colors';
+import { $askForHarnessInstallationApproval } from './$askForHarnessInstallationApproval';
+import { $installHarness } from './$installHarness';
+import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
+import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
+import { formatHarnessInstallationWarning } from './formatHarnessInstallationWarning';
+
+/**
+ * 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
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void> {
+    const { definition, installationState, installedVersion, latestVersion } = status;
+
+    if (installationState === 'up-to-date') {
+        console.info(colors.gray(`✔ ${definition.label} ${installedVersion} is up to date.`));
+        return;
+    }
+
+    if (installationState === 'unknown') {
+        console.info(
+            colors.gray(
+                `✔ ${definition.label} ${installedVersion} is installed, the newest version could not be checked.`,
+            ),
+        );
+        return;
+    }
+
+    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 (!isInstallationApproved) {
+        console.info(colors.gray(`Skipped, run \`${buildHarnessInstallCommand(definition)}\` to do it manually.`));
+        return;
+    }
+
+    await $installHarness(definition);
+}
+
+// Note: [🟡] Code for CLI harness installation handling [$applyHarnessInstallationStatus](src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,31 @@
+import colors from 'colors';
+import { createInterface } from 'readline';
+
+/**
+ * Asks the user in the terminal whether the harness should be installed or updated right 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> {
+    if (!process.stdin.isTTY) {
+        // Note: In non-interactive environments like CI there is nobody who could confirm the installation
+        return false;
+    }
+
+    const readlineInterface = createInterface({ input: process.stdin, output: process.stdout });
+
+    try {
+        const answer = await new Promise<string>((resolve) => {
+            readlineInterface.question(colors.cyan(`${question} [y/N] `), resolve);
+        });
+
+        return ['y', 'yes'].includes(answer.trim().toLowerCase());
+    } finally {
+        readlineInterface.close();
+    }
+}
+
+// Note: [🟡] Code for CLI harness installation approval [$askForHarnessInstallationApproval](src/cli/cli-commands/common/harness/$askForHarnessInstallationApproval.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,46 @@
+import { $resolveInstalledHarnessVersion } from './$resolveInstalledHarnessVersion';
+import { $resolveLatestHarnessVersion } from './$resolveLatestHarnessVersion';
+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.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and queries npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $checkHarnessInstallation(definition: HarnessDefinition): Promise<HarnessInstallationStatus> {
+    const [installedVersion, latestVersion] = await Promise.all([
+        $resolveInstalledHarnessVersion(definition),
+        $resolveLatestHarnessVersion(definition),
+    ]);
+
+    return {
+        definition,
+        installationState: resolveHarnessInstallationState(installedVersion, latestVersion),
+        installedVersion,
+        latestVersion,
+    };
+}
+
+/**
+ * Derives the installation state from the detected versions.
+ */
+function resolveHarnessInstallationState(
+    installedVersion: string | null,
+    latestVersion: string | null,
+): HarnessInstallationState {
+    if (installedVersion === null) {
+        return 'not-installed';
+    }
+
+    if (latestVersion === null) {
+        return 'unknown';
+    }
+
+    return isHarnessVersionOutdated(installedVersion, latestVersion) ? '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/$ensureHarnessInstallations.ts

@@ -0,0 +1,48 @@
+import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+import { $applyHarnessInstallationStatus } from './$applyHarnessInstallationStatus';
+import { $checkHarnessInstallation } from './$checkHarnessInstallation';
+import type { HarnessDefinition } from './HarnessDefinition';
+import { getHarnessDefinition } from './HarnessDefinition';
+
+/**
+ * Checks that every given CLI coding harness is installed globally and up to date and offers to
+ * install or update the ones which are not.
+ *
+ * Harness names which are `undefined`, for example when no `--harness` is selected in a dry run,
+ * are ignored so that every call site can pass its raw selection.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it may install npm packages
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $ensureHarnessInstallations(
+    harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>,
+): Promise<void> {
+    const definitions = resolveCheckedHarnessDefinitions(harnessNames);
+
+    if (definitions.length === 0) {
+        return;
+    }
+
+    // Note: Detection of all harnesses runs in parallel, the questions have to be asked one by one
+    const statuses = await Promise.all(definitions.map((definition) => $checkHarnessInstallation(definition)));
+
+    for (const status of statuses) {
+        await $applyHarnessInstallationStatus(status);
+    }
+}
+
+/**
+ * Resolves the definitions of the harnesses which should be checked, without duplicates.
+ */
+function resolveCheckedHarnessDefinitions(
+    harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>,
+): ReadonlyArray<HarnessDefinition> {
+    const selectedHarnessNames = harnessNames.filter(
+        (harnessName): harnessName is PromptRunnerHarnessName => harnessName !== undefined,
+    );
+
+    return Array.from(new Set(selectedHarnessNames)).map((harnessName) => getHarnessDefinition(harnessName));
+}
+
+// Note: [🟡] Code for CLI harness installation orchestration [$ensureHarnessInstallations](src/cli/cli-commands/common/harness/$ensureHarnessInstallations.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,56 @@
+import colors from 'colors';
+import { spaceTrim } from 'spacetrim';
+import { assertsError } from '../../../../errors/assertsError';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
+import type { HarnessDefinition } from './HarnessDefinition';
+
+/**
+ * Installs or updates one CLI coding harness globally through npm.
+ *
+ * A failed installation is reported but never aborts the running command, because the harness check
+ * is only an assistant - the command itself may still work with a manually managed harness.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs a global npm package
+ *
+ * @returns `true` when the harness has been installed, `false` when the installation failed
+ * @private internal utility of `promptbookCli`
+ */
+export async function $installHarness(definition: HarnessDefinition): Promise<boolean> {
+    const installCommand = buildHarnessInstallCommand(definition);
+
+    console.info(colors.cyan(`Installing ${definition.label} with \`${installCommand}\`...`));
+
+    try {
+        await $execCommand({
+            command: installCommand,
+            crashOnError: true,
+            isVerbose: true,
+            env: definition.npmInstallEnvironment ? { ...definition.npmInstallEnvironment } : undefined,
+        });
+    } catch (error) {
+        assertsError(error);
+        const installErrorMessage = error.message;
+
+        console.error(
+            colors.red(
+                spaceTrim(
+                    (block) => `
+                        Could not install **${definition.label}**.
+
+                        Install it manually with \`${installCommand}\` and run the command again.
+
+                        ${block(installErrorMessage)}
+                    `,
+                ),
+            ),
+        );
+
+        return false;
+    }
+
+    console.info(colors.green(`${definition.label} has been installed.`));
+    return true;
+}
+
+// Note: [🟡] Code for CLI harness installation [$installHarness](src/cli/cli-commands/common/harness/$installHarness.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,29 @@
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import { extractHarnessVersionFromOutput } from './extractHarnessVersionFromOutput';
+import type { HarnessDefinition } from './HarnessDefinition';
+
+/**
+ * Time limit for asking the globally installed harness command for its version.
+ */
+const HARNESS_VERSION_COMMAND_TIMEOUT_MS = 30 * 1000;
+
+/**
+ * Reads the version of the globally installed harness command.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command
+ *
+ * @returns The installed version or `null` when the harness command is not available globally
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolveInstalledHarnessVersion(definition: HarnessDefinition): Promise<string | null> {
+    const output = await $execCommand({
+        command: `${definition.commandName} --version`,
+        crashOnError: true,
+        timeout: HARNESS_VERSION_COMMAND_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+
+    return extractHarnessVersionFromOutput(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/$resolveLatestHarnessVersion.ts

@@ -0,0 +1,34 @@
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import { extractHarnessVersionFromOutput } from './extractHarnessVersionFromOutput';
+import type { HarnessDefinition } from './HarnessDefinition';
+
+/**
+ * Time limit for the whole `npm view` lookup of the newest published harness version.
+ */
+const HARNESS_LATEST_VERSION_COMMAND_TIMEOUT_MS = 60 * 1000;
+
+/**
+ * Time limit for one npm registry request, so an unreachable registry never blocks the command.
+ */
+const NPM_REGISTRY_FETCH_TIMEOUT_MS = 20 * 1000;
+
+/**
+ * Reads the newest version of the harness published to npm.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it queries the npm registry
+ *
+ * @returns The newest published version or `null` when the registry could not be reached
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolveLatestHarnessVersion(definition: HarnessDefinition): Promise<string | null> {
+    const output = await $execCommand({
+        command: `npm view ${definition.npmPackageName} version --fetch-timeout=${NPM_REGISTRY_FETCH_TIMEOUT_MS} --fetch-retries=1`,
+        crashOnError: true,
+        timeout: HARNESS_LATEST_VERSION_COMMAND_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+
+    return extractHarnessVersionFromOutput(output);
+}
+
+// Note: [🟡] Code for CLI harness registry lookup [$resolveLatestHarnessVersion](src/cli/cli-commands/common/harness/$resolveLatestHarnessVersion.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,102 @@
+import { spaceTrim } from 'spacetrim';
+import { UnexpectedError } from '../../../../errors/UnexpectedError';
+import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+
+/**
+ * Static description of one supported CLI coding harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessDefinition = {
+    /**
+     * Harness identifier used by the `--harness` option.
+     */
+    readonly harnessName: PromptRunnerHarnessName;
+
+    /**
+     * Human-readable harness name shown in the terminal.
+     */
+    readonly label: string;
+
+    /**
+     * Globally installed command which runs the harness.
+     */
+    readonly commandName: string;
+
+    /**
+     * Npm package which installs the harness command globally.
+     */
+    readonly npmPackageName: string;
+
+    /**
+     * Extra environment variables required by the global npm installation of this harness.
+     */
+    readonly npmInstallEnvironment?: Readonly<Record<string, string>>;
+};
+
+/**
+ * Single source of truth about how each supported CLI coding harness is installed and detected.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, HarnessDefinition>> = {
+    'openai-codex': {
+        harnessName: 'openai-codex',
+        label: 'OpenAI Codex',
+        commandName: 'codex',
+        npmPackageName: '@openai/codex',
+    },
+    'github-copilot': {
+        harnessName: 'github-copilot',
+        label: 'GitHub Copilot',
+        commandName: 'copilot',
+        npmPackageName: '@github/copilot',
+        // Note: The GitHub Copilot CLI downloads its native binary in a postinstall script
+        npmInstallEnvironment: { npm_config_ignore_scripts: 'false' },
+    },
+    cline: {
+        harnessName: 'cline',
+        label: 'Cline',
+        commandName: 'cline',
+        npmPackageName: 'cline',
+    },
+    'claude-code': {
+        harnessName: 'claude-code',
+        label: 'Claude Code',
+        commandName: 'claude',
+        npmPackageName: '@anthropic-ai/claude-code',
+    },
+    opencode: {
+        harnessName: 'opencode',
+        label: 'Opencode',
+        commandName: 'opencode',
+        npmPackageName: 'opencode-ai',
+    },
+    gemini: {
+        harnessName: 'gemini',
+        label: 'Gemini CLI',
+        commandName: 'gemini',
+        npmPackageName: '@google/gemini-cli',
+    },
+};
+
+/**
+ * Looks up the definition of one supported CLI coding harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function getHarnessDefinition(harnessName: PromptRunnerHarnessName): HarnessDefinition {
+    const definition = HARNESS_DEFINITIONS[harnessName];
+
+    if (definition === undefined) {
+        throw new UnexpectedError(
+            spaceTrim(`
+                Missing harness definition for \`${harnessName}\`.
+
+                Every harness must be described in \`HARNESS_DEFINITIONS\`.
+            `),
+        );
+    }
+
+    return definition;
+}

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

@@ -0,0 +1,42 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+
+/**
+ * Result of comparing the globally installed harness version with the newest published one.
+ *
+ * - `up-to-date` the newest published version is installed
+ * - `outdated` an older version is installed
+ * - `not-installed` the harness command is not available globally
+ * - `unknown` the harness is installed but the newest published version could not be resolved, for example when offline
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationState = 'up-to-date' | 'outdated' | 'not-installed' | 'unknown';
+
+/**
+ * Installation state of one CLI coding harness on the current machine.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationStatus = {
+    /**
+     * Harness the status belongs to.
+     */
+    readonly definition: HarnessDefinition;
+
+    /**
+     * Comparison of the installed version with the newest published one.
+     */
+    readonly installationState: HarnessInstallationState;
+
+    /**
+     * Version of the globally installed harness command or `null` when the harness is not installed.
+     */
+    readonly installedVersion: string | null;
+
+    /**
+     * Newest version published to npm or `null` when it could not be resolved.
+     */
+    readonly latestVersion: string | null;
+};
+
+// Note: [🟡] Code for CLI harness installation status [HarnessInstallationStatus](src/cli/cli-commands/common/harness/HarnessInstallationStatus.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,15 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+
+/**
+ * Builds the shell command which installs or updates one CLI coding harness globally.
+ *
+ * The very same command is executed by `$installHarness` and printed as the manual fallback,
+ * so the user always sees exactly what Promptbook would run.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function buildHarnessInstallCommand(definition: HarnessDefinition): string {
+    return `npm install -g ${definition.npmPackageName}@latest`;
+}
+
+// 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/extractHarnessVersionFromOutput.ts

@@ -0,0 +1,28 @@
+/**
+ * Pattern matching one `major.minor.patch` version anywhere in the output of a harness version command.
+ */
+const HARNESS_VERSION_PATTERN = /\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/u;
+
+/**
+ * Extracts the version from the raw output of a harness `--version` command.
+ *
+ * Harness CLIs print their version in many shapes, for example `2.1.199 (Claude Code)`,
+ * `codex-cli 0.144.4`, `GitHub Copilot CLI 1.0.61.` or after unrelated deprecation warning lines,
+ * so the first version-looking token of the first matching line wins.
+ *
+ * @returns The parsed version or `null` when the output contains no version
+ * @private internal utility of `promptbookCli`
+ */
+export function extractHarnessVersionFromOutput(output: string): string | null {
+    for (const line of output.split('\n')) {
+        const versionMatch = HARNESS_VERSION_PATTERN.exec(line);
+
+        if (versionMatch !== null) {
+            return versionMatch[1] ?? null;
+        }
+    }
+
+    return null;
+}
+
+// Note: [🟡] Code for CLI harness version parsing [extractHarnessVersionFromOutput](src/cli/cli-commands/common/harness/extractHarnessVersionFromOutput.ts) should never be published outside of `@promptbook/cli`