@promptbook/cli 0.114.0-3 → 0.114.0-30

package/src/cli/cli-commands/common/npm/$resolveLatestNpmPackageVersion.ts

@@ -0,0 +1,49 @@
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import { extractNpmPackageVersionFromOutput } from './extractNpmPackageVersionFromOutput';
+
+/**
+ * Time limit for the whole `npm view` lookup of the newest published package version.
+ */
+const NPM_PACKAGE_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;
+
+/**
+ * Pattern matching npm's JSON-encoded package version result.
+ */
+const NPM_VIEW_JSON_VERSION_PATTERN = /"(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)"/u;
+
+/**
+ * Reads the newest version of one npm package.
+ *
+ * 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 $resolveLatestNpmPackageVersion(npmPackageName: string): Promise<string | null> {
+    const output = await $execCommand({
+        command: `npm view ${npmPackageName} version --json --loglevel=error --fetch-timeout=${NPM_REGISTRY_FETCH_TIMEOUT_MS} --fetch-retries=1`,
+        crashOnError: true,
+        timeout: NPM_PACKAGE_LATEST_VERSION_COMMAND_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+
+    return extractLatestNpmPackageVersionFromNpmViewOutput(output);
+}
+
+/**
+ * Extracts the version from npm's JSON result while tolerating warnings emitted before or after that result.
+ *
+ * @private internal utility of `$resolveLatestNpmPackageVersion`
+ */
+function extractLatestNpmPackageVersionFromNpmViewOutput(output: string): string | null {
+    const jsonVersionMatch = NPM_VIEW_JSON_VERSION_PATTERN.exec(output);
+
+    return jsonVersionMatch?.[1] ?? extractNpmPackageVersionFromOutput(output, { isLastMatchPreferred: true });
+}
+
+// Note: [🟡] Code for CLI npm package registry lookup [$resolveLatestNpmPackageVersion](src/cli/cli-commands/common/npm/$resolveLatestNpmPackageVersion.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/npm/$resolveNpmGlobalPrefixPath.ts

