@promptbook/javascript 0.113.0-8 → 0.114.0-0

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/AgentsServerChildEnvironment.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="node" />
+import type { number_port } from '../../../../types/number_positive';
+/**
+ * Subprocess environment carrying the explicit local worker credential.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerChildEnvironment = NodeJS.ProcessEnv & {
+    readonly PTBK_AGENTS_SERVER_URL: string;
+    readonly PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN: string;
+};
+/**
+ * Creates the subprocess environment for Next and its internal local runner bridge.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function createAgentsServerChildEnvironment(port: number_port, agentRootPath: string): AgentsServerChildEnvironment;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/AgentsServerChildEnvironment.test.d.ts

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

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/AgentsServerLogStreams.d.ts

@@ -0,0 +1,30 @@
+/// <reference types="node" />
+import { type WriteStream } from 'fs';
+import type { AgentsServerRuntimePaths } from './AgentsServerRuntimePaths';
+/**
+ * Logger handles kept open for the foreground Agents Server lifetime.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerLogStreams = {
+    readonly next: WriteStream;
+    readonly runner: WriteStream;
+};
+/**
+ * Creates file streams for service output persisted below `./logs`.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function createAgentsServerLogStreams(runtimePaths: AgentsServerRuntimePaths): AgentsServerLogStreams;
+/**
+ * Closes all foreground service log streams.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function closeAgentsServerLogStreams(logStreams: AgentsServerLogStreams): void;
+/**
+ * Appends one timestamped runner lifecycle event into its persistent log file.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function logRunnerEvent(logStream: WriteStream, event: string): void;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/AgentsServerRuntimePaths.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Captures foreground file locations for one Agents Server launch.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerRuntimePaths = {
+    readonly launchWorkingDirectory: string;
+    readonly appPath: string;
+    readonly agentRootPath: string;
+    readonly logDirectoryPath: string;
+    readonly nextLogPath: string;
+    readonly runnerLogPath: string;
+};
+/**
+ * Resolves local app, agent-root, and log paths for one foreground launch.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function resolveAgentsServerRuntimePaths(): Promise<AgentsServerRuntimePaths>;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/AgentsServerSupervisorState.d.ts

@@ -0,0 +1,37 @@
+/// <reference types="node" />
+import type { CoderRunUiHandle } from '../../../../../scripts/run-codex-prompts/ui/renderCoderRunUi';
+/**
+ * Mutable supervisor state shared with child-process and watcher callbacks.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerSupervisorState = {
+    isContinuing: boolean;
+    uiHandle?: CoderRunUiHandle;
+    lastUserChatJobWorkerError?: {
+        message: string;
+        repeatCount: number;
+    };
+    nextExit?: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    };
+};
+/**
+ * Adds one Next or worker output line to the rich terminal UI when it is active.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function addUiOutput(state: AgentsServerSupervisorState, output: string): void;
+/**
+ * Adds one service error line to the rich terminal UI when it is active.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function addUiError(state: AgentsServerSupervisorState, error: string): void;
+/**
+ * Throws when the server child stopped while the watcher was still expected to be foreground work.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function assertNextServerStillRunning(state: AgentsServerSupervisorState): void;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/LocalAgentRunnerLimits.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Local runner limits loaded from the running Agents Server app.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type LocalAgentRunnerLimits = {
+    readonly maxFailedAttempts: number;
+    readonly maxParallelMessages: number;
+};

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/PreparedAgentsServerLaunch.d.ts

@@ -0,0 +1,13 @@
+import type { PreparedAgentsServerRuntime } from '../buildAgentsServer/PreparedAgentsServerRuntime';
+import type { AgentsServerChildEnvironment } from './AgentsServerChildEnvironment';
+import type { AgentsServerRuntimePaths } from './AgentsServerRuntimePaths';
+/**
+ * Prepared Next runtime and child environment used by one foreground launch.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type PreparedAgentsServerLaunch = {
+    readonly runtimeArtifacts: PreparedAgentsServerRuntime;
+    readonly runtimeChildEnvironment: AgentsServerChildEnvironment;
+    readonly runtimePaths: AgentsServerRuntimePaths;
+};

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/StartAgentsServerOptions.d.ts

@@ -0,0 +1,24 @@
+import type { number_port } from '../../../../types/number_positive';
+import type { ThinkingLevel } from '../../coder/ThinkingLevel';
+import type { PromptRunnerHarnessName } from '../../common/promptRunnerCliOptions';
+/**
+ * Next runtime mode supported by the local Agents Server foreground launcher.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type AgentsServerNextRuntimeMode = 'start' | 'dev';
+/**
+ * Options required to start the foreground Agents Server service group.
+ *
+ * @private internal type of `startAgentsServer`
+ */
+export type StartAgentsServerOptions = {
+    readonly port: number_port;
+    readonly agentName: PromptRunnerHarnessName;
+    readonly model?: string;
+    readonly noUi: boolean;
+    readonly thinkingLevel?: ThinkingLevel;
+    readonly allowCredits: boolean;
+    readonly nextRuntimeMode: AgentsServerNextRuntimeMode;
+    readonly isBuildForced: boolean;
+};

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/createInternalRouteErrorMessage.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Builds a foreground failure message for one internal Agents Server route.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function createInternalRouteErrorMessage(routeLabel: string, response: Response, details: string | null): string;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/createLocalAgentRunOptions.d.ts

