@promptbook/cli 0.113.0-9 → 0.114.0-0

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

@@ -3,8 +3,10 @@ import { Command as Program /* <- Note: [🔸] Using Program because Command is
 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 { handleActionErrors } from '../common/handleActionErrors';
+import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -33,11 +35,13 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             - Automatically stages and commits changes with agent identity unless --no-commit is used
             - 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
             - Supports GPG signing of commits
             - Optional post-prompt verification with test-feedback retries
-            - Progress tracking and interactive controls
+            - Progress tracking and interactive P/S/X terminal controls
             - Dry-run mode to preview prompts
         `),
     );
@@ -62,7 +66,30 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
         false,
     );
     addPromptRunnerExecutionOptions(command);
-    command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
+    command.option(
+        '--isolate',
+        spaceTrim(`
+            Implement each prompt in its own temporary git worktree with its own isolated environment.
+            A verified task is merged back into the branch the coder runs on and the worktree is deleted.
+            A task that cannot be merged is marked as failed and its worktree is kept for a manual merge.
+        `),
+        false,
+    );
+    command.option(
+        '--priority <minimum-priority>',
+        'Alias for --min-priority; filter prompts by minimum priority level',
+        createNonNegativeIntegerOptionParser('--priority'),
+    );
+    command.option(
+        '--min-priority <minimum-priority>',
+        'Filter prompts by minimum priority level',
+        createNonNegativeIntegerOptionParser('--min-priority'),
+    );
+    command.option(
+        '--max-priority <maximum-priority>',
+        'Filter prompts by maximum priority level',
+        createNonNegativeIntegerOptionParser('--max-priority'),
+    );
     command.option(
         '--limit <run-count>',
         'Stop after processing this many prompt runs',
@@ -112,7 +139,10 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 context,
                 test,
                 preserveLogs,
+                isolate: isIsolated,
                 priority,
+                minPriority: minimumPriority,
+                maxPriority: maximumPriority,
                 limit,
                 waitAfterPrompt: waitAfterPromptValue,
                 waitBetweenPrompts: waitBetweenPromptsValue,
@@ -126,7 +156,10 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly context?: string;
                 readonly test?: string | string[];
                 readonly preserveLogs: boolean;
-                readonly priority: number;
+                readonly isolate: boolean;
+                readonly priority?: number;
+                readonly minPriority?: number;
+                readonly maxPriority?: number;
                 readonly limit?: number;
                 readonly waitAfterPrompt?: string;
                 readonly waitBetweenPrompts?: string;
@@ -141,6 +174,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 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)
@@ -167,9 +202,12 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 context,
                 testCommand,
                 preserveLogs,
+                isIsolated,
                 noUi: runnerOptions.noUi,
                 thinkingLevel: runnerOptions.thinkingLevel,
-                priority,
+                priority: priority ?? 0,
+                minimumPriority,
+                maximumPriority,
                 limit,
                 normalizeLineEndings: runnerOptions.normalizeLineEndings,
                 allowCredits: runnerOptions.allowCredits,
@@ -197,19 +235,6 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     );
 }
 
-/**
- * Parses an integer option value
- *
- * @private internal utility of `coder run` 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/server.ts

@@ -9,7 +9,9 @@ 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,
@@ -46,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
         `),
     );
 
@@ -79,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(`
@@ -125,6 +142,8 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 test,
                 preserveLogs,
                 priority,
+                minPriority: minimumPriority,
+                maxPriority: maximumPriority,
                 waitAfterPrompt: waitAfterPromptValue,
                 waitBetweenPrompts: waitBetweenPromptsValue,
                 waitAfterError: waitAfterErrorValue,
@@ -138,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;
@@ -153,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);
@@ -176,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,
@@ -225,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`