@promptbook/cli 0.114.0-0 → 0.114.0-10

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

@@ -0,0 +1,49 @@
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import { extractNpmPackageVersionFromOutput } from './extractNpmPackageVersionFromOutput';
+
+/**
+ * Time limit for the whole `npm view` lookup of the newest published package version.
+ */
+const NPM_PACKAGE_LATEST_VERSION_COMMAND_TIMEOUT_MS = 60 * 1000;
+
+/**
+ * Time limit for one npm registry request, so an unreachable registry never blocks the command.
+ */
+const NPM_REGISTRY_FETCH_TIMEOUT_MS = 20 * 1000;
+
+/**
+ * Pattern matching npm's JSON-encoded package version result.
+ */
+const NPM_VIEW_JSON_VERSION_PATTERN = /"(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)"/u;
+
+/**
+ * Reads the newest version of one npm package.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it queries the npm registry
+ *
+ * @returns The newest published version or `null` when the registry could not be reached
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolveLatestNpmPackageVersion(npmPackageName: string): Promise<string | null> {
+    const output = await $execCommand({
+        command: `npm view ${npmPackageName} version --json --loglevel=error --fetch-timeout=${NPM_REGISTRY_FETCH_TIMEOUT_MS} --fetch-retries=1`,
+        crashOnError: true,
+        timeout: NPM_PACKAGE_LATEST_VERSION_COMMAND_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+
+    return extractLatestNpmPackageVersionFromNpmViewOutput(output);
+}
+
+/**
+ * Extracts the version from npm's JSON result while tolerating warnings emitted before or after that result.
+ *
+ * @private internal utility of `$resolveLatestNpmPackageVersion`
+ */
+function extractLatestNpmPackageVersionFromNpmViewOutput(output: string): string | null {
+    const jsonVersionMatch = NPM_VIEW_JSON_VERSION_PATTERN.exec(output);
+
+    return jsonVersionMatch?.[1] ?? extractNpmPackageVersionFromOutput(output, { isLastMatchPreferred: true });
+}
+
+// Note: [🟡] Code for CLI npm package registry lookup [$resolveLatestNpmPackageVersion](src/cli/cli-commands/common/npm/$resolveLatestNpmPackageVersion.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/npm/buildNpmPackageInstallCommand.ts

@@ -0,0 +1,28 @@
+/**
+ * Place where an npm package should be installed or updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NpmPackageInstallationLocation = 'local-dependency' | 'local-development-dependency' | 'global';
+
+/**
+ * Builds an npm command which installs or updates a package in the requested existing location.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function buildNpmPackageInstallCommand(
+    npmPackageName: string,
+    installationLocation: NpmPackageInstallationLocation,
+): string {
+    if (installationLocation === 'global') {
+        return `npm install -g ${npmPackageName}@latest`;
+    }
+
+    if (installationLocation === 'local-development-dependency') {
+        return `npm install --save-dev ${npmPackageName}@latest`;
+    }
+
+    return `npm install --save ${npmPackageName}@latest`;
+}
+
+// Note: [🟡] Code for CLI npm install commands [buildNpmPackageInstallCommand](src/cli/cli-commands/common/npm/buildNpmPackageInstallCommand.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/npm/extractNpmPackageVersionFromOutput.ts

@@ -0,0 +1,25 @@
+/**
+ * Pattern matching one `major.minor.patch` version anywhere in npm or CLI command output.
+ */
+const NPM_PACKAGE_VERSION_PATTERN = /\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/gu;
+
+/**
+ * Extracts an npm package version from raw command output.
+ *
+ * Both npm and CLI commands may emit unrelated warnings before the version. CLI commands use the first matching token;
+ * npm registry commands can opt into the last matching token because npm warnings commonly precede their output.
+ *
+ * @returns The parsed version or `null` when the output contains no version
+ * @private internal utility of `promptbookCli`
+ */
+export function extractNpmPackageVersionFromOutput(
+    output: string,
+    { isLastMatchPreferred = false }: { readonly isLastMatchPreferred?: boolean } = {},
+): string | null {
+    const versionMatches = Array.from(output.matchAll(NPM_PACKAGE_VERSION_PATTERN));
+    const versionMatch = isLastMatchPreferred ? versionMatches[versionMatches.length - 1] : versionMatches[0];
+
+    return versionMatch?.[1] ?? null;
+}
+
+// Note: [🟡] Code for CLI npm package version parsing [extractNpmPackageVersionFromOutput](src/cli/cli-commands/common/npm/extractNpmPackageVersionFromOutput.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.ts

