@promptbook/cli 0.114.0-3 → 0.114.0-31

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

@@ -0,0 +1,46 @@
+import type {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+} from 'commander';
+
+/**
+ * Commander option bag for opting out of automatic coding-harness update checks.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdateCliOptions = {
+    readonly harnessUpdate: boolean;
+};
+
+/**
+ * Normalized automatic coding-harness update-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedHarnessUpdateCliOptions = {
+    readonly isHarnessUpdateCheckEnabled: boolean;
+};
+
+/**
+ * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function addHarnessUpdateOption(command: Program): void {
+    command.option('--no-harness-update', 'Skip checking whether the installed coding harnesses are up to date');
+}
+
+/**
+ * Converts the Commander harness-update flag into the normalized harness-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function normalizeHarnessUpdateCliOptions(
+    cliOptions: HarnessUpdateCliOptions,
+): NormalizedHarnessUpdateCliOptions {
+    return {
+        isHarnessUpdateCheckEnabled: cliOptions.harnessUpdate,
+    };
+}
+
+// Note: [🟡] Code for CLI harness update options [harnessUpdateCliOptions](src/cli/cli-commands/common/harnessUpdateCliOptions.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

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

@@ -0,0 +1,15 @@
+import { $askForConfirmation } from '../$askForConfirmation';
+
+/**
+ * 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 or the terminal is not interactive
+ * @private internal utility of `promptbookCli`
+ */
+export async function $askForNpmPackageInstallationApproval(question: string): Promise<boolean> {
+    return $askForConfirmation(question);
+}
+
+// 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/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