@promptbook/cli 0.114.0-32 → 0.114.0-34

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

@@ -1,4 +1,3 @@
-import colors from 'colors';
 import {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
     Option,
@@ -9,14 +8,16 @@ 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 { $assertSufficientFreeDiskSpace } from '../common/disk-space/$assertSufficientFreeDiskSpace';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
-    addHarnessUpdateOption,
-    normalizeHarnessUpdateCliOptions,
-    type HarnessUpdateCliOptions,
-} from '../common/harnessUpdateCliOptions';
+    addQuestionsOption,
+    assertUserConfirmationIsAllowed,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -24,8 +25,11 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
+import { addCoderAgentOption, type CoderAgentCliOptions } from './agentCliOptions';
+import { printCoderRunFailure } from './printCoderRunFailure';
 
 /**
  * Default port used by `ptbk coder server`.
@@ -47,21 +51,26 @@ const DEFAULT_CODER_SERVER_PORT = '4441';
 export function $initializeCoderServerCommand(program: Program): $side_effect {
     const command = program.command('server');
     command.description(
-        spaceTrim(`
-            Start a coder server that watches for prompts and serves a kanban web UI
+        spaceTrim(
+            (block) => `
+                Start a coder server that watches for prompts and serves a kanban web UI
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+                ${block(PROMPT_RUNNER_DESCRIPTION)}
 
-            Features:
-            - Runs the same prompt processing as \`ptbk coder run\`
-            - 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)
-            - Play / pause button in the browser stays in sync with the CLI pause state
-            - Terminal controls match \`ptbk coder run\`: P pause/resume, S skip waiting, X end after current prompt
-        `),
+                ${block(QUESTIONS_DESCRIPTION)}
+
+                Features:
+                - Runs the same prompt processing as \`ptbk coder run\`
+                - Refuses to start on a nearly full disk and pauses the run when the free disk space becomes critical, unless --no-questions is used
+                - Checks that the selected harness is installed and up to date on startup unless --no-questions 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)
+                - Play / pause button in the browser stays in sync with the CLI pause state
+                - Terminal controls match \`ptbk coder run\`: P pause/resume, S skip waiting, X end after current prompt
+            `,
+        ),
     );
 
     command.addOption(
@@ -71,11 +80,8 @@ 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',
-    );
+    addQuestionsOption(command);
+    addCoderAgentOption(command);
     command.option(
         '--context <context-or-file>',
         'Append extra instructions either inline or from a file path relative to the current project',
@@ -90,21 +96,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
         false,
     );
     addPromptRunnerExecutionOptions(command);
-    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'),
-    );
+    addPromptPriorityOptions(command);
     command.option(
         '--wait-after-prompt <duration>',
         spaceTrim(`
@@ -174,22 +166,27 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 readonly auto: boolean;
                 readonly autoMigrate: boolean;
                 readonly allowDestructiveAutoMigrate: boolean;
-            } & PromptRunnerCliOptions;
+            } & PromptRunnerCliOptions & CoderAgentCliOptions;
 
             const port = parseCoderServerPort(rawPort);
             const testCommand = normalizeCommandOptionValue(test);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
-                cliOptions as HarnessUpdateCliOptions,
-            );
-
-            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
 
             // [1] Parse the wait options and --no-auto (same logic as `coder run`)
             const waitForUser = !auto;
+
+            assertUserConfirmationIsAllowed({ ...questionsOptions, isWaitingForUser: waitForUser });
+
+            // Note: Checked before anything is installed or written, because installing a harness and coding
+            //       itself both need the disk space which is missing
+            await $assertSufficientFreeDiskSpace(process.cwd());
+
+            await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
+
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);
@@ -220,6 +217,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 allowDestructiveAutoMigrate,
                 autoPush: runnerOptions.autoPush,
                 autoPull: runnerOptions.autoPull,
+                isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled,
             };
 
             // Note: Import dynamically to avoid loading heavy dependencies until needed
@@ -231,8 +229,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 await runCodexPromptsServer(runOptions);
             } catch (error) {
                 assertsError(error);
-                console.error(colors.bgRed(`${error.name}`));
-                console.error(colors.red(error.stack || error.message));
+                printCoderRunFailure(error);
                 return process.exit(1);
             }
 

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

@@ -1,15 +1,16 @@
-import colors from 'colors';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $requireCliSubcommand } from '../common/$requireCliSubcommand';
 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';
 import { $initializeCoderGenerateBoilerplatesCommand } from './coder/generate-boilerplates';
 import { $initializeCoderInitCommand } from './coder/init';
+import { $initializeCoderListCommand } from './coder/list';
 import { $initializeCoderPingCommand } from './coder/ping';
 import { $initializeCoderRunCommand } from './coder/run';
 import { $initializeCoderServerCommand } from './coder/server';
@@ -23,6 +24,7 @@ import { $initializeCoderVerifyCommand } from './coder/verify';
  * - 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
+ * - list: List ready prompts in priority order without running them
  * - run: Run coding prompts with AI agents
  * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
@@ -44,6 +46,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             - 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
+            - list: List ready prompts in priority order without running them
             - run: Run coding prompts with AI agents
             - ping: Test the connection, response time and quota of one harness and model
             - server: Start a long-running coder server with a kanban web UI
@@ -58,6 +61,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
+    $initializeCoderListCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
     $initializeCoderPingCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
@@ -65,11 +69,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);
 
     // If no subcommand is provided, show help
-    coderCommand.action(() => {
-        console.info(colors.yellow('Please specify a subcommand.'));
-        console.info('');
-        coderCommand.help();
-    });
+    $requireCliSubcommand(coderCommand);
 }
 
 // Note: [🟡] Code for CLI command [coder](src/cli/cli-commands/coder.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/$askForConfirmation.ts

@@ -1,15 +1,25 @@
 import colors from 'colors';
 import { createInterface } from 'readline';
+import type { NormalizedQuestionsCliOptions } from './questionsCliOptions';
 
 /**
  * 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.
  *
- * @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, the terminal is not interactive
+ *          or the questions are disabled by `--no-questions`.
  * @private internal utility of `promptbookCli`
  */