@@ -0,0 +1,165 @@
+/**
+ * Parsed parts of one npm package version used for precedence comparison.
+ *
+ * @private internal utility of `isNpmPackageVersionOutdated`
+ */
+type ParsedNpmPackageVersion = {
+    readonly releaseSegments: ReadonlyArray<number>;
+    readonly prereleaseIdentifiers: ReadonlyArray<number | string> | null;
+};
+
+/**
+ * Compares an installed npm package version with the newest published version.
+ *
+ * Release and prerelease identifiers follow semantic-version precedence while build metadata is ignored. Harnesses can
+ * preserve their historical behavior by setting `isPrereleaseIgnored`, because some harness commands report a build
+ * suffix which does not correspond to npm release precedence.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function isNpmPackageVersionOutdated(
+    installedVersion: string,
+    latestVersion: string,
+    { isPrereleaseIgnored = false }: { readonly isPrereleaseIgnored?: boolean } = {},
+): boolean {
+    const installedPackageVersion = parseNpmPackageVersion(installedVersion);
+    const latestPackageVersion = parseNpmPackageVersion(latestVersion);
+    const releaseComparison = compareNumericSegments(
+        installedPackageVersion.releaseSegments,
+        latestPackageVersion.releaseSegments,
+    );
+
+    if (releaseComparison !== 0) {
+        return releaseComparison < 0;
+    }
+
+    if (isPrereleaseIgnored) {
+        return false;
+    }
+
+    return (
+        comparePrereleaseIdentifiers(
+            installedPackageVersion.prereleaseIdentifiers,
+            latestPackageVersion.prereleaseIdentifiers,
+        ) < 0
+    );
+}
+
+/**
+ * Parses semantic-version release and prerelease parts, ignoring build metadata.
+ */
+function parseNpmPackageVersion(version: string): ParsedNpmPackageVersion {
+    const buildMetadataSeparatorIndex = version.indexOf('+');
+    const versionWithoutBuildMetadata = (
+        buildMetadataSeparatorIndex === -1 ? version : version.slice(0, buildMetadataSeparatorIndex)
+    ).trim();
+    const prereleaseSeparatorIndex = versionWithoutBuildMetadata.indexOf('-');
+    const releasePart =
+        prereleaseSeparatorIndex === -1
+            ? versionWithoutBuildMetadata
+            : versionWithoutBuildMetadata.slice(0, prereleaseSeparatorIndex);
+    const prereleasePart =
+        prereleaseSeparatorIndex === -1 ? null : versionWithoutBuildMetadata.slice(prereleaseSeparatorIndex + 1);
+
+    return {
+        releaseSegments: releasePart.split('.').map(parseNumericVersionIdentifier),
+        prereleaseIdentifiers:
+            prereleasePart === null
+                ? null
+                : prereleasePart
+                      .split('.')
+                      .map((identifier) => (/^\d+$/u.test(identifier) ? Number.parseInt(identifier, 10) : identifier)),
+    };
+}
+
+/**
+ * Parses one numeric release identifier while retaining the former tolerant behavior for malformed input.
+ */
+function parseNumericVersionIdentifier(identifier: string): number {
+    const identifierNumber = Number.parseInt(identifier, 10);
+
+    return Number.isNaN(identifierNumber) ? 0 : identifierNumber;
+}
+
+/**
+ * Compares numeric version segments, treating omitted trailing segments as zero.
+ */
+function compareNumericSegments(firstSegments: ReadonlyArray<number>, secondSegments: ReadonlyArray<number>): number {
+    const segmentCount = Math.max(firstSegments.length, secondSegments.length);
+
+    for (let segmentIndex = 0; segmentIndex < segmentCount; segmentIndex++) {
+        const firstSegment = firstSegments[segmentIndex] ?? 0;
+        const secondSegment = secondSegments[segmentIndex] ?? 0;
+
+        if (firstSegment !== secondSegment) {
+            return firstSegment < secondSegment ? -1 : 1;
+        }
+    }
+
+    return 0;
+}
+
+/**
+ * Compares semantic-version prerelease identifiers.
+ */
+function comparePrereleaseIdentifiers(
+    firstIdentifiers: ReadonlyArray<number | string> | null,
+    secondIdentifiers: ReadonlyArray<number | string> | null,
+): number {
+    if (firstIdentifiers === null || secondIdentifiers === null) {
+        if (firstIdentifiers === secondIdentifiers) {
+            return 0;
+        }
+
+        // Note: A version without prerelease identifiers has higher precedence than a prerelease
+        return firstIdentifiers === null ? 1 : -1;
+    }
+
+    const identifierCount = Math.max(firstIdentifiers.length, secondIdentifiers.length);
+
+    for (let identifierIndex = 0; identifierIndex < identifierCount; identifierIndex++) {
+        const firstIdentifier = firstIdentifiers[identifierIndex];
+        const secondIdentifier = secondIdentifiers[identifierIndex];
+
+        if (firstIdentifier === undefined || secondIdentifier === undefined) {
+            if (firstIdentifier === secondIdentifier) {
+                return 0;
+            }
+
+            return firstIdentifier === undefined ? -1 : 1;
+        }
+
+        const identifierComparison = comparePrereleaseIdentifier(firstIdentifier, secondIdentifier);
+
+        if (identifierComparison !== 0) {
+            return identifierComparison;
+        }
+    }
+
+    return 0;
+}
+
+/**
+ * Compares two individual semantic-version prerelease identifiers.
+ */
+function comparePrereleaseIdentifier(firstIdentifier: number | string, secondIdentifier: number | string): number {
+    if (firstIdentifier === secondIdentifier) {
+        return 0;
+    }
+
+    if (typeof firstIdentifier === 'number' && typeof secondIdentifier === 'number') {
+        return firstIdentifier < secondIdentifier ? -1 : 1;
+    }
+
+    if (typeof firstIdentifier === 'number') {
+        return -1;
+    }
+
+    if (typeof secondIdentifier === 'number') {
+        return 1;
+    }
+
+    return firstIdentifier < secondIdentifier ? -1 : 1;
+}
+
+// Note: [🟡] Code for CLI npm package version comparison [isNpmPackageVersionOutdated](src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.ts) should never be published outside of `@promptbook/cli`

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

