@promptbook/cli 0.114.0-3 → 0.114.0-31

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

@@ -1,27 +1,43 @@
 import { $resolveInstalledHarnessVersion } from './$resolveInstalledHarnessVersion';
-import { $resolveLatestHarnessVersion } from './$resolveLatestHarnessVersion';
+import { $resolveLatestNpmPackageVersion } from '../npm/$resolveLatestNpmPackageVersion';
+import { isNpmPackageVersionOutdated } from '../npm/isNpmPackageVersionOutdated';
+import { $resolveHarnessInstallationOrigin } from './$resolveHarnessInstallationOrigin';
 import type { HarnessDefinition } from './HarnessDefinition';
+import { UNKNOWN_HARNESS_INSTALLATION_ORIGIN } from './HarnessInstallationOrigin';
 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> {
-    const [installedVersion, latestVersion] = await Promise.all([
+export async function $checkHarnessInstallation(
+    definition: HarnessDefinition,
+    isHarnessUpdateCheckEnabled = true,
+): Promise<HarnessInstallationStatus> {
+    // Note: The origin is only needed to update an outdated harness, so it is not looked up without the update check
+    const [installedVersion, latestVersion, installationOrigin] = await Promise.all([
         $resolveInstalledHarnessVersion(definition),
-        $resolveLatestHarnessVersion(definition),
+        isHarnessUpdateCheckEnabled
+            ? $resolveLatestNpmPackageVersion(definition.npmPackageName)
+            : Promise.resolve(null),
+        isHarnessUpdateCheckEnabled
+            ? $resolveHarnessInstallationOrigin(definition)
+            : Promise.resolve(UNKNOWN_HARNESS_INSTALLATION_ORIGIN),
     ]);
 
     return {
         definition,
-        installationState: resolveHarnessInstallationState(installedVersion, latestVersion),
+        installationState: resolveHarnessInstallationState(
+            installedVersion,
+            latestVersion,
+            isHarnessUpdateCheckEnabled,
+        ),
         installedVersion,
         latestVersion,
+        installationOrigin,
     };
 }
 
@@ -31,16 +47,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/$resolveHarnessCommandPath.ts

@@ -0,0 +1,46 @@
+import { realpath } from 'fs/promises';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import type { HarnessDefinition } from './HarnessDefinition';
+
+/**
+ * Time limit for looking up where the harness command lives.
+ */
+const HARNESS_COMMAND_LOOKUP_TIMEOUT_MS = 30 * 1000;
+
+/**
+ * Finds out which file is really executed when the harness command runs.
+ *
+ * The lookup deliberately uses the very same `PATH` which runs the harness, so it reports the copy of the
+ * harness which Promptbook itself would use. Symbolic links are followed, because installers like the
+ * standalone OpenAI Codex installer only link their package into a directory on `PATH`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs a command in a shell
+ *
+ * @returns Resolved path of the harness command or `null` when the command is not available
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolveHarnessCommandPath(definition: HarnessDefinition): Promise<string | null> {
+    const lookupCommand =
+        process.platform === 'win32' ? `where ${definition.commandName}` : `command -v ${definition.commandName}`;
+
+    const output: string = await $execCommand({
+        command: lookupCommand,
+        crashOnError: true,
+        timeout: HARNESS_COMMAND_LOOKUP_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+
+    // Note: `where` lists every match on its own line, only the first one is really executed
+    const commandPath = output
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line !== '');
+
+    if (commandPath === undefined) {
+        return null;
+    }
+
+    return await realpath(commandPath).catch(() => commandPath);
+}
+
+// Note: [🟡] Code for CLI harness command lookup [$resolveHarnessCommandPath](src/cli/cli-commands/common/harness/$resolveHarnessCommandPath.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,36 @@
+import { $resolveNpmGlobalPrefixPath } from '../npm/$resolveNpmGlobalPrefixPath';
+import { $resolveHarnessCommandPath } from './$resolveHarnessCommandPath';
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
+import { UNKNOWN_HARNESS_INSTALLATION_ORIGIN } from './HarnessInstallationOrigin';
+import { resolveHarnessInstallationMethodFromPaths } from './resolveHarnessInstallationMethodFromPaths';
+
+/**
+ * Finds out where one CLI coding harness is really installed and which tool manages it.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs shell commands
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolveHarnessInstallationOrigin(
+    definition: HarnessDefinition,
+): Promise<HarnessInstallationOrigin> {
+    const commandPath = await $resolveHarnessCommandPath(definition);
+
+    if (commandPath === null) {
+        return UNKNOWN_HARNESS_INSTALLATION_ORIGIN;
+    }
+
+    const npmGlobalPrefixPath = await $resolveNpmGlobalPrefixPath();
+
+    return {
+        commandPath,
+        installationMethod: resolveHarnessInstallationMethodFromPaths({
+            definition,
+            commandPath,
+            npmGlobalPrefixPath,
+        }),
+    };
+}
+
+// Note: [🟡] Code for CLI harness installation origin detection [$resolveHarnessInstallationOrigin](src/cli/cli-commands/common/harness/$resolveHarnessInstallationOrigin.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,100 @@
+import colors from 'colors';
+import { spaceTrim } from 'spacetrim';
+import { assertsError } from '../../../../errors/assertsError';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import type { HarnessDefinition } from './HarnessDefinition';
+
+/**
+ * What one harness installation command does with the harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOperation = 'install' | 'update';
+
+/**
+ * Words describing each operation in the terminal output.
+ */
+const HARNESS_INSTALLATION_OPERATION_WORDS: Readonly<
+    Record<HarnessInstallationOperation, { readonly running: string; readonly finished: string }>
+> = {
+    install: { running: 'Installing', finished: 'installed' },
+    update: { running: 'Updating', finished: 'updated' },
+};
+
+/**
+ * Options of one command which installs or updates a CLI coding harness.
+ *
+ * @private internal utility of `$runHarnessInstallationCommand`
+ */
+type HarnessInstallationCommandOptions = {
+    /**
+     * Harness which is installed or updated.
+     */
+    readonly definition: HarnessDefinition;
+
+    /**
+     * What the command does with the harness.
+     */
+    readonly operation: HarnessInstallationOperation;
+
+    /**
+     * Shell command which does it.
+     */
+    readonly command: string;
+
+    /**
+     * Extra environment variables required by the command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};
+
+/**
+ * Runs one command which installs or updates a CLI coding harness.
+ *
+ * A failed installation is reported but never aborts the running command, because the harness check
+ * is only an assistant - the command itself may still work with a manually managed harness.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs software
+ *
+ * @returns `true` when the command succeeded, `false` when it failed
+ * @private internal utility of `promptbookCli`
+ */
+export async function $runHarnessInstallationCommand(options: HarnessInstallationCommandOptions): Promise<boolean> {
+    const { definition, operation, command, environment } = options;
+    const operationWords = HARNESS_INSTALLATION_OPERATION_WORDS[operation];
+
+    console.info(colors.cyan(`${operationWords.running} ${definition.label} with \`${command}\`...`));
+
+    try {
+        await $execCommand({
+            command,
+            crashOnError: true,
+            isVerbose: true,
+            env: environment ? { ...environment } : undefined,
+        });
+    } catch (error) {
+        assertsError(error);
+        const installErrorMessage = error.message;
+
+        console.error(
+            colors.red(
+                spaceTrim(
+                    (block) => `
+                        Could not ${operation} **${definition.label}**.
+
+                        Run \`${command}\` manually and run the command again.
+
+                        ${block(installErrorMessage)}
+                    `,
+                ),
+            ),
+        );
+
+        return false;
+    }
+
+    console.info(colors.green(`${definition.label} has been ${operationWords.finished}.`));
+    return true;
+}
+
+// Note: [🟡] Code for CLI harness installation commands [$runHarnessInstallationCommand](src/cli/cli-commands/common/harness/$runHarnessInstallationCommand.ts) should never be published outside of `@promptbook/cli`

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

@@ -2,6 +2,28 @@ import { spaceTrim } from 'spacetrim';
 import { UnexpectedError } from '../../../../errors/UnexpectedError';
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
 
+/**
+ * Description of a standalone *(self-managed)* installation of one CLI coding harness.
+ *
+ * Some harnesses are also distributed by their own installer which puts the harness outside of npm and
+ * updates it in place. Such an installation must never be updated with `npm install -g`, because that
+ * installs a second copy of the harness instead of updating the one which is really used.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessStandaloneInstallation = {
+    /**
+     * Directory names which appear in the resolved path of a standalone installation of the harness,
+     * for example `.codex` in `~/.codex/packages/standalone/current/bin/codex`.
+     */
+    readonly directoryNames: ReadonlyArray<string>;
+
+    /**
+     * Command which updates the standalone installation in place.
+     */
+    readonly updateCommand: string;
+};
+
 /**
  * Static description of one supported CLI coding harness.
  *
@@ -32,6 +54,18 @@ export type HarnessDefinition = {
      * Extra environment variables required by the global npm installation of this harness.
      */
     readonly npmInstallEnvironment?: Readonly<Record<string, string>>;
+
+    /**
+     * Project-local files or directories which this harness can create and which should not be committed.
+     */
+    readonly projectGitignoreRules: ReadonlyArray<string>;
+
+    /**
+     * How a standalone installation of this harness is recognized and updated.
+     *
+     * Harnesses which are distributed only through npm leave this undefined.
+     */
+    readonly standaloneInstallation?: HarnessStandaloneInstallation;
 };
 
 /**
@@ -45,12 +79,19 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         label: 'OpenAI Codex',
         commandName: 'codex',
         npmPackageName: '@openai/codex',
+        projectGitignoreRules: ['.codex'],
+        // Note: The official standalone installer keeps its package in `~/.codex` and links it onto the `PATH`
+        standaloneInstallation: {
+            directoryNames: ['.codex'],
+            updateCommand: 'codex update',
+        },
     },
     'github-copilot': {
         harnessName: 'github-copilot',
         label: 'GitHub Copilot',
         commandName: 'copilot',
         npmPackageName: '@github/copilot',
+        projectGitignoreRules: ['.github/copilot/settings.local.json'],
         // Note: The GitHub Copilot CLI downloads its native binary in a postinstall script
         npmInstallEnvironment: { npm_config_ignore_scripts: 'false' },
     },
@@ -59,24 +100,35 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         label: 'Cline',
         commandName: 'cline',
         npmPackageName: 'cline',
+        projectGitignoreRules: ['.cline'],
     },
     'claude-code': {
         harnessName: 'claude-code',
         label: 'Claude Code',
         commandName: 'claude',
         npmPackageName: '@anthropic-ai/claude-code',
+        projectGitignoreRules: ['.claude'],
     },
     opencode: {
         harnessName: 'opencode',
         label: 'Opencode',
         commandName: 'opencode',
         npmPackageName: 'opencode-ai',
+        projectGitignoreRules: ['.opencode'],
     },
     gemini: {
         harnessName: 'gemini',
         label: 'Gemini CLI',
         commandName: 'gemini',
         npmPackageName: '@google/gemini-cli',
+        projectGitignoreRules: ['.gemini'],
+    },
+    'qwen-code': {
+        harnessName: 'qwen-code',
+        label: 'Qwen Code',
+        commandName: 'qwen',
+        npmPackageName: '@qwen-code/qwen-code',
+        projectGitignoreRules: ['.qwen'],
     },
 };
 
@@ -100,3 +152,16 @@ export function getHarnessDefinition(harnessName: PromptRunnerHarnessName): Harn
 
     return definition;
 }
+
+/**
+ * Lists the unique project ignore rules required by the selected harnesses, in selection order.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function getHarnessProjectGitignoreRules(
+    harnessNames: ReadonlyArray<PromptRunnerHarnessName>,
+): ReadonlyArray<string> {
+    return Array.from(
+        new Set(harnessNames.flatMap((harnessName) => getHarnessDefinition(harnessName).projectGitignoreRules)),
+    );
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Way in which the globally available harness command got onto the current machine.
+ *
+ * - `npm-global` the command comes from a global npm installation, so `npm install -g` really updates it
+ * - `standalone` the command was installed by the own installer of the harness and updates itself in place
+ * - `homebrew` the command is managed by Homebrew, so only `brew` may update it
+ * - `unknown` the command lives somewhere else or could not be located at all
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationMethod = 'npm-global' | 'standalone' | 'homebrew' | 'unknown';
+
+/**
+ * Place where the harness command really lives together with the way it was installed there.
+ *
+ * Knowing the origin is what keeps an update from installing a **second** copy of a harness which is
+ * managed outside of npm, for example the standalone installation of OpenAI Codex.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOrigin = {
+    /**
+     * Resolved path of the harness command with every symbolic link followed
+     * or `null` when the command could not be located.
+     */
+    readonly commandPath: string | null;
+
+    /**
+     * Way in which the harness command was installed.
+     */
+    readonly installationMethod: HarnessInstallationMethod;
+};
+
+/**
+ * Origin used when the harness command was not looked up at all, for example when the update check is disabled.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const UNKNOWN_HARNESS_INSTALLATION_ORIGIN: HarnessInstallationOrigin = {
+    commandPath: null,
+    installationMethod: 'unknown',
+};
+
+// Note: [🟡] Code for CLI harness installation origin [HarnessInstallationOrigin](src/cli/cli-commands/common/harness/HarnessInstallationOrigin.ts) should never be published outside of `@promptbook/cli`

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

@@ -1,4 +1,5 @@
 import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
 
 /**
  * Result of comparing the globally installed harness version with the newest published one.
@@ -6,11 +7,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 +26,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;
 
@@ -37,6 +39,11 @@ export type HarnessInstallationStatus = {
      * Newest version published to npm or `null` when it could not be resolved.
      */
     readonly latestVersion: string | null;
+
+    /**
+     * Place where the harness command lives together with the way it was installed there.
+     */
+    readonly installationOrigin: HarnessInstallationOrigin;
 };
 
 // Note: [🟡] Code for CLI harness installation status [HarnessInstallationStatus](src/cli/cli-commands/common/harness/HarnessInstallationStatus.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,27 @@
