@promptbook/cli 0.114.0-3 → 0.114.0-31

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`

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

@@ -0,0 +1,259 @@
+import { readFile } from 'fs/promises';
+import { dirname, join, resolve } from 'path';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import {
+    PROMPTBOOK_CLI_NPM_PACKAGE_NAMES,
+    type LocalPromptbookCliInstallation,
+    type PromptbookCliInstallation,
+    type PromptbookCliInstallationLocation,
+    type PromptbookCliNpmPackageName,
+} from './PromptbookCliInstallation';
+
+/**
+ * Time limit for listing directly installed global npm packages.
+ */
+const NPM_GLOBAL_PACKAGE_LIST_COMMAND_TIMEOUT_MS = 30 * 1000;
+
+/**
+ * Filename of an npm package manifest.
+ */
+const PACKAGE_JSON_FILENAME = 'package.json';
+
+/**
+ * Directory containing locally installed npm packages.
+ */
+const NODE_MODULES_DIRECTORY_NAME = 'node_modules';
+
+/**
+ * JSON object shape used while reading package manifests without assuming unrelated fields.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+type JsonObject = Readonly<Record<string, unknown>>;
+
+/**
+ * Finds every directly declared local or directly installed global Promptbook CLI package which can be updated.
+ *
+ * Transitive packages are deliberately ignored because this command must update the dependency chosen by the current
+ * project or global npm installation, not mutate a dependency owned by another package.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests and runs npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>> {
+    const [localInstallations, globalInstallations] = await Promise.all([
+        $resolveLocalPromptbookCliInstallations(),
+        $resolveGlobalPromptbookCliInstallations(),
+    ]);
+
+    return [...localInstallations, ...globalInstallations];
+}
+
+/**
+ * Finds the closest ancestor `package.json` which directly declares a Promptbook CLI package.
+ */
+async function $resolveLocalPromptbookCliInstallations(): Promise<ReadonlyArray<LocalPromptbookCliInstallation>> {
+    let candidateProjectPath = resolve(process.cwd());
+    let isFileSystemRootReached = false;
+
+    while (!isFileSystemRootReached) {
+        const projectPackageJson = await $readJsonObject(join(candidateProjectPath, PACKAGE_JSON_FILENAME));
+
+        if (projectPackageJson !== null) {
+            const declaredPackages = resolveDeclaredPromptbookCliPackages(projectPackageJson);
+
+            if (declaredPackages.length > 0) {
+                const installations = await Promise.all(
+                    declaredPackages.map(async ({ npmPackageName, installationLocation }) => {
+                        const installedVersion = await $resolveLocalInstalledNpmPackageVersion(
+                            candidateProjectPath,
+                            npmPackageName,
+                        );
+
+                        return installedVersion === null
+                            ? undefined
+                            : {
+                                  npmPackageName,
+                                  installedVersion,
+                                  installationLocation,
+                                  projectPath: candidateProjectPath,
+                              };
+                    }),
+                );
+
+                return installations.filter(isDefined);
+            }
+        }
+
+        const parentPath = dirname(candidateProjectPath);
+        isFileSystemRootReached = parentPath === candidateProjectPath;
+        candidateProjectPath = parentPath;
+    }
+
+    return [];
+}
+
+/**
+ * Finds Promptbook CLI package names declared in dependencies or development dependencies.
+ */
+function resolveDeclaredPromptbookCliPackages(packageJson: JsonObject): ReadonlyArray<{
+    readonly npmPackageName: PromptbookCliNpmPackageName;
+    readonly installationLocation: Exclude<PromptbookCliInstallationLocation, 'global'>;
+}> {
+    const declaredPackages: Array<{
+        readonly npmPackageName: PromptbookCliNpmPackageName;
+        readonly installationLocation: Exclude<PromptbookCliInstallationLocation, 'global'>;
+    }> = [];
+
+    for (const npmPackageName of PROMPTBOOK_CLI_NPM_PACKAGE_NAMES) {
+        if (readNestedStringProperty(packageJson, 'dependencies', npmPackageName) !== undefined) {
+            declaredPackages.push({ npmPackageName, installationLocation: 'local-dependency' });
+            continue;
+        }
+
+        if (readNestedStringProperty(packageJson, 'devDependencies', npmPackageName) !== undefined) {
+            declaredPackages.push({ npmPackageName, installationLocation: 'local-development-dependency' });
+        }
+    }
+
+    return declaredPackages;
+}
+
+/**
+ * Reads an installed local package version while following npm's ancestor `node_modules` lookup behavior.
+ */
+async function $resolveLocalInstalledNpmPackageVersion(
+    projectPath: string,
+    npmPackageName: PromptbookCliNpmPackageName,
+): Promise<string | null> {
+    let candidateNodeModulesParentPath = projectPath;
+    let isFileSystemRootReached = false;
+
+    while (!isFileSystemRootReached) {
+        const installedPackageJson = await $readJsonObject(
+            join(candidateNodeModulesParentPath, NODE_MODULES_DIRECTORY_NAME, npmPackageName, PACKAGE_JSON_FILENAME),
+        );
+        const installedVersion =
+            installedPackageJson === null ? undefined : readStringProperty(installedPackageJson, 'version');
+
+        if (installedVersion !== undefined) {
+            return installedVersion;
+        }
+
+        const parentPath = dirname(candidateNodeModulesParentPath);
+        isFileSystemRootReached = parentPath === candidateNodeModulesParentPath;
+        candidateNodeModulesParentPath = parentPath;
+    }
+
+    return null;
+}
+
+/**
+ * Finds Promptbook CLI packages listed by npm as direct global installations.
+ */
+async function $resolveGlobalPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>> {
+    const output = await $execCommand({
+        command: 'npm list --global --depth=0 --json --loglevel=error',
+        // Note: npm can return a non-zero status for an unrelated broken global package while still printing useful JSON
+        crashOnError: false,
+        timeout: NPM_GLOBAL_PACKAGE_LIST_COMMAND_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+    const globalPackageList = parseJsonObjectFromCommandOutput(output);
+    const globalDependencies =
+        globalPackageList === null ? null : readObjectProperty(globalPackageList, 'dependencies');
+
+    if (globalDependencies === null) {
+        return [];
+    }
+
+    return PROMPTBOOK_CLI_NPM_PACKAGE_NAMES.flatMap((npmPackageName) => {
+        const packageMetadata = readObjectProperty(globalDependencies, npmPackageName);
+        const installedVersion = packageMetadata === null ? undefined : readStringProperty(packageMetadata, 'version');
+
+        return installedVersion === undefined
+            ? []
+            : [{ npmPackageName, installedVersion, installationLocation: 'global' as const }];
+    });
+}
+
+/**
+ * Reads a JSON object, returning `null` for missing or malformed files because update checks must stay advisory.
+ */
+async function $readJsonObject(filePath: string): Promise<JsonObject | null> {
+    try {
+        const parsedValue: unknown = JSON.parse(await readFile(filePath, 'utf8'));
+
+        return isJsonObject(parsedValue) ? parsedValue : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Parses a JSON object from command output while tolerating npm warnings around the JSON payload.
+ */
+function parseJsonObjectFromCommandOutput(output: string): JsonObject | null {
+    const jsonStartIndex = output.indexOf('{');
+    const jsonEndIndex = output.lastIndexOf('}');
+
+    if (jsonStartIndex === -1 || jsonEndIndex < jsonStartIndex) {
+        return null;
+    }
+
+    try {
+        const parsedValue: unknown = JSON.parse(output.slice(jsonStartIndex, jsonEndIndex + 1));
+
+        return isJsonObject(parsedValue) ? parsedValue : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Checks whether an unknown value can be read as a JSON object.
+ */
+function isJsonObject(value: unknown): value is JsonObject {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Reads one string property from a JSON object.
+ */
+function readStringProperty(jsonObject: JsonObject, propertyName: string): string | undefined {
+    const value = jsonObject[propertyName];
+
+    return typeof value === 'string' ? value : undefined;
+}
+
+/**
+ * Reads one object property from a JSON object.
+ */
+function readObjectProperty(jsonObject: JsonObject, propertyName: string): JsonObject | null {
+    const value = jsonObject[propertyName];
+
+    return isJsonObject(value) ? value : null;
+}
+
+/**
+ * Reads one string property nested under another JSON object property.
+ */
+function readNestedStringProperty(
+    jsonObject: JsonObject,
+    parentPropertyName: string,
+    propertyName: string,
+): string | undefined {
+    const nestedValue = readObjectProperty(jsonObject, parentPropertyName);
+
+    return nestedValue === null ? undefined : readStringProperty(nestedValue, propertyName);
+}
+
+/**
+ * Narrows an array after `undefined` values were removed.
+ */
+function isDefined<TValue>(value: TValue | undefined): value is TValue {
+    return value !== undefined;
+}
+
+// Note: [🟡] Code for Promptbook CLI installation detection [$resolvePromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,55 @@
+import colors from 'colors';
+import { spaceTrim } from 'spacetrim';
+import { assertsError } from '../../../../errors/assertsError';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import { buildPromptbookCliInstallCommand } from './buildPromptbookCliInstallCommand';
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+
+/**
+ * Updates one Promptbook CLI package in its existing local or global location.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs an npm package
+ *
+ * @returns `true` when the package update succeeds, `false` when it fails
+ * @private internal utility of `promptbookCli`
+ */
+export async function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean> {
+    const { npmPackageName, installationLocation } = status.installation;
+    const installCommand = buildPromptbookCliInstallCommand(status.installation);
+    const updateWorkingDirectory = installationLocation === 'global' ? process.cwd() : status.installation.projectPath;
+
+    console.info(colors.cyan(`Updating Promptbook CLI package \`${npmPackageName}\` with \`${installCommand}\`...`));
+
+    try {
+        await $execCommand({
+            command: installCommand,
+            cwd: updateWorkingDirectory,
+            crashOnError: true,
+            isVerbose: true,
+        });
+    } catch (error) {
+        assertsError(error);
+        const updateErrorMessage = error.message;
+
+        console.error(
+            colors.red(
+                spaceTrim(
+                    (block) => `
+                        Could not update **Promptbook CLI** package \`${npmPackageName}\`.
+
+                        Update it manually with \`${installCommand}\` and run the command again.
+
+                        ${block(updateErrorMessage)}
+                    `,
+                ),
+            ),
+        );
+
+        return false;
+    }
+
+    console.info(colors.green(`Promptbook CLI package \`${npmPackageName}\` has been updated.`));
+    return true;
+}
+
+// Note: [🟡] Code for Promptbook CLI installation update [$updatePromptbookCliInstallation](src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.ts

