@promptbook/cli 0.114.0-26 → 0.114.0-28

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,13 @@ export type HarnessDefinition = {
      * Extra environment variables required by the global npm installation of this harness.
      */
     readonly npmInstallEnvironment?: Readonly<Record<string, 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,6 +74,11 @@ export const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, Harne
         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',

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.
@@ -38,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

@@ -4,9 +4,12 @@ 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 {

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`

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

@@ -0,0 +1,47 @@
+import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+
+/**
+ * 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`
+ */
+export function resolveHarnessUpdatePlan(
+    definition: HarnessDefinition,
+    installationMethod: HarnessInstallationMethod,
+): HarnessUpdatePlan {
+    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`

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

@@ -26,7 +26,7 @@ export type NormalizedHarnessUpdateCliOptions = {
  * @private internal utility of `promptbookCli`
  */
 export function addHarnessUpdateOption(command: Program): void {
-    command.option('--no-harness-update', 'Skip checking whether globally installed coding harnesses are up to date');
+    command.option('--no-harness-update', 'Skip checking whether the installed coding harnesses are up to date');
 }
 
 /**

package/src/cli/cli-commands/common/npm/$resolveNpmGlobalPrefixPath.ts

@@ -0,0 +1,51 @@
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+
+/**
+ * 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: Promise<string | null> | null = 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`
+ */
+export function $resolveNpmGlobalPrefixPath(): Promise<string | null> {
+    if (npmGlobalPrefixPathPromise === null) {
+        npmGlobalPrefixPathPromise = $readNpmGlobalPrefixPath();
+    }
+
+    return npmGlobalPrefixPathPromise;
+}
+
+/**
+ * Asks npm for the global prefix once.
+ */
+async function $readNpmGlobalPrefixPath(): Promise<string | null> {
+    const output: string = 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;
+}
+
+// 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`