+/**
+ * How an outdated CLI coding harness can be brought up to date where it is really installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdatePlan = {
+    /**
+     * Command which updates the harness in place
+     * or `null` when the installation is not understood well enough to name one.
+     */
+    readonly command: string | null;
+
+    /**
+     * Whether Promptbook may run the command itself instead of only printing it.
+     *
+     * Only installations which Promptbook can update without any side effect are updated automatically,
+     * everything else is left to the user together with the instructions.
+     */
+    readonly isRunnableByPromptbook: boolean;
+
+    /**
+     * Extra environment variables required by the update command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};
+
+// Note: [🟡] Code for CLI harness update plan [HarnessUpdatePlan](src/cli/cli-commands/common/harness/HarnessUpdatePlan.ts) should never be published outside of `@promptbook/cli`

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

@@ -1,15 +1,19 @@
+import { buildNpmPackageInstallCommand } from '../npm/buildNpmPackageInstallCommand';
 import type { HarnessDefinition } from './HarnessDefinition';
 
 /**
  * Builds the shell command which installs or updates one CLI coding harness globally.
  *
- * The very same command is executed by `$installHarness` and printed as the manual fallback,
+ * The very same command is executed by `$runHarnessInstallationCommand` and printed as the manual fallback,
  * so the user always sees exactly what Promptbook would run.
  *
+ * Note: This command installs the harness through npm, so it may only update a harness which npm really owns,
+ * see `resolveHarnessUpdatePlan`.
+ *
  * @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/harness/formatHarnessInstallationWarning.ts

@@ -1,13 +1,24 @@
 import { spaceTrim } from 'spacetrim';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 
+/**
+ * Human-readable description of each way a harness can be installed.
+ */
+const HARNESS_INSTALLATION_METHOD_DESCRIPTIONS: Readonly<Record<HarnessInstallationMethod, string>> = {
+    'npm-global': 'global npm installation',
+    standalone: 'standalone installation',
+    homebrew: 'Homebrew installation',
+    unknown: 'unknown installation method',
+};
+
 /**
  * Formats the warning shown when a harness is missing or outdated.
  *
  * @private internal utility of `promptbookCli`
  */
 export function formatHarnessInstallationWarning(status: HarnessInstallationStatus): string {
-    const { definition, installedVersion, latestVersion } = status;
+    const { definition, installedVersion, latestVersion, installationOrigin } = status;
 
     if (status.installationState === 'not-installed') {
         return spaceTrim(`
@@ -17,12 +28,23 @@ export function formatHarnessInstallationWarning(status: HarnessInstallationStat
         `);
     }
 
-    return spaceTrim(`
-        **${definition.label}** is outdated.
+    const warningLines = [
+        `**${definition.label}** is outdated.`,
+        '',
+        `Installed version: \`${installedVersion}\``,
+        `Newest version: \`${latestVersion}\``,
+    ];
+
+    if (installationOrigin.commandPath !== null) {
+        const installationMethodDescription =
+            HARNESS_INSTALLATION_METHOD_DESCRIPTIONS[installationOrigin.installationMethod];
+
+        warningLines.push(
+            `Installed command: \`${installationOrigin.commandPath}\` *(${installationMethodDescription})*`,
+        );
+    }
 
-        Installed version: \`${installedVersion}\`
-        Newest version: \`${latestVersion}\`
-    `);
+    return spaceTrim(warningLines.join('\n'));
 }
 
 // Note: [🟡] Code for CLI harness installation warning [formatHarnessInstallationWarning](src/cli/cli-commands/common/harness/formatHarnessInstallationWarning.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,41 @@