@@ -1,5 +1,6 @@
 import { readFile, stat, writeFile } from 'fs/promises';
 import { join } from 'path';
+import { spaceTrim } from 'spacetrim';
 import { escapeRegExp } from '../../../utils/chat/escapeRegExp';
 
 /**
@@ -118,7 +119,15 @@ export async function ensureProjectGitignoreFile({
         return 'unchanged';
     }
 
-    const nextGitignoreContent = appendBlock(currentGitignoreContent || '', [blockHeader, ...missingRules].join('\n'));
+    const nextGitignoreContent = appendBlock(
+        currentGitignoreContent || '',
+        spaceTrim(
+            (block) => `
+                ${block(blockHeader)}
+                ${block(missingRules.join('\n'))}
+            `,
+        ),
+    );
     await writeFile(gitignorePath, nextGitignoreContent, 'utf-8');
     return currentGitignoreContent === undefined ? 'created' : 'updated';
 }

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

@@ -0,0 +1,69 @@
+import { $resolveLatestNpmPackageVersion } from '../npm/$resolveLatestNpmPackageVersion';
+import { isNpmPackageVersionOutdated } from '../npm/isNpmPackageVersionOutdated';
+import { $resolvePromptbookCliInstallations } from './$resolvePromptbookCliInstallations';
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+import type {
+    PromptbookCliInstallationState,
+    PromptbookCliInstallationStatus,
+} from './PromptbookCliInstallationStatus';
+
+/**
+ * Checks every local and global Promptbook CLI installation against the newest npm version.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads installed packages and queries npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $checkPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallationStatus>> {
+    const installations = await $resolvePromptbookCliInstallations();
+
+    if (installations.length === 0) {
+        return [];
+    }
+
+    const latestVersionsByNpmPackageName = await $resolveLatestVersionsByNpmPackageName(installations);
+
+    return installations.map((installation) => {
+        const latestVersion = latestVersionsByNpmPackageName.get(installation.npmPackageName) ?? null;
+
+        return {
+            installation,
+            installationState: resolvePromptbookCliInstallationState(installation.installedVersion, latestVersion),
+            latestVersion,
+        };
+    });
+}
+
+/**
+ * Resolves each package's newest version once, even when it is installed locally and globally.
+ */
+async function $resolveLatestVersionsByNpmPackageName(
+    installations: ReadonlyArray<PromptbookCliInstallation>,
+): Promise<ReadonlyMap<PromptbookCliInstallation['npmPackageName'], string | null>> {
+    const npmPackageNames = Array.from(new Set(installations.map(({ npmPackageName }) => npmPackageName)));
+    const latestVersionEntries = await Promise.all(
+        npmPackageNames.map(async (npmPackageName) => {
+            const latestVersion = await $resolveLatestNpmPackageVersion(npmPackageName);
+
+            return [npmPackageName, latestVersion] as const;
+        }),
+    );
+
+    return new Map(latestVersionEntries);
+}
+
+/**
+ * Derives the update state of one installed Promptbook CLI package.
+ */
+function resolvePromptbookCliInstallationState(
+    installedVersion: string,
+    latestVersion: string | null,
+): PromptbookCliInstallationState {
+    if (latestVersion === null) {
+        return 'unknown';
+    }
+
+    return isNpmPackageVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
+}
+
+// Note: [🟡] Code for Promptbook CLI installation check [$checkPromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$checkPromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`

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