@@ -0,0 +1,51 @@
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+
+/**
+ * Time limit for asking npm where it installs global packages.
+ */
+const NPM_GLOBAL_PREFIX_COMMAND_TIMEOUT_MS = 30 * 1000;
+
+/**
+ * Cached lookup, because the global npm prefix cannot change while one command runs and several
+ * harnesses are checked at the same time.
+ */
+let npmGlobalPrefixPathPromise: Promise<string | null> | null = null;
+
+/**
+ * Reads the root directory under which npm installs global packages.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs npm
+ *
+ * @returns The global npm prefix or `null` when npm could not be asked for it
+ * @private internal utility of `promptbookCli`
+ */
+export function $resolveNpmGlobalPrefixPath(): Promise<string | null> {
+    if (npmGlobalPrefixPathPromise === null) {
+        npmGlobalPrefixPathPromise = $readNpmGlobalPrefixPath();
+    }
+
+    return npmGlobalPrefixPathPromise;
+}
+
+/**
+ * Asks npm for the global prefix once.
+ */
+async function $readNpmGlobalPrefixPath(): Promise<string | null> {
+    const output: string = await $execCommand({
+        command: 'npm prefix --global --loglevel=error',
+        crashOnError: true,
+        timeout: NPM_GLOBAL_PREFIX_COMMAND_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+
+    // Note: npm prints the prefix as the last line, warnings emitted before it are ignored
+    const prefixPath = output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '')
+        .pop();
+
+    return prefixPath ?? null;
+}
+
+// Note: [🟡] Code for CLI npm global prefix lookup [$resolveNpmGlobalPrefixPath](src/cli/cli-commands/common/npm/$resolveNpmGlobalPrefixPath.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/npm/buildNpmPackageInstallCommand.ts

@@ -0,0 +1,28 @@
+/**
+ * Place where an npm package should be installed or updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NpmPackageInstallationLocation = 'local-dependency' | 'local-development-dependency' | 'global';
+
+/**
+ * Builds an npm command which installs or updates a package in the requested existing location.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function buildNpmPackageInstallCommand(
+    npmPackageName: string,
+    installationLocation: NpmPackageInstallationLocation,
+): string {
+    if (installationLocation === 'global') {
+        return `npm install -g ${npmPackageName}@latest`;
+    }
+
+    if (installationLocation === 'local-development-dependency') {
+        return `npm install --save-dev ${npmPackageName}@latest`;
+    }
+
+    return `npm install --save ${npmPackageName}@latest`;
+}
+
+// Note: [🟡] Code for CLI npm install commands [buildNpmPackageInstallCommand](src/cli/cli-commands/common/npm/buildNpmPackageInstallCommand.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/npm/extractNpmPackageVersionFromOutput.ts

@@ -0,0 +1,25 @@
+/**
+ * Pattern matching one `major.minor.patch` version anywhere in npm or CLI command output.
+ */
+const NPM_PACKAGE_VERSION_PATTERN = /\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/gu;
+
+/**
+ * Extracts an npm package version from raw command output.
+ *
+ * Both npm and CLI commands may emit unrelated warnings before the version. CLI commands use the first matching token;
+ * npm registry commands can opt into the last matching token because npm warnings commonly precede their output.
+ *
+ * @returns The parsed version or `null` when the output contains no version
+ * @private internal utility of `promptbookCli`
+ */
+export function extractNpmPackageVersionFromOutput(
+    output: string,
+    { isLastMatchPreferred = false }: { readonly isLastMatchPreferred?: boolean } = {},
+): string | null {
+    const versionMatches = Array.from(output.matchAll(NPM_PACKAGE_VERSION_PATTERN));
+    const versionMatch = isLastMatchPreferred ? versionMatches[versionMatches.length - 1] : versionMatches[0];
+
+    return versionMatch?.[1] ?? null;
+}
+
+// Note: [🟡] Code for CLI npm package version parsing [extractNpmPackageVersionFromOutput](src/cli/cli-commands/common/npm/extractNpmPackageVersionFromOutput.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.ts

@@ -0,0 +1,165 @@
+/**
+ * Parsed parts of one npm package version used for precedence comparison.
+ *
+ * @private internal utility of `isNpmPackageVersionOutdated`
+ */
+type ParsedNpmPackageVersion = {
+    readonly releaseSegments: ReadonlyArray<number>;
+    readonly prereleaseIdentifiers: ReadonlyArray<number | string> | null;
+};
+
+/**
+ * Compares an installed npm package version with the newest published version.
+ *
+ * Release and prerelease identifiers follow semantic-version precedence while build metadata is ignored. Harnesses can
+ * preserve their historical behavior by setting `isPrereleaseIgnored`, because some harness commands report a build
+ * suffix which does not correspond to npm release precedence.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function isNpmPackageVersionOutdated(
+    installedVersion: string,
+    latestVersion: string,
+    { isPrereleaseIgnored = false }: { readonly isPrereleaseIgnored?: boolean } = {},
+): boolean {
+    const installedPackageVersion = parseNpmPackageVersion(installedVersion);
+    const latestPackageVersion = parseNpmPackageVersion(latestVersion);
+    const releaseComparison = compareNumericSegments(
+        installedPackageVersion.releaseSegments,
+        latestPackageVersion.releaseSegments,
+    );
+
+    if (releaseComparison !== 0) {
+        return releaseComparison < 0;
+    }
+
+    if (isPrereleaseIgnored) {
+        return false;
+    }
+
+    return (
+        comparePrereleaseIdentifiers(
+            installedPackageVersion.prereleaseIdentifiers,
+            latestPackageVersion.prereleaseIdentifiers,
+        ) < 0
+    );
+}
+
+/**
+ * Parses semantic-version release and prerelease parts, ignoring build metadata.
+ */
+function parseNpmPackageVersion(version: string): ParsedNpmPackageVersion {
+    const buildMetadataSeparatorIndex = version.indexOf('+');
+    const versionWithoutBuildMetadata = (
+        buildMetadataSeparatorIndex === -1 ? version : version.slice(0, buildMetadataSeparatorIndex)
+    ).trim();
+    const prereleaseSeparatorIndex = versionWithoutBuildMetadata.indexOf('-');
+    const releasePart =
+        prereleaseSeparatorIndex === -1
+            ? versionWithoutBuildMetadata
+            : versionWithoutBuildMetadata.slice(0, prereleaseSeparatorIndex);
+    const prereleasePart =
+        prereleaseSeparatorIndex === -1 ? null : versionWithoutBuildMetadata.slice(prereleaseSeparatorIndex + 1);
+
+    return {
+        releaseSegments: releasePart.split('.').map(parseNumericVersionIdentifier),
+        prereleaseIdentifiers:
+            prereleasePart === null
+                ? null
+                : prereleasePart
+                      .split('.')
+                      .map((identifier) => (/^\d+$/u.test(identifier) ? Number.parseInt(identifier, 10) : identifier)),
+    };
+}
+
+/**
+ * Parses one numeric release identifier while retaining the former tolerant behavior for malformed input.
+ */
+function parseNumericVersionIdentifier(identifier: string): number {
+    const identifierNumber = Number.parseInt(identifier, 10);
+
+    return Number.isNaN(identifierNumber) ? 0 : identifierNumber;
+}
+
+/**
+ * Compares numeric version segments, treating omitted trailing segments as zero.
+ */
+function compareNumericSegments(firstSegments: ReadonlyArray<number>, secondSegments: ReadonlyArray<number>): number {
+    const segmentCount = Math.max(firstSegments.length, secondSegments.length);
+
+    for (let segmentIndex = 0; segmentIndex < segmentCount; segmentIndex++) {
+        const firstSegment = firstSegments[segmentIndex] ?? 0;
+        const secondSegment = secondSegments[segmentIndex] ?? 0;
+
+        if (firstSegment !== secondSegment) {
+            return firstSegment < secondSegment ? -1 : 1;
+        }
+    }
+
+    return 0;
+}
+
+/**
+ * Compares semantic-version prerelease identifiers.
+ */
+function comparePrereleaseIdentifiers(
+    firstIdentifiers: ReadonlyArray<number | string> | null,
+    secondIdentifiers: ReadonlyArray<number | string> | null,
+): number {
+    if (firstIdentifiers === null || secondIdentifiers === null) {
+        if (firstIdentifiers === secondIdentifiers) {
+            return 0;
+        }
+
+        // Note: A version without prerelease identifiers has higher precedence than a prerelease
+        return firstIdentifiers === null ? 1 : -1;
+    }
+
+    const identifierCount = Math.max(firstIdentifiers.length, secondIdentifiers.length);
+
+    for (let identifierIndex = 0; identifierIndex < identifierCount; identifierIndex++) {
+        const firstIdentifier = firstIdentifiers[identifierIndex];
+        const secondIdentifier = secondIdentifiers[identifierIndex];
+
+        if (firstIdentifier === undefined || secondIdentifier === undefined) {
+            if (firstIdentifier === secondIdentifier) {
+                return 0;
+            }
+
+            return firstIdentifier === undefined ? -1 : 1;
+        }
+
+        const identifierComparison = comparePrereleaseIdentifier(firstIdentifier, secondIdentifier);
+
+        if (identifierComparison !== 0) {
+            return identifierComparison;
+        }
+    }
+
+    return 0;
+}
+
+/**
+ * Compares two individual semantic-version prerelease identifiers.
+ */
+function comparePrereleaseIdentifier(firstIdentifier: number | string, secondIdentifier: number | string): number {
+    if (firstIdentifier === secondIdentifier) {
+        return 0;
+    }
+
+    if (typeof firstIdentifier === 'number' && typeof secondIdentifier === 'number') {
+        return firstIdentifier < secondIdentifier ? -1 : 1;
+    }
+
+    if (typeof firstIdentifier === 'number') {
+        return -1;
+    }
+
+    if (typeof secondIdentifier === 'number') {
+        return 1;
+    }
+
+    return firstIdentifier < secondIdentifier ? -1 : 1;
+}
+
+// Note: [🟡] Code for CLI npm package version comparison [isNpmPackageVersionOutdated](src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.ts) should never be published outside of `@promptbook/cli`

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

@@ -1,5 +1,6 @@
 import { readFile, stat, writeFile } from 'fs/promises';
 import { join } from 'path';
+import { spaceTrim } from 'spacetrim';
 import { escapeRegExp } from '../../../utils/chat/escapeRegExp';
 
 /**
@@ -118,7 +119,15 @@ export async function ensureProjectGitignoreFile({
         return 'unchanged';
     }
 
-    const nextGitignoreContent = appendBlock(currentGitignoreContent || '', [blockHeader, ...missingRules].join('\n'));
+    const nextGitignoreContent = appendBlock(
+        currentGitignoreContent || '',
+        spaceTrim(
+            (block) => `
+                ${block(blockHeader)}
+                ${block(missingRules.join('\n'))}
+            `,
+        ),
+    );
     await writeFile(gitignorePath, nextGitignoreContent, 'utf-8');
     return currentGitignoreContent === undefined ? 'created' : 'updated';
 }

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

@@ -10,6 +10,8 @@ import {
     PTBK_MODEL_ENV,
     PTBK_THINKING_LEVEL_ENV,
 } from '../../../book-3.0/cliAgentEnv';
+import type { GitChangesMode } from '../coder/GitChangesMode';
+import { DEFAULT_GIT_CHANGES_MODE, GIT_CHANGES_MODE_VALUES } from '../coder/GitChangesMode';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 import { THINKING_LEVEL_VALUES } from '../coder/ThinkingLevel';
 
@@ -40,7 +42,7 @@ export type PromptRunnerCliOptions = {
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly commit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -68,7 +70,7 @@ export type NormalizedPromptRunnerCliOptions = {
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly noCommit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -98,6 +100,7 @@ export const PROMPT_RUNNER_DESCRIPTION = spaceTrim(`
     - claude-code: Claude Code integration
     - opencode: Opencode integration
     - gemini: Google Gemini CLI integration (requires --model)
+    - qwen-code: Qwen Code CLI integration (requires --model)
 `);
 
 /**
@@ -105,8 +108,16 @@ export const PROMPT_RUNNER_DESCRIPTION = spaceTrim(`
  *
  * @private internal utility of `promptbookCli`
  */
-export const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION =
-    'Select runner: openai-codex, github-copilot, cline, claude-code, opencode, gemini (required for non-dry-run)';
+export const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = `Select runner: ${PROMPT_RUNNER_HARNESS_NAMES.join(
+    ', ',
+)} (required for non-dry-run)`;
+
+/**
+ * Runner harness names listed as alternatives of the `--harness` option in error messages.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const PROMPT_RUNNER_HARNESS_OPTION_HINT = `--harness <${PROMPT_RUNNER_HARNESS_NAMES.join('|')}>`;
 
 /**
  * Commander description for the `--model` option.
@@ -114,10 +125,25 @@ export const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION =
  * @private internal utility of `promptbookCli`
  */
 export const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION = spaceTrim(`
-    Model to use (required for openai-codex and gemini)
+    Model to use (required for openai-codex, gemini and qwen-code)
 
     OpenAI examples: gpt-5.2-codex, default
     Gemini examples: gemini-3-flash-preview, default
+    Qwen examples: qwen3.8-max, default
+
+    For openai-codex, "default" overrides no model at all and keeps the one configured in Codex itself, which is what a ChatGPT-account login accepts
+`);
+
+/**
+ * Commander description for the `--git-changes` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const GIT_CHANGES_OPTION_DESCRIPTION = spaceTrim(`
+    Decide what happens when the working tree has uncommitted changes before a prompt starts:
+    - fail: refuse to start and ask for a commit or a stash (the default)
+    - ignore: start anyway and leave the uncommitted changes where they are
+    - continue: resume the single prompt which was left in the middle of its implementation
 `);
 
 /**
@@ -165,7 +191,11 @@ export function addPromptRunnerRuntimeOptions(command: Program): void {
 export function addPromptRunnerExecutionOptions(command: Program): void {
     addPromptRunnerRuntimeOptions(command);
     command.option('--no-commit', 'Leave successful changes in the working directory instead of creating git commits');
-    command.option('--ignore-git-changes', 'Skip clean working tree check before running prompts', false);
+    command.addOption(
+        new Option('--git-changes <mode>', GIT_CHANGES_OPTION_DESCRIPTION)
+            .choices([...GIT_CHANGES_MODE_VALUES])
+            .default(DEFAULT_GIT_CHANGES_MODE),
+    );
     command.option(
         '--no-normalize-line-endings',
         'Disable automatic LF normalization for files changed in each coding round',
@@ -190,7 +220,7 @@ export function normalizePromptRunnerCliOptions(
     return {
         ...selectionOptions,
         noCommit: !cliOptions.commit,
-        ignoreGitChanges: cliOptions.ignoreGitChanges,
+        gitChanges: cliOptions.gitChanges ?? DEFAULT_GIT_CHANGES_MODE,
         normalizeLineEndings: cliOptions.normalizeLineEndings,
         autoPush: cliOptions.autoPush,
         autoPull: cliOptions.autoPull,
@@ -231,11 +261,7 @@ function resolvePromptRunnerHarnessName(
             return undefined;
         }
 
-        throw new Error(
-            colors.red(
-                'You must choose a harness using --harness <openai-codex|github-copilot|cline|claude-code|opencode|gemini>',
-            ),
-        );
+        throw new Error(colors.red(`You must choose a harness using ${PROMPT_RUNNER_HARNESS_OPTION_HINT}`));
     }
 
     if (isPromptRunnerHarnessName(harness)) {

package/src/cli/cli-commands/common/promptbook-cli/$checkPromptbookCliInstallations.ts

@@ -0,0 +1,69 @@
+import { $resolveLatestNpmPackageVersion } from '../npm/$resolveLatestNpmPackageVersion';
+import { isNpmPackageVersionOutdated } from '../npm/isNpmPackageVersionOutdated';
+import { $resolvePromptbookCliInstallations } from './$resolvePromptbookCliInstallations';
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+import type {
+    PromptbookCliInstallationState,
+    PromptbookCliInstallationStatus,
+} from './PromptbookCliInstallationStatus';
+
+/**
+ * Checks every local and global Promptbook CLI installation against the newest npm version.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads installed packages and queries npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $checkPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallationStatus>> {
+    const installations = await $resolvePromptbookCliInstallations();
+
+    if (installations.length === 0) {
+        return [];
+    }
+
+    const latestVersionsByNpmPackageName = await $resolveLatestVersionsByNpmPackageName(installations);
+
+    return installations.map((installation) => {
+        const latestVersion = latestVersionsByNpmPackageName.get(installation.npmPackageName) ?? null;
+
+        return {
+            installation,
+            installationState: resolvePromptbookCliInstallationState(installation.installedVersion, latestVersion),
+            latestVersion,
+        };
+    });
+}
+
+/**
+ * Resolves each package's newest version once, even when it is installed locally and globally.
+ */
+async function $resolveLatestVersionsByNpmPackageName(
+    installations: ReadonlyArray<PromptbookCliInstallation>,
+): Promise<ReadonlyMap<PromptbookCliInstallation['npmPackageName'], string | null>> {
+    const npmPackageNames = Array.from(new Set(installations.map(({ npmPackageName }) => npmPackageName)));
+    const latestVersionEntries = await Promise.all(
+        npmPackageNames.map(async (npmPackageName) => {
+            const latestVersion = await $resolveLatestNpmPackageVersion(npmPackageName);
+
+            return [npmPackageName, latestVersion] as const;
+        }),
+    );
+
+    return new Map(latestVersionEntries);
+}
+
+/**
+ * Derives the update state of one installed Promptbook CLI package.
+ */
+function resolvePromptbookCliInstallationState(
+    installedVersion: string,
+    latestVersion: string | null,
+): PromptbookCliInstallationState {
+    if (latestVersion === null) {
+        return 'unknown';
+    }
+
+    return isNpmPackageVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
+}
+
+// Note: [🟡] Code for Promptbook CLI installation check [$checkPromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$checkPromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.ts

@@ -0,0 +1,117 @@
+import colors from 'colors';
+import { spaceTrim } from 'spacetrim';
+import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
+import { $checkPromptbookCliInstallations } from './$checkPromptbookCliInstallations';
+import { $updatePromptbookCliInstallation } from './$updatePromptbookCliInstallation';
+import { buildPromptbookCliInstallCommand } from './buildPromptbookCliInstallCommand';
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+import { formatPromptbookCliInstallationWarning } from './formatPromptbookCliInstallationWarning';
+
+/**
+ * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
+ *
+ * Once an update succeeds, the caller must stop the current run and let the user start a fresh process. A local npm
+ * update can modify `package.json` and a lockfile, which would make the coder's clean-working-tree preflight fail;
+ * the current Node.js process has also already loaded the old CLI implementation.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests, queries npm,
+ * asks the user, and may install npm packages
+ *
+ * @returns `true` when at least one installation was updated and the current coder run should stop
+ * @private internal utility of `promptbookCli`
+ */
+export async function $ensurePromptbookCliInstallations(): Promise<boolean> {
+    if (!process.stdin.isTTY) {
+        // Note: Non-interactive runs cannot approve an update and should not wait for registry checks
+        return false;
+    }
+
+    const statuses = await $checkPromptbookCliInstallations();
+    const outdatedStatuses = statuses.filter(({ installationState }) => installationState === 'outdated');
+
+    if (outdatedStatuses.length === 0) {
+        reportPromptbookCliInstallationStatuses(statuses);
+        return false;
+    }
+
+    console.warn(colors.yellow(formatPromptbookCliInstallationWarning(outdatedStatuses)));
+
+    const isUpdateApproved = await $askForNpmPackageInstallationApproval('Update Promptbook CLI now?');
+
+    if (!isUpdateApproved) {
+        reportManualPromptbookCliUpdateCommands(outdatedStatuses);
+        return false;
+    }
+
+    const updateResults: Array<boolean> = [];
+
+    for (const status of outdatedStatuses) {
+        updateResults.push(await $updatePromptbookCliInstallation(status));
+    }
+
+    const isAnyInstallationUpdated = updateResults.some(Boolean);
+    const isEveryInstallationUpdated = updateResults.every(Boolean);
+
+    if (!isAnyInstallationUpdated) {
+        console.info(colors.gray('Promptbook CLI could not be updated; continuing with the installed version.'));
+        return false;
+    }
+
+    console.info(
+        isEveryInstallationUpdated
+            ? colors.green('Promptbook CLI update is complete. Run the command again to use the new version.')
+            : colors.yellow(
+                  'Some Promptbook CLI installations were updated. Resolve the errors above, then run the command again.',
+              ),
+    );
+    return true;
+}
+
+/**
+ * Reports successful and unverifiable Promptbook CLI checks when no update is required.
+ */
+function reportPromptbookCliInstallationStatuses(statuses: ReadonlyArray<PromptbookCliInstallationStatus>): void {
+    for (const status of statuses) {
+        const { npmPackageName, installedVersion } = status.installation;
+
+        if (status.installationState === 'up-to-date') {
+            console.info(colors.gray(`✔ Promptbook CLI \`${npmPackageName}\` ${installedVersion} is up to date.`));
+            continue;
+        }
+
+        if (status.installationState === 'unknown') {
+            console.info(
+                colors.gray(
+                    `✔ Promptbook CLI \`${npmPackageName}\` ${installedVersion} is installed; the newest version could not be checked.`,
+                ),
+            );
+        }
+    }
+}
+
+/**
+ * Prints the exact commands which would update all declined outdated installations.
+ */
+function reportManualPromptbookCliUpdateCommands(
+    outdatedStatuses: ReadonlyArray<PromptbookCliInstallationStatus>,
+): void {
+    const manualInstallCommands = outdatedStatuses
+        .map((status) => `- \`${buildPromptbookCliInstallCommand(status.installation)}\``)
+        .join('\n');
+
+    console.info(
+        colors.gray(
+            spaceTrim(
+                (block) => `
+                    Skipped updating Promptbook CLI.
+
+                    Run these commands manually:
+
+                    ${block(manualInstallCommands)}
+                `,
+            ),
+        ),
+    );
+}
+
+// Note: [🟡] Code for Promptbook CLI installation orchestration [$ensurePromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`