@promptbook/cli 0.114.0-25 → 0.114.0-27

package/umd/index.umd.js

@@ -58,7 +58,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-25';
+    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-27';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3713,7 +3713,7 @@
      *
      * @private internal constant of `buildAgentsServer`
      */
-    const NODE_MODULES_DIRECTORY_NAME$1 = 'node_modules';
+    const NODE_MODULES_DIRECTORY_NAME$2 = 'node_modules';
 
     /**
      * Returns true when one path is nested below a `node_modules` segment.
@@ -3721,7 +3721,7 @@
      * @private internal utility of `buildAgentsServer`
      */
     function isPathInsideNodeModules(path) {
-        return path.split(/[\\/]+/u).includes(NODE_MODULES_DIRECTORY_NAME$1);
+        return path.split(/[\\/]+/u).includes(NODE_MODULES_DIRECTORY_NAME$2);
     }
 
     /**
@@ -3834,7 +3834,7 @@
      * Links the materialized runtime back to the package dependency tree used by the installed CLI.
      */
     async function ensureMaterializedRuntimeNodeModulesLink(options) {
-        const nodeModulesLinkPath = path.join(options.materializedRuntimeRootPath, NODE_MODULES_DIRECTORY_NAME$1);
+        const nodeModulesLinkPath = path.join(options.materializedRuntimeRootPath, NODE_MODULES_DIRECTORY_NAME$2);
         try {
             const existingLinkStats = await promises.lstat(nodeModulesLinkPath);
             await promises.rm(nodeModulesLinkPath, {
@@ -3920,7 +3920,7 @@
      */
     function resolveNodeModulesPath(nextCliPath) {
         const normalizedNextCliPath = nextCliPath.replace(/\\/gu, '/');
-        const marker = `/${NODE_MODULES_DIRECTORY_NAME$1}/next/`;
+        const marker = `/${NODE_MODULES_DIRECTORY_NAME$2}/next/`;
         const markerIndex = normalizedNextCliPath.lastIndexOf(marker);
         if (markerIndex === -1) {
             return path.resolve(nextCliPath, '..', '..', '..');
@@ -20073,29 +20073,36 @@
     /**
      * `WRITING RULES` commitment definition.
      *
-     * It adds constraints that apply strictly to writing style and presentation
-     * rather than task-solving behavior.
+     * The `WRITING RULES`/`WRITING RULE` commitment adds constraints that apply strictly to writing style
+     * and presentation rather than task-solving behavior.
+     *
+     * Example usage in agent source:
+     *
+     * ```book
+     * WRITING RULES Keep every response under 120 words
+     * WRITING RULE Always end the message with an emoji
+     * ```
      *
      * @private [🪔] Maybe export the commitments through some package
      */
     class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition {
-        constructor() {
-            super('WRITING RULES');
+        constructor(type = 'WRITING RULES') {
+            super(type);
         }
         /**
-         * Short one-line description of `WRITING RULES`.
+         * Short one-line description of `WRITING RULES`/`WRITING RULE`.
          */
         get description() {
             return 'Add writing-only constraints such as tone, length, formatting, or emoji usage.';
         }
         /**
-         * Icon for `WRITING RULES`.
+         * Icon for `WRITING RULES`/`WRITING RULE`.
          */
         get icon() {
             return '📝';
         }
         /**
-         * Markdown documentation for `WRITING RULES`.
+         * Markdown documentation for `WRITING RULES`/`WRITING RULE` commitment.
          */
         get documentation() {
             return _spaceTrim.spaceTrim(`
@@ -20105,6 +20112,7 @@
 
             ## Key aspects
 
+            - All writing rules are treated equally regardless of singular/plural form.
             - Use it for writing-only constraints such as tone, formatting, length, emoji usage, punctuation, or reading level.
             - Do **not** use it for problem-solving behavior, policy, tool usage, or decision-making logic. Use \`RULE\` for that.
             - Newer writing-rules blocks override conflicting earlier writing-rules blocks.
@@ -20303,7 +20311,8 @@
         new LanguageCommitmentDefinition('LANGUAGE'),
         new LanguageCommitmentDefinition('LANGUAGES'),
         new WritingSampleCommitmentDefinition(),
-        new WritingRulesCommitmentDefinition(),
+        new WritingRulesCommitmentDefinition('WRITING RULES'),
+        new WritingRulesCommitmentDefinition('WRITING RULE'),
         new SampleCommitmentDefinition('SAMPLE'),
         new SampleCommitmentDefinition('EXAMPLE'),
         new FormatCommitmentDefinition('FORMAT'),
@@ -24119,6 +24128,11 @@
             label: 'OpenAI Codex',
             commandName: 'codex',
             npmPackageName: '@openai/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',
@@ -43089,6 +43103,53 @@
     }
     // 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`
 
+    /**
+     * Words describing each operation in the terminal output.
+     */
+    const HARNESS_INSTALLATION_OPERATION_WORDS = {
+        install: { running: 'Installing', finished: 'installed' },
+        update: { running: 'Updating', finished: 'updated' },
+    };
+    /**
+     * 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`
+     */
+    async function $runHarnessInstallationCommand(options) {
+        const { definition, operation, command, environment } = options;
+        const operationWords = HARNESS_INSTALLATION_OPERATION_WORDS[operation];
+        console.info(colors__default["default"].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__default["default"].red(_spaceTrim.spaceTrim((block) => `
+                        Could not ${operation} **${definition.label}**.
+
+                        Run \`${command}\` manually and run the command again.
+
+                        ${block(installErrorMessage)}
+                    `)));
+            return false;
+        }
+        console.info(colors__default["default"].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`
+
     /**
      * Builds an npm command which installs or updates a package in the requested existing location.
      *
@@ -43108,9 +43169,12 @@
     /**
      * 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`
      */
     function buildHarnessInstallCommand(definition) {
@@ -43119,76 +43183,114 @@
     // Note: [🟡] Code for CLI harness install command [buildHarnessInstallCommand](src/cli/cli-commands/common/harness/buildHarnessInstallCommand.ts) should never be published outside of `@promptbook/cli`
 
     /**
-     * Installs or updates one CLI coding harness globally through npm.
-     *
-     * 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 a global npm package
+     * Human-readable description of each way a harness can be installed.
+     */
+    const HARNESS_INSTALLATION_METHOD_DESCRIPTIONS = {
+        '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.
      *
-     * @returns `true` when the harness has been installed, `false` when the installation failed
      * @private internal utility of `promptbookCli`
      */
-    async function $installHarness(definition) {
-        const installCommand = buildHarnessInstallCommand(definition);
-        console.info(colors__default["default"].cyan(`Installing ${definition.label} with \`${installCommand}\`...`));
-        try {
-            await $execCommand({
-                command: installCommand,
-                crashOnError: true,
-                isVerbose: true,
-                env: definition.npmInstallEnvironment ? { ...definition.npmInstallEnvironment } : undefined,
-            });
-        }
-        catch (error) {
-            assertsError(error);
-            const installErrorMessage = error.message;
-            console.error(colors__default["default"].red(_spaceTrim.spaceTrim((block) => `
-                        Could not install **${definition.label}**.
-
-                        Install it manually with \`${installCommand}\` and run the command again.
+    function formatHarnessInstallationWarning(status) {
+        const { definition, installedVersion, latestVersion, installationOrigin } = status;
+        if (status.installationState === 'not-installed') {
+            return _spaceTrim.spaceTrim(`
+            **${definition.label}** is not installed globally.
 
-                        ${block(installErrorMessage)}
-                    `)));
-            return false;
+            The \`${definition.commandName}\` command was not found, so the \`${definition.harnessName}\` harness cannot run.
+        `);
         }
-        console.info(colors__default["default"].green(`${definition.label} has been installed.`));
-        return true;
+        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})*`);
+        }
+        return _spaceTrim.spaceTrim(warningLines.join('\n'));
     }
-    // Note: [🟡] Code for CLI harness installation [$installHarness](src/cli/cli-commands/common/harness/$installHarness.ts) should never be published outside of `@promptbook/cli`
+    // Note: [🟡] Code for CLI harness installation warning [formatHarnessInstallationWarning](src/cli/cli-commands/common/harness/formatHarnessInstallationWarning.ts) should never be published outside of `@promptbook/cli`
 
     /**
-     * Formats the warning shown when a harness is missing or outdated.
+     * Formats the instruction shown when an outdated harness must be updated by the user.
      *
      * @private internal utility of `promptbookCli`
      */
-    function formatHarnessInstallationWarning(status) {
-        const { definition, installedVersion, latestVersion } = status;
-        if (status.installationState === 'not-installed') {
+    function formatHarnessManualUpdateInstruction(status, updatePlan) {
+        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.spaceTrim(`
-            **${definition.label}** is not installed globally.
+            ${commandLocation} is not managed by npm, so Promptbook leaves it alone.
 
-            The \`${definition.commandName}\` command was not found, so the \`${definition.harnessName}\` harness cannot run.
+            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.spaceTrim(`
-        **${definition.label}** is outdated.
+        ${commandLocation} ${unknownInstallationReason}, so Promptbook cannot tell how it was installed.
 
-        Installed version: \`${installedVersion}\`
-        Newest version: \`${latestVersion}\`
+        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 installation warning [formatHarnessInstallationWarning](src/cli/cli-commands/common/harness/formatHarnessInstallationWarning.ts) should never be published outside of `@promptbook/cli`
+    // 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`
+
+    /**
+     * Decides how one outdated CLI coding harness should be updated.
+     *
+     * The plan follows the way the harness was installed, because `npm install -g` updates only a harness
+     * which npm owns and installs a **second** copy of every other one.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function resolveHarnessUpdatePlan(definition, installationMethod) {
+        if (installationMethod === 'npm-global') {
+            return {
+                command: buildHarnessInstallCommand(definition),
+                isRunnableByPromptbook: true,
+                environment: definition.npmInstallEnvironment,
+            };
+        }
+        if (installationMethod === 'standalone' && definition.standaloneInstallation !== undefined) {
+            return {
+                command: definition.standaloneInstallation.updateCommand,
+                isRunnableByPromptbook: true,
+            };
+        }
+        if (installationMethod === 'homebrew') {
+            // Note: The formula may be named differently than the command, so the update is only suggested
+            return {
+                command: `brew upgrade ${definition.commandName}`,
+                isRunnableByPromptbook: false,
+            };
+        }
+        return {
+            command: null,
+            isRunnableByPromptbook: false,
+        };
+    }
+    // Note: [🟡] Code for CLI harness update planning [resolveHarnessUpdatePlan](src/cli/cli-commands/common/harness/resolveHarnessUpdatePlan.ts) should never be published outside of `@promptbook/cli`
 
     /**
      * Reports one detected harness installation status and offers to install or update the harness.
      *
-     * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs npm packages
+     * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs software
      *
      * @private internal utility of `promptbookCli`
      */
     async function $applyHarnessInstallationStatus(status) {
-        const { definition, installationState, installedVersion, latestVersion } = status;
+        const { definition, installationState, installedVersion } = status;
         if (installationState === 'up-to-date') {
             console.info(colors__default["default"].gray(`✔ ${definition.label} ${installedVersion} is up to date.`));
             return;
@@ -43202,14 +43304,50 @@
             return;
         }
         console.warn(colors__default["default"].yellow(formatHarnessInstallationWarning(status)));
-        const isInstallationApproved = await $askForNpmPackageInstallationApproval(installationState === 'not-installed'
-            ? `Install ${definition.label} globally now?`
-            : `Update ${definition.label} to ${latestVersion} now?`);
+        if (installationState === 'not-installed') {
+            await $applyMissingHarnessInstallation(definition);
+            return;
+        }
+        await $applyOutdatedHarnessInstallation(status);
+    }
+    /**
+     * Offers to install a missing harness globally through npm.
+     */
+    async function $applyMissingHarnessInstallation(definition) {
+        const installCommand = buildHarnessInstallCommand(definition);
+        const isInstallationApproved = await $askForNpmPackageInstallationApproval(`Install ${definition.label} globally now?`);
         if (!isInstallationApproved) {
-            console.info(colors__default["default"].gray(`Skipped, run \`${buildHarnessInstallCommand(definition)}\` to do it manually.`));
+            console.info(colors__default["default"].gray(`Skipped, run \`${installCommand}\` to do it manually.`));
+            return;
+        }
+        await $runHarnessInstallationCommand({
+            definition,
+            operation: 'install',
+            command: installCommand,
+            environment: definition.npmInstallEnvironment,
+        });
+    }
+    /**
+     * Offers to update an outdated harness exactly where it is installed.
+     */
+    async function $applyOutdatedHarnessInstallation(status) {
+        const { definition, latestVersion, installationOrigin } = status;
+        const updatePlan = resolveHarnessUpdatePlan(definition, installationOrigin.installationMethod);
+        if (updatePlan.command === null || !updatePlan.isRunnableByPromptbook) {
+            console.info(colors__default["default"].gray(formatHarnessManualUpdateInstruction(status, updatePlan)));
+            return;
+        }
+        const isUpdateApproved = await $askForNpmPackageInstallationApproval(`Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`);
+        if (!isUpdateApproved) {
+            console.info(colors__default["default"].gray(`Skipped, run \`${updatePlan.command}\` to do it manually.`));
             return;
         }
-        await $installHarness(definition);
+        await $runHarnessInstallationCommand({
+            definition,
+            operation: 'update',
+            command: updatePlan.command,
+            environment: updatePlan.environment,
+        });
     }
     // Note: [🟡] Code for CLI harness installation handling [$applyHarnessInstallationStatus](src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.ts) should never be published outside of `@promptbook/cli`
 
@@ -43409,6 +43547,186 @@
     }
     // 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`
 
+    /**
+     * 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 = 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`
+     */
+    function $resolveNpmGlobalPrefixPath() {
+        if (npmGlobalPrefixPathPromise === null) {
+            npmGlobalPrefixPathPromise = $readNpmGlobalPrefixPath();
+        }
+        return npmGlobalPrefixPathPromise;
+    }
+    /**
+     * Asks npm for the global prefix once.
+     */
+    async function $readNpmGlobalPrefixPath() {
+        const output = 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 && prefixPath !== void 0 ? 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`
+
+    /**
+     * 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`
+     */
+    async function $resolveHarnessCommandPath(definition) {
+        const lookupCommand = process.platform === 'win32' ? `where ${definition.commandName}` : `command -v ${definition.commandName}`;
+        const output = 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 promises.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`
+
+    /**
+     * 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`
+     */
+    const UNKNOWN_HARNESS_INSTALLATION_ORIGIN = {
+        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`
+
+    /**
+     * Directory which holds npm packages, so it appears in the resolved path of every globally installed npm binary
+     * on systems where the global binary is only a symbolic link into the package.
+     *
+     * Note: Written in lower case because it is compared against normalized paths.
+     */
+    const NODE_MODULES_DIRECTORY_NAME$1 = 'node_modules';
+    /**
+     * Directory into which Homebrew unpacks every formula, so it appears in the resolved path of
+     * everything Homebrew manages and in nothing else.
+     *
+     * Note: Written in lower case because it is compared against normalized paths.
+     */
+    const HOMEBREW_DIRECTORY_NAME = 'cellar';
+    /**
+     * Decides how a harness command was installed from the place where it really lives.
+     *
+     * Only a command which npm owns may be updated with `npm install -g`, every other command has to be
+     * updated where it is installed, otherwise the update silently adds a second copy of the harness.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function resolveHarnessInstallationMethodFromPaths(paths) {
+        var _a, _b;
+        const { definition, commandPath, npmGlobalPrefixPath } = paths;
+        const normalizedCommandPath = normalizeInstallationPath(commandPath);
+        const commandPathDirectoryNames = normalizedCommandPath.split('/');
+        // Note: A Homebrew formula may bundle its own `node_modules` and may live under the npm prefix of a
+        //       Homebrew-installed Node, so Homebrew has to be recognized before anything npm-shaped
+        if (commandPathDirectoryNames.includes(HOMEBREW_DIRECTORY_NAME)) {
+            return 'homebrew';
+        }
+        const standaloneDirectoryNames = (_b = (_a = definition.standaloneInstallation) === null || _a === void 0 ? void 0 : _a.directoryNames) !== null && _b !== void 0 ? _b : [];
+        if (standaloneDirectoryNames.some((directoryName) => commandPathDirectoryNames.includes(normalizeInstallationPath(directoryName)))) {
+            return 'standalone';
+        }
+        // Note: npm is not always reachable, but its own package directory is a reliable fallback marker
+        if (normalizedCommandPath.includes(`/${NODE_MODULES_DIRECTORY_NAME$1}/${normalizeInstallationPath(definition.npmPackageName)}/`)) {
+            return 'npm-global';
+        }
+        if (isPathInsideDirectory(normalizedCommandPath, npmGlobalPrefixPath)) {
+            return 'npm-global';
+        }
+        return 'unknown';
+    }
+    /**
+     * Normalizes one path so that paths coming from different tools and platforms can be compared.
+     *
+     * Note: The comparison is case-insensitive because Windows paths are, and two harness paths which differ
+     * only in letter casing do not exist in practice.
+     */
+    function normalizeInstallationPath(path) {
+        return path.trim().replace(/\\/gu, '/').replace(/\/+$/u, '').toLowerCase();
+    }
+    /**
+     * Checks whether one path lies inside a directory.
+     */
+    function isPathInsideDirectory(normalizedPath, directoryPath) {
+        if (directoryPath === null) {
+            return false;
+        }
+        const normalizedDirectoryPath = normalizeInstallationPath(directoryPath);
+        return normalizedDirectoryPath !== '' && normalizedPath.startsWith(`${normalizedDirectoryPath}/`);
+    }
+    // Note: [🟡] Code for CLI harness installation method detection [resolveHarnessInstallationMethodFromPaths](src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * 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`
+     */
+    async function $resolveHarnessInstallationOrigin(definition) {
+        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`
+
     /**
      * Detects whether one CLI coding harness is installed globally and, when enabled, whether it is up to date.
      *
@@ -43417,17 +43735,22 @@
      * @private internal utility of `promptbookCli`
      */
     async function $checkHarnessInstallation(definition, isHarnessUpdateCheckEnabled = true) {
-        const [installedVersion, latestVersion] = await Promise.all([
+        // 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),
             isHarnessUpdateCheckEnabled
                 ? $resolveLatestNpmPackageVersion(definition.npmPackageName)
                 : Promise.resolve(null),
+            isHarnessUpdateCheckEnabled
+                ? $resolveHarnessInstallationOrigin(definition)
+                : Promise.resolve(UNKNOWN_HARNESS_INSTALLATION_ORIGIN),
         ]);
         return {
             definition,
             installationState: resolveHarnessInstallationState(installedVersion, latestVersion, isHarnessUpdateCheckEnabled),
             installedVersion,
             latestVersion,
+            installationOrigin,
         };
     }
     /**
@@ -43486,7 +43809,7 @@
      * @private internal utility of `promptbookCli`
      */
     function addHarnessUpdateOption(command) {
-        command.option('--no-harness-update', 'Skip checking whether globally installed coding harnesses are up to date');
+        command.option('--no-harness-update', 'Skip checking whether the installed coding harnesses are up to date');
     }
     /**
      * Converts the Commander harness-update flag into the normalized harness-check option.
@@ -44063,7 +44386,7 @@
                 - CODING_AGENT_GIT_EMAIL
                 - CODING_AGENT_GIT_SIGNING_KEY
 
-                Checks that the coding harnesses are installed globally and up to date unless \`--no-harness-update\` is used:
+                Checks that the coding harnesses are installed and up to date unless \`--no-harness-update\` is used:
                 ${block(listCheckedHarnessLabels())}
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
@@ -44171,7 +44494,7 @@
             - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
             - Optional --period keeps the quota window refreshing by pinging once per period until stopped
             - Leaves the project exactly as it was — nothing is read, written, changed or committed
-            - Checks that the selected harness is installed globally and up to date unless --no-harness-update is used
+            - Checks that the selected harness is installed and up to date unless --no-harness-update is used
             - Use --no-ui to stream the raw harness output instead of only the compact result
         `));
         addPromptRunnerSelectionOptions(command);
@@ -44665,7 +44988,7 @@
             - Optional --isolate runs every prompt in its own temporary git worktree and merges it back when verified
             - Optional --preserve-logs keeps temp prompt/log artifacts after successful rounds
             - Optional --no-ui keeps plain streaming console output for logging and debugging
-            - Checks that the selected harness is installed globally and up to date before the first prompt unless --no-harness-update is used
+            - Checks that the selected harness is installed and up to date before the first prompt unless --no-harness-update is used
             - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
             - Optional pre-coding test run that can stop or repair pre-existing failures
@@ -44822,7 +45145,7 @@
 
             Features:
             - Runs the same prompt processing as \`ptbk coder run\`
-            - Checks that the selected harness is installed globally and up to date on startup unless --no-harness-update is used
+            - Checks that the selected harness is installed and up to date on startup unless --no-harness-update is used
             - Does not exit when all prompts are done; polls for new prompt files instead
             - Serves a kanban board at http://localhost:<port> for visual progress tracking
             - Allows editing prompt files directly from the browser (Trello-style)