@@ -0,0 +1,76 @@
+import type { NpmPackageInstallationLocation } from '../npm/buildNpmPackageInstallCommand';
+
+/**
+ * Npm packages which directly provide the `ptbk` executable.
+ *
+ * `ptbk` is the preferred package and forwards to `@promptbook/cli`; the latter can also be installed directly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const PROMPTBOOK_CLI_NPM_PACKAGE_NAMES = ['ptbk', '@promptbook/cli'] as const;
+
+/**
+ * Npm package which directly provides the `ptbk` executable.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliNpmPackageName = (typeof PROMPTBOOK_CLI_NPM_PACKAGE_NAMES)[number];
+
+/**
+ * Place where one Promptbook CLI package is installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationLocation = NpmPackageInstallationLocation;
+
+/**
+ * Fields shared by local and global Promptbook CLI installations.
+ *
+ * @private internal utility of `PromptbookCliInstallation`
+ */
+type PromptbookCliInstallationBase = {
+    /**
+     * Npm package that provides the CLI.
+     */
+    readonly npmPackageName: PromptbookCliNpmPackageName;
+
+    /**
+     * Version from the installed package's `package.json`.
+     */
+    readonly installedVersion: string;
+};
+
+/**
+ * One directly declared local Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type LocalPromptbookCliInstallation = PromptbookCliInstallationBase & {
+    /**
+     * Local manifest section containing the package.
+     */
+    readonly installationLocation: Exclude<PromptbookCliInstallationLocation, 'global'>;
+
+    /**
+     * Project directory containing the `package.json` which declares the package.
+     */
+    readonly projectPath: string;
+};
+
+/**
+ * One directly installed global Promptbook CLI package.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type GlobalPromptbookCliInstallation = PromptbookCliInstallationBase & {
+    readonly installationLocation: 'global';
+};
+
+/**
+ * One local or global Promptbook CLI package that can be updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallation = LocalPromptbookCliInstallation | GlobalPromptbookCliInstallation;
+
+// Note: [🟡] Code for Promptbook CLI installation definitions [PromptbookCliInstallation](src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.ts) should never be published outside of `@promptbook/cli`