@promptbook/markdown-utils 0.114.0-2 → 0.114.0-20

package/esm/src/book-components/BookEditor/createUnknownCommitmentDiagnostics.d.ts

@@ -0,0 +1,28 @@
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+/**
+ * Monaco diagnostic shown when a Book source uses an uppercase commitment not registered by Promptbook.
+ *
+ * @private internal type of `BookEditorMonaco`
+ */
+type UnknownCommitmentDiagnostic = {
+    readonly startLineNumber: number;
+    readonly startColumn: number;
+    readonly endLineNumber: number;
+    readonly endColumn: number;
+    readonly message: string;
+    readonly source: string;
+    readonly severity: 'error';
+};
+/**
+ * Creates Book editor diagnostics for uppercase commitments not registered by Promptbook.
+ *
+ * Unknown commitment blocks remain valid extra context in the generated system message,
+ * but the editor marks their keywords so authors can spot likely typos immediately.
+ *
+ * @param agentSource - Current editor content.
+ * @returns Error markers for all unknown commitment keywords.
+ *
+ * @private internal utility of `BookEditorMonaco`
+ */
+export declare function createUnknownCommitmentDiagnostics(agentSource?: string_book): ReadonlyArray<UnknownCommitmentDiagnostic>;
+export {};

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

@@ -591,8 +591,9 @@ export type ChatProps = {
         progress?: number;
     }>;
     /**
-     * Content to be shown inside the chat bar in head
-     * If not provided, the chat bar will not be rendered
+     * Optional content displayed in the chat header above the message list.
+     *
+     * If not provided, the header row is not rendered.
      */
     readonly children?: ReactNode;
     /**

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

@@ -0,0 +1,13 @@
+import { type ReactElement } from 'react';
+/**
+ * Renders one unified diff with added, removed and context lines told apart.
+ *
+ * @param options - Diff text and whether it holds only the beginning of the real diff.
+ * @returns Readable diff block.
+ *
+ * @private function of ChatToolCallModal
+ */
+export declare function renderAgentProjectDiff(options: {
+    readonly diff: string;
+    readonly isDiffTruncated: boolean;
+}): ReactElement;

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

@@ -0,0 +1,16 @@
+import { type ReactElement } from 'react';
+import type { AgentProjectToolCallResult } from '../utils/agentProjectToolCall';
+/**
+ * Renders the detail view of one project the answer worked with.
+ *
+ * The card answers the two questions a project chip raises: what this project is right now — its
+ * runtime state and where to open it — and what this very message did to it.
+ *
+ * @param options - Parsed project chip payload.
+ * @returns Project details section for the tool modal.
+ *
+ * @private function of ChatToolCallModal
+ */
+export declare function renderAgentProjectToolCallDetails(options: {
+    readonly project: AgentProjectToolCallResult;
+}): ReactElement;

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

@@ -0,0 +1,11 @@
+import type { WindowLike as DomWindowLike } from 'dompurify';
+/**
+ * Provides a DOM `window` for runtimes which do not have one, for example Node.js during server-side rendering
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it creates and caches one shared DOM window
+ *
+ * @returns DOM window which can back a DOM-dependent library like `DOMPurify`
+ * @throws {EnvironmentMismatchError} When the current runtime can not create a DOM window
+ * @private utility of `renderMarkdown`
+ */
+export declare function $provideServerDomWindow(): DomWindowLike;

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

