@promptbook/components 0.114.0-4 → 0.114.0-40

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

@@ -1,9 +1,10 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 /**
  * Reports one detected harness installation status and offers to install or update the harness.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs npm packages
+ * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs software
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void>;
+export declare function $applyHarnessInstallationStatus(status: HarnessInstallationStatus, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

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

@@ -1,10 +1,10 @@
 import type { HarnessDefinition } from './HarnessDefinition';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 /**
- * Detects whether one CLI coding harness is installed globally and whether it is up to date.
+ * Detects whether one CLI coding harness is installed globally and, when enabled, whether it is up to date.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and queries npm
+ * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and may query npm
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $checkHarnessInstallation(definition: HarnessDefinition): Promise<HarnessInstallationStatus>;
+export declare function $checkHarnessInstallation(definition: HarnessDefinition, isHarnessUpdateCheckEnabled?: boolean): Promise<HarnessInstallationStatus>;

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

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/harness/$ensureHarnessInstallations.d.ts

@@ -1,7 +1,8 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
 /**
- * Checks that every given CLI coding harness is installed globally and up to date and offers to
- * install or update the ones which are not.
+ * Checks that every given CLI coding harness is installed globally and, when the questions are enabled, up to date.
+ * Offers to install missing harnesses and update outdated ones.
  *
  * Harness names which are `undefined`, for example when no `--harness` is selected in a dry run,
  * are ignored so that every call site can pass its raw selection.
@@ -10,4 +11,4 @@ import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>): Promise<void>;
+export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>, questionsOptions: NormalizedQuestionsCliOptions): Promise<void>;

package/esm/src/cli/cli-commands/common/harness/$resolveHarnessCommandPath.d.ts

@@ -0,0 +1,14 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * Finds out which file is really executed when the harness command runs.
+ *
+ * The lookup deliberately uses the very same `PATH` which runs the harness, so it reports the copy of the
+ * harness which Promptbook itself would use. Symbolic links are followed, because installers like the
+ * standalone OpenAI Codex installer only link their package into a directory on `PATH`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs a command in a shell
+ *
+ * @returns Resolved path of the harness command or `null` when the command is not available
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveHarnessCommandPath(definition: HarnessDefinition): Promise<string | null>;

package/esm/src/cli/cli-commands/common/harness/$resolveHarnessInstallationOrigin.d.ts

@@ -0,0 +1,10 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
+/**
+ * Finds out where one CLI coding harness is really installed and which tool manages it.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs shell commands
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveHarnessInstallationOrigin(definition: HarnessDefinition): Promise<HarnessInstallationOrigin>;

package/esm/src/cli/cli-commands/common/harness/$runHarnessInstallationCommand.d.ts

@@ -0,0 +1,43 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * What one harness installation command does with the harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOperation = 'install' | 'update';
+/**
+ * Options of one command which installs or updates a CLI coding harness.
+ *
+ * @private internal utility of `$runHarnessInstallationCommand`
+ */
+type HarnessInstallationCommandOptions = {
+    /**
+     * Harness which is installed or updated.
+     */
+    readonly definition: HarnessDefinition;
+    /**
+     * What the command does with the harness.
+     */
+    readonly operation: HarnessInstallationOperation;
+    /**
+     * Shell command which does it.
+     */
+    readonly command: string;
+    /**
+     * Extra environment variables required by the command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};
+/**
+ * Runs one command which installs or updates a CLI coding harness.
+ *
+ * A failed installation is reported but never aborts the running command, because the harness check
+ * is only an assistant - the command itself may still work with a manually managed harness.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs software
+ *
+ * @returns `true` when the command succeeded, `false` when it failed
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $runHarnessInstallationCommand(options: HarnessInstallationCommandOptions): Promise<boolean>;
+export {};

package/esm/src/cli/cli-commands/common/harness/HarnessDefinition.d.ts

@@ -1,4 +1,46 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+/**
+ * Description of a standalone *(self-managed)* installation of one CLI coding harness.
+ *
+ * Some harnesses are also distributed by their own installer which puts the harness outside of npm and
+ * updates it in place. Such an installation must never be updated with `npm install -g`, because that
+ * installs a second copy of the harness instead of updating the one which is really used.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessStandaloneInstallation = {
+    /**
+     * Directory names which appear in the resolved path of a standalone installation of the harness,
+     * for example `.codex` in `~/.codex/packages/standalone/current/bin/codex`.
+     */
+    readonly directoryNames: ReadonlyArray<string>;
+    /**
+     * Command which updates the standalone installation in place.
+     */
+    readonly updateCommand: string;
+};
+/**
+ * Description of how the user signs in to one CLI coding harness again.
+ *
+ * Every harness refuses to work once its login is missing or its session has expired, and each of them is
+ * signed in differently - some have a dedicated login command, others sign in from their own interactive UI.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessAuthenticationMethod = {
+    /**
+     * Command which starts the sign-in flow of the harness.
+     */
+    readonly command: string;
+    /**
+     * Step which finishes the sign-in inside the started command.
+     *
+     * Harnesses which sign in from their own interactive user interface leave the user in that interface, so
+     * naming just the command would not be enough to get them signed in. Harnesses with a dedicated login
+     * command leave this undefined.
+     */
+    readonly interactiveStep?: string;
+};
 /**
  * Static description of one supported CLI coding harness.
  *
@@ -25,6 +67,20 @@ export type HarnessDefinition = {
      * Extra environment variables required by the global npm installation of this harness.
      */
     readonly npmInstallEnvironment?: Readonly<Record<string, string>>;