@@ -0,0 +1,9 @@
+import type { AgentRunOptions } from '../../../../../scripts/run-agent-messages/AgentRunOptions';
+import type { LocalAgentRunnerLimits } from './LocalAgentRunnerLimits';
+import type { StartAgentsServerOptions } from './StartAgentsServerOptions';
+/**
+ * Creates local no-git agent runner options for folders managed by the Agents Server database.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function createLocalAgentRunOptions(options: StartAgentsServerOptions, localAgentRunnerLimits: LocalAgentRunnerLimits): AgentRunOptions;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/forwardChildOutput.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="node" />
+import type { WriteStream } from 'fs';
+import type { AgentsServerSupervisorState } from './AgentsServerSupervisorState';
+/**
+ * Persists one child output chunk and forwards readable lines into UI or plain output.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function forwardChildOutput(chunk: string, options: {
+    readonly label: string;
+    readonly logStream: WriteStream;
+    readonly state: AgentsServerSupervisorState;
+}): void;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/loadAgentsServerProjectEnvironment.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Loads launch-directory `.env` values without overriding explicit process environment.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function loadAgentsServerProjectEnvironment(launchWorkingDirectory: string): void;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/prepareAgentsServerLaunch.d.ts

@@ -0,0 +1,18 @@
+import type { AgentsServerChildEnvironment } from './AgentsServerChildEnvironment';
+import type { AgentsServerLogStreams } from './AgentsServerLogStreams';
+import type { AgentsServerRuntimePaths } from './AgentsServerRuntimePaths';
+import type { AgentsServerSupervisorState } from './AgentsServerSupervisorState';
+import type { PreparedAgentsServerLaunch } from './PreparedAgentsServerLaunch';
+import type { StartAgentsServerOptions } from './StartAgentsServerOptions';
+/**
+ * Prepares the shared Next runtime for either production start or hot-reloading development mode.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function prepareAgentsServerLaunch(options: {
+    readonly childEnvironment: AgentsServerChildEnvironment;
+    readonly logStreams: AgentsServerLogStreams;
+    readonly startOptions: StartAgentsServerOptions;
+    readonly runtimePaths: AgentsServerRuntimePaths;
+    readonly state: AgentsServerSupervisorState;
+}): Promise<PreparedAgentsServerLaunch>;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/readInternalRouteErrorDetails.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads an internal route error payload so foreground logs show the route-level reason.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function readInternalRouteErrorDetails(response: Response): Promise<string | null>;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/resolveAgentsServerChildHostname.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="node" />
+/**
+ * Resolves the optional Next hostname from the prepared child environment.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function resolveAgentsServerChildHostname(environment: NodeJS.ProcessEnv): string | null;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/startNextServer.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+import { type ChildProcess } from 'child_process';
+import type { AgentsServerChildEnvironment } from './AgentsServerChildEnvironment';
+import type { AgentsServerLogStreams } from './AgentsServerLogStreams';
+import type { AgentsServerRuntimePaths } from './AgentsServerRuntimePaths';
+import type { AgentsServerSupervisorState } from './AgentsServerSupervisorState';
+import type { StartAgentsServerOptions } from './StartAgentsServerOptions';
+/**
+ * Starts the configured Next server mode and wires its logs into the foreground dashboard.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function startNextServer(options: {
+    readonly nextCliPath: string;
+    readonly startOptions: StartAgentsServerOptions;
+    readonly runtimePaths: AgentsServerRuntimePaths;
+    readonly childEnvironment: AgentsServerChildEnvironment;
+    readonly logStreams: AgentsServerLogStreams;
+    readonly state: AgentsServerSupervisorState;
+}): ChildProcess;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/startUserChatJobWorkerPump.d.ts

@@ -0,0 +1,15 @@
+import type { number_port } from '../../../../types/number_positive';
+import type { AgentsServerChildEnvironment } from './AgentsServerChildEnvironment';
+import type { AgentsServerLogStreams } from './AgentsServerLogStreams';
+import type { AgentsServerSupervisorState } from './AgentsServerSupervisorState';
+/**
+ * Starts periodic internal worker calls that queue and reconcile local message-folder jobs.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function startUserChatJobWorkerPump(options: {
+    readonly port: number_port;
+    readonly environment: AgentsServerChildEnvironment;
+    readonly logStreams: AgentsServerLogStreams;
+    readonly state: AgentsServerSupervisorState;
+}): () => void;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/stopChildProcess.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="node" />
+import type { ChildProcess } from 'child_process';
+/**
+ * Stops only the child process spawned for the local Next server.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function stopChildProcess(commandProcess: ChildProcess | undefined): void;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer/waitForLocalAgentRunnerLimits.d.ts

@@ -0,0 +1,16 @@
+import type { number_port } from '../../../../types/number_positive';
+import type { AgentsServerChildEnvironment } from './AgentsServerChildEnvironment';
+import type { AgentsServerLogStreams } from './AgentsServerLogStreams';
+import type { AgentsServerSupervisorState } from './AgentsServerSupervisorState';
+import type { LocalAgentRunnerLimits } from './LocalAgentRunnerLimits';
+/**
+ * Waits until the internal Next route can return current local runner limits.
+ *
+ * @private internal utility of `startAgentsServer`
+ */
+export declare function waitForLocalAgentRunnerLimits(options: {
+    readonly port: number_port;
+    readonly environment: AgentsServerChildEnvironment;
+    readonly logStreams: AgentsServerLogStreams;
+    readonly state: AgentsServerSupervisorState;
+}): Promise<LocalAgentRunnerLimits>;