@@ -0,0 +1,85 @@
+import type { AgentMessageProjectChange } from '../../../utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * Synthetic tool name used for agent-project chips in chat UI.
+ *
+ * The Agents Server emits one such tool call per project an answer viewed or edited, so the chat
+ * shows which projects the agent worked with below the message that touched them.
+ *
+ * @private internal chat-ui marker for touched agent projects
+ */
+export declare const AGENT_PROJECT_TOOL_CALL_NAME = "agent_project_touched";
+/**
+ * Safe, user-facing metadata shown in agent-project chips.
+ *
+ * Everything besides the project name is optional, because a chip written by an older server — or
+ * one whose project has meanwhile been deleted — still has to render.
+ *
+ * @private internal chat-ui type for touched agent projects
+ */
+export type AgentProjectToolCallResult = {
+    /**
+     * Directory name of the project.
+     */
+    readonly projectName: string;
+    /**
+     * Human-readable project name shown in the chip.
+     */
+    readonly displayName?: string;
+    /**
+     * Short project description, resolved the same way as on the project page.
+     */
+    readonly description?: string;
+    /**
+     * Link to the project page, when the chat knows where the project lives.
+     */
+    readonly projectHref?: string;
+    /**
+     * Address the running project itself is served on, when it has one.
+     */
+    readonly projectUrl?: string;
+    /**
+     * Whether the project was running when the answer finished.
+     */
+    readonly isRunning?: boolean;
+    /**
+     * Runtime status label, the same one the project page shows.
+     */
+    readonly runtimeStatusLabel?: string;
+    /**
+     * Total size of the project, already formatted for display.
+     */
+    readonly sizeLabel?: string;
+    /**
+     * Count of files inside the project.
+     */
+    readonly fileCount?: number;
+    /**
+     * Whether the project folder is a git repository.
+     */
+    readonly isGitRepository?: boolean;
+    /**
+     * What this very message changed in the project, when it changed anything.
+     *
+     * Its `projectName` repeats the one above because the change is reported by the agent runner
+     * in exactly this shape, and reusing it keeps the two descriptions from drifting apart.
+     */
+    readonly change?: AgentMessageProjectChange;
+};
+/**
+ * Parses the project-chip payload from one tool result.
+ *
+ * @param result - Raw tool result payload.
+ * @returns Parsed project metadata, or `null` when the result describes no project.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function parseAgentProjectToolCallResult(result: unknown): AgentProjectToolCallResult | null;
+/**
+ * Resolves the chip label of one touched agent project.
+ *
+ * @param projectResult - Parsed project metadata.
+ * @returns Human-readable project name.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveAgentProjectToolCallLabel(projectResult: AgentProjectToolCallResult): string;

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

@@ -0,0 +1,38 @@
+import type { AgentMessageTouchedExternalSource } from '../../../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+/**
+ * Synthetic tool name used for external-source chips in chat UI.
+ *
+ * The Agents Server emits one such tool call per source outside the agent an answer viewed or
+ * edited, so the chat shows which services, websites and searches the agent really reached below
+ * the message that touched them. Work the agent does inside itself emits nothing.
+ *
+ * @private internal chat-ui marker for touched external sources
+ */
+export declare const EXTERNAL_SOURCE_TOOL_CALL_NAME = "external_source_touched";
+/**
+ * Parses the external-source chip payload from one tool result.
+ *
+ * @param result - Raw tool result payload.
+ * @returns Parsed source metadata, or `null` when the result describes no external source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function parseExternalSourceToolCallResult(result: unknown): AgentMessageTouchedExternalSource | null;
+/**
+ * Resolves the chip label of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns User-facing name of the source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveExternalSourceToolCallLabel(externalSource: AgentMessageTouchedExternalSource): string;
+/**
+ * Resolves the chip emoji of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns Emoji telling apart an integration, a website and a search.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveExternalSourceToolCallEmoji(externalSource: AgentMessageTouchedExternalSource): string;

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

@@ -1,4 +1,22 @@
 import type { string_html, string_markdown } from '../../../types/string_markdown';
+/**
+ * Attribute marking a client action generated for an inline-reference menu.
+ *
+ * @private utility shared with `MarkdownContent`
+ */
+export declare const MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE = "data-promptbook-inline-reference-menu-action";
+/**
+ * Attribute identifying the inline reference which owns a client menu action.
+ *
+ * @private utility shared with `MarkdownContent`
+ */
+export declare const MARKDOWN_INLINE_REFERENCE_MENU_ACTION_REFERENCE_ATTRIBUTE = "data-promptbook-inline-reference-menu-action-reference";
+/**
+ * Attribute marking a favicon rendered inside an inline-reference chip.
+ *
+ * @private utility shared with `MarkdownContent`
+ */
+export declare const MARKDOWN_INLINE_REFERENCE_ICON_ATTRIBUTE = "data-promptbook-inline-reference-icon";
 /**
  * Options for markdown rendering.
  */
