@promptbook/cli 0.114.0-5 → 0.114.0-50

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/npm/$askForNpmPackageInstallationApproval.ts

@@ -0,0 +1,20 @@
+import { $askForConfirmation } from '../$askForConfirmation';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
+
+/**
+ * Asks the user in the terminal whether an npm package should be installed or updated now.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin
+ *
+ * @returns `true` when the user confirms, `false` when the user declines, the terminal is not interactive
+ *          or the questions are disabled by `--no-questions`
+ * @private internal utility of `promptbookCli`
+ */
+export async function $askForNpmPackageInstallationApproval(
+    question: string,
+    questionsOptions: NormalizedQuestionsCliOptions,
+): Promise<boolean> {
+    return $askForConfirmation(question, questionsOptions);
+}
+
+// Note: [🟡] Code for CLI npm package installation approval [$askForNpmPackageInstallationApproval](src/cli/cli-commands/common/npm/$askForNpmPackageInstallationApproval.ts) should never be published outside of `@promptbook/cli`

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/$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`

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

@@ -0,0 +1,78 @@
+import type { Command } from 'commander';
+import { constants } from 'fs';
+import { access, realpath, stat } from 'fs/promises';
+import { resolve } from 'path';
+import { EnvironmentMismatchError } from '../../../errors/EnvironmentMismatchError';
+import { spaceTrim } from '../../../utils/organization/spaceTrim';
+
+/**
+ * Optional project selection shared by workspace actions, independently of Book and harness selection.
+ * @private internal CLI options
+ */
+export type ProjectCliOptions = { readonly path?: string };
+
+/**
+ * Registers project selection without capturing a directory during command registration.
+ * @private internal CLI registration helper
+ */
+export function addProjectPathOption(command: Command): void {
+    command.option(
+        '--path <directory>',
+        'Project directory (default: invocation current directory); relative paths start there',
+    );
+}
+
+/**
+ * Registers additional context independently of primary-agent selection.
+ * @private internal CLI registration helper
+ */
+export function addProjectContextOption(command: Command): void {
+    command.option(
+        '--context <context-or-file>',
+        'Additional instructions (default: project AGENTS.md); inline text or a project-relative file replaces the default; an empty value disables it',
+    );
+}
+
+/**
+ * Captures an invocation's directory at action time. No process-global state is changed.
+ * @private internal CLI normalization helper
+ */
+export function normalizeProjectCliOptions(
+    options: ProjectCliOptions,
+    invocationDirectory = process.cwd(),
+): { readonly projectDirectory: string } {
+    const selectedPath = options.path;
+    if (selectedPath !== undefined && !selectedPath.trim()) {
+        throw new EnvironmentMismatchError(
+            spaceTrim('Pass a non-empty project directory in `--path`, or omit it to use the current directory.'),
+        );
+    }
+    return { projectDirectory: resolve(invocationDirectory, selectedPath ?? '.') };
+}
+
+/**
+ * Validates the selected directory before any setup writes, without selecting an enclosing Git root.
+ * @private shared project resolution for CLI services
+ */
+export async function resolveProjectDirectory(projectDirectory: string): Promise<string> {
+    const requestedPath = resolve(projectDirectory);
+    try {
+        const projectPath = await realpath(requestedPath);
+        if (!(await stat(projectPath)).isDirectory()) {
+            throw new EnvironmentMismatchError(spaceTrim(`Project path \`${requestedPath}\` is not a directory.`));
+        }
+        await access(projectPath, constants.R_OK | constants.X_OK);
+        return projectPath;
+    } catch (error) {
+        throw new EnvironmentMismatchError(
+            spaceTrim(`
+            Cannot access project directory \`${requestedPath}\`.
+            Check that it exists, is a directory, and is readable and searchable; correct \`--path\` before retrying.
+
+            ${error instanceof Error ? error.message : String(error)}
+        `),
+        );
+    }
+}
+
+// Note: [💞] Shared project registration and resolution helpers.

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';
 
 /**
@@ -112,17 +113,40 @@ export async function ensureProjectGitignoreFile({
 }: EnsureProjectGitignoreFileOptions): Promise<ProjectInitializationStatus> {
     const gitignorePath = join(projectPath, GITIGNORE_FILE_PATH);
     const currentGitignoreContent = await readTextFileIfExists(gitignorePath);
-    const missingRules = rules.filter((rule) => !hasGitignoreRule(currentGitignoreContent || '', rule));
+    const missingRules = getMissingGitignoreRules(currentGitignoreContent || '', rules);
 
     if (currentGitignoreContent !== undefined && missingRules.length === 0) {
         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';
 }
 
+/**
+ * Lists the ignore rules which are not yet present in a project's `.gitignore` file.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export async function getMissingProjectGitignoreRules(
+    projectPath: string,
+    rules: ReadonlyArray<string>,
+): Promise<ReadonlyArray<string>> {
+    const gitignorePath = join(projectPath, GITIGNORE_FILE_PATH);
+    const currentGitignoreContent = (await readTextFileIfExists(gitignorePath)) || '';
+
+    return getMissingGitignoreRules(currentGitignoreContent, rules);
+}
+
 /**
  * Reads one text file when it exists, otherwise returns `undefined`.
  *
@@ -182,9 +206,17 @@ function parseEnvVariableNames(envContent: string): Set<string> {
  * Detects whether `.gitignore` already covers one exact rule.
  */
 function hasGitignoreRule(gitignoreContent: string, rule: string): boolean {
-    const normalizedRulePattern = rule.startsWith('/') ? `/?${escapeRegExp(rule.slice(1))}` : escapeRegExp(rule);
+    const normalizedRule = rule.startsWith('/') ? rule.slice(1) : rule;
+    const normalizedRulePattern = `/?${escapeRegExp(normalizedRule)}`;
     return new RegExp(`(^|[\\r\\n])${normalizedRulePattern}(?:[\\r\\n]|$)`, 'u').test(gitignoreContent);
 }
 
+/**
+ * Finds the unique rules which are not covered by existing `.gitignore` content.
+ */
+function getMissingGitignoreRules(gitignoreContent: string, rules: ReadonlyArray<string>): ReadonlyArray<string> {
+    return Array.from(new Set(rules)).filter((rule) => !hasGitignoreRule(gitignoreContent, rule));
+}
+
 // Note: [🟡] Code for CLI project initialization [projectInitialization](src/cli/cli-commands/common/projectInitialization.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/promptPriorityCliOptions.ts

@@ -0,0 +1,30 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+import { createNonNegativeIntegerOptionParser } from './createNonNegativeIntegerOptionParser';
+
+/**
+ * Registers the shared prompt-priority filter options on a queue-based `ptbk coder` command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function addPromptPriorityOptions(command: Program): void {
+    command.option(
+        '--priority <minimum-priority>',
+        'Alias for --min-priority; filter prompts by minimum priority level',
+        createNonNegativeIntegerOptionParser('--priority'),
+    );
+    command.option(
+        '--min-priority <minimum-priority>',
+        'Filter prompts by minimum priority level',
+        createNonNegativeIntegerOptionParser('--min-priority'),
+    );
+    command.option(
+        '--max-priority <maximum-priority>',
+        'Filter prompts by maximum priority level',
+        createNonNegativeIntegerOptionParser('--max-priority'),
+    );
+}
+
+// Note: [🟡] Code for CLI prompt priority options [promptPriorityCliOptions](src/cli/cli-commands/common/promptPriorityCliOptions.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names