@promptbook/cli 0.114.0-47 → 0.114.0-49

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

@@ -1,7 +1,4 @@
-import {
-    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
-    Option,
-} from 'commander';
+import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
@@ -10,6 +7,7 @@ import { $assertSufficientFreeDiskSpace } from '../common/disk-space/$assertSuff
 import { validateCoderRunOptions } from '../common/validateCoderRunOptions';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
@@ -29,13 +27,13 @@ import {
 } from '../common/promptRunnerCliOptions';
 import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import {
-    DEFAULT_CODER_TEST_COMMAND,
-    TEST_BEFORE_MODE_VALUES,
-    type TestBeforeMode,
-} from '../../../../scripts/run-codex-prompts/testing/TestBeforeMode';
+    resolveCoderCheckCommand,
+    type CheckBeforeMode,
+} from '../../../../scripts/run-codex-prompts/checks/CheckBeforeMode';
+import { addCoderCheckOptions, normalizeCheckCommandOption } from '../common/coderCheckCliOptions';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
-import { addCoderAgentOption, type CoderAgentCliOptions } from './agentCliOptions';
+import { addCoderExecutionOptions, type CoderAgentCliOptions } from './agentCliOptions';
 import { printCoderRunFailure } from './printCoderRunFailure';
 
 /**
@@ -75,8 +73,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             - Offers to add missing project-local ignore rules for the selected harness
             - 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
+            - Optional pre-coding check run that can stop or repair pre-existing failures
+            - Optional post-prompt checks with check-feedback retries
             - Progress tracking and interactive P/S/X terminal controls; O changes only the dashboard output view
             - Dry-run mode to preview prompts
         `,
@@ -86,25 +84,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
     addQuestionsOption(command);
-    addCoderAgentOption(command, 'developer');
-    command.option(
-        '--context <context-or-file>',
-        'Append extra instructions either inline or from a file path relative to the current project',
-    );
-    command.option(
-        '--test <test-command...>',
-        'Run a verification command after each prompt; quote it when the command itself contains top-level flags',
-    );
-    command.addOption(
-        new Option(
-            '--test-before <mode>',
-            `Run tests before coding: ${TEST_BEFORE_MODE_VALUES.join(
-                ', ',
-            )} (defaults to no; uses npm test when --test is omitted)`,
-        )
-            .choices([...TEST_BEFORE_MODE_VALUES])
-            .default('no'),
-    );
+    addCoderExecutionOptions(command);
+    addCoderCheckOptions(command, true);
     command.option(
         '--preserve-logs',
         'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics',
@@ -166,12 +147,13 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const {
                 dryRun,
                 agent,
                 context,
-                test,
-                testBefore,
+                check,
+                checkBefore,
                 preserveLogs,
                 isolate: isIsolated,
                 priority,
@@ -188,8 +170,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly dryRun: boolean;
                 readonly agent?: string;
                 readonly context?: string;
-                readonly test?: string | string[];
-                readonly testBefore: TestBeforeMode;
+                readonly check?: string | string[];
+                readonly checkBefore: CheckBeforeMode;
                 readonly preserveLogs: boolean;
                 readonly isolate: boolean;
                 readonly priority?: number;
@@ -205,8 +187,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             } & PromptRunnerCliOptions &
                 CoderAgentCliOptions;
 
-            const configuredTestCommand = normalizeCommandOptionValue(test);
-            const testCommand = configuredTestCommand ?? (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND);
+            const checkCommand = resolveCoderCheckCommand(normalizeCheckCommandOption(check), checkBefore);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
@@ -239,8 +220,8 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 model: runnerOptions.model,
                 agent,
                 context,
-                testCommand,
-                testBefore,
+                checkCommand,
+                checkBefore,
                 preserveLogs,
                 isIsolated,
                 noUi: runnerOptions.noUi,
@@ -260,20 +241,25 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
             validateCoderRunOptions(runOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: dryRun ? 'read-only' : 'mutate',
                 ...questionsOptions,
             });
 
+            const { resolveCoderProjectContext } = await import(
+                '../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext'
+            );
+            const projectContext = await resolveCoderProjectContext({
+                projectPath: workspace.projectPath,
+                agent,
+                context,
+            });
+
             if (!dryRun) {
-                // Reject missing or unreadable Books before offering installations or project configuration writes.
-                const { resolveCoderAgentBook } = await import(
-                    '../../../../scripts/run-codex-prompts/common/resolveCoderAgent'
-                );
-                await resolveCoderAgentBook(agent, workspace.projectPath, { defaultRole: 'developer' });
                 // Check disk space before installations and repository writes; previews require no setup.
                 await $assertSufficientFreeDiskSpace(workspace.projectPath);
 
-                if (await $ensurePromptbookCliInstallations(questionsOptions)) {
+                if (await $ensurePromptbookCliInstallations(questionsOptions, workspace.projectPath)) {
                     return process.exit(0);
                 }
 
@@ -289,8 +275,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             const { runCodexPrompts } = await import('../../../../scripts/run-codex-prompts/main/runCodexPrompts');
 
             try {
-                // Override process.argv to pass options to the legacy parseRunOptions if needed
-                await runCodexPrompts({ ...runOptions, workspace });
+                await runCodexPrompts({ ...runOptions, workspace, projectContext });
             } catch (error) {
                 assertsError(error);
                 printCoderRunFailure(error);
@@ -302,24 +287,5 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     );
 }
 
-/**
- * Joins one Commander option that may be parsed either as a single string or a variadic token array.
- *
- * @private internal utility of `coder run` command
- */
-function normalizeCommandOptionValue(value: string | string[] | undefined): string | undefined {
-    if (value === undefined) {
-        return undefined;
-    }
-
-    const parts = Array.isArray(value) ? value : [value];
-    const normalizedValue = parts
-        .map((part) => part.trim())
-        .filter(Boolean)
-        .join(' ')
-        .trim();
-    return normalizedValue === '' ? undefined : normalizedValue;
-}
-
 // Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -3,6 +3,7 @@ import {
     Option,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import { addCoderCheckOptions, normalizeCheckCommandOption } from '../common/coderCheckCliOptions';
 import { NETWORK_LIMITS } from '../../../constants';
 import { assertsError } from '../../../errors/assertsError';
 import { NotAllowed } from '../../../errors/NotAllowed';
