@promptbook/cli 0.114.0-5 → 0.114.0-7

package/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.ts

@@ -0,0 +1,94 @@
+import colors from 'colors';
+import { spaceTrim } from 'spacetrim';
+import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+import { $checkPromptbookCliInstallations } from './$checkPromptbookCliInstallations';
+import { $updatePromptbookCliInstallation } from './$updatePromptbookCliInstallation';
+import { buildPromptbookCliInstallCommand } from './buildPromptbookCliInstallCommand';
+import { formatPromptbookCliInstallationWarning } from './formatPromptbookCliInstallationWarning';
+
+/**
+ * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
+ *
+ * Once an update is approved, the caller must stop the current run and let the user start a fresh process. A local
+ * npm update can modify `package.json` and a lockfile, which would make the coder's working-tree preflight fail;
+ * more importantly, this Node.js process has already loaded the old CLI implementation.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests, queries npm,
+ * asks the user, and may install npm packages
+ *
+ * @returns `true` when an update was approved and the current coder run should stop
+ * @private internal utility of `promptbookCli`
+ */
+export async function $ensurePromptbookCliInstallations(): Promise<boolean> {
+    if (!process.stdin.isTTY) {
+        // Note: Non-interactive runs cannot approve an update and should not wait for registry checks.
+        return false;
+    }
+
+    const statuses = await $checkPromptbookCliInstallations();
+    const outdatedStatuses = statuses.filter(({ installationState }) => installationState === 'outdated');
+
+    if (outdatedStatuses.length === 0) {
+        reportPromptbookCliInstallationStatuses(statuses);
+        return false;
+    }
+
+    console.warn(colors.yellow(formatPromptbookCliInstallationWarning(outdatedStatuses)));
+
+    const isUpdateApproved = await $askForNpmPackageInstallationApproval('Update Promptbook CLI now?');
+
+    if (!isUpdateApproved) {
+        const manualInstallCommands = outdatedStatuses
+            .map((status) => `- \`${buildPromptbookCliInstallCommand(status.installation)}\``)
+            .join('\n');
+
+        console.info(
+            colors.gray(
+                spaceTrim(
+                    (block) => `
+                        Skipped updating Promptbook CLI.
+
+                        Run one of these commands manually:
+
+                        ${block(manualInstallCommands)}
+                    `,
+                ),
+            ),
+        );
+        return false;
+    }
+
+    for (const status of outdatedStatuses) {
+        await $updatePromptbookCliInstallation(status);
+    }
+
+    console.info(colors.green('Promptbook CLI update is complete. Run the command again to use the new version.'));
+    return true;
+}
+
+/**
+ * Reports successful and unverifiable Promptbook CLI checks when no update is required.
+ *
+ * @private internal utility of `$ensurePromptbookCliInstallations`
+ */
+function reportPromptbookCliInstallationStatuses(statuses: ReadonlyArray<PromptbookCliInstallationStatus>): void {
+    for (const status of statuses) {
+        const { npmPackageName, installedVersion } = status.installation;
+
+        if (status.installationState === 'up-to-date') {
+            console.info(colors.gray(`✔ Promptbook CLI \`${npmPackageName}\` ${installedVersion} is up to date.`));
+            continue;
+        }
+
+        if (status.installationState === 'unknown') {
+            console.info(
+                colors.gray(
+                    `✔ Promptbook CLI \`${npmPackageName}\` ${installedVersion} is installed; the newest version could not be checked.`,
+                ),
+            );
+        }
+    }
+}
+
+// Note: [🟡] Code for Promptbook CLI installation orchestration [$ensurePromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.ts