package/esm/src/cli/cli-commands/agents-server/startAgentsServer.d.ts

@@ -1,36 +1,9 @@
-import type { ThinkingLevel } from '../coder/ThinkingLevel';
-import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
-import type { number_port } from '../../../types/number_positive';
-/**
- * Next runtime mode supported by the local Agents Server foreground launcher.
- *
- * @private internal type of `ptbk agents-server`
- */
-export type AgentsServerNextRuntimeMode = 'start' | 'dev';
-/**
- * Options required to start the foreground Agents Server service group.
- *
- * @private internal type of `ptbk agents-server`
- */
-export type StartAgentsServerOptions = {
-    readonly port: number_port;
-    readonly agentName: PromptRunnerHarnessName;
-    readonly model?: string;
-    readonly noUi: boolean;
-    readonly thinkingLevel?: ThinkingLevel;
-    readonly allowCredits: boolean;
-    readonly nextRuntimeMode: AgentsServerNextRuntimeMode;
-    readonly isBuildForced: boolean;
-};
+import type { StartAgentsServerOptions } from './startAgentsServer/StartAgentsServerOptions';
+export { loadAgentsServerProjectEnvironment } from './startAgentsServer/loadAgentsServerProjectEnvironment';
+export type { AgentsServerNextRuntimeMode, StartAgentsServerOptions, } from './startAgentsServer/StartAgentsServerOptions';
 /**
  * Starts the Agents Server web app and local coding-agent queue workers in the foreground.
  *
  * @private internal utility of `ptbk agents-server`
  */
 export declare function startAgentsServer(options: StartAgentsServerOptions): Promise<void>;
