@promptbook/cli 0.114.0-5 → 0.114.0-50

package/src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.ts

@@ -0,0 +1,37 @@
+import { statfs } from 'fs/promises';
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+import { resolveFreeDiskSpaceLevel } from './resolveFreeDiskSpaceLevel';
+
+/**
+ * Measures the free disk space on the filesystem which hosts the given path.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+ *
+ * @returns the measurement, or `null` when the filesystem can not be measured, for example on a platform which
+ *          does not report filesystem statistics - a run is never stopped by a measurement which could not be taken
+ * @private internal utility of `promptbookCli`
+ */
+export async function $readFreeDiskSpaceStatus(inspectedPath: string): Promise<FreeDiskSpaceStatus | null> {
+    try {
+        const fileSystemStats = await statfs(inspectedPath);
+        const blockSizeBytes = fileSystemStats.bsize;
+        const availableBytes = fileSystemStats.bavail * blockSizeBytes;
+        const totalBytes = fileSystemStats.blocks * blockSizeBytes;
+
+        if (!Number.isFinite(availableBytes) || availableBytes < 0) {
+            return null;
+        }
+
+        return {
+            inspectedPath,
+            availableBytes,
+            totalBytes,
+            level: resolveFreeDiskSpaceLevel(availableBytes),
+        };
+    } catch {
+        // Note: A path or a platform which can not report its free disk space must not stop `ptbk coder` from running
+        return null;
+    }
+}
+
+// Note: [🟡] Code for CLI free disk space handling [$readFreeDiskSpaceStatus](src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/disk-space/FreeDiskSpaceStatus.ts

@@ -0,0 +1,39 @@
+/**
+ * How much free disk space is left, measured against the `ptbk coder` free disk space limits.
+ *
+ * - `sufficient` - there is enough free disk space to start a run and to keep it running
+ * - `low` - there is not enough free disk space to start a new run
+ * - `critical` - there is not enough free disk space to keep a started run going
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceLevel = 'sufficient' | 'low' | 'critical';
+
+/**
+ * One measurement of the free disk space on the filesystem which hosts the inspected path.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type FreeDiskSpaceStatus = {
+    /**
+     * Path whose filesystem was measured.
+     */
+    readonly inspectedPath: string;
+
+    /**
+     * Bytes which are still available to the current user on that filesystem.
+     */
+    readonly availableBytes: number;
+
+    /**
+     * Total size of that filesystem in bytes.
+     */
+    readonly totalBytes: number;
+
+    /**
+     * Severity of the measured free disk space.
+     */
+    readonly level: FreeDiskSpaceLevel;
+};
+
+// Note: [🟡] Code for CLI free disk space handling [FreeDiskSpaceStatus](src/cli/cli-commands/common/disk-space/FreeDiskSpaceStatus.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.ts