@@ -0,0 +1,223 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import {
+    PROMPTBOOK_CLI_NPM_PACKAGE_NAMES,
+    type PromptbookCliInstallation,
+    type PromptbookCliInstallationLocation,
+    type PromptbookCliNpmPackageName,
+} from './PromptbookCliInstallation';
+
+/**
+ * Time limit for resolving npm's global `node_modules` directory.
+ */
+const NPM_GLOBAL_NODE_MODULES_PATH_COMMAND_TIMEOUT_MS = 30 * 1000;
+
+/**
+ * JSON object shape used while reading package manifests without assuming unrelated fields.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+type JsonObject = Readonly<Record<string, unknown>>;
+
+/**
+ * Finds every locally or globally installed Promptbook CLI package which can be updated.
+ *
+ * A local package must be declared directly in the current project's `package.json`; transitive packages are not
+ * updated because this command must not change dependencies chosen by another package.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests and runs npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>> {
+    const [localInstallations, globalInstallations] = await Promise.all([
+        $resolveLocalPromptbookCliInstallations(),
+        $resolveGlobalPromptbookCliInstallations(),
+    ]);
+
+    return [...localInstallations, ...globalInstallations];
+}
+
+/**
+ * Finds Promptbook CLI packages installed directly in the current project's dependencies.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+async function $resolveLocalPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>> {
+    const projectPath = process.cwd();
+    const projectPackageJson = await $readJsonObject(join(projectPath, 'package.json'));
+
+    if (projectPackageJson === null) {
+        return [];
+    }
+
+    const installations = await Promise.all(
+        PROMPTBOOK_CLI_NPM_PACKAGE_NAMES.map(async (npmPackageName) => {
+            const installationLocation = resolveLocalPromptbookCliInstallationLocation(
+                projectPackageJson,
+                npmPackageName,
+            );
+
+            if (installationLocation === undefined) {
+                return undefined;
+            }
+
+            const installedVersion = await $resolveInstalledNpmPackageVersion(
+                join(projectPath, 'node_modules'),
+                npmPackageName,
+            );
+
+            if (installedVersion === undefined) {
+                return undefined;
+            }
+
+            return { npmPackageName, installedVersion, installationLocation };
+        }),
+    );
+
+    return installations.filter(isDefined);
+}
+
+/**
+ * Finds Promptbook CLI packages installed in npm's global `node_modules` directory.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+async function $resolveGlobalPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>> {
+    const globalNodeModulesPath = await $resolveNpmGlobalNodeModulesPath();
+
+    if (globalNodeModulesPath === null) {
+        return [];
+    }
+
+    const installations = await Promise.all(
+        PROMPTBOOK_CLI_NPM_PACKAGE_NAMES.map(async (npmPackageName) => {
+            const installedVersion = await $resolveInstalledNpmPackageVersion(globalNodeModulesPath, npmPackageName);
+
+            if (installedVersion === undefined) {
+                return undefined;
+            }
+
+            return {
+                npmPackageName,
+                installedVersion,
+                installationLocation: 'global' as const,
+            };
+        }),
+    );
+
+    return installations.filter(isDefined);
+}
+
+/**
+ * Resolves the current project's manifest section that declares a Promptbook CLI package.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+function resolveLocalPromptbookCliInstallationLocation(
+    packageJson: JsonObject,
+    npmPackageName: PromptbookCliNpmPackageName,
+): PromptbookCliInstallationLocation | undefined {
+    if (readNestedStringProperty(packageJson, 'dependencies', npmPackageName) !== undefined) {
+        return 'local-dependency';
+    }
+
+    if (readNestedStringProperty(packageJson, 'devDependencies', npmPackageName) !== undefined) {
+        return 'local-development-dependency';
+    }
+
+    return undefined;
+}
+
+/**
+ * Reads an installed npm package version from a `node_modules` directory.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+async function $resolveInstalledNpmPackageVersion(
+    nodeModulesPath: string,
+    npmPackageName: PromptbookCliNpmPackageName,
+): Promise<string | undefined> {
+    const installedPackageJson = await $readJsonObject(join(nodeModulesPath, npmPackageName, 'package.json'));
+
+    return installedPackageJson === null ? undefined : readStringProperty(installedPackageJson, 'version');
+}
+
+/**
+ * Resolves npm's global `node_modules` directory without querying the registry.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+async function $resolveNpmGlobalNodeModulesPath(): Promise<string | null> {
+    const output = await $execCommand({
+        command: 'npm root --global',
+        crashOnError: true,
+        timeout: NPM_GLOBAL_NODE_MODULES_PATH_COMMAND_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+
+    const globalNodeModulesPath = output.trim();
+    return globalNodeModulesPath === '' ? null : globalNodeModulesPath;
+}
+
+/**
+ * Reads a JSON object, returning `null` for missing or malformed files because update checks must stay advisory.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+async function $readJsonObject(filePath: string): Promise<JsonObject | null> {
+    try {
+        const parsedValue: unknown = JSON.parse(await readFile(filePath, 'utf8'));
+
+        return isJsonObject(parsedValue) ? parsedValue : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Checks whether an unknown value can be read as a JSON object.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+function isJsonObject(value: unknown): value is JsonObject {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Reads one string property from a JSON object.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+function readStringProperty(jsonObject: JsonObject, propertyName: string): string | undefined {
+    const value = jsonObject[propertyName];
+
+    return typeof value === 'string' ? value : undefined;
+}
+
+/**
+ * Reads one string property nested under another JSON object property.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+function readNestedStringProperty(
+    jsonObject: JsonObject,
+    parentPropertyName: string,
+    propertyName: string,
+): string | undefined {
+    const nestedValue = jsonObject[parentPropertyName];
+
+    return isJsonObject(nestedValue) ? readStringProperty(nestedValue, propertyName) : undefined;
+}
+
+/**
+ * Narrows an array after `undefined` values were removed.
+ *
+ * @private internal utility of `$resolvePromptbookCliInstallations`
+ */
+function isDefined<TValue>(value: TValue | undefined): value is TValue {
+    return value !== undefined;
+}
+
+// Note: [🟡] Code for Promptbook CLI installation detection [$resolvePromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.ts

