@promptbook/cli 0.114.0-5 → 0.114.0-7

package/src/cli/cli-commands/coder/add.ts

@@ -102,11 +102,11 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
             const description = await resolveCoderPromptDescription(descriptionArgument);
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
 
             const { /* filePath,*/ emojiTag } = await addCoderPrompt({
                 projectPath,
@@ -117,7 +117,7 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
 
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: `${emojiTag} Add prompt`,
             });
         }),

package/src/cli/cli-commands/coder/boilerplateCount.ts

@@ -29,7 +29,7 @@ export type BoilerplateCount = {
      * Number of prompts written into each generated file.
      *
      * Note: More than one prompt per file is an advanced option - each prompt is one separate
-     *       coding task separated by `---` and tagged with its own fresh emoji tag.
+     *       coding task separated by `---`, with all prompts in the file sharing its fresh emoji tag.
      */
     readonly promptsPerFileCount: number;
 };

package/src/cli/cli-commands/coder/generate-boilerplates.ts

@@ -39,7 +39,7 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
     command.description(
         spaceTrim(
             (block) => `
-                Generate prompt boilerplate files with unique emoji tags
+                Generate prompt boilerplate files with one unique emoji tag per file
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
             `,
@@ -71,11 +71,11 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
             const projectPath = process.cwd();
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
 
             await generatePromptBoilerplate({
                 projectPath,
@@ -85,7 +85,7 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
 
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: `Prompts ${formatBoilerplateCount(boilerplateCount)}`,
             });
 
@@ -95,7 +95,7 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
 }
 
 /**
- * Generates boilerplate prompt files with unique emoji tags.
+ * Generates boilerplate prompt files with one unique emoji tag per file.
  *
  * @private internal function of `generatePromptBoilerplate` command
  */
@@ -134,10 +134,10 @@ export async function generatePromptBoilerplate({
         colors.blue(`Highest existing number for ${promptNumbering.datePrefix} found: ${highestNumberFormatted}`),
     );
 
-    // Note: Every single generated prompt is one separate coding task, so each of them reserves its own fresh emoji tag
     const promptsCount = filesCount * promptsPerFileCount;
     const { availableCount, selectedEmojis } = await getFreshPromptEmojiTags({
-        count: promptsCount,
+        // Note: Each generated file reserves one fresh emoji tag shared by all of its prompt sections
+        count: filesCount,
         rootDir: projectPath,
     });
 
@@ -154,9 +154,7 @@ export async function generatePromptBoilerplate({
     for (let i = 0; i < filesCount; i++) {
         const number = promptNumbering.startNumber + i * promptNumbering.step;
         const title = titles[i % titles.length]!;
-        const emojiTags = selectedEmojis
-            .slice(i * promptsPerFileCount, (i + 1) * promptsPerFileCount)
-            .map((emoji) => formatPromptEmojiTag(emoji));
+        const emojiTag = formatPromptEmojiTag(selectedEmojis[i]!);
         const filename = buildPromptFilename(
             promptNumbering.datePrefix,
             number,
@@ -165,7 +163,8 @@ export async function generatePromptBoilerplate({
         const filepath = join(PROMPTS_DIRECTORY_PATH, filename);
         const absoluteFilepath = join(projectPath, filepath);
         const content = buildBoilerplatePromptFileContent({
-            emojiTags,
+            emojiTag,
+            promptsPerFileCount,
             title,
             body: promptTemplate.content,
         });
@@ -175,7 +174,7 @@ export async function generatePromptBoilerplate({
             absoluteFilepath,
             filename,
             content,
-            emojiTags,
+            emojiTag,
             number,
         });
     }
@@ -185,7 +184,7 @@ export async function generatePromptBoilerplate({
 
     for (const file of filesToCreate) {
         writeFileSync(file.absoluteFilepath, file.content, 'utf-8');
-        console.info(colors.green(`✓ Created: ${file.filename} with ${file.emojiTags.join(' ')}`));
+        console.info(colors.green(`✓ Created: ${file.filename} with ${file.emojiTag}`));
     }
 
     console.info(
@@ -196,31 +195,32 @@ export async function generatePromptBoilerplate({
 }
 
 /**
- * Builds the markdown content of one generated prompt file with one prompt section per emoji tag.
+ * Builds the markdown content of one generated prompt file with one prompt section per prompt.
  *
- * Multiple prompts in one file are separated by the `---` separator, exactly like the prompt runner expects them.
+ * Multiple prompts in one file share the file emoji tag and are separated by the `---` separator,
+ * exactly like the prompt runner expects them.
  *
  * @private internal utility of `generatePromptBoilerplate` command
  */
 function buildBoilerplatePromptFileContent({
-    emojiTags,
+    emojiTag,
+    promptsPerFileCount,
     title,
     body,
 }: {
-    readonly emojiTags: ReadonlyArray<string>;
+    readonly emojiTag: string;
+    readonly promptsPerFileCount: number;
     readonly title: string;
     readonly body: string;
 }): string {
-    return emojiTags
-        .map((emojiTag) =>
-            buildCoderPromptSection({
-                statusLine: '[-]',
-                emojiTag,
-                title,
-                body,
-            }),
-        )
-        .join('\n\n---\n\n');
+    return Array.from({ length: promptsPerFileCount }, () =>
+        buildCoderPromptSection({
+            statusLine: '[-]',
+            emojiTag,
+            title,
+            body,
+        }),
+    ).join('\n\n---\n\n');
 }
 
 /**

package/src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts

@@ -4,12 +4,13 @@ import { DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE } from './boilerplateCount';
  * Default npm scripts initialized by `ptbk coder init`.
  */
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
-    'coder:generate-boilerplates': `ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ./prompts/templates/common.md`,
-    'coder:add': 'ptbk coder add --template ./prompts/templates/common.md',
+    // Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
+    'coder:generate-boilerplates': `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ./prompts/templates/common.md`,
+    'coder:add': 'npx ptbk coder add --template ./prompts/templates/common.md',
     'coder:run':
-        'ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
+        'npx ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
     // 'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
-    'coder:verify': 'ptbk coder verify',
+    'coder:verify': 'npx ptbk coder verify',
 } as const satisfies Readonly<Record<string, string>>;
 
 /**

package/src/cli/cli-commands/coder/init.ts

@@ -82,11 +82,11 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
             const projectPath = process.cwd();
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
 
             const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
@@ -94,7 +94,7 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
 
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: 'Initialize Promptbook Coder',
             });
 

package/src/cli/cli-commands/coder/run.ts

@@ -10,6 +10,7 @@ import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativ
 import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import { $ensurePromptbookCliInstallations } from '../common/promptbook-cli/$ensurePromptbookCliInstallations';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -41,12 +42,14 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
             Features:
             - Automatically stages and commits changes with agent identity unless --no-commit is used
+            - Commits only the prompt file and the files the coding agent has changed, leaving unrelated changes alone
             - Optional post-commit git push with explicit --auto-push opt-in
             - Optional pre-prompt git pull with explicit --auto-pull opt-in
             - Optional --isolate runs every prompt in its own temporary git worktree and merges it back when verified
             - Optional --preserve-logs keeps temp prompt/log artifacts after successful rounds
             - Optional --no-ui keeps plain streaming console output for logging and debugging
             - Checks that the selected harness is installed globally and up to date before the first prompt
+            - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
             - Optional pre-coding test run that can stop or repair pre-existing failures
             - Optional post-prompt verification with test-feedback retries
@@ -196,8 +199,6 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 isAgentRequired: !dryRun,
             });
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
-
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
             //   --no-auto: wait for user confirmation before each prompt (interactive mode)
@@ -205,6 +206,13 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             //   --wait-between-prompts: pace from start of one prompt to start of next
             //   --wait-after-error: wait before retrying after an error (default 10m)
             const waitForUser = !auto;
+
+            if (waitForUser && (await $ensurePromptbookCliInstallations())) {
+                return process.exit(0);
+            }
+
+            await $ensureHarnessInstallations([runnerOptions.agentName]);
+
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);

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

@@ -26,7 +26,7 @@ export type CoderGitSyncCliOptions = {
 export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
     Git synchronization:
     - --auto-pull pulls the latest changes before this command changes anything
-    - --commit commits the changes made by this command
+    - --commit commits only the files this command has changed, unrelated changes stay in the working tree
     - --auto-push pushes the created commit to the remote repository
 `);
 
@@ -39,7 +39,11 @@ export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
  * @private internal utility of `promptbookCli`
  */
 export function addCoderGitSyncOptions(command: Program): void {
-    command.option('--commit', 'Commit the changes made by this command with the coding-agent git identity', false);
+    command.option(
+        '--commit',
+        'Commit the files changed by this command with the coding-agent git identity, leaving unrelated changes uncommitted',
+        false,
+    );
     command.option('--auto-push', 'Automatically git push the created commit, requires --commit', false);
     command.option(
         '--auto-pull',

package/src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.ts

@@ -1,5 +1,5 @@
 import colors from 'colors';
-import { $askForHarnessInstallationApproval } from './$askForHarnessInstallationApproval';
+import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
 import { $installHarness } from './$installHarness';
 import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
@@ -31,7 +31,7 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
 
     console.warn(colors.yellow(formatHarnessInstallationWarning(status)));
 
-    const isInstallationApproved = await $askForHarnessInstallationApproval(
+    const isInstallationApproved = await $askForNpmPackageInstallationApproval(
         installationState === 'not-installed'
             ? `Install ${definition.label} globally now?`
             : `Update ${definition.label} to ${latestVersion} now?`,

package/src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts

@@ -1,8 +1,8 @@
 import { $resolveInstalledHarnessVersion } from './$resolveInstalledHarnessVersion';
-import { $resolveLatestHarnessVersion } from './$resolveLatestHarnessVersion';
+import { $resolveLatestNpmPackageVersion } from '../npm/$resolveLatestNpmPackageVersion';
 import type { HarnessDefinition } from './HarnessDefinition';
 import type { HarnessInstallationState, HarnessInstallationStatus } from './HarnessInstallationStatus';
-import { isHarnessVersionOutdated } from './isHarnessVersionOutdated';
+import { isNpmPackageVersionOutdated } from '../npm/isNpmPackageVersionOutdated';
 
 /**
  * Detects whether one CLI coding harness is installed globally and whether it is up to date.
@@ -14,7 +14,7 @@ import { isHarnessVersionOutdated } from './isHarnessVersionOutdated';
 export async function $checkHarnessInstallation(definition: HarnessDefinition): Promise<HarnessInstallationStatus> {
     const [installedVersion, latestVersion] = await Promise.all([
         $resolveInstalledHarnessVersion(definition),
-        $resolveLatestHarnessVersion(definition),
+        $resolveLatestNpmPackageVersion(definition.npmPackageName),
     ]);
 
     return {
@@ -40,7 +40,7 @@ function resolveHarnessInstallationState(
         return 'unknown';
     }
 
-    return isHarnessVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
+    return isNpmPackageVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
 }
 
 // Note: [🟡] Code for CLI harness installation check [$checkHarnessInstallation](src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/$resolveInstalledHarnessVersion.ts

@@ -1,5 +1,5 @@
 import { $execCommand } from '../../../../utils/execCommand/$execCommand';
-import { extractHarnessVersionFromOutput } from './extractHarnessVersionFromOutput';
+import { extractNpmPackageVersionFromOutput } from '../npm/extractNpmPackageVersionFromOutput';
 import type { HarnessDefinition } from './HarnessDefinition';
 
 /**
@@ -23,7 +23,7 @@ export async function $resolveInstalledHarnessVersion(definition: HarnessDefinit
         isVerbose: false,
     }).catch(() => '');
 
-    return extractHarnessVersionFromOutput(output);
+    return extractNpmPackageVersionFromOutput(output);
 }
 
 // Note: [🟡] Code for CLI harness version detection [$resolveInstalledHarnessVersion](src/cli/cli-commands/common/harness/$resolveInstalledHarnessVersion.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/{harness/$askForHarnessInstallationApproval.ts → npm/$askForNpmPackageInstallationApproval.ts}

@@ -2,14 +2,14 @@ import colors from 'colors';
 import { createInterface } from 'readline';
 
 /**
- * Asks the user in the terminal whether the harness should be installed or updated right now.
+ * 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 $askForHarnessInstallationApproval(question: string): Promise<boolean> {
+export async function $askForNpmPackageInstallationApproval(question: string): Promise<boolean> {
     if (!process.stdin.isTTY) {
         // Note: In non-interactive environments like CI there is nobody who could confirm the installation
         return false;
@@ -28,4 +28,4 @@ export async function $askForHarnessInstallationApproval(question: string): Prom
     }
 }
 
-// Note: [🟡] Code for CLI harness installation approval [$askForHarnessInstallationApproval](src/cli/cli-commands/common/harness/$askForHarnessInstallationApproval.ts) should never be published outside of `@promptbook/cli`
+// 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/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 JSON 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/{harness/isHarnessVersionOutdated.ts → npm/isNpmPackageVersionOutdated.ts}

@@ -1,12 +1,12 @@
 /**
- * Compares the installed harness version with the newest version published to npm.
+ * Compares an installed npm package version with the newest published version.
  *
  * Only the numeric `major.minor.patch` segments are compared and pre-release suffixes are ignored,
- * so a harness installed from a pre-release build of the newest version is not reported as outdated.
+ * so a package installed from a pre-release build of the newest version is not reported as outdated.
  *
  * @private internal utility of `promptbookCli`
  */
-export function isHarnessVersionOutdated(installedVersion: string, latestVersion: string): boolean {
+export function isNpmPackageVersionOutdated(installedVersion: string, latestVersion: string): boolean {
     const installedSegments = parseVersionSegments(installedVersion);
     const latestSegments = parseVersionSegments(latestVersion);
     const segmentCount = Math.max(installedSegments.length, latestSegments.length);
@@ -25,6 +25,8 @@ export function isHarnessVersionOutdated(installedVersion: string, latestVersion
 
 /**
  * Splits one version into its numeric segments, dropping the pre-release and build suffix.
+ *
+ * @private internal utility of `isNpmPackageVersionOutdated`
  */
 function parseVersionSegments(version: string): ReadonlyArray<number> {
     const [numericVersion = ''] = version.trim().split(/[-+]/u);
@@ -36,4 +38,4 @@ function parseVersionSegments(version: string): ReadonlyArray<number> {
     });
 }
 
-// Note: [🟡] Code for CLI harness version comparison [isHarnessVersionOutdated](src/cli/cli-commands/common/harness/isHarnessVersionOutdated.ts) should never be published outside of `@promptbook/cli`
+// 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,73 @@
+import { $resolveLatestNpmPackageVersion } from '../npm/$resolveLatestNpmPackageVersion';
+import { isNpmPackageVersionOutdated } from '../npm/isNpmPackageVersionOutdated';
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+import type {
+    PromptbookCliInstallationState,
+    PromptbookCliInstallationStatus,
+} from './PromptbookCliInstallationStatus';
+import { $resolvePromptbookCliInstallations } from './$resolvePromptbookCliInstallations';
+
+/**
+ * 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.
+ *
+ * @private internal utility of `$checkPromptbookCliInstallations`
+ */
+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.
+ *
+ * @private internal utility of `$checkPromptbookCliInstallations`
+ */
+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`