-export async function $askForConfirmation(question: string): Promise<boolean> {
+export async function $askForConfirmation(
+    question: string,
+    { isAskingQuestionsEnabled }: NormalizedQuestionsCliOptions,
+): Promise<boolean> {
+    if (!isAskingQuestionsEnabled) {
+        // Note: `--no-questions` forbids asking, so the optional change is declined without blocking the run.
+        return false;
+    }
+
     if (!process.stdin.isTTY) {
         // Note: In non-interactive environments like CI there is nobody who could confirm the change.
         return false;

package/src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.ts

@@ -0,0 +1,35 @@
+import { spaceTrim } from 'spacetrim';
+import { LimitReachedError } from '../../../../errors/LimitReachedError';
+import { $readFreeDiskSpaceStatus } from './$readFreeDiskSpaceStatus';
+import { formatLowFreeDiskSpaceWarning } from './formatLowFreeDiskSpaceWarning';
+
+/**
+ * Refuses to start one `ptbk coder` command when the disk which hosts the project is nearly full.
+ *
+ * A run which starts without enough free disk space fails somewhere in the middle, after the coding agent has
+ * already rewritten a part of the project, so it is stopped before it writes anything at all.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+ *
+ * @throws {LimitReachedError} when there is not enough free disk space left to start
+ * @private internal utility of `promptbookCli`
+ */
+export async function $assertSufficientFreeDiskSpace(inspectedPath: string): Promise<void> {
+    const freeDiskSpaceStatus = await $readFreeDiskSpaceStatus(inspectedPath);
+
+    if (freeDiskSpaceStatus === null || freeDiskSpaceStatus.level === 'sufficient') {
+        return;
+    }
+
+    throw new LimitReachedError(
+        spaceTrim(
+            (block) => `
+                There is not enough free disk space to run \`ptbk coder\`.
+
+                ${block(formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus))}
+            `,
+        ),
+    );
+}
+
+// Note: [🟡] Code for CLI free disk space handling [$assertSufficientFreeDiskSpace](src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.ts

@@ -0,0 +1,37 @@
+import { statfs } from 'fs/promises';
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+import { resolveFreeDiskSpaceLevel } from './resolveFreeDiskSpaceLevel';
+
+/**
+ * Measures the free disk space on the filesystem which hosts the given path.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+ *
+ * @returns the measurement, or `null` when the filesystem can not be measured, for example on a platform which
+ *          does not report filesystem statistics - a run is never stopped by a measurement which could not be taken
+ * @private internal utility of `promptbookCli`
+ */
+export async function $readFreeDiskSpaceStatus(inspectedPath: string): Promise<FreeDiskSpaceStatus | null> {
+    try {
+        const fileSystemStats = await statfs(inspectedPath);
+        const blockSizeBytes = fileSystemStats.bsize;
+        const availableBytes = fileSystemStats.bavail * blockSizeBytes;
+        const totalBytes = fileSystemStats.blocks * blockSizeBytes;
+
+        if (!Number.isFinite(availableBytes) || availableBytes < 0) {
+            return null;
+        }
+
+        return {
+            inspectedPath,
+            availableBytes,
+            totalBytes,
+            level: resolveFreeDiskSpaceLevel(availableBytes),
+        };
+    } catch {
+        // Note: A path or a platform which can not report its free disk space must not stop `ptbk coder` from running
+        return null;
+    }
+}
+
+// Note: [🟡] Code for CLI free disk space handling [$readFreeDiskSpaceStatus](src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/disk-space/FreeDiskSpaceStatus.ts

@@ -0,0 +1,39 @@
+/**
+ * How much free disk space is left, measured against the `ptbk coder` free disk space limits.
+ *
+ * - `sufficient` - there is enough free disk space to start a run and to keep it running
+ * - `low` - there is not enough free disk space to start a new run
+ * - `critical` - there is not enough free disk space to keep a started run going
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceLevel = 'sufficient' | 'low' | 'critical';
+
+/**
+ * One measurement of the free disk space on the filesystem which hosts the inspected path.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceStatus = {
+    /**
+     * Path whose filesystem was measured.
+     */
+    readonly inspectedPath: string;
+
+    /**
+     * Bytes which are still available to the current user on that filesystem.
+     */
+    readonly availableBytes: number;
+
+    /**
+     * Total size of that filesystem in bytes.
+     */
+    readonly totalBytes: number;
+
+    /**
+     * Severity of the measured free disk space.
+     */
+    readonly level: FreeDiskSpaceLevel;
+};
+
+// Note: [🟡] Code for CLI free disk space handling [FreeDiskSpaceStatus](src/cli/cli-commands/common/disk-space/FreeDiskSpaceStatus.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.ts

@@ -0,0 +1,26 @@
+/**
+ * Byte units used when one amount of disk space is written for a human.
+ */
+const FREE_DISK_SPACE_BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'] as const;
+
+/**
+ * Writes one byte count as a compact human-readable amount of disk space, for example `812 MB` or `1.5 GB`.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function formatFreeDiskSpaceBytes(bytes: number): string {
+    if (!Number.isFinite(bytes) || bytes <= 0) {
+        return '0 B';
+    }
+
+    const unitIndex = Math.min(FREE_DISK_SPACE_BYTE_UNITS.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / Math.pow(1024, unitIndex);
+    // Note: One decimal place only matters for small values, `476 GB` is more readable than `476.3 GB`
+    const decimalPlaceCount = value >= 10 || unitIndex === 0 ? 0 : 1;
+    // Note: An empty decimal place only adds noise, `2 GB` is more readable than `2.0 GB`
+    const displayedValue = value.toFixed(decimalPlaceCount).replace(/\.0$/, '');
+
+    return `${displayedValue} ${FREE_DISK_SPACE_BYTE_UNITS[unitIndex]}`;
+}
+
+// Note: [🟡] Code for CLI free disk space handling [formatFreeDiskSpaceBytes](src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.ts

@@ -0,0 +1,33 @@
+import { spaceTrim } from 'spacetrim';
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+import { formatFreeDiskSpaceBytes } from './formatFreeDiskSpaceBytes';
+import { CRITICALLY_LOW_FREE_DISK_SPACE_BYTES, LOW_FREE_DISK_SPACE_BYTES } from './freeDiskSpaceConstants';
+
+/**
+ * Writes the shared warning which explains one low free disk space measurement and how to get out of it.
+ *
+ * The very same wording is used by the check which refuses to start a run and by the check which pauses
+ * a run that ran out of disk space while it was working.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus: FreeDiskSpaceStatus): string {
+    const { inspectedPath } = freeDiskSpaceStatus;
+    const availableSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.availableBytes);
+    const totalSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.totalBytes);
+    const requiredSpaceToStart = formatFreeDiskSpaceBytes(LOW_FREE_DISK_SPACE_BYTES);
+    const requiredSpaceToContinue = formatFreeDiskSpaceBytes(CRITICALLY_LOW_FREE_DISK_SPACE_BYTES);
+
+    return spaceTrim(`
+        Only **${availableSpace}** of ${totalSpace} is left on the disk which hosts \`${inspectedPath}\`.
+
+        **\`ptbk coder\` needs at least ${requiredSpaceToStart} of free disk space to start a run and at least ${requiredSpaceToContinue} to keep one running.**
+
+        Actionable hints:
+        - Free up disk space on the drive which hosts \`${inspectedPath}\`.
+        - Remove build artifacts, package caches and \`node_modules\` folders of projects you are not working on.
+        - Remove the temporary worktrees which earlier \`--isolate\` runs left behind.
+    `);
+}
+
+// Note: [🟡] Code for CLI free disk space handling [formatLowFreeDiskSpaceWarning](src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.ts

@@ -0,0 +1,33 @@
+/**
+ * Free disk space below which `ptbk coder` refuses to start a new run.
+ *
+ * A coding round writes prompt and log artifacts, lets the harness rewrite the project, may install npm packages,
+ * may create a git worktree for `--isolate` and usually runs a build, so a run started with less than this
+ * would very likely die somewhere in the middle with a filesystem error.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const LOW_FREE_DISK_SPACE_BYTES = 2 * 1024 * 1024 * 1024;
+
+/**
+ * Free disk space below which a started `ptbk coder` run stops at its next checkpoint and waits until space is freed.
+ *
+ * This limit is lower than `LOW_FREE_DISK_SPACE_BYTES`, because interrupting a run which is already in progress
+ * is more expensive than not starting one at all.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const CRITICALLY_LOW_FREE_DISK_SPACE_BYTES = 1 * 1024 * 1024 * 1024;
+
+/**
+ * How long one free disk space measurement is reused before the filesystem is measured again during a run.
+ *
+ * Pause checkpoints are passed very often - for example on every tick of a timed wait - so without this
+ * interval the filesystem would be measured many times per second.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const FREE_DISK_SPACE_RECHECK_INTERVAL_MS = 60 * 1000;
+
+// Note: [🟡] Code for CLI free disk space handling [freeDiskSpaceConstants](src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.ts

@@ -0,0 +1,21 @@
+import type { FreeDiskSpaceLevel } from './FreeDiskSpaceStatus';
+import { CRITICALLY_LOW_FREE_DISK_SPACE_BYTES, LOW_FREE_DISK_SPACE_BYTES } from './freeDiskSpaceConstants';
+
+/**
+ * Classifies one measured amount of free disk space against the `ptbk coder` free disk space limits.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function resolveFreeDiskSpaceLevel(availableBytes: number): FreeDiskSpaceLevel {
+    if (availableBytes < CRITICALLY_LOW_FREE_DISK_SPACE_BYTES) {
+        return 'critical';
+    }
+
+    if (availableBytes < LOW_FREE_DISK_SPACE_BYTES) {
+        return 'low';
+    }
+
+    return 'sufficient';
+}
+
+// Note: [🟡] Code for CLI free disk space handling [resolveFreeDiskSpaceLevel](src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.ts) should never be published outside of `@promptbook/cli`

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

@@ -1,5 +1,6 @@
 import colors from 'colors';
 import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 import { $runHarnessInstallationCommand } from './$runHarnessInstallationCommand';
 import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
 import type { HarnessDefinition } from './HarnessDefinition';
@@ -15,7 +16,10 @@ import { resolveHarnessUpdatePlan } from './resolveHarnessUpdatePlan';
  *
  * @private internal utility of `promptbookCli`
  */
-export async function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void> {
+export async function $applyHarnessInstallationStatus(
+    status: HarnessInstallationStatus,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
     const { definition, installationState, installedVersion } = status;
 
     if (installationState === 'up-to-date') {
@@ -42,21 +46,25 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
     console.warn(colors.yellow(formatHarnessInstallationWarning(status)));
 
     if (installationState === 'not-installed') {
-        await $applyMissingHarnessInstallation(definition);
+        await $applyMissingHarnessInstallation(definition, questionsOptions);
         return;
     }
 
-    await $applyOutdatedHarnessInstallation(status);
+    await $applyOutdatedHarnessInstallation(status, questionsOptions);
 }
 
 /**
  * Offers to install a missing harness globally through npm.
  */
-async function $applyMissingHarnessInstallation(definition: HarnessDefinition): Promise<void> {
+async function $applyMissingHarnessInstallation(
+    definition: HarnessDefinition,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
     const installCommand = buildHarnessInstallCommand(definition);
 
     const isInstallationApproved = await $askForNpmPackageInstallationApproval(
         `Install ${definition.label} globally now?`,
+        questionsOptions,
     );
 
     if (!isInstallationApproved) {
@@ -75,7 +83,10 @@ async function $applyMissingHarnessInstallation(definition: HarnessDefinition):
 /**
  * Offers to update an outdated harness exactly where it is installed.
  */
-async function $applyOutdatedHarnessInstallation(status: HarnessInstallationStatus): Promise<void> {
+async function $applyOutdatedHarnessInstallation(
+    status: HarnessInstallationStatus,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
     const { definition, latestVersion, installationOrigin } = status;
     const updatePlan = resolveHarnessUpdatePlan(definition, installationOrigin.installationMethod);
 
@@ -86,6 +97,7 @@ async function $applyOutdatedHarnessInstallation(status: HarnessInstallationStat
 
     const isUpdateApproved = await $askForNpmPackageInstallationApproval(
         `Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`,
+        questionsOptions,
     );
 
     if (!isUpdateApproved) {

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

@@ -1,11 +1,12 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 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, when enabled, up to date.
+ * Checks that every given CLI coding harness is installed globally and, when the questions are 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,
@@ -17,7 +18,7 @@ import { getHarnessDefinition } from './HarnessDefinition';
  */
 export async function $ensureHarnessInstallations(
     harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>,
-    isHarnessUpdateCheckEnabled = true,
+    questionsOptions: NormalizedQuestionsCliOptions,
 ): Promise<void> {
     const definitions = resolveCheckedHarnessDefinitions(harnessNames);
 
@@ -25,13 +26,17 @@ export async function $ensureHarnessInstallations(
         return;
     }
 
+    // Note: An outdated harness can be updated only after the user confirms it, so `--no-questions`
+    //       skips the slower npm registry lookup entirely and only reports what is installed.
+    const isHarnessUpdateCheckEnabled = questionsOptions.isAskingQuestionsEnabled;
+
     // 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, isHarnessUpdateCheckEnabled)),
     );
 
     for (const status of statuses) {
-        await $applyHarnessInstallationStatus(status);
+        await $applyHarnessInstallationStatus(status, questionsOptions);
     }
 }