@promptbook/javascript 0.114.0-1 → 0.114.0-11

package/esm/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -72,6 +72,52 @@ export type AvatarVisualRenderContext = {
  * @private shared contract for the avatar rendering system
  */
 export type AvatarVisual = (context: AvatarVisualRenderContext) => void;
+/**
+ * One painted character cell of a terminal-text avatar frame.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextCell = {
+    /**
+     * Single character painted in the cell.
+     */
+    readonly character: string;
+    /**
+     * Color of the character as a CSS color string, optionally with an alpha channel.
+     */
+    readonly color: string_color;
+};
+/**
+ * One rendered terminal-text avatar frame as a grid of character cells.
+ *
+ * Rows are ordered top to bottom, cells left to right, and `null` leaves the terminal background visible.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextGrid = ReadonlyArray<ReadonlyArray<AvatarVisualTerminalTextCell | null>>;
+/**
+ * Rendering context forwarded to a terminal-text avatar visual.
+ *
+ * Unlike `AvatarVisualRenderContext` this carries no canvas, because the visual paints
+ * character cells of a fixed terminal grid instead of pixels.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextRenderContext = {
+    readonly columns: number;
+    readonly rows: number;
+    readonly timeMs: number;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly palette: AvatarPalette;
+    readonly createRandom: (salt: string) => () => number;
+    readonly interaction: AvatarInteractionState;
+};
+/**
+ * Signature of one terminal-text avatar visual renderer.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalText = (context: AvatarVisualTerminalTextRenderContext) => AvatarVisualTerminalTextGrid;
 /**
  * Metadata and renderer for one built-in avatar visual.
  *
@@ -84,6 +130,14 @@ export type AvatarVisualDefinition = {
     readonly isAnimated: boolean;
     readonly supportsPointerTracking?: boolean;
     readonly render: AvatarVisual;
+    /**
+     * Optional native terminal renderer of visuals which are themselves made of characters.
+     *
+     * Character-based visuals lose their identity when they are rasterized onto a canvas and
+     * converted back into half-block ASCII art, so they paint the terminal character grid directly.
+     * Visuals without this renderer are rasterized through `renderAvatarVisualAsciiArt` instead.
+     */
+    readonly renderTerminalText?: AvatarVisualTerminalText;
 };
 /**
  * Props of the shared `<Avatar/>` component.

package/esm/src/book-2.0/agent-source/AgentBasicInformation.d.ts

@@ -31,13 +31,13 @@ export type BookParameter = {
 };
 /**
  * Capability of the agent
- * This is parsed from commitments like USE BROWSER, USE SEARCH ENGINE, KNOWLEDGE, etc.
+ * This is parsed from commitments like USE CALENDAR, USE PROJECT, KNOWLEDGE, etc.
  */
 export type AgentCapability = {
     /**
      * The type of the capability
      */
-    type: 'browser' | 'search-engine' | 'knowledge' | 'timeout' | 'time' | 'user-location' | 'inheritance' | 'import' | 'image-generator' | 'team' | 'email' | 'popup' | 'privacy' | 'project' | 'calendar' | 'wallet';
+    type: 'knowledge' | 'user-location' | 'inheritance' | 'import' | 'image-generator' | 'team' | 'popup' | 'privacy' | 'project' | 'calendar';
     /**
      * The label to display for this capability
      */
@@ -122,7 +122,7 @@ export type AgentBasicInformation = {
     parameters: Array<BookParameter>;
     /**
      * Capabilities of the agent
-     * This is parsed from commitments like USE BROWSER, USE SEARCH ENGINE, KNOWLEDGE, etc.
+     * This is parsed from commitments like USE CALENDAR, USE PROJECT, KNOWLEDGE, etc.
      */
     capabilities: Array<AgentCapability>;
     /**

package/esm/src/book-2.0/book-language-documentation/BookLanguageManualDictionary.d.ts

@@ -86,9 +86,7 @@ export type BookLanguageManualDictionary = {
     readonly metadataLabels: {
         readonly bookLanguageVersion: string;
         readonly generatedAt: string;
-        readonly commitmentGroups: string;
-        readonly implementedCommitments: string;
-        readonly placeholderCommitments: string;
+        readonly commitmentCount: string;
     };
     /**
      * Heading of the table of contents.
@@ -128,7 +126,6 @@ export type BookLanguageManualDictionary = {
     readonly primitivesSections: {
         readonly coreSyntax: BookLanguageManualChapter;
         readonly references: BookLanguageManualChapter;
-        readonly keywordsTitle: string;
     };
     /**
      * Suffixes distinguishing a server-specific catalog from the portable one.
@@ -141,18 +138,7 @@ export type BookLanguageManualDictionary = {
      * Labels used in every commitment catalog entry.
      */
     readonly commitmentLabels: {
-        readonly status: string;
         readonly aliases: string;
-        readonly semantics: string;
-        readonly typeSchema: string;
-        readonly blockSchema: string;
-        readonly lowLevelNotice: string;
-        readonly usage: string;
-        readonly usageOccurrence: string;
-        readonly usageOccurrences: string;
-        readonly statusImplemented: string;
-        readonly statusPlaceholder: string;
-        readonly noAliases: string;
     };
     /**
      * Labels used by end-to-end example sections.

package/esm/src/book-2.0/book-language-documentation/getBookLanguageManualCommitmentGroups.d.ts

@@ -16,7 +16,7 @@ export type BookLanguageManualCommitmentGroups = {
      */
     readonly documented: ReadonlyArray<BookLanguageManualCommitmentGroup>;
     /**
-     * Low-level and unfinished commitments documented in their own closing chapter.
+     * Low-level commitments documented in their own closing chapter.
      */
     readonly lowLevel: ReadonlyArray<BookLanguageManualCommitmentGroup>;
 };

package/esm/src/book-2.0/book-language-documentation/renderCommitmentCatalogSection.d.ts

@@ -10,10 +10,6 @@ export type RenderCommitmentCatalogSectionOptions = {
      * Grouped commitment definition with aliases.
      */
     readonly groupedCommitment: BookLanguageManualCommitmentGroup;
-    /**
-     * Number of uses across the selected server agents.
-     */
-    readonly usageCount: number;
     /**
      * Translated labels of the manual.
      */

package/esm/src/book-3.0/AgentTeamConversationWorkspace.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Relative directory for an active TEAM conversation workspace.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_TEAM_CONVERSATIONS_DIRECTORY_PATH: string;
+/**
+ * Relative directory where completed TEAM conversation transcripts are retained.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_FINISHED_TEAM_CONVERSATIONS_DIRECTORY_PATH: string;
+/**
+ * Name of the JSON manifest that describes one TEAM conversation workspace.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME = "team.json";
+/**
+ * Name of the read-only teammate-source directory inside one TEAM workspace.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME = "teammates";
+/**
+ * One primary agent represented in a TEAM workspace manifest.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentTeamConversationPrimaryAgent = {
+    readonly permanentId: string;
+    readonly agentName: string;
+};
+/**
+ * One local teammate made available to the coding harness for a single user turn.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentTeamConversationTeammate = {
+    readonly permanentId: string;
+    readonly agentName: string;
+    readonly url: string;
+    readonly instructions: string;
+    readonly sourceFileName: string;
+};
+/**
+ * Persisted roster snapshot for the optional TEAM workspace of one queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentTeamConversationWorkspaceManifest = {
+    readonly version: 1;
+    readonly primaryAgent: AgentTeamConversationPrimaryAgent;
+    readonly teammates: ReadonlyArray<AgentTeamConversationTeammate>;
+};
+/**
+ * Creates the stable directory name that belongs to one queued `.book` message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createAgentTeamConversationWorkspaceDirectoryName(messageFileName: string): string;
+/**
+ * Creates the relative active workspace path for one queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createAgentTeamConversationWorkspacePath(messageFileName: string): string;
+/**
+ * Creates the relative completed-workspace path for one queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createFinishedAgentTeamConversationWorkspacePath(messageFileName: string): string;
+/**
+ * Creates the source-snapshot file name for one teammate.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createAgentTeamTeammateSourceFileName(teammatePermanentId: string): string;
+/**
+ * Checks whether unknown JSON has the minimum shape required for a TEAM workspace manifest.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function isAgentTeamConversationWorkspaceManifest(value: unknown): value is AgentTeamConversationWorkspaceManifest;

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/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/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.
      */
@@ -25,15 +50,43 @@ export type MarkdownInlineReference = {
      * Link target for the rendered reference.
      */
     readonly href: string;
+    /**
+     * Optional URL prefixes which also identify this reference in the authored markdown.
+     *
+     * 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.
  *
@@ -67,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/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/agentCodingFile.d.ts

@@ -1,3 +1,4 @@
+import { string_markdown } from '../../../types/typeAliases';
 /**
  * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
  *
@@ -9,6 +10,4 @@ export declare const AGENT_CODING_FILE_PATH = "AGENT_CODING.md";
  *
  * @private internal utility of `ptbk coder`
  */
-export declare function getDefaultCoderAgentCodingFileContent({ packageJsonScripts, }: {
-    readonly packageJsonScripts: Readonly<Record<string, string>>;
-}): string;
+export declare function getDefaultCoderAgentCodingFileContent(): string_markdown;

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

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder ping` 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 $initializeCoderPingCommand(program: Program): $side_effect;

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

@@ -9,6 +9,7 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
  * - 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/$askForHarnessInstallationApproval.d.ts → npm/$askForNpmPackageInstallationApproval.d.ts}

@@ -1,9 +1,9 @@
 /**
- * Asks the user in the terminal whether the harness should be installed or updated right now.
+ * 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 or the terminal is not interactive
  * @private internal utility of `promptbookCli`
  */
-export declare function $askForHarnessInstallationApproval(question: string): Promise<boolean>;
+export declare function $askForNpmPackageInstallationApproval(question: string): 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/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/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/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/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/$ensurePromptbookCliInstallations.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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(): Promise<boolean>;

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