@promptbook/cli 0.114.0-5 → 0.114.0-50

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/HARNESS_DEFAULT_MODELS.ts

@@ -0,0 +1,37 @@
+import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+
+/**
+ * Latest OpenAI flagship used by harnesses which support OpenAI models.
+ */
+const OPENAI_FLAGSHIP_MODEL = 'gpt-6-astra';
+
+/**
+ * Latest Gemini model for coding and long-running agent tasks.
+ */
+const GEMINI_FLAGSHIP_MODEL = 'gemini-3.8-flash';
+
+/**
+ * [🕕] Default models shared by CLI execution, project initialization and the coder landing page.
+ *
+ * Checked against provider documentation on 2026-09-21:
+ * - https://developers.openai.com/codex/models
+ * - https://github.blog/changelog/2026-09-04-gpt-6-astra-is-generally-available-in-github-copilot/
+ * - https://code.claude.com/docs/en/model-config
+ * - https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash
+ * - https://qwenlm.github.io/qwen-code-docs/en/blog/updates/weekly-update-2026-08-27/
+ *
+ * Claude's `fable` alias follows its current flagship. OpenCode needs a provider-qualified model;
+ * the Cline adapter uses Google's provider and therefore needs a Gemini model ID.
+ * Keep this module free of runtime dependencies so the landing page can consume the same defaults.
+ *
+ * @private internal configuration of CLI harness integrations
+ */
+export const HARNESS_DEFAULT_MODELS = {
+    'openai-codex': OPENAI_FLAGSHIP_MODEL,
+    'github-copilot': OPENAI_FLAGSHIP_MODEL,
+    'claude-code': 'fable',
+    gemini: GEMINI_FLAGSHIP_MODEL,
+    'qwen-code': 'qwen3.8-max',
+    opencode: `openai/${OPENAI_FLAGSHIP_MODEL}`,
+    cline: GEMINI_FLAGSHIP_MODEL,
+} as const satisfies Readonly<Record<PromptRunnerHarnessName, string>>;

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

@@ -2,6 +2,52 @@ 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;
+};
+
+/**
+ * Description of how the user signs in to one CLI coding harness again.
+ *
+ * Every harness refuses to work once its login is missing or its session has expired, and each of them is
+ * signed in differently - some have a dedicated login command, others sign in from their own interactive UI.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessAuthenticationMethod = {
+    /**
+     * Command which starts the sign-in flow of the harness.
+     */
+    readonly command: string;
+
+    /**
+     * Step which finishes the sign-in inside the started command.
+     *
+     * Harnesses which sign in from their own interactive user interface leave the user in that interface, so
+     * naming just the command would not be enough to get them signed in. Harnesses with a dedicated login
+     * command leave this undefined.
+     */
+    readonly interactiveStep?: string;
+};
+
 /**
  * Static description of one supported CLI coding harness.
  *
@@ -32,6 +78,23 @@ 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 the user signs in to this harness again after its login is missing or has expired.
+     */
+    readonly authenticationMethod: HarnessAuthenticationMethod;
+
+    /**
+     * 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 +108,21 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         label: 'OpenAI Codex',
         commandName: 'codex',
         npmPackageName: '@openai/codex',
+        projectGitignoreRules: ['.codex'],
+        authenticationMethod: { command: 'codex login' },
+        // 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'],
+        authenticationMethod: { command: 'copilot', interactiveStep: 'running the `/login` command inside it' },
         // Note: The GitHub Copilot CLI downloads its native binary in a postinstall script
         npmInstallEnvironment: { npm_config_ignore_scripts: 'false' },
     },
@@ -59,24 +131,40 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         label: 'Cline',
         commandName: 'cline',
         npmPackageName: 'cline',
+        projectGitignoreRules: ['.cline'],
+        authenticationMethod: { command: 'cline', interactiveStep: 'signing in to the provider inside it' },
     },
     'claude-code': {
         harnessName: 'claude-code',
         label: 'Claude Code',
         commandName: 'claude',
         npmPackageName: '@anthropic-ai/claude-code',
+        projectGitignoreRules: ['.claude'],
+        authenticationMethod: { command: 'claude', interactiveStep: 'running the `/login` command inside it' },
     },
     opencode: {
         harnessName: 'opencode',
         label: 'Opencode',
         commandName: 'opencode',
         npmPackageName: 'opencode-ai',
+        projectGitignoreRules: ['.opencode'],
+        authenticationMethod: { command: 'opencode auth login' },
     },
     gemini: {
         harnessName: 'gemini',
         label: 'Gemini CLI',
         commandName: 'gemini',
         npmPackageName: '@google/gemini-cli',
+        projectGitignoreRules: ['.gemini'],
+        authenticationMethod: { command: 'gemini', interactiveStep: 'running the `/auth` command inside it' },
+    },
+    'qwen-code': {
+        harnessName: 'qwen-code',
+        label: 'Qwen Code',
+        commandName: 'qwen',
+        npmPackageName: '@qwen-code/qwen-code',
+        projectGitignoreRules: ['.qwen'],
+        authenticationMethod: { command: 'qwen', interactiveStep: 'running the `/auth` command inside it' },
     },
 };
 
@@ -100,3 +188,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`

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

@@ -0,0 +1,111 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+
+/**
+ * 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 = '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';
+
+/**
+ * Options describing where the harness command was found.
+ *
+ * @private internal utility of `resolveHarnessInstallationMethodFromPaths`
+ */
+type HarnessInstallationPaths = {
+    /**
+     * Harness whose command was located.
+     */
+    readonly definition: HarnessDefinition;
+
+    /**
+     * Resolved path of the harness command with every symbolic link followed.
+     */
+    readonly commandPath: string;
+
+    /**
+     * Root directory of global npm installations or `null` when npm could not be asked for it.
+     */
+    readonly npmGlobalPrefixPath: string | null;
+};
+
+/**
+ * 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`
+ */
+export function resolveHarnessInstallationMethodFromPaths(paths: HarnessInstallationPaths): HarnessInstallationMethod {
+    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 = definition.standaloneInstallation?.directoryNames ?? [];
+
+    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}/${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: string): string {
+    return path.trim().replace(/\\/gu, '/').replace(/\/+$/u, '').toLowerCase();
+}
+
+/**
+ * Checks whether one path lies inside a directory.
+ */
+function isPathInsideDirectory(normalizedPath: string, directoryPath: string | null): boolean {
+    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`