+import { spaceTrim } from 'spacetrim';
+import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
+import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+
+/**
+ * Formats the instruction shown when an outdated harness must be updated by the user.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function formatHarnessManualUpdateInstruction(
+    status: HarnessInstallationStatus,
+    updatePlan: HarnessUpdatePlan,
+): string {
+    const { definition, installationOrigin } = status;
+
+    const commandLocation =
+        installationOrigin.commandPath === null
+            ? `The \`${definition.commandName}\` command`
+            : `The \`${definition.commandName}\` command at \`${installationOrigin.commandPath}\``;
+
+    if (updatePlan.command !== null) {
+        return spaceTrim(`
+            ${commandLocation} is not managed by npm, so Promptbook leaves it alone.
+
+            Update it manually with \`${updatePlan.command}\`.
+        `);
+    }
+
+    const unknownInstallationReason =
+        installationOrigin.commandPath === null ? 'could not be located' : 'is not inside the global npm prefix';
+    const npmInstallCommand = buildHarnessInstallCommand(definition);
+
+    return spaceTrim(`
+        ${commandLocation} ${unknownInstallationReason}, so Promptbook cannot tell how it was installed.
+
+        Update it the same way it was installed - \`${npmInstallCommand}\` would install a **second** copy of ${definition.label} instead of updating the one which is really used.
+    `);
+}
+
+// Note: [🟡] Code for CLI harness manual update instruction [formatHarnessManualUpdateInstruction](src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.ts) should never be published outside of `@promptbook/cli`