@@ -12,6 +13,7 @@ import { $assertSufficientFreeDiskSpace } from '../common/disk-space/$assertSuff
 import { validateCoderRunOptions } from '../common/validateCoderRunOptions';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
@@ -31,7 +33,7 @@ import {
 import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
-import { addCoderAgentOption, type CoderAgentCliOptions } from './agentCliOptions';
+import { addCoderExecutionOptions, type CoderAgentCliOptions } from './agentCliOptions';
 import { printCoderRunFailure } from './printCoderRunFailure';
 
 /**
@@ -84,15 +86,8 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
     addQuestionsOption(command);
-    addCoderAgentOption(command, 'developer');
-    command.option(
-        '--context <context-or-file>',
-        'Append extra instructions either inline or from a file path relative to the current project',
-    );
-    command.option(
-        '--test <test-command...>',
-        'Run a verification command after each prompt; quote it when the command itself contains top-level flags',
-    );
+    addCoderExecutionOptions(command);
+    addCoderCheckOptions(command, false);
     command.option(
         '--preserve-logs',
         'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics',
@@ -139,12 +134,13 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const {
                 port: rawPort,
                 dryRun,
                 agent,
                 context,
-                test,
+                check,
                 preserveLogs,
                 priority,
                 minPriority: minimumPriority,
@@ -160,7 +156,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 readonly dryRun: boolean;
                 readonly agent?: string;
                 readonly context?: string;
-                readonly test?: string | string[];
+                readonly check?: string | string[];
                 readonly preserveLogs: boolean;
                 readonly priority?: number;
                 readonly minPriority?: number;
@@ -175,7 +171,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 CoderAgentCliOptions;
 
             const port = parseCoderServerPort(rawPort);
-            const testCommand = normalizeCommandOptionValue(test);
+            const checkCommand = normalizeCheckCommandOption(check);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
@@ -203,7 +199,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 model: runnerOptions.model,
                 agent,
                 context,
-                testCommand,
+                checkCommand,
                 preserveLogs,
                 noUi: runnerOptions.noUi,
                 thinkingLevel: runnerOptions.thinkingLevel,
@@ -221,16 +217,21 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
 
             validateCoderRunOptions(runOptions);
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: dryRun ? 'read-only' : 'mutate',
                 ...questionsOptions,
             });
 
+            const { resolveCoderProjectContext } = await import(
+                '../../../../scripts/run-codex-prompts/common/resolveCoderProjectContext'
+            );
+            const projectContext = await resolveCoderProjectContext({
+                projectPath: workspace.projectPath,
+                agent,
+                context,
+            });
+
             if (!dryRun) {
-                // Reject missing or unreadable Books before offering installations or project configuration writes.
-                const { resolveCoderAgentBook } = await import(
-                    '../../../../scripts/run-codex-prompts/common/resolveCoderAgent'
-                );
-                await resolveCoderAgentBook(agent, workspace.projectPath, { defaultRole: 'developer' });
                 // Check disk space before installations and repository writes; previews require no setup.
                 await $assertSufficientFreeDiskSpace(workspace.projectPath);
 
@@ -248,7 +249,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
             );
 
             try {
-                await runCodexPromptsServer({ ...runOptions, workspace });
+                await runCodexPromptsServer({ ...runOptions, workspace, projectContext });
             } catch (error) {
                 assertsError(error);
                 printCoderRunFailure(error);
@@ -281,24 +282,5 @@ function parseCoderServerPort(rawPort: string): number_port {
     return port as number_port;
 }
 
-/**
- * Joins one Commander option that may be parsed either as a single string or a variadic token array.
- *
- * @private internal utility of `coder server` command
- */
-function normalizeCommandOptionValue(value: string | string[] | undefined): string | undefined {
-    if (value === undefined) {
-        return undefined;
-    }
-
-    const parts = Array.isArray(value) ? value : [value];
-    const normalizedValue = parts
-        .map((part) => part.trim())
-        .filter(Boolean)
-        .join(' ')
-        .trim();
-    return normalizedValue === '' ? undefined : normalizedValue;
-}
-
 // Note: [🟡] Code for CLI command [server](src/cli/cli-commands/coder/server.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -20,6 +20,7 @@ import {
 } from '../common/coderGitSyncCliOptions';
 import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
 import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -81,6 +82,7 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { order, ignore } = cliOptions as {
                 readonly order: VerifyPromptsOrder;
                 readonly ignore: ReadonlyArray<string>;
@@ -89,6 +91,7 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
 
             const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
                 policy: 'mutate',
                 isAskingQuestionsEnabled: cliOptions.questions,
             });

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