@@ -0,0 +1,53 @@
+import colors from 'colors';
+import { spaceTrim } from 'spacetrim';
+import { assertsError } from '../../../../errors/assertsError';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+import { buildPromptbookCliInstallCommand } from './buildPromptbookCliInstallCommand';
+
+/**
+ * Updates one Promptbook CLI package in its existing local or global location.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs an npm package
+ *
+ * @returns `true` when the package update succeeds, `false` when it fails
+ * @private internal utility of `promptbookCli`
+ */
+export async function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean> {
+    const { npmPackageName } = status.installation;
+    const installCommand = buildPromptbookCliInstallCommand(status.installation);
+
+    console.info(colors.cyan(`Updating Promptbook CLI package \`${npmPackageName}\` with \`${installCommand}\`...`));
+
+    try {
+        await $execCommand({
+            command: installCommand,
+            crashOnError: true,
+            isVerbose: true,
+        });
+    } catch (error) {
+        assertsError(error);
+        const updateErrorMessage = error.message;
+
+        console.error(
+            colors.red(
+                spaceTrim(
+                    (block) => `
+                        Could not update **Promptbook CLI** package \`${npmPackageName}\`.
+
+                        Update it manually with \`${installCommand}\` and run the command again.
+
+                        ${block(updateErrorMessage)}
+                    `,
+                ),
+            ),
+        );
+
+        return false;
+    }
+
+    console.info(colors.green(`Promptbook CLI package \`${npmPackageName}\` has been updated.`));
+    return true;
+}
+
+// Note: [🟡] Code for Promptbook CLI installation update [$updatePromptbookCliInstallation](src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.ts

@@ -0,0 +1,46 @@
+/**
+ * Npm packages which provide an executable Promptbook CLI.
+ *
+ * `ptbk` is the preferred package and forwards to `@promptbook/cli`; the latter can also be installed directly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export const PROMPTBOOK_CLI_NPM_PACKAGE_NAMES = ['ptbk', '@promptbook/cli'] as const;
+
+/**
+ * Npm package which provides an executable Promptbook CLI.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliNpmPackageName = (typeof PROMPTBOOK_CLI_NPM_PACKAGE_NAMES)[number];
+
+/**
+ * Place where one Promptbook CLI package is installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationLocation = 'local-dependency' | 'local-development-dependency' | 'global';
+
+/**
+ * One installed Promptbook CLI package that can be updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallation = {
+    /**
+     * Npm package that provides the CLI.
+     */
+    readonly npmPackageName: PromptbookCliNpmPackageName;
+
+    /**
+     * Version from the package's installed `package.json`.
+     */
+    readonly installedVersion: string;
+
+    /**
+     * Local manifest section or global npm installation containing the package.
+     */
+    readonly installationLocation: PromptbookCliInstallationLocation;
+};
+
+// Note: [🟡] Code for Promptbook CLI installation definitions [PromptbookCliInstallation](src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallationStatus.ts

@@ -0,0 +1,32 @@
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+
+/**
+ * Result of comparing one installed Promptbook CLI package with the newest published version.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationState = 'up-to-date' | 'outdated' | 'unknown';
+
+/**
+ * Version status of one Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationStatus = {
+    /**
+     * Installed CLI package being checked.
+     */
+    readonly installation: PromptbookCliInstallation;
+
+    /**
+     * Result of comparing the installed version with the newest published version.
+     */
+    readonly installationState: PromptbookCliInstallationState;
+
+    /**
+     * Newest published package version, or `null` when npm could not be reached.
+     */
+    readonly latestVersion: string | null;
+};
+
+// Note: [🟡] Code for Promptbook CLI installation status [PromptbookCliInstallationStatus](src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallationStatus.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.ts

