@promptbook/node 0.113.0-9 → 0.114.0-0

package/esm/src/book-components/Chat/Chat/pagePreview/PagePreviewViewport.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Viewport of one live page-preview browser session, in CSS pixels.
+ *
+ * @private type shared between `<LiveBrowserPreview/>` and the Agents Server page-preview routes
+ */
+export type PagePreviewViewport = {
+    readonly width: number;
+    readonly height: number;
+};
+/**
+ * Smallest viewport accepted for one live page-preview browser session.
+ *
+ * @private constant shared between `<LiveBrowserPreview/>` and the Agents Server page-preview routes
+ */
+export declare const PAGE_PREVIEW_MIN_VIEWPORT: PagePreviewViewport;
+/**
+ * Largest viewport accepted for one live page-preview browser session.
+ *
+ * @private constant shared between `<LiveBrowserPreview/>` and the Agents Server page-preview routes
+ */
+export declare const PAGE_PREVIEW_MAX_VIEWPORT: PagePreviewViewport;
+/**
+ * Viewport used when the client did not measure its preview area yet.
+ *
+ * @private constant shared between `<LiveBrowserPreview/>` and the Agents Server page-preview routes
+ */
+export declare const PAGE_PREVIEW_DEFAULT_VIEWPORT: PagePreviewViewport;
+/**
+ * Clamps one requested page-preview viewport into the supported bounds.
+ *
+ * @param width - Requested viewport width.
+ * @param height - Requested viewport height.
+ * @returns Rounded viewport within the supported bounds, or `null` when the values are not finite numbers.
+ *
+ * @private utility shared between `<LiveBrowserPreview/>` and the Agents Server page-preview routes
+ */
+export declare function clampPagePreviewViewport(width: unknown, height: unknown): PagePreviewViewport | null;

package/esm/src/book-components/Chat/Chat/pagePreview/createPagePreviewSessionId.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Prefix of every live page-preview browser session id.
+ *
+ * @private constant shared between `<LiveBrowserPreview/>` and the Agents Server page-preview routes
+ */
+export declare const PAGE_PREVIEW_SESSION_ID_PREFIX = "page-preview-";
+/**
+ * Pattern accepted for client-created page-preview session identifiers.
+ *
+ * @private constant shared between `<LiveBrowserPreview/>` and the Agents Server page-preview routes
+ */
+export declare const PAGE_PREVIEW_SESSION_ID_PATTERN: RegExp;
+/**
+ * Creates one client-side page-preview browser session id.
+ *
+ * @returns Session id accepted by the Agents Server page-preview routes.
+ *
+ * @private utility of `<LiveBrowserPreview/>`
+ */
+export declare function createPagePreviewSessionId(): string;

package/esm/src/book-components/Chat/Chat/pagePreview/normalizePagePreviewInputEvent.d.ts

@@ -0,0 +1,13 @@
+import type { PagePreviewInputEvent } from './PagePreviewInputEvent';
+/**
+ * Validates and normalizes one untrusted page-preview input payload into a typed input event.
+ *
+ * Note: This performs only structural validation shared by client and server — the Agents Server
+ * additionally re-checks `goto` URLs against private/internal targets before navigating.
+ *
+ * @param payload - Unknown JSON payload (usually the parsed request body).
+ * @returns Normalized input event or `null` when the payload is invalid.
+ *
+ * @private utility shared between `<LiveBrowserPreview/>` and the Agents Server page-preview routes
+ */
+export declare function normalizePagePreviewInputEvent(payload: unknown): PagePreviewInputEvent | null;

package/esm/src/book-components/Chat/Chat/pagePreview/normalizePagePreviewInputEvent.test.d.ts

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

package/esm/src/book-components/Chat/Chat/resolveChatRatingMessageKey.d.ts

