@promptbook/cli 0.114.0-11 → 0.114.0-13

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,
@@ -33,11 +38,13 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
             - 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
+            - Checks that the selected harness is installed globally 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.action(
@@ -46,8 +53,11 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
             );
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
 
             // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
             const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');

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

@@ -10,6 +10,11 @@ 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 {
@@ -48,7 +53,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             - 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 globally and up to date before the first prompt unless --no-harness-update is used
             - 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
@@ -60,6 +65,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',
@@ -198,6 +204,9 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
@@ -211,7 +220,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 return process.exit(0);
             }
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
 
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);

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,
@@ -48,7 +53,7 @@ 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 globally and up to date on startup unless --no-harness-update is used
             - 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 +69,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 +179,11 @@ 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);
 
             // [1] Parse the wait options and --no-auto (same logic as `coder run`)
             const waitForUser = !auto;

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

@@ -20,6 +20,11 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
         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(

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

@@ -5,21 +5,28 @@ import type { HarnessDefinition } from './HarnessDefinition';
 import type { HarnessInstallationState, HarnessInstallationStatus } from './HarnessInstallationStatus';
 
 /**
- * Detects whether one CLI coding harness is installed globally and whether it is up to date.
+ * Detects whether one CLI coding harness is installed globally and, when enabled, 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
+ * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and may query npm
  *
  * @private internal utility of `promptbookCli`
  */
-export async function $checkHarnessInstallation(definition: HarnessDefinition): Promise<HarnessInstallationStatus> {
+export async function $checkHarnessInstallation(
+    definition: HarnessDefinition,
+    isHarnessUpdateCheckEnabled = true,
+): Promise<HarnessInstallationStatus> {
     const [installedVersion, latestVersion] = await Promise.all([
         $resolveInstalledHarnessVersion(definition),
-        $resolveLatestNpmPackageVersion(definition.npmPackageName),
+        isHarnessUpdateCheckEnabled ? $resolveLatestNpmPackageVersion(definition.npmPackageName) : Promise.resolve(null),
     ]);
 
     return {
         definition,
-        installationState: resolveHarnessInstallationState(installedVersion, latestVersion),
+        installationState: resolveHarnessInstallationState(
+            installedVersion,
+            latestVersion,
+            isHarnessUpdateCheckEnabled,
+        ),
         installedVersion,
         latestVersion,
     };
@@ -31,11 +38,16 @@ export async function $checkHarnessInstallation(definition: HarnessDefinition):
 function resolveHarnessInstallationState(
     installedVersion: string | null,
     latestVersion: string | null,
+    isHarnessUpdateCheckEnabled: boolean,
 ): HarnessInstallationState {
     if (installedVersion === null) {
         return 'not-installed';
     }
 
+    if (!isHarnessUpdateCheckEnabled) {
+        return 'installed';
+    }
+
     if (latestVersion === null) {
         return 'unknown';
     }

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

@@ -5,8 +5,8 @@ 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.
+ * Checks that every given CLI coding harness is installed globally and, when enabled, up to date.
+ * Offers to install missing harnesses and update outdated ones.
  *
  * 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.
@@ -17,6 +17,7 @@ import { getHarnessDefinition } from './HarnessDefinition';
  */
 export async function $ensureHarnessInstallations(
     harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>,
+    isHarnessUpdateCheckEnabled = true,
 ): Promise<void> {
     const definitions = resolveCheckedHarnessDefinitions(harnessNames);
 
@@ -25,7 +26,9 @@ export async function $ensureHarnessInstallations(
     }
 
     // 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)));
+    const statuses = await Promise.all(
+        definitions.map((definition) => $checkHarnessInstallation(definition, isHarnessUpdateCheckEnabled)),
+    );
 
     for (const status of statuses) {
         await $applyHarnessInstallationStatus(status);

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

@@ -6,11 +6,12 @@ import type { HarnessDefinition } from './HarnessDefinition';
  * - `up-to-date` the newest published version is installed
  * - `outdated` an older version is installed
  * - `not-installed` the harness command is not available globally
+ * - `installed` the harness is installed and automatic update checking was disabled
  * - `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';
+export type HarnessInstallationState = 'up-to-date' | 'outdated' | 'not-installed' | 'installed' | 'unknown';
 
 /**
  * Installation state of one CLI coding harness on the current machine.
@@ -24,7 +25,7 @@ export type HarnessInstallationStatus = {
     readonly definition: HarnessDefinition;
 
     /**
-     * Comparison of the installed version with the newest published one.
+     * Installation state, including whether the newest published version was checked.
      */
     readonly installationState: HarnessInstallationState;
 

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

@@ -0,0 +1,49 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+
+/**
+ * Commander option bag for opting out of automatic coding-harness update checks.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdateCliOptions = {
+    readonly harnessUpdate: boolean;
+};
+
+/**
+ * Normalized automatic coding-harness update-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedHarnessUpdateCliOptions = {
+    readonly isHarnessUpdateCheckEnabled: boolean;
+};
+
+/**
+ * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function addHarnessUpdateOption(command: Program): void {
+    command.option(
+        '--no-harness-update',
+        'Skip checking whether globally installed coding harnesses are up to date',
+    );
+}
+
+/**
+ * Converts the Commander harness-update flag into the normalized harness-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function normalizeHarnessUpdateCliOptions(
+    cliOptions: HarnessUpdateCliOptions,
+): NormalizedHarnessUpdateCliOptions {
+    return {
+        isHarnessUpdateCheckEnabled: cliOptions.harnessUpdate,
+    };
+}
+
+// Note: [🟡] Code for CLI harness update options [harnessUpdateCliOptions](src/cli/cli-commands/common/harnessUpdateCliOptions.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

package/src/executables/platforms/locateAppOnWindows.ts

@@ -1,4 +1,4 @@
-import { join } from 'path';
+import { delimiter, join } from 'path';
 import { assertsError } from '../../errors/assertsError';
 import { $provideFilesystemForNode } from '../../scrapers/_common/register/$provideFilesystemForNode';
 import type { string_executable_path } from '../../types/string_filename';
@@ -6,7 +6,7 @@ import { isExecutable } from '../../utils/files/isExecutable';
 import type { LocateAppOptions } from '../locateApp';
 
 /**
- * Attempts to locate the specified application on a Windows system by searching common installation directories.
+ * Attempts to locate the specified application on a Windows system by searching PATH and common installation directories.
  * Returns the path to the executable if found, or null otherwise.
  *
  * @private within the repository
@@ -16,18 +16,21 @@ export async function locateAppOnWindows({
     windowsSuffix,
 }: Pick<Required<LocateAppOptions>, 'appName' | 'windowsSuffix'>): Promise<string_executable_path | null> {
     try {
-        const prefixes = [
+        const EXECUTABLE_FILENAME = windowsSuffix.replace(/^.*[\\/]/, '');
+        const PATH_EXECUTABLE_PATHS = (process.env.PATH || '')
+            .split(delimiter)
+            .filter(Boolean)
+            .map((pathPrefix) => join(pathPrefix, EXECUTABLE_FILENAME));
+        const INSTALLATION_EXECUTABLE_PATHS = [
             process.env.LOCALAPPDATA,
             join(process.env.LOCALAPPDATA || '', 'Programs'),
             process.env.PROGRAMFILES,
             process.env['PROGRAMFILES(X86)'],
-        ];
+        ].map((pathPrefix) => pathPrefix + windowsSuffix);
 
-        for (const prefix of prefixes) {
-            const path = prefix + windowsSuffix;
-
-            if (await isExecutable(path, $provideFilesystemForNode())) {
-                return path;
+        for (const executablePath of [...PATH_EXECUTABLE_PATHS, ...INSTALLATION_EXECUTABLE_PATHS]) {
+            if (await isExecutable(executablePath, $provideFilesystemForNode())) {
+                return executablePath;
             }
         }