@@ -24,7 +24,7 @@ import { $initializeCoderVerifyCommand } from './coder/verify';
  * The coder command provides utilities for automated coding:
  * - init: Initialize coder configuration in current project
  * - add: Add one ready-to-run prompt file to the queue
- * - plan: Discuss features with Planner and author reviewed PRDs
+ * - plan: Discuss features with Developer and author reviewed PRDs
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
  * - list: List ready prompts in priority order without running them
@@ -46,7 +46,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             Subcommands:
             - init: Initialize coder configuration in current project
             - add: Add one ready-to-run prompt file to the queue
-            - plan: Discuss features with Planner and author reviewed PRDs
+            - plan: Discuss features with Developer and author reviewed PRDs
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
             - find-unwritten: List prompt sections that still need to be authored

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

@@ -0,0 +1,107 @@
+import { Command, Option } from 'commander';
+import { spaceTrim } from 'spacetrim';
+import { CHECK_BEFORE_MODE_VALUES } from '../../../../scripts/run-codex-prompts/checks/CheckBeforeMode';
+import { quoteBashArgument } from '../../../../scripts/run-codex-prompts/common/runGoScript/quoteBashArgument';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/** Standalone shell composition tokens remain operators when a command is supplied as several arguments. */
+const SHELL_COMPOSITION_TOKENS = new Set([
+    '&&',
+    '||',
+    '|',
+    '|&',
+    '&',
+    ';',
+    '(',
+    ')',
+    '>',
+    '>>',
+    '<',
+    '2>',
+    '2>>',
+    '2>&1',
+]);
+
+/**
+ * Retired aggregate option spellings and their canonical replacements, used only for migration diagnostics.
+ * @private shared CLI migration definitions for Coder execution
+ */
+export const LEGACY_CODER_CHECK_OPTIONS = [
+    ['--test', '--check'],
+    ['--test-before', '--check-before'],
+] as const;
+
+/**
+ * Registers the shared project check command and rejects retired aggregate-test spellings.
+ * @private shared CLI registration for Coder execution
+ */
+export function addCoderCheckOptions(command: Command, isCheckBeforeSupported: boolean): void {
+    command.option(
+        '--check <check-command...>',
+        'Run project checks after each prompt; quote the full command when it contains flags or shell composition',
+    );
+    if (isCheckBeforeSupported) {
+        command.addOption(
+            new Option(
+                '--check-before <mode>',
+                `Check before coding: ${CHECK_BEFORE_MODE_VALUES.join(
+                    ', ',
+                )} (defaults to no; uses npm run check when --check is omitted)`,
+            )
+                .choices([...CHECK_BEFORE_MODE_VALUES])
+                .default('no'),
+        );
+    }
+
+    // These diagnostic-only options never forward a value or start execution.
+    for (const [legacyFlag, replacementFlag] of LEGACY_CODER_CHECK_OPTIONS) {
+        command.addOption(new Option(`${legacyFlag} [value...]`).hideHelp());
+        command.on(`option:${legacyFlag.slice(2)}`, () => {
+            command.error(formatLegacyCoderCheckOptionError(legacyFlag, replacementFlag));
+        });
+    }
+}
+
+/**
+ * Builds the same actionable migration diagnostic for registered and direct-script entrypoints.
+ * @private shared CLI diagnostic for Coder execution
+ */
+export function formatLegacyCoderCheckOptionError(legacyFlag: string, replacementFlag: string): string {
+    return `Aggregate verification option \`${legacyFlag}\` was renamed to \`${replacementFlag}\`. Update your command and package.json scripts.`;
+}
+
+/**
+ * Normalizes shell command tokens without parsing a quoted command again or losing spaced argument boundaries.
+ * @private shared command normalization for Coder execution
+ */
+export function normalizeCheckCommandOption(value: string | ReadonlyArray<string> | undefined): string | undefined {
+    if (value === undefined) return undefined;
+    const parts = typeof value === 'string' ? [value] : value;
+    const firstPart = parts[0]?.trim() ?? '';
+    for (const [legacyFlag, replacementFlag] of LEGACY_CODER_CHECK_OPTIONS) {
+        if (firstPart === legacyFlag || firstPart.startsWith(`${legacyFlag}=`)) {
+            throw new NotAllowed(formatLegacyCoderCheckOptionError(legacyFlag, replacementFlag));
+        }
+    }
+    const command =
+        parts.length === 1
+            ? parts[0]!.trim()
+            : parts
+                  .map((part) =>
+                      !SHELL_COMPOSITION_TOKENS.has(part) && (!part || /[\s'"\\$`;&|<>()*?]/u.test(part))
+                          ? quoteBashArgument(part)
+                          : part,
+                  )
+                  .join(' ')
+                  .trim();
+    if (!command || !firstPart || firstPart.startsWith('-')) {
+        throw new NotAllowed(
+            spaceTrim(`
+            Option \`--check\` requires a non-empty shell command, for example \`--check "npm run check"\`.
+        `),
+        );
+    }
+    return command;
+}
+
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

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/promptbook-cli/$checkPromptbookCliInstallations.ts

@@ -14,8 +14,10 @@ import type {
  *
  * @private internal utility of `promptbookCli`
  */
-export async function $checkPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallationStatus>> {
-    const installations = await $resolvePromptbookCliInstallations();
+export async function $checkPromptbookCliInstallations(
+    projectPath = process.cwd(),
+): Promise<ReadonlyArray<PromptbookCliInstallationStatus>> {
+    const installations = await $resolvePromptbookCliInstallations(projectPath);
 
     if (installations.length === 0) {
         return [];

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

@@ -23,6 +23,7 @@ import { formatPromptbookCliInstallationWarning } from './formatPromptbookCliIns
  */
 export async function $ensurePromptbookCliInstallations(
     questionsOptions: NormalizedQuestionsCliOptions,
+    projectPath = process.cwd(),
 ): Promise<boolean> {
     if (!questionsOptions.isAskingQuestionsEnabled) {
         // Note: `--no-questions` forbids asking for the approval, so the registry checks would be useless
@@ -34,7 +35,7 @@ export async function $ensurePromptbookCliInstallations(
         return false;
     }
 
-    const statuses = await $checkPromptbookCliInstallations();
+    const statuses = await $checkPromptbookCliInstallations(projectPath);
     const outdatedStatuses = statuses.filter(({ installationState }) => installationState === 'outdated');
 
     if (outdatedStatuses.length === 0) {
@@ -57,7 +58,7 @@ export async function $ensurePromptbookCliInstallations(
     const updateResults: Array<boolean> = [];
 
     for (const status of outdatedStatuses) {
-        updateResults.push(await $updatePromptbookCliInstallation(status));
+        updateResults.push(await $updatePromptbookCliInstallation(status, projectPath));
     }
 
     const isAnyInstallationUpdated = updateResults.some(Boolean);

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

@@ -41,9 +41,11 @@ type JsonObject = Readonly<Record<string, unknown>>;
  *
  * @private internal utility of `promptbookCli`
  */
-export async function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>> {
+export async function $resolvePromptbookCliInstallations(
+    projectPath = process.cwd(),
+): Promise<ReadonlyArray<PromptbookCliInstallation>> {
     const [localInstallations, globalInstallations] = await Promise.all([
-        $resolveLocalPromptbookCliInstallations(),
+        $resolveLocalPromptbookCliInstallations(projectPath),
         $resolveGlobalPromptbookCliInstallations(),
     ]);
 
@@ -53,8 +55,10 @@ export async function $resolvePromptbookCliInstallations(): Promise<ReadonlyArra
 /**
  * Finds the closest ancestor `package.json` which directly declares a Promptbook CLI package.
  */
-async function $resolveLocalPromptbookCliInstallations(): Promise<ReadonlyArray<LocalPromptbookCliInstallation>> {
-    let candidateProjectPath = resolve(process.cwd());
+async function $resolveLocalPromptbookCliInstallations(
+    projectPath: string,
+): Promise<ReadonlyArray<LocalPromptbookCliInstallation>> {
+    let candidateProjectPath = resolve(projectPath);
     let isFileSystemRootReached = false;
 
     while (!isFileSystemRootReached) {

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

@@ -13,10 +13,13 @@ import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallatio
  * @returns `true` when the package update succeeds, `false` when it fails
  * @private internal utility of `promptbookCli`
  */
-export async function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean> {
+export async function $updatePromptbookCliInstallation(
+    status: PromptbookCliInstallationStatus,
+    projectPath = process.cwd(),
+): Promise<boolean> {
     const { npmPackageName, installationLocation } = status.installation;
     const installCommand = buildPromptbookCliInstallCommand(status.installation);
-    const updateWorkingDirectory = installationLocation === 'global' ? process.cwd() : status.installation.projectPath;
+    const updateWorkingDirectory = installationLocation === 'global' ? projectPath : status.installation.projectPath;
 
     console.info(colors.cyan(`Updating Promptbook CLI package \`${npmPackageName}\` with \`${installCommand}\`...`));