@@ -17,6 +35,13 @@ export type MarkdownInlineReference = {
      * Raw reference text between `[[` and `]]`.
      */
     readonly reference: string;
+    /**
+     * Optional text aliases which should render as this reference when an agent mentions them in markdown.
+     *
+     * They are also accepted inside a `[[reference]]` token. This lets application code use a stable
+     * technical reference while recognizing a human-facing name in older messages.
+     */
+    readonly sourceTextAliases?: ReadonlyArray<string>;
     /**
      * Human-readable label rendered inside the link chip.
      */
@@ -26,21 +51,42 @@ export type MarkdownInlineReference = {
      */
     readonly href: string;
     /**
-     * Markdown link destination prefixes that should render as this reference as well.
+     * Optional URL prefixes which also identify this reference in the authored markdown.
      *
-     * This supports legacy links such as an Agents Server project file URL while keeping
-     * `reference` as the canonical `[[project]]` token.
+     * A markdown link or a bare URL pointing to one of these prefixes is rendered as the same chip
+     * as the `[[reference]]` token. Both absolute URLs (for example `https://project.example.com`)
+     * and application paths (for example `/agents/agent/projects/website`) are supported; a path
+     * prefix matches on any host so that both relative and absolute links are recognized.
      */
     readonly sourceHrefPrefixes?: ReadonlyArray<string>;
     /**
      * Optional hover title for the rendered reference.
      */
     readonly title?: string;
+    /**
+     * Optional favicon and text fallback rendered before the reference label.
+     */
+    readonly icon?: MarkdownInlineReferenceIcon;
     /**
      * Optional expandable menu shown when the reference chip is clicked.
      */
     readonly menu?: MarkdownInlineReferenceMenu;
 };
+/**
+ * Visual identity rendered inside one markdown inline-reference chip.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReferenceIcon = {
+    /**
+     * Optional image URL. The fallback remains visible when the image is unavailable.
+     */
+    readonly src?: string | null;
+    /**
+     * Short text rendered when the image is missing or broken.
+     */
+    readonly fallbackText: string;
+};
 /**
  * Status displayed alongside an expandable markdown inline reference.
  *
@@ -74,6 +120,25 @@ export type MarkdownInlineReferenceMenuOption = {
      * Optional hover text for the option.
      */
     readonly title?: string;
+    /**
+     * Optional client action rendered as a button instead of a link.
+     */
+    readonly action?: MarkdownInlineReferenceMenuAction;
+};
+/**
+ * Client-side action exposed by an expandable markdown inline-reference menu.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type MarkdownInlineReferenceMenuAction = {
+    /**
+     * Stable identifier unique within the owning reference menu.
+     */
+    readonly id: string;
+    /**
+     * Callback invoked when the menu button is selected.
+     */
+    readonly onSelect: () => void | Promise<void>;
 };
 /**
  * Expandable menu configuration for a markdown inline reference.

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

@@ -1,4 +1,22 @@
 import type { TODO_any } from '../../../utils/organization/TODO_any';
+/**
+ * Tool name of one scheduled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const SET_TIMEOUT_TOOL_CALL_NAME = "set_timeout";
+/**
+ * Tool name of one re-planned wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const UPDATE_TIMEOUT_TOOL_CALL_NAME = "update_timeout";
+/**
+ * Tool name of one cancelled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const CANCEL_TIMEOUT_TOOL_CALL_NAME = "cancel_timeout";
 /**
  * Action performed by timeout tools.
  *
@@ -140,4 +158,16 @@ export declare function buildTimeoutToolPrimarySentence(presentation: TimeoutToo
  * @private internal utility of `<Chat/>`
  */
 export declare function buildTimeoutToolScheduleSentence(presentation: TimeoutToolCallPresentation, translations?: TimeoutToolCallTranslations): string | null;
+/**
+ * Converts timeout duration into natural language sentence fragments.
+ *
+ * Shared by every timeout surface: the chat chips, the goal-chat planned messages of the Agents
+ * Server, and the planned-message prompt section of the agent-folder runner.
+ *
+ * @param milliseconds - Duration or repeat interval in milliseconds.
+ * @returns Label such as `5 minutes` or `1 hour 30 minutes`.
+ *
+ * @private internal utility of `<Chat/>` and the Agents Server planned messages
+ */
+export declare function formatTimeoutDurationHuman(milliseconds: number): string;
 export {};

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