@@ -0,0 +1,8 @@
+import type { id } from '../../../types/string_token';
+import type { ChatMessage } from '../types/ChatMessage';
+/**
+ * Resolves the stable key used for local chat feedback state.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function resolveChatRatingMessageKey(message: Pick<ChatMessage, 'id' | 'content'>): id;

package/esm/src/book-components/Chat/MarkdownContent/MarkdownContent.d.ts

@@ -1,11 +1,13 @@
 /// <reference types="react" />
 import type { string_markdown } from '../../../types/string_markdown';
+import type { MarkdownInlineReference } from '../utils/renderMarkdown';
 /**
  * Props for markdown content.
  */
 type MarkdownContentProps = {
     content: string_markdown;
     className?: string;
+    inlineReferences?: ReadonlyArray<MarkdownInlineReference>;
     onCreateAgent?: (bookContent: string) => void;
     theme?: 'LIGHT' | 'DARK';
 };

package/esm/src/book-components/Chat/SourceChip/SourceChip.test.d.ts

@@ -0,0 +1,2 @@
+/** @jest-environment jsdom */
+export {};

package/esm/src/book-components/Chat/hooks/useResolvedCitationLabel.test.d.ts

@@ -0,0 +1,2 @@
+/** @jest-environment jsdom */
+export {};

package/esm/src/book-components/Chat/utils/renderMarkdown.d.ts