@@ -0,0 +1,22 @@
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+
+/**
+ * Builds the npm command that updates one existing Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function buildPromptbookCliInstallCommand(installation: PromptbookCliInstallation): string {
+    const { npmPackageName, installationLocation } = installation;
+
+    if (installationLocation === 'global') {
+        return `npm install --global ${npmPackageName}@latest`;
+    }
+
+    if (installationLocation === 'local-development-dependency') {
+        return `npm install --save-dev ${npmPackageName}@latest`;
+    }
+
+    return `npm install --save ${npmPackageName}@latest`;
+}
+
+// Note: [🟡] Code for Promptbook CLI installation command [buildPromptbookCliInstallCommand](src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptbook-cli/formatPromptbookCliInstallationWarning.ts

@@ -0,0 +1,47 @@
+import { spaceTrim } from 'spacetrim';
+import type { PromptbookCliInstallationLocation } from './PromptbookCliInstallation';
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+
+/**
+ * Formats the warning shown when one or more Promptbook CLI installations are outdated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function formatPromptbookCliInstallationWarning(
+    statuses: ReadonlyArray<PromptbookCliInstallationStatus>,
+): string {
+    const statusLines = statuses.map((status) => {
+        const { npmPackageName, installedVersion, installationLocation } = status.installation;
+
+        return `- ${formatPromptbookCliInstallationLocation(
+            installationLocation,
+        )} \`${npmPackageName}\`: installed \`${installedVersion}\`, newest \`${status.latestVersion}\``;
+    });
+
+    return spaceTrim(
+        (block) => `
+            **Promptbook CLI** is outdated.
+
+            ${block(statusLines.join('\n'))}
+        `,
+    );
+}
+
+/**
+ * Describes an installation location in text suitable for an update warning.
+ *
+ * @private internal utility of `formatPromptbookCliInstallationWarning`
+ */
+function formatPromptbookCliInstallationLocation(installationLocation: PromptbookCliInstallationLocation): string {
+    if (installationLocation === 'global') {
+        return 'Globally installed';
+    }
+
+    if (installationLocation === 'local-development-dependency') {
+        return 'Locally in `devDependencies`';
+    }
+
+    return 'Locally in `dependencies`';
+}
+
+// Note: [🟡] Code for Promptbook CLI installation warning [formatPromptbookCliInstallationWarning](src/cli/cli-commands/common/promptbook-cli/formatPromptbookCliInstallationWarning.ts) should never be published outside of `@promptbook/cli`

package/src/commands/FORMAT/formatCommandParser.ts

@@ -70,8 +70,8 @@ export const formatCommandParser: PipelineTaskCommandParser<FormatCommand> = {
      */
     $applyToTaskJson(command: FormatCommand, $taskJson: $TaskJson): $side_effect {
         if ($taskJson.format !== undefined && command.format !== $taskJson.format) {
-            throw new ParseError(`Format format is already defined to "${$taskJson.format}".
-                Now you try to redefine it by "${command.format}"`);
+            throw new ParseError(spaceTrim(`Format format is already defined to "${$taskJson.format}".
+                Now you try to redefine it by "${command.format}"`));
         }
         $taskJson.format = command.format;
     },

package/src/llm-providers/openai/utils/buildToolInvocationScript.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import {
     TOOL_PROGRESS_TOKEN_ARGUMENT,
     TOOL_PROGRESS_TOKEN_PARAMETER,
@@ -16,26 +17,28 @@ export function buildToolInvocationScript(options: {
 }): string {
     const { functionName, functionArgsExpression } = options;
 
-    return `
-        const args = ${functionArgsExpression};
-        const runtimeContextRaw =
-            typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
+    return spaceTrim(
+        (block) => `
+            const args = ${block(functionArgsExpression)};
+            const runtimeContextRaw =
+                typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
+                    ? undefined
+                    : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
 
-        if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
-        }
+            if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+                args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
+            }
 
-        const toolProgressTokenRaw =
-            typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_PROGRESS_TOKEN_PARAMETER};
+            const toolProgressTokenRaw =
+                typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
+                    ? undefined
+                    : ${TOOL_PROGRESS_TOKEN_PARAMETER};
 
-        if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
-        }
+            if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+                args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
+            }
 
-        return await ${functionName}(args);
-    `;
+            return await ${functionName}(args);
+        `,
+    );
 }