@@ -18,6 +18,12 @@ export declare const PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV = "PTBK_AGENTS_SE
  * @private internal constant of `buildAgentsServer`
  */
 export declare const PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV = "PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION";
+/**
+ * Environment variable that disables throwaway webpack filesystem caches for CLI-owned production builds.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export declare const PTBK_AGENTS_SERVER_DISABLE_WEBPACK_FILESYSTEM_CACHE_ENV = "PTBK_AGENTS_SERVER_DISABLE_WEBPACK_FILESYSTEM_CACHE";
 /**
  * Adds dependency-resolution environment required by the materialized Agents Server runtime.
  *
@@ -25,4 +31,5 @@ export declare const PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV = "PTBK_AGENT
  */
 export declare function createAgentsServerRuntimeEnvironment(environment: NodeJS.ProcessEnv, nodeModulesPath: string, options?: {
     readonly isNextValidationIgnored?: boolean;
+    readonly isWebpackFilesystemCacheDisabled?: boolean;
 }): NodeJS.ProcessEnv;

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

@@ -0,0 +1,28 @@
+/**
+ * Supported values of the `--git-changes` option, which decides what happens with a dirty working tree.
+ *
+ * - `fail` — refuse to start while the working tree has uncommitted changes
+ * - `ignore` — start anyway and leave the uncommitted changes where they are
+ * - `continue` — resume the single prompt which was left in the middle of its implementation
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare const GIT_CHANGES_MODE_VALUES: readonly ["fail", "ignore", "continue"];
+/**
+ * Behavior requested for a working tree which has uncommitted changes.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export type GitChangesMode = (typeof GIT_CHANGES_MODE_VALUES)[number];
+/**
+ * Mode applied when `--git-changes` is not used at all.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare const DEFAULT_GIT_CHANGES_MODE: GitChangesMode;
+/**
+ * Checks whether a value is a supported `--git-changes` mode.
+ *
+ * @private internal shared utility of `ptbk coder run`
+ */
+export declare function isGitChangesMode(value: string): value is GitChangesMode;

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

@@ -0,0 +1,52 @@
+/**
+ * How many prompt boilerplate files are generated and how many prompts each of them contains.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export type BoilerplateCount = {
+    /**
+     * Number of generated prompt boilerplate files.
+     */
+    readonly filesCount: number;
+    /**
+     * Number of prompts written into each generated file.
+     *
+     * Note: More than one prompt per file is an advanced option - each prompt is one separate
+     *       coding task separated by `---`, with all prompts in the file sharing its fresh emoji tag.
+     */
+    readonly promptsPerFileCount: number;
+};
+/**
+ * Number of prompt boilerplate files and prompts per file used when `--count` is not provided.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const DEFAULT_BOILERPLATE_COUNT: BoilerplateCount;
+/**
+ * Formats one boilerplate count back into the `N*M` notation of the `--count` option.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function formatBoilerplateCount({ filesCount, promptsPerFileCount }: BoilerplateCount): string;
+/**
+ * Default value of the `--count` option rendered in the `N*M` notation, for example `5*1`.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE: string;
+/**
+ * Description of the `--count` option shared by all commands which generate prompt boilerplates.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare const BOILERPLATE_COUNT_OPTION_DESCRIPTION: string;
+/**
+ * Parses the `--count` option value into the number of files and the number of prompts in each of them.
+ *
+ * Both notations are supported:
+ * - `N` and `N*1` => N files with one prompt each
+ * - `N*M` => N files with M prompts each
+ *
+ * @private internal utility of `ptbk coder`
+ */
+export declare function parseBoilerplateCount(countOption: string): BoilerplateCount;

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

@@ -1,5 +1,6 @@
 import type { Command as Program } from 'commander';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import type { BoilerplateCount } from './boilerplateCount';
 /**
  * Initializes `coder generate-boilerplates` command for Promptbook CLI utilities
  *
@@ -9,12 +10,12 @@ import type { $side_effect } from '../../../utils/organization/$side_effect';
  */
 export declare function $initializeCoderGenerateBoilerplatesCommand(program: Program): $side_effect;
 /**
- * Generates boilerplate prompt files with unique emoji tags.
+ * Generates boilerplate prompt files with one unique emoji tag per file.
  *
  * @private internal function of `generatePromptBoilerplate` command
  */