@@ -4,6 +4,84 @@ import type { string_html, string_markdown } from '../../../types/string_markdow
  */
 type RenderMarkdownOptions = {
     readonly citationReferenceClassName?: string;
+    readonly inlineReferences?: ReadonlyArray<MarkdownInlineReference>;
+    readonly inlineReferenceClassName?: string;
+};
+/**
+ * One inline markdown reference converted from `[[reference]]` into a safe link chip.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReference = {
+    /**
+     * Raw reference text between `[[` and `]]`.
+     */
+    readonly reference: string;
+    /**
+     * Human-readable label rendered inside the link chip.
+     */
+    readonly label: string;
+    /**
+     * Link target for the rendered reference.
+     */
+    readonly href: string;
+    /**
+     * Optional hover title for the rendered reference.
+     */
+    readonly title?: string;
+    /**
+     * Optional expandable menu shown when the reference chip is clicked.
+     */
+    readonly menu?: MarkdownInlineReferenceMenu;
+};
+/**
+ * Status displayed alongside an expandable markdown inline reference.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReferenceMenuStatus = {
+    /**
+     * Accessible text describing the current reference status.
+     */
+    readonly label: string;
+    /**
+     * Whether the status should be rendered as active.
+     */
+    readonly isActive: boolean;
+};
+/**
+ * One destination in an expandable markdown inline reference menu.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReferenceMenuOption = {
+    /**
+     * Text rendered for the option.
+     */
+    readonly label: string;
+    /**
+     * New-tab destination, or `null` while the option is unavailable.
+     */
+    readonly href: string | null;
+    /**
+     * Optional hover text for the option.
+     */
+    readonly title?: string;
+};
+/**
+ * Expandable menu configuration for a markdown inline reference.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReferenceMenu = {
+    /**
+     * Current reference status shown in the chip and menu.
+     */
+    readonly status: MarkdownInlineReferenceMenuStatus;
+    /**
+     * New-tab actions listed in the expanded menu.
+     */
+    readonly options: ReadonlyArray<MarkdownInlineReferenceMenuOption>;
 };
 /**
  * Convert markdown content to HTML.

package/esm/src/book-components/Chat/utils/resolveCitationSourceDisplay.d.ts

@@ -0,0 +1,149 @@
+import type { ParsedCitation } from './parseCitationsFromContent';
+/**
+ * Broad source category used by chat citation chips.
+ *
+ * @private utility type of `<Chat/>` citation rendering
+ */
+export type CitationSourceKind = 'archive' | 'audio' | 'code' | 'document' | 'file' | 'image' | 'json' | 'plain-text' | 'presentation' | 'spreadsheet' | 'table' | 'video' | 'website';
+/**
+ * Image subtype when the citation source carries enough information to identify it.
+ *
+ * @private utility type of `<Chat/>` citation rendering
+ */
+export type CitationImageFormat = 'avif' | 'gif' | 'image' | 'jpeg' | 'png' | 'svg' | 'webp';
+/**
+ * Render-ready metadata for one citation source.
+ *
+ * @private utility type of `<Chat/>` citation rendering
+ */
+export type CitationSourceDisplay = {
+    /**
+     * Broad source category.
+     */
+    readonly kind: CitationSourceKind;
+    /**
+     * Human-readable fallback label used before optional host metadata resolution.
+     */
+    readonly label: string;
+    /**
+     * Best known HTTP(S) target for previews and URL snippets.
+     */
+    readonly targetUrl?: string;
+    /**
+     * Image URL that can be rendered as a thumbnail.
+     */
+    readonly thumbnailUrl?: string;
+    /**
+     * Lower-cased file extension when one is known.
+     */
+    readonly extension?: string;
+    /**
+     * Image subtype when known.
+     */
+    readonly imageFormat?: CitationImageFormat;
+};
+/**
+ * Internal source signature before final labels/preview URLs are resolved.
+ *
+ * @private utility type of `<Chat/>` citation rendering
+ */
+export type CitationSourceSignature = {
+    /**
+     * Broad source category.
+     */
+    readonly kind: CitationSourceKind;
+    /**
+     * Image subtype when known.
+     */
+    readonly imageFormat?: CitationImageFormat;
+};
+/**
+ * Resolves render-ready source metadata for one citation.
+ *
+ * @param citation - Citation metadata from a rendered chat message.
+ * @returns Display label, source category, and optional preview URLs.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function resolveCitationSourceDisplay(citation: ParsedCitation): CitationSourceDisplay;
+/**
+ * Returns whether the provided value is a valid HTTP(S) URL.
+ *
+ * @param value - Candidate string to inspect.
+ * @returns True when the value parses as an HTTP or HTTPS URL.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function isCitationSourceUrl(value: string): boolean;
+/**
+ * Determines whether a citation should be displayed as a text snippet instead of a file/URL.
+ *
+ * @param citation - Parsed citation metadata.
+ * @returns True when the citation looks like inline text instead of a document or URL.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function isPlainTextCitationSource(citation: ParsedCitation): boolean;
+/**
+ * Creates a readable fallback label from a citation source when no title metadata is available.
+ *
+ * @param source - Raw citation source value.
+ * @returns Human-friendly source label.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function createReadableCitationSourceDisplayLabel(source: string): string;
+/**
+ * Creates a compact host/path label for URL-backed file citations.
+ *
+ * @param rawUrl - Raw URL value.
+ * @returns URL snippet such as `github.com/.../source.json`, or null for invalid URLs.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function createCitationUrlSnippet(rawUrl: string): string | null;
+/**
+ * Resolves a source signature from a file extension.
+ *
+ * @param extension - Lower- or mixed-case file extension.
+ * @returns Source signature or null for unknown extensions.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function resolveCitationSourceSignatureFromFileExtension(extension: string | null | undefined): CitationSourceSignature | null;
+/**
+ * Resolves a source signature from an HTTP content type.
+ *
+ * @param contentType - Raw Content-Type header value.
+ * @returns Source signature or null when the content type is not specific enough.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function resolveCitationSourceSignatureFromContentType(contentType: string): CitationSourceSignature | null;
+/**
+ * Resolves a source signature from decoded source text.
+ *
+ * @param source - Raw citation source text.
+ * @returns Source signature for JSON/binary-like source text, otherwise null.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function resolveRawCitationSourceSignature(source: string): CitationSourceSignature | null;
+/**
+ * Resolves a source signature from response bytes.
+ *
+ * @param bytes - Leading response bytes.
+ * @returns Source signature for known binary formats, otherwise null.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function resolveCitationSourceSignatureFromBytes(bytes: Uint8Array): CitationSourceSignature | null;
+/**
+ * Creates a generic fallback label for a source signature.
+ *
+ * @param signature - Source signature.
+ * @returns Human-readable fallback label.
+ *
+ * @private utility of `<Chat/>` citation rendering
+ */
+export declare function createCitationSourceSignatureFallbackLabel(signature: CitationSourceSignature): string;