@@ -0,0 +1,26 @@
+/**
+ * Byte units used when one amount of disk space is written for a human.
+ */
+const FREE_DISK_SPACE_BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'] as const;
+
+/**
+ * Writes one byte count as a compact human-readable amount of disk space, for example `812 MB` or `1.5 GB`.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function formatFreeDiskSpaceBytes(bytes: number): string {
+    if (!Number.isFinite(bytes) || bytes <= 0) {
+        return '0 B';
+    }
+
+    const unitIndex = Math.min(FREE_DISK_SPACE_BYTE_UNITS.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / Math.pow(1024, unitIndex);
+    // Note: One decimal place only matters for small values, `476 GB` is more readable than `476.3 GB`
+    const decimalPlaceCount = value >= 10 || unitIndex === 0 ? 0 : 1;
+    // Note: An empty decimal place only adds noise, `2 GB` is more readable than `2.0 GB`
+    const displayedValue = value.toFixed(decimalPlaceCount).replace(/\.0$/, '');
+
+    return `${displayedValue} ${FREE_DISK_SPACE_BYTE_UNITS[unitIndex]}`;
+}
+
+// Note: [🟡] Code for CLI free disk space handling [formatFreeDiskSpaceBytes](src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.ts

@@ -0,0 +1,33 @@
+import { spaceTrim } from 'spacetrim';
+import type { FreeDiskSpaceStatus } from './FreeDiskSpaceStatus';
+import { formatFreeDiskSpaceBytes } from './formatFreeDiskSpaceBytes';
+import { CRITICALLY_LOW_FREE_DISK_SPACE_BYTES, LOW_FREE_DISK_SPACE_BYTES } from './freeDiskSpaceConstants';
+
+/**
+ * Writes the shared warning which explains one low free disk space measurement and how to get out of it.
+ *
+ * The very same wording is used by the check which refuses to start a run and by the check which pauses
+ * a run that ran out of disk space while it was working.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus: FreeDiskSpaceStatus): string {
+    const { inspectedPath } = freeDiskSpaceStatus;
+    const availableSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.availableBytes);
+    const totalSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.totalBytes);
+    const requiredSpaceToStart = formatFreeDiskSpaceBytes(LOW_FREE_DISK_SPACE_BYTES);
+    const requiredSpaceToContinue = formatFreeDiskSpaceBytes(CRITICALLY_LOW_FREE_DISK_SPACE_BYTES);
+
+    return spaceTrim(`
+        Only **${availableSpace}** of ${totalSpace} is left on the disk which hosts \`${inspectedPath}\`.
+
+        **\`ptbk coder\` needs at least ${requiredSpaceToStart} of free disk space to start a run and at least ${requiredSpaceToContinue} to keep one running.**
+
+        Actionable hints:
+        - Free up disk space on the drive which hosts \`${inspectedPath}\`.
+        - Remove build artifacts, package caches and \`node_modules\` folders of projects you are not working on.
+        - Remove the temporary worktrees which earlier \`--isolate\` runs left behind.
+    `);
+}
+
+// Note: [🟡] Code for CLI free disk space handling [formatLowFreeDiskSpaceWarning](src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.ts

@@ -0,0 +1,33 @@
+/**
+ * Free disk space below which `ptbk coder` refuses to start a new run.
+ *
+ * A coding round writes prompt and log artifacts, lets the harness rewrite the project, may install npm packages,
+ * may create a git worktree for `--isolate` and usually runs a build, so a run started with less than this
+ * would very likely die somewhere in the middle with a filesystem error.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const LOW_FREE_DISK_SPACE_BYTES = 2 * 1024 * 1024 * 1024;
+
+/**
+ * Free disk space below which a started `ptbk coder` run stops at its next checkpoint and waits until space is freed.
+ *
+ * This limit is lower than `LOW_FREE_DISK_SPACE_BYTES`, because interrupting a run which is already in progress
+ * is more expensive than not starting one at all.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const CRITICALLY_LOW_FREE_DISK_SPACE_BYTES = 1 * 1024 * 1024 * 1024;
+
+/**
+ * How long one free disk space measurement is reused before the filesystem is measured again during a run.
+ *
+ * Pause checkpoints are passed very often - for example on every tick of a timed wait - so without this
+ * interval the filesystem would be measured many times per second.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const FREE_DISK_SPACE_RECHECK_INTERVAL_MS = 60 * 1000;
+
+// Note: [🟡] Code for CLI free disk space handling [freeDiskSpaceConstants](src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.ts

@@ -0,0 +1,21 @@
+import type { FreeDiskSpaceLevel } from './FreeDiskSpaceStatus';
+import { CRITICALLY_LOW_FREE_DISK_SPACE_BYTES, LOW_FREE_DISK_SPACE_BYTES } from './freeDiskSpaceConstants';
+
+/**
+ * Classifies one measured amount of free disk space against the `ptbk coder` free disk space limits.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function resolveFreeDiskSpaceLevel(availableBytes: number): FreeDiskSpaceLevel {
+    if (availableBytes < CRITICALLY_LOW_FREE_DISK_SPACE_BYTES) {
+        return 'critical';
+    }
+
+    if (availableBytes < LOW_FREE_DISK_SPACE_BYTES) {
+        return 'low';
+    }
+
+    return 'sufficient';
+}
+
+// Note: [🟡] Code for CLI free disk space handling [resolveFreeDiskSpaceLevel](src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,40 @@
+import { constants } from 'fs';
+import { copyFile, mkdir, stat } from 'fs/promises';
+import { dirname, join } from 'path';
+import { resolveBundledAgentBookPath } from './resolveBundledAgentBookPath';
+
+/**
+ * Adam's location relative to a directory of local agents.
+ *
+ * @private internal constant of CLI agent initialization
+ */
+export const ADAM_AGENT_BOOK_RELATIVE_PATH = '.core/adam.book';
+
+/**
+ * Creates the same Adam book used by the Agent Server without overwriting a project-owned book.
+ *
+ * @private internal utility of CLI agent initialization
+ */
+export async function ensureAdamAgentBook(agentDirectoryPath: string): Promise<'created' | 'unchanged'> {
+    const adamBookPath = join(agentDirectoryPath, ADAM_AGENT_BOOK_RELATIVE_PATH);
+    if (
+        await stat(adamBookPath).then(
+            (entry) => entry.isFile(),
+            () => false,
+        )
+    ) {
+        return 'unchanged';
+    }
+
+    const bundledAdamBookPath = await resolveBundledAgentBookPath('agents/default/.core/adam.book');
+    await mkdir(dirname(adamBookPath), { recursive: true });
+    try {
+        await copyFile(bundledAdamBookPath, adamBookPath, constants.COPYFILE_EXCL);
+        return 'created';
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+            return 'unchanged';
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,35 @@
+import { stat, writeFile } from 'fs/promises';
+import { join } from 'path';
+import type { ProjectInitializationStatus } from './projectInitialization';
+
+/**
+ * Creates one project text file with default content, preserving any existing file.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export async function ensureProjectTextFile(
+    projectPath: string,
+    relativeFilePath: string,
+    fileContent: string,
+): Promise<ProjectInitializationStatus> {
+    const absoluteFilePath = join(projectPath, relativeFilePath);
+    if (await isExistingFile(absoluteFilePath)) {
+        return 'unchanged';
+    }
+
+    await writeFile(absoluteFilePath, `${fileContent}\n`, 'utf-8');
+    return 'created';
+}
+
+/**
+ * Checks whether a path exists and is a file.
+ */
+async function isExistingFile(path: string): Promise<boolean> {
+    try {
+        return (await stat(path)).isFile();
+    } catch {
+        return false;
+    }
+}
+
+// Note: [🟡] Code for project text file bootstrapping [ensureProjectTextFile](src/cli/cli-commands/common/ensureProjectTextFile.ts) should never be published outside of `@promptbook/cli`

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

@@ -1,25 +1,39 @@
 import colors from 'colors';
-import { $askForHarnessInstallationApproval } from './$askForHarnessInstallationApproval';
-import { $installHarness } from './$installHarness';
+import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
+import { $runHarnessInstallationCommand } from './$runHarnessInstallationCommand';
 import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
+import type { HarnessDefinition } from './HarnessDefinition';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 import { formatHarnessInstallationWarning } from './formatHarnessInstallationWarning';
+import { formatHarnessManualUpdateInstruction } from './formatHarnessManualUpdateInstruction';
+import { resolveHarnessUpdatePlan } from './resolveHarnessUpdatePlan';
 
 /**
  * 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`
  */
-export async function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void> {
-    const { definition, installationState, installedVersion, latestVersion } = status;
+export async function $applyHarnessInstallationStatus(
+    status: HarnessInstallationStatus,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
+    const { definition, installationState, installedVersion } = status;
 
     if (installationState === 'up-to-date') {
         console.info(colors.gray(`✔ ${definition.label} ${installedVersion} is up to date.`));
         return;
     }
 
+    if (installationState === 'installed') {
+        console.info(
+            colors.gray(`✔ ${definition.label} ${installedVersion} is installed. Skipped checking for updates.`),
+        );
+        return;
+    }
+
     if (installationState === 'unknown') {
         console.info(
             colors.gray(
@@ -31,18 +45,72 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
 
     console.warn(colors.yellow(formatHarnessInstallationWarning(status)));
 
-    const isInstallationApproved = await $askForHarnessInstallationApproval(
-        installationState === 'not-installed'
-            ? `Install ${definition.label} globally now?`
-            : `Update ${definition.label} to ${latestVersion} now?`,
+    if (installationState === 'not-installed') {
+        await $applyMissingHarnessInstallation(definition, questionsOptions);
+        return;
+    }
+
+    await $applyOutdatedHarnessInstallation(status, questionsOptions);
+}
+
+/**
+ * Offers to install a missing harness globally through npm.
+ */
+async function $applyMissingHarnessInstallation(
+    definition: HarnessDefinition,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
+    const installCommand = buildHarnessInstallCommand(definition);
+
+    const isInstallationApproved = await $askForNpmPackageInstallationApproval(
+        `Install ${definition.label} globally now?`,
+        questionsOptions,
     );
 
     if (!isInstallationApproved) {
-        console.info(colors.gray(`Skipped, run \`${buildHarnessInstallCommand(definition)}\` to do it manually.`));
+        console.info(colors.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: HarnessInstallationStatus,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<void> {
+    const { definition, latestVersion, installationOrigin } = status;
+    const updatePlan = resolveHarnessUpdatePlan(definition, installationOrigin.installationMethod);
+
+    if (updatePlan.command === null || !updatePlan.isRunnableByPromptbook) {
+        console.info(colors.gray(formatHarnessManualUpdateInstruction(status, updatePlan)));
+        return;
+    }
+
+    const isUpdateApproved = await $askForNpmPackageInstallationApproval(
+        `Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`,
+        questionsOptions,
+    );
+
+    if (!isUpdateApproved) {
+        console.info(colors.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`

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

@@ -1,12 +1,15 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 import { $applyHarnessInstallationStatus } from './$applyHarnessInstallationStatus';
 import { $checkHarnessInstallation } from './$checkHarnessInstallation';
 import type { HarnessDefinition } from './HarnessDefinition';
 import { getHarnessDefinition } from './HarnessDefinition';
+import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
+import { NotAllowed } from '../../../../errors/NotAllowed';
 
 /**
- * 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 the questions are 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 +20,8 @@ import { getHarnessDefinition } from './HarnessDefinition';
  */
 export async function $ensureHarnessInstallations(
     harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>,
+    questionsOptions: NormalizedQuestionsCliOptions,
+    options: { readonly isRequired?: boolean } = {},
 ): Promise<void> {
     const definitions = resolveCheckedHarnessDefinitions(harnessNames);
 
@@ -24,11 +29,27 @@ export async function $ensureHarnessInstallations(
         return;
     }
 
+    // Note: An outdated harness can be updated only after the user confirms it, so `--no-questions`
+    //       skips the slower npm registry lookup entirely and only reports what is installed.
+    const isHarnessUpdateCheckEnabled = questionsOptions.isAskingQuestionsEnabled;
+
     // 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);
+        await $applyHarnessInstallationStatus(status, questionsOptions);
+        if (options.isRequired && status.installationState === 'not-installed') {
+            const rechecked = await $checkHarnessInstallation(status.definition, false);
+            if (rechecked.installationState === 'not-installed') {
+                throw new NotAllowed(
+                    `Repair requires ${status.definition.label}. Install it with \`${buildHarnessInstallCommand(
+                        status.definition,
+                    )}\`, then retry. No other task was executed.`,
+                );
+            }
+        }
     }
 }
 

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`