+    /**
+     * Project-local files or directories which this harness can create and which should not be committed.
+     */
+    readonly projectGitignoreRules: ReadonlyArray<string>;
+    /**
+     * How the user signs in to this harness again after its login is missing or has expired.
+     */
+    readonly authenticationMethod: HarnessAuthenticationMethod;
+    /**
+     * How a standalone installation of this harness is recognized and updated.
+     *
+     * Harnesses which are distributed only through npm leave this undefined.
+     */
+    readonly standaloneInstallation?: HarnessStandaloneInstallation;
 };
 /**
  * Single source of truth about how each supported CLI coding harness is installed and detected.
@@ -38,3 +94,9 @@ export declare const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessNam
  * @private internal utility of `promptbookCli`
  */
 export declare function getHarnessDefinition(harnessName: PromptRunnerHarnessName): HarnessDefinition;
+/**
+ * Lists the unique project ignore rules required by the selected harnesses, in selection order.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function getHarnessProjectGitignoreRules(harnessNames: ReadonlyArray<PromptRunnerHarnessName>): ReadonlyArray<string>;

package/esm/src/cli/cli-commands/common/harness/HarnessInstallationOrigin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Way in which the globally available harness command got onto the current machine.
+ *
+ * - `npm-global` the command comes from a global npm installation, so `npm install -g` really updates it
+ * - `standalone` the command was installed by the own installer of the harness and updates itself in place
+ * - `homebrew` the command is managed by Homebrew, so only `brew` may update it
+ * - `unknown` the command lives somewhere else or could not be located at all
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationMethod = 'npm-global' | 'standalone' | 'homebrew' | 'unknown';
+/**
+ * Place where the harness command really lives together with the way it was installed there.
+ *
+ * Knowing the origin is what keeps an update from installing a **second** copy of a harness which is
+ * managed outside of npm, for example the standalone installation of OpenAI Codex.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOrigin = {
+    /**
+     * Resolved path of the harness command with every symbolic link followed
+     * or `null` when the command could not be located.
+     */
+    readonly commandPath: string | null;
+    /**
+     * Way in which the harness command was installed.
+     */
+    readonly installationMethod: HarnessInstallationMethod;
+};
+/**
+ * Origin used when the harness command was not looked up at all, for example when the update check is disabled.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const UNKNOWN_HARNESS_INSTALLATION_ORIGIN: HarnessInstallationOrigin;

package/esm/src/cli/cli-commands/common/harness/HarnessInstallationStatus.d.ts

@@ -1,15 +1,17 @@
 import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
 /**
  * Result of comparing the globally installed harness version with the newest published one.
  *
  * - `up-to-date` the newest published version is installed
  * - `outdated` an older version is installed
  * - `not-installed` the harness command is not available globally
+ * - `installed` the harness is installed and automatic update checking was disabled
  * - `unknown` the harness is installed but the newest published version could not be resolved, for example when offline
  *
  * @private internal utility of `promptbookCli`
  */