package/esm/src/book-components/Chat/utils/thinkingMessageVariants.d.ts

@@ -7,6 +7,15 @@
  * @private internal helper for Promptbook chat placeholders
  */
 export declare function normalizeThinkingMessageVariants(thinkingMessages?: ReadonlyArray<string>): ReadonlyArray<string>;
+/**
+ * Parses configured thinking-message variants without applying default fallbacks.
+ *
+ * @param thinkingMessages Raw thinking-message variants.
+ * @returns Trimmed non-empty variants.
+ *
+ * @private internal helper for Promptbook chat placeholders
+ */
+export declare function parseThinkingMessageVariants(thinkingMessages?: ReadonlyArray<string> | null): ReadonlyArray<string>;
 /**
  * Returns a random delay used between browser-side thinking-message rotations.
  *

package/esm/src/cli/cli-commands/agent-folder/agentProjectPaths.d.ts

@@ -1,5 +1,5 @@
-import { AGENT_BOOK_FILE_PATH, AGENT_FAILED_MESSAGES_DIRECTORY_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../../../book-3.0/agentFolderPaths';
-export { AGENT_BOOK_FILE_PATH, AGENT_FAILED_MESSAGES_DIRECTORY_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH, };
+import { AGENT_BOOK_FILE_PATH, AGENT_FAILED_MESSAGES_DIRECTORY_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH, AGENT_PROJECTS_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../../../book-3.0/agentFolderPaths';
+export { AGENT_BOOK_FILE_PATH, AGENT_FAILED_MESSAGES_DIRECTORY_PATH, AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH, AGENT_PROJECTS_DIRECTORY_PATH, AGENT_QUEUED_MESSAGES_DIRECTORY_PATH, };
 /**
  * Relative path to local knowledge files initialized by `ptbk agent-folder init`.
  *

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

@@ -6,6 +6,7 @@ import type { number_port } from '../../../../types/number_positive';
  * @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;
 };
 /**

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/PreparedAgentsServerLaunch.d.ts

@@ -1,4 +1,4 @@
-import type { PreparedAgentsServerRuntime } from '../buildAgentsServer';
+import type { PreparedAgentsServerRuntime } from '../buildAgentsServer/PreparedAgentsServerRuntime';
 import type { AgentsServerChildEnvironment } from './AgentsServerChildEnvironment';
 import type { AgentsServerRuntimePaths } from './AgentsServerRuntimePaths';
 /**

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

@@ -1,6 +1,6 @@
 /// <reference types="node" />
 import type { WriteStream } from 'fs';
-import { type AgentsServerSupervisorState } from './AgentsServerSupervisorState';
+import type { AgentsServerSupervisorState } from './AgentsServerSupervisorState';
 /**
  * Persists one child output chunk and forwards readable lines into UI or plain output.
  *

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

@@ -3,7 +3,7 @@ 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 { AgentsServerSupervisorState } from './AgentsServerSupervisorState';
 import type { StartAgentsServerOptions } from './StartAgentsServerOptions';
 /**
  * Starts the configured Next server mode and wires its logs into the foreground dashboard.

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

@@ -1,7 +1,7 @@
 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 { AgentsServerSupervisorState } from './AgentsServerSupervisorState';
 /**
  * Starts periodic internal worker calls that queue and reconcile local message-folder jobs.
  *

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

@@ -1,6 +1,6 @@
 import type { StartAgentsServerOptions } from './startAgentsServer/StartAgentsServerOptions';
 export { loadAgentsServerProjectEnvironment } from './startAgentsServer/loadAgentsServerProjectEnvironment';
-export type { AgentsServerNextRuntimeMode, StartAgentsServerOptions } from './startAgentsServer/StartAgentsServerOptions';
+export type { AgentsServerNextRuntimeMode, StartAgentsServerOptions, } from './startAgentsServer/StartAgentsServerOptions';
 /**
  * Starts the Agents Server web app and local coding-agent queue workers in the foreground.
  *

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 {};