-export declare function generatePromptBoilerplate({ projectPath, filesCount, templateOption, }: {
+export declare function generatePromptBoilerplate({ projectPath, boilerplateCount, templateOption, }: {
     readonly projectPath: string;
-    readonly filesCount: number;
+    readonly boilerplateCount: BoilerplateCount;
     readonly templateOption?: string;
 }): Promise<void>;

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

@@ -1,12 +1,9 @@
 import type { Command as Program } from 'commander';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 /**
- * Initializes `coder ping` command for Promptbook CLI utilities.
+ * Initializes `coder ping` command for Promptbook CLI utilities
  *
- * The command makes one small, isolated harness/model call, prints its result
- * and reports how long the harness/model turn took.
- *
- * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ * 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`
  */

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

@@ -1,4 +1,4 @@
-import type { Command as Program } from 'commander';
+import { Command as Program } from 'commander';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 /**
  * Initializes `coder verify` command for Promptbook CLI utilities

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

@@ -12,3 +12,15 @@ export declare const DEFAULT_WAIT_AFTER_ERROR_MS: number;
  * @private internal utility of `ptbk coder` wait handling
  */
 export declare function parseOptionalWaitDuration(value: string | undefined, defaultMs: number): number;
+/**
+ * Parses an optional Commander period duration string and returns the resolved milliseconds.
+ *
+ * Returns `undefined` when the flag was not provided or was provided without a non-empty value,
+ * which means the command runs only once instead of repeating itself.
+ *
+ * @throws {NotAllowed} When the duration is not a positive one, because a non-positive period
+ *                      would repeat the command without ever pausing between two rounds
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined;

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

@@ -8,8 +8,8 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * - 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
- * - ping: Test one harness and model connection with a disposable task
  * - run: Run coding prompts with AI agents
+ * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags
  *

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

@@ -0,0 +1,34 @@
+import type { Command as Program } from 'commander';
+import type { CoderGitSyncOptions } from '../../../../scripts/run-codex-prompts/git/coderGitSync';
+export type { CoderGitSyncOptions };
+/**
+ * Commander option bag for the shared `ptbk coder` git synchronization flags.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type CoderGitSyncCliOptions = {
+    readonly commit: boolean;
+    readonly autoPush: boolean;
+    readonly autoPull: boolean;
+};
+/**
+ * Description block shared by the `ptbk coder` commands which can synchronize their changes with git.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const CODER_GIT_SYNC_DESCRIPTION: string;
+/**
+ * Registers the shared `--commit`, `--auto-push` and `--auto-pull` flags on a `ptbk coder` command.
+ *
+ * Note: Unlike `ptbk coder run`, which commits by default and opts out through `--no-commit`,
+ *       these commands never touch git unless the flags are used explicitly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addCoderGitSyncOptions(command: Program): void;
+/**
+ * Converts the Commander git synchronization flags into normalized git synchronization options.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizeCoderGitSyncCliOptions(cliOptions: CoderGitSyncCliOptions): CoderGitSyncOptions;

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

@@ -1,7 +1,7 @@
 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.
+ * Checks that every given CLI coding harness is installed globally and, when 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 +10,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>, isHarnessUpdateCheckEnabled?: boolean): Promise<void>;

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

@@ -5,11 +5,12 @@ import type { HarnessDefinition } from './HarnessDefinition';
  * - `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 +22,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;
     /**

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

@@ -0,0 +1,29 @@
+import type { Command as Program } from 'commander';
+/**
+ * Commander option bag for opting out of automatic coding-harness update checks.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdateCliOptions = {
+    readonly harnessUpdate: boolean;
+};
+/**
+ * Normalized automatic coding-harness update-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedHarnessUpdateCliOptions = {
+    readonly isHarnessUpdateCheckEnabled: boolean;
+};
+/**
+ * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addHarnessUpdateOption(command: Program): void;
+/**
+ * Converts the Commander harness-update flag into the normalized harness-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizeHarnessUpdateCliOptions(cliOptions: HarnessUpdateCliOptions): NormalizedHarnessUpdateCliOptions;