-/**
- * Loads launch-directory `.env` values without overriding explicit process environment.
- *
- * @private internal utility of `ptbk agents-server`
- */
-export declare function loadAgentsServerProjectEnvironment(launchWorkingDirectory: string): void;

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

@@ -0,0 +1,36 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder add` command for Promptbook CLI utilities
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeCoderAddCommand(program: Program): $side_effect;
+/**
+ * Result of adding one prompt file with `coder add`.
+ *
+ * @private internal utility of `coder add` command
+ */
+export type AddCoderPromptResult = {
+    /**
+     * Project-relative path of the created prompt file.
+     */
+    readonly filePath: string;
+    /**
+     * Emoji tag assigned to the created prompt, for example `[✨🪴]`.
+     */
+    readonly emojiTag: string;
+};
+/**
+ * Adds one ready-to-run prompt file containing a single prompt built from the description and template.
+ *
+ * @private internal utility of `coder add` command
+ */
+export declare function addCoderPrompt({ projectPath, description, priority, templateOption, }: {
+    readonly projectPath: string;
+    readonly description: string;
+    readonly priority: number;
+    readonly templateOption?: string;
+}): Promise<AddCoderPromptResult>;

package/esm/src/cli/cli-commands/coder/add.test.d.ts

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

package/esm/src/cli/cli-commands/coder/boilerplateTemplates.d.ts

@@ -135,3 +135,27 @@ export declare function resolveCoderPromptTemplate({ projectPath, templateOption
     readonly projectPath: string;
     readonly templateOption?: string;
 }): Promise<ResolvedCoderPromptTemplate>;
+/**
+ * Builds one prompt section (status line, emoji-tagged title, and body) shared by
+ * `coder generate-boilerplates` and `coder add`.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function buildCoderPromptSection({ statusLine, emojiTag, title, body, }: {
+    /**
+     * Checklist status marker of the section, for example `[-]`, `[ ]`, or `[ ] !!`.
+     */
+    readonly statusLine: string;
+    /**
+     * Emoji tag rendered before the title, for example `[✨🪴]`.
+     */
+    readonly emojiTag: string;
+    /**
+     * Single-line title rendered right after the emoji tag.
+     */
+    readonly title: string;
+    /**
+     * Markdown body rendered below the title.
+     */
+    readonly body: string;
+}): string;

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

@@ -5,6 +5,7 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  *
  * 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
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
  * - run: Run coding prompts with AI agents

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

@@ -0,0 +1,10 @@
+/**
+ * Creates a Commander argument parser that accepts only non-negative integers.
+ *
+ * The returned parser is meant to be passed as the coercion callback of `command.option(...)`.
+ * It throws a branded `NotAllowed` error with a clear message referencing the given option name
+ * when the provided value is not a non-negative integer.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function createNonNegativeIntegerOptionParser(optionName: string): (value: string) => number;

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

@@ -0,0 +1,9 @@
+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
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void>;

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

@@ -0,0 +1,9 @@
+/**
+ * Asks the user in the terminal whether the harness should be installed or updated right 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 declare function $askForHarnessInstallationApproval(question: string): Promise<boolean>;

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

@@ -0,0 +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.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and queries npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $checkHarnessInstallation(definition: HarnessDefinition): Promise<HarnessInstallationStatus>;

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

@@ -0,0 +1,13 @@
+import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it may install npm packages
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $ensureHarnessInstallations(harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>): Promise<void>;

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

@@ -0,0 +1,13 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * Installs or updates one CLI coding harness globally through npm.
+ *
+ * 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 a global npm package
+ *
+ * @returns `true` when the harness has been installed, `false` when the installation failed
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $installHarness(definition: HarnessDefinition): Promise<boolean>;

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

@@ -0,0 +1,10 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * Reads the version of the globally installed harness command.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command
+ *
+ * @returns The installed version or `null` when the harness command is not available globally
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveInstalledHarnessVersion(definition: HarnessDefinition): Promise<string | null>;

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

@@ -0,0 +1,10 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * Reads the newest version of the harness published to npm.
+ *
+ * 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>;

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

@@ -0,0 +1,40 @@
+import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+/**
+ * Static description of one supported CLI coding harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessDefinition = {
+    /**
+     * Harness identifier used by the `--harness` option.
+     */
+    readonly harnessName: PromptRunnerHarnessName;
+    /**
+     * Human-readable harness name shown in the terminal.
+     */
+    readonly label: string;
+    /**
+     * Globally installed command which runs the harness.
+     */
+    readonly commandName: string;
+    /**
+     * Npm package which installs the harness command globally.
+     */
+    readonly npmPackageName: string;
+    /**
+     * Extra environment variables required by the global npm installation of this harness.
+     */
+    readonly npmInstallEnvironment?: Readonly<Record<string, string>>;
+};
+/**
+ * Single source of truth about how each supported CLI coding harness is installed and detected.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const HARNESS_DEFINITIONS: Readonly<Record<PromptRunnerHarnessName, HarnessDefinition>>;
+/**
+ * Looks up the definition of one supported CLI coding harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function getHarnessDefinition(harnessName: PromptRunnerHarnessName): HarnessDefinition;

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

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

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

@@ -0,0 +1,35 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * 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
+ * - `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';
+/**
+ * Installation state of one CLI coding harness on the current machine.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationStatus = {
+    /**
+     * Harness the status belongs to.
+     */
+    readonly definition: HarnessDefinition;
+    /**
+     * Comparison of the installed version with the newest published one.
+     */
+    readonly installationState: HarnessInstallationState;
+    /**
+     * Version of the globally installed harness command or `null` when the harness is not installed.
+     */
+    readonly installedVersion: string | null;
+    /**
+     * Newest version published to npm or `null` when it could not be resolved.
+     */
+    readonly latestVersion: string | null;
+};

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

@@ -0,0 +1,10 @@
+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,
+ * so the user always sees exactly what Promptbook would run.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function buildHarnessInstallCommand(definition: HarnessDefinition): string;

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

@@ -0,0 +1,11 @@
+/**
+ * Extracts the version from the raw output of a harness `--version` command.
+ *
+ * Harness CLIs print their version in many shapes, for example `2.1.199 (Claude Code)`,
+ * `codex-cli 0.144.4`, `GitHub Copilot CLI 1.0.61.` or after unrelated deprecation warning lines,
+ * so the first version-looking token of the first matching line wins.
+ *
+ * @returns The parsed version or `null` when the output contains no version
+ * @private internal utility of `promptbookCli`
+ */
+export declare function extractHarnessVersionFromOutput(output: string): string | null;

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

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

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

@@ -0,0 +1,7 @@
+import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
+/**
+ * Formats the warning shown when a harness is missing or outdated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatHarnessInstallationWarning(status: HarnessInstallationStatus): string;