@@ -0,0 +1,117 @@
+import colors from 'colors';
+import { spaceTrim } from 'spacetrim';
+import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
+import { $checkPromptbookCliInstallations } from './$checkPromptbookCliInstallations';
+import { $updatePromptbookCliInstallation } from './$updatePromptbookCliInstallation';
+import { buildPromptbookCliInstallCommand } from './buildPromptbookCliInstallCommand';
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+import { formatPromptbookCliInstallationWarning } from './formatPromptbookCliInstallationWarning';
+
+/**
+ * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
+ *
+ * Once an update succeeds, 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 clean-working-tree preflight fail;
+ * the current Node.js process has also 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 at least one installation was updated 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) {
+        reportManualPromptbookCliUpdateCommands(outdatedStatuses);
+        return false;
+    }
+
+    const updateResults: Array<boolean> = [];
+
+    for (const status of outdatedStatuses) {
+        updateResults.push(await $updatePromptbookCliInstallation(status));
+    }
+
+    const isAnyInstallationUpdated = updateResults.some(Boolean);
+    const isEveryInstallationUpdated = updateResults.every(Boolean);
+
+    if (!isAnyInstallationUpdated) {
+        console.info(colors.gray('Promptbook CLI could not be updated; continuing with the installed version.'));
+        return false;
+    }
+
+    console.info(
+        isEveryInstallationUpdated
+            ? colors.green('Promptbook CLI update is complete. Run the command again to use the new version.')
+            : colors.yellow(
+                  'Some Promptbook CLI installations were updated. Resolve the errors above, then run the command again.',
+              ),
+    );
+    return true;
+}
+
+/**
+ * Reports successful and unverifiable Promptbook CLI checks when no update is required.
+ */
+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.`,
+                ),
+            );
+        }
+    }
+}
+
+/**
+ * Prints the exact commands which would update all declined outdated installations.
+ */
+function reportManualPromptbookCliUpdateCommands(
+    outdatedStatuses: ReadonlyArray<PromptbookCliInstallationStatus>,
+): void {
+    const manualInstallCommands = outdatedStatuses
+        .map((status) => `- \`${buildPromptbookCliInstallCommand(status.installation)}\``)
+        .join('\n');
+
+    console.info(
+        colors.gray(
+            spaceTrim(
+                (block) => `
+                    Skipped updating Promptbook CLI.
+
+                    Run these commands manually:
+
+                    ${block(manualInstallCommands)}
+                `,
+            ),
+        ),
+    );
+}
+
+// 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`