@promptbook/cli 0.114.0-2 → 0.114.0-21

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

@@ -1,25 +1,34 @@
 import { $resolveInstalledHarnessVersion } from './$resolveInstalledHarnessVersion';
-import { $resolveLatestHarnessVersion } from './$resolveLatestHarnessVersion';
+import { $resolveLatestNpmPackageVersion } from '../npm/$resolveLatestNpmPackageVersion';
+import { isNpmPackageVersionOutdated } from '../npm/isNpmPackageVersionOutdated';
 import type { HarnessDefinition } from './HarnessDefinition';
 import type { HarnessInstallationState, HarnessInstallationStatus } from './HarnessInstallationStatus';
-import { isHarnessVersionOutdated } from './isHarnessVersionOutdated';
 
 /**
- * Detects whether one CLI coding harness is installed globally and whether it is up to date.
+ * 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),
-        $resolveLatestHarnessVersion(definition),
+        isHarnessUpdateCheckEnabled
+            ? $resolveLatestNpmPackageVersion(definition.npmPackageName)
+            : Promise.resolve(null),
     ]);
 
     return {
         definition,
-        installationState: resolveHarnessInstallationState(installedVersion, latestVersion),
+        installationState: resolveHarnessInstallationState(
+            installedVersion,
+            latestVersion,
+            isHarnessUpdateCheckEnabled,
+        ),
         installedVersion,
         latestVersion,
     };
@@ -31,16 +40,23 @@ 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';
     }
 
-    return isHarnessVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
+    return isNpmPackageVersionOutdated(installedVersion, latestVersion, { isPrereleaseIgnored: true })
+        ? 'outdated'
+        : 'up-to-date';
 }
 
 // Note: [🟡] Code for CLI harness installation check [$checkHarnessInstallation](src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts) should never be published outside of `@promptbook/cli`

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

@@ -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/$resolveInstalledHarnessVersion.ts

@@ -1,5 +1,5 @@
 import { $execCommand } from '../../../../utils/execCommand/$execCommand';
-import { extractHarnessVersionFromOutput } from './extractHarnessVersionFromOutput';
+import { extractNpmPackageVersionFromOutput } from '../npm/extractNpmPackageVersionFromOutput';
 import type { HarnessDefinition } from './HarnessDefinition';
 
 /**
@@ -23,7 +23,7 @@ export async function $resolveInstalledHarnessVersion(definition: HarnessDefinit
         isVerbose: false,
     }).catch(() => '');
 
-    return extractHarnessVersionFromOutput(output);
+    return extractNpmPackageVersionFromOutput(output);
 }
 
 // Note: [🟡] Code for CLI harness version detection [$resolveInstalledHarnessVersion](src/cli/cli-commands/common/harness/$resolveInstalledHarnessVersion.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/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/harness/buildHarnessInstallCommand.ts

@@ -1,3 +1,4 @@
+import { buildNpmPackageInstallCommand } from '../npm/buildNpmPackageInstallCommand';
 import type { HarnessDefinition } from './HarnessDefinition';
 
 /**
@@ -9,7 +10,7 @@ import type { HarnessDefinition } from './HarnessDefinition';
  * @private internal utility of `promptbookCli`
  */
 export function buildHarnessInstallCommand(definition: HarnessDefinition): string {
-    return `npm install -g ${definition.npmPackageName}@latest`;
+    return buildNpmPackageInstallCommand(definition.npmPackageName, 'global');
 }
 
 // Note: [🟡] Code for CLI harness install command [buildHarnessInstallCommand](src/cli/cli-commands/common/harness/buildHarnessInstallCommand.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,46 @@
+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/cli/cli-commands/common/{harness/$askForHarnessInstallationApproval.ts → npm/$askForNpmPackageInstallationApproval.ts}

@@ -2,14 +2,14 @@ import colors from 'colors';
 import { createInterface } from 'readline';
 
 /**
- * Asks the user in the terminal whether the harness should be installed or updated right now.
+ * Asks the user in the terminal whether an npm package should be installed or updated now.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin
  *
  * @returns `true` when the user confirms, `false` when the user declines or the terminal is not interactive
  * @private internal utility of `promptbookCli`
  */
-export async function $askForHarnessInstallationApproval(question: string): Promise<boolean> {
+export async function $askForNpmPackageInstallationApproval(question: string): Promise<boolean> {
     if (!process.stdin.isTTY) {
         // Note: In non-interactive environments like CI there is nobody who could confirm the installation
         return false;
@@ -28,4 +28,4 @@ export async function $askForHarnessInstallationApproval(question: string): Prom
     }
 }
 
-// Note: [🟡] Code for CLI harness installation approval [$askForHarnessInstallationApproval](src/cli/cli-commands/common/harness/$askForHarnessInstallationApproval.ts) should never be published outside of `@promptbook/cli`
+// Note: [🟡] Code for CLI npm package installation approval [$askForNpmPackageInstallationApproval](src/cli/cli-commands/common/npm/$askForNpmPackageInstallationApproval.ts) should never be published outside of `@promptbook/cli`

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/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;
@@ -120,6 +122,18 @@ export const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION = spaceTrim(`
     Gemini examples: gemini-3-flash-preview, default
 `);
 
+/**
+ * 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
+`);
+
 /**
  * Registers runner selection flags on a command.
  *
@@ -165,7 +179,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 +208,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,

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`