-export type HarnessInstallationState = 'up-to-date' | 'outdated' | 'not-installed' | 'unknown';
+export type HarnessInstallationState = 'up-to-date' | 'outdated' | 'not-installed' | 'installed' | 'unknown';
 /**
  * Installation state of one CLI coding harness on the current machine.
  *
@@ -21,7 +23,7 @@ export type HarnessInstallationStatus = {
      */
     readonly definition: HarnessDefinition;
     /**
-     * Comparison of the installed version with the newest published one.
+     * Installation state, including whether the newest published version was checked.
      */
     readonly installationState: HarnessInstallationState;
     /**
@@ -32,4 +34,8 @@ export type HarnessInstallationStatus = {
      * Newest version published to npm or `null` when it could not be resolved.
      */
     readonly latestVersion: string | null;
+    /**
+     * Place where the harness command lives together with the way it was installed there.
+     */
+    readonly installationOrigin: HarnessInstallationOrigin;
 };

package/esm/src/cli/cli-commands/common/harness/HarnessUpdatePlan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How an outdated CLI coding harness can be brought up to date where it is really installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdatePlan = {
+    /**
+     * Command which updates the harness in place
+     * or `null` when the installation is not understood well enough to name one.
+     */
+    readonly command: string | null;
+    /**
+     * Whether Promptbook may run the command itself instead of only printing it.
+     *
+     * Only installations which Promptbook can update without any side effect are updated automatically,
+     * everything else is left to the user together with the instructions.
+     */
+    readonly isRunnableByPromptbook: boolean;
+    /**
+     * Extra environment variables required by the update command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};

package/esm/src/cli/cli-commands/common/harness/buildHarnessInstallCommand.d.ts

@@ -2,9 +2,12 @@ import type { HarnessDefinition } from './HarnessDefinition';
 /**
  * Builds the shell command which installs or updates one CLI coding harness globally.
  *
- * The very same command is executed by `$installHarness` and printed as the manual fallback,
+ * The very same command is executed by `$runHarnessInstallationCommand` and printed as the manual fallback,
  * so the user always sees exactly what Promptbook would run.
  *
+ * Note: This command installs the harness through npm, so it may only update a harness which npm really owns,
+ * see `resolveHarnessUpdatePlan`.
+ *
  * @private internal utility of `promptbookCli`
  */
 export declare function buildHarnessInstallCommand(definition: HarnessDefinition): string;

package/esm/src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.d.ts

@@ -0,0 +1,8 @@
+import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+/**
+ * Formats the instruction shown when an outdated harness must be updated by the user.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatHarnessManualUpdateInstruction(status: HarnessInstallationStatus, updatePlan: HarnessUpdatePlan): string;

package/esm/src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.d.ts

@@ -0,0 +1,31 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+/**
+ * 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 declare function resolveHarnessInstallationMethodFromPaths(paths: HarnessInstallationPaths): HarnessInstallationMethod;
+export {};

package/esm/src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/harness/resolveHarnessUpdatePlan.d.ts

@@ -0,0 +1,12 @@
+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 declare function resolveHarnessUpdatePlan(definition: HarnessDefinition, installationMethod: HarnessInstallationMethod): HarnessUpdatePlan;

package/esm/src/cli/cli-commands/common/harness/resolveHarnessUpdatePlan.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,11 @@
+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 declare function $askForNpmPackageInstallationApproval(question: string, questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;

package/{umd/src/cli/cli-commands/common/harness/$resolveLatestHarnessVersion.d.ts → esm/src/cli/cli-commands/common/npm/$resolveLatestNpmPackageVersion.d.ts}

@@ -1,10 +1,9 @@
-import type { HarnessDefinition } from './HarnessDefinition';
 /**
- * Reads the newest version of the harness published to npm.
+ * 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 declare function $resolveLatestHarnessVersion(definition: HarnessDefinition): Promise<string | null>;
+export declare function $resolveLatestNpmPackageVersion(npmPackageName: string): Promise<string | null>;

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

@@ -0,0 +1 @@
+export {};

package/esm/src/cli/cli-commands/common/npm/$resolveNpmGlobalPrefixPath.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function $resolveNpmGlobalPrefixPath(): Promise<string | null>;

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

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function buildNpmPackageInstallCommand(npmPackageName: string, installationLocation: NpmPackageInstallationLocation): string;

package/esm/src/cli/cli-commands/common/npm/buildNpmPackageInstallCommand.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function extractNpmPackageVersionFromOutput(output: string, { isLastMatchPreferred }?: {
+    readonly isLastMatchPreferred?: boolean;
+}): string | null;

package/esm/src/cli/cli-commands/common/npm/extractNpmPackageVersionFromOutput.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function isNpmPackageVersionOutdated(installedVersion: string, latestVersion: string, { isPrereleaseIgnored }?: {
+    readonly isPrereleaseIgnored?: boolean;
+}): boolean;

package/esm/src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -50,6 +50,12 @@ export declare function ensureProjectEnvFile<TEnvVariable extends ProjectEnvVari
  * @private internal utility of Promptbook CLI project initialization
  */
 export declare function ensureProjectGitignoreFile({ projectPath, blockHeader, rules, }: EnsureProjectGitignoreFileOptions): Promise<ProjectInitializationStatus>;
+/**
+ * Lists the ignore rules which are not yet present in a project's `.gitignore` file.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function getMissingProjectGitignoreRules(projectPath: string, rules: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
 /**
  * Reads one text file when it exists, otherwise returns `undefined`.
  *

package/esm/src/cli/cli-commands/common/promptPriorityCliOptions.d.ts

@@ -0,0 +1,7 @@
+import type { Command as Program } from 'commander';
+/**
+ * Registers the shared prompt-priority filter options on a queue-based `ptbk coder` command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addPromptPriorityOptions(command: Program): void;

package/esm/src/cli/cli-commands/common/promptRunnerCliOptions.d.ts

@@ -1,5 +1,6 @@
 import { Command as Program } from 'commander';
 import { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV } from '../../../book-3.0/cliAgentEnv';
+import type { GitChangesMode } from '../coder/GitChangesMode';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 /**
@@ -7,7 +8,7 @@ export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
  *
  * @private internal utility of `promptbookCli`
  */
-export declare const PROMPT_RUNNER_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+export declare const PROMPT_RUNNER_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini", "qwen-code"];
 /**
  * Runner identifier supported by Promptbook CLI agent orchestration commands.
  *
@@ -25,7 +26,7 @@ export type PromptRunnerCliOptions = {
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly commit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -48,7 +49,7 @@ export type NormalizedPromptRunnerCliOptions = {
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly noCommit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -71,13 +72,25 @@ export declare const PROMPT_RUNNER_DESCRIPTION: string;
  *
  * @private internal utility of `promptbookCli`
  */
-export declare const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = "Select runner: openai-codex, github-copilot, cline, claude-code, opencode, gemini (required for non-dry-run)";
+export declare const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION: string;
+/**
+ * Runner harness names listed as alternatives of the `--harness` option in error messages.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_HARNESS_OPTION_HINT: string;
 /**
  * Commander description for the `--model` option.
  *
  * @private internal utility of `promptbookCli`
  */
 export declare const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION: string;
+/**
+ * Commander description for the `--git-changes` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const GIT_CHANGES_OPTION_DESCRIPTION: string;
 /**
  * Registers runner selection flags on a command.
  *

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

@@ -0,0 +1,9 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Checks every local and global Promptbook CLI installation against the newest npm version.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads installed packages and queries npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $checkPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallationStatus>>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,15 @@
+import type { NormalizedQuestionsCliOptions } from '../questionsCliOptions';
+/**
+ * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
+ *
+ * Once an update succeeds, the caller must stop the current run and let the user start a fresh process. A local npm
+ * update can modify `package.json` and a lockfile, which would make the coder's clean-working-tree preflight fail;
+ * the current Node.js process has also already loaded the old CLI implementation.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests, queries npm,
+ * asks the user, and may install npm packages
+ *
+ * @returns `true` when at least one installation was updated and the current coder run should stop
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $ensurePromptbookCliInstallations(questionsOptions: NormalizedQuestionsCliOptions): Promise<boolean>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,12 @@
+import { type PromptbookCliInstallation } from './PromptbookCliInstallation';
+/**
+ * Finds every directly declared local or directly installed global Promptbook CLI package which can be updated.
+ *
+ * Transitive packages are deliberately ignored because this command must update the dependency chosen by the current
+ * project or global npm installation, not mutate a dependency owned by another package.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests and runs npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,10 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Updates one Promptbook CLI package in its existing local or global location.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs an npm package
+ *
+ * @returns `true` when the package update succeeds, `false` when it fails
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean>;

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

@@ -0,0 +1 @@
+export {};