@promptbook/cli 0.114.0-5 → 0.114.0-50

package/esm/src/cli/common/$requireCliSubcommand.d.ts

@@ -0,0 +1,18 @@
+import type { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Makes one CLI command which only groups subcommands ask for a subcommand instead of doing anything on its own.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers an action in the CLI
+ *
+ * @private utility of CLI
+ */
+export declare function $requireCliSubcommand(command: Command): $side_effect;
+/**
+ * Asks for a subcommand of one CLI command, prints its help and exits the process.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it writes to the console and exits the process
+ *
+ * @private utility of CLI
+ */
+export declare function $reportMissingCliSubcommand(command: Command): never;

package/esm/src/cli/common/$requireCliSubcommand.test.d.ts

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

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

@@ -84,8 +84,23 @@ export declare class AgentCollectionInSupabase {
     private mapAgentBasicInformationRow;
     /**
      * Retrieves the permanent ID of an agent by its name or permanent ID.
+     *
+     * An agent that still exists always wins over a soft-deleted one, so a name that was deleted and
+     * later created again resolves to the agent that is live now instead of to the recycle-bin leftover.
+     * Soft-deleted agents stay resolvable as a fallback because the recycle bin restores them by name
+     * or permanent id.
      */
     getAgentPermanentId(agentNameOrPermanentId: string_agent_name | string_agent_permanent_id): Promise<string_agent_permanent_id>;
+    /**
+     * Looks up the permanent id of the oldest agent matching one name or permanent id.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
+     * @param options - Whether soft-deleted agents may be matched as well.
+     * @returns Permanent id of the matched agent, or `null` when nothing matches.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private findAgentPermanentId;
     /**
      * Retrieves the source code of an agent by its name or permanent ID.
      */

package/esm/src/commitments/TEAM/TEAM.test.d.ts

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

package/esm/src/commitments/WRITING_RULES/WRITING_RULES.d.ts

@@ -3,23 +3,30 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * `WRITING RULES` commitment definition.
  *
- * It adds constraints that apply strictly to writing style and presentation
- * rather than task-solving behavior.
+ * The `WRITING RULES`/`WRITING RULE` commitment adds constraints that apply strictly to writing style
+ * and presentation rather than task-solving behavior.
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * WRITING RULES Keep every response under 120 words
+ * WRITING RULE Always end the message with an emoji
+ * ```
  *
  * @private [🪔] Maybe export the commitments through some package
  */
-export declare class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES'> {
-    constructor();
+export declare class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES' | 'WRITING RULE'> {
+    constructor(type?: 'WRITING RULES' | 'WRITING RULE');
     /**
-     * Short one-line description of `WRITING RULES`.
+     * Short one-line description of `WRITING RULES`/`WRITING RULE`.
      */
     get description(): string;
     /**
-     * Icon for `WRITING RULES`.
+     * Icon for `WRITING RULES`/`WRITING RULE`.
      */
     get icon(): string;
     /**
-     * Markdown documentation for `WRITING RULES`.
+     * Markdown documentation for `WRITING RULES`/`WRITING RULE` commitment.
      */
     get documentation(): string;
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;

package/esm/src/commitments/index.d.ts

@@ -55,4 +55,4 @@ import { NotYetImplementedCommitmentDefinition } from './_base/NotYetImplemented
  *
  * @private Use functions to access commitments instead of this array directly
  */
-export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDescriptionCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaFullnameCommitmentDefinition, MetaIdCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaThinkingMessageCommitmentDefinition, MetaVisibilityCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];
+export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDescriptionCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaFullnameCommitmentDefinition, MetaIdCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaThinkingMessageCommitmentDefinition, MetaVisibilityCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];

package/esm/src/conversion/archive/loadJsZipModule.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Loads the ZIP archive library (`jszip`) on demand
+ *
+ * Note: [🐌] Loaded lazily to keep the startup of the `ptbk` CLI utility fast
+ *
+ * @private internal utility of `loadArchive` and `saveArchive`
+ */
+export declare const loadJsZipModule: () => Promise<{
+    default: typeof import('jszip');
+}>;

package/esm/src/executables/platforms/locateAppOnWindows.d.ts

@@ -1,7 +1,7 @@
 import type { string_executable_path } from '../../types/string_filename';
 import type { LocateAppOptions } from '../locateApp';
 /**
- * Attempts to locate the specified application on a Windows system by searching common installation directories.
+ * Attempts to locate the specified application on a Windows system by searching PATH and common installation directories.
  * Returns the path to the executable if found, or null otherwise.
  *
  * @private within the repository

package/esm/src/executables/platforms/locateAppOnWindows.test.d.ts

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

package/esm/src/llm-providers/vercel/VercelExecutionToolsOptions.d.ts

@@ -17,7 +17,10 @@ export type VercelExecutionToolsOptions = CommonToolsOptions & Pick<LlmExecution
      */
     readonly availableModels: ReadonlyArray<AvailableModel>;
     /**
-     * Additional settings for chat models when calling `vercelProvider.chat('model-name', settings)`
+     * Additional settings for chat models, for example `temperature` or `providerOptions`
+     *
+     * Note: Since Vercel AI SDK v5 these settings belong to the model call, not to
+     *       `vercelProvider.chat('model-name')` which takes just the model name
      */
-    readonly additionalChatSettings?: Partial<Parameters<VercelProvider['chat']>[1]>;
+    readonly additionalChatSettings?: Partial<Omit<Parameters<ReturnType<VercelProvider['chat']>['doGenerate']>[0], 'prompt'>>;
 };

package/esm/src/utils/agent-message-runtime/AgentMessageProjectChange.d.ts

@@ -0,0 +1,76 @@
+/**
+ * One file an answered agent message created, edited or deleted inside one project.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageProjectChangedFile = {
+    /**
+     * Path of the file relative to the project root, using `/` separators.
+     */
+    readonly path: string;
+    /**
+     * Count of lines added to the file.
+     */
+    readonly insertionCount: number;
+    /**
+     * Count of lines removed from the file.
+     */
+    readonly deletionCount: number;
+};
+/**
+ * Everything answering one single message changed inside one agent project.
+ *
+ * Each agent project is a git repository and every answer which modifies it is committed there
+ * automatically, so this describes exactly one such commit — the trace of what one message really
+ * did to one project, which a chat can show below the answer that did it.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageProjectChange = {
+    /**
+     * Directory name of the changed project inside the agent `projects/` folder.
+     */
+    readonly projectName: string;
+    /**
+     * Full hash of the commit holding the changes of this message.
+     */
+    readonly commitHash: string;
+    /**
+     * ISO 8601 timestamp when the changes were committed.
+     */
+    readonly committedAt: string;
+    /**
+     * Files the message changed, ordered as git reports them.
+     */
+    readonly changedFiles: ReadonlyArray<AgentMessageProjectChangedFile>;
+    /**
+     * Count of lines added across all changed files.
+     */
+    readonly insertionCount: number;
+    /**
+     * Count of lines removed across all changed files.
+     */
+    readonly deletionCount: number;
+    /**
+     * Unified diff of the commit, shortened when the change is too large to carry into a chat.
+     */
+    readonly diff: string;
+    /**
+     * Whether `diff` holds only the beginning of the real diff.
+     */
+    readonly isDiffTruncated: boolean;
+};
+/**
+ * Validates one already-parsed JSON value as a project change.
+ *
+ * @param value - Raw serialized project change.
+ * @returns The typed project change, or `null` when the value does not match the expected shape,
+ * so consumers can silently skip foreign or malformed entries.
+ *
+ * @private internal utility of the agent-message runtime
+ */
+export declare function normalizeAgentMessageProjectChange(value: unknown): AgentMessageProjectChange | null;

package/esm/src/utils/agent-message-runtime/AgentMessageTouchedExternalSource.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Category of one external source an answered agent message touched.
+ *
+ * -   `integration` is a third-party service reached through an integration, for example Gmail.
+ * -   `website` is a concrete web address the agent fetched or browsed.
+ * -   `search` is a lookup the agent ran against a web search engine.
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageTouchedExternalSourceKind = 'integration' | 'website' | 'search';
+/**
+ * One source outside the agent itself which answering a single message viewed or edited.
+ *
+ * Everything the agent does inside its own folder stays internal and is never described here;
+ * this records only the reach beyond it, so a chat can tell which outside services and websites
+ * one answer really involved.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageTouchedExternalSource = {
+    /**
+     * Category of the touched source.
+     */
+    readonly kind: AgentMessageTouchedExternalSourceKind;
+    /**
+     * User-facing name of the source, for example `Gmail`, `example.com` or the search query.
+     */
+    readonly name: string;
+    /**
+     * Address of the source, when the touch names a concrete one.
+     */
+    readonly url?: string;
+};
+/**
+ * Validates one already-parsed JSON value as a touched external source.
+ *
+ * @param value - Raw serialized source.
+ * @returns The typed source, or `null` when the value does not match the expected shape, so
+ * consumers can silently skip foreign or malformed entries.
+ *
+ * @private internal utility of the agent-message runtime
+ */
+export declare function normalizeAgentMessageTouchedExternalSource(value: unknown): AgentMessageTouchedExternalSource | null;

package/esm/src/utils/agent-message-runtime/parseAgentMessageRuntimeLogEvents.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One string-keyed payload of a coding-harness tool invocation.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+type RuntimeLogToolInput = Record<string, unknown>;
+/**
+ * One content block of a Claude Code `stream-json` assistant event.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogContentBlock = {
+    readonly type?: string;
+    readonly text?: string;
+    readonly name?: string;
+    readonly input?: RuntimeLogToolInput;
+};
+/**
+ * One file path touched by a Codex `file_change` item.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogFileChange = {
+    readonly path?: string;
+};
+/**
+ * Minimal shape of one coding-harness runtime log event.
+ *
+ * The runtime log mixes two harness formats — Claude Code `stream-json` (`type`/`message`) and
+ * Codex JSONL (`type`/`item`) — so both are described by one permissive structure and every
+ * consumer reads only the fields it understands.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogEvent = {
+    readonly type?: string;
+    readonly message?: {
+        readonly content?: ReadonlyArray<AgentMessageRuntimeLogContentBlock>;
+    };
+    readonly item?: {
+        readonly type?: string;
+        readonly command?: string;
+        readonly exit_code?: number | null;
+        readonly changes?: ReadonlyArray<AgentMessageRuntimeLogFileChange>;
+        readonly server?: string;
+        readonly tool?: string;
+        readonly query?: string;
+    };
+};
+/**
+ * Parses every structured event out of one coding-harness runtime log.
+ *
+ * The local agent runner streams the answering harness output into a live runtime log file, one
+ * JSON event per line, optionally prefixed by shell noise. Lines without a usable JSON object are
+ * skipped so a partially written or interleaved log never breaks its consumers.
+ *
+ * @param logText - Raw runtime log content.
+ * @returns Structured events in the order they were streamed.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function parseAgentMessageRuntimeLogEvents(logText: string | null | undefined): ReadonlyArray<AgentMessageRuntimeLogEvent>;
+export {};

package/esm/src/utils/agent-message-runtime/resolveAgentMessageRuntimeActivity.d.ts

@@ -5,9 +5,9 @@
  * Claude Code `--output-format stream-json`) into a live runtime log file next to the queued
  * message. This helper extracts the most recent natural-language assistant narration so the
  * durable chat can show what the agent is doing right now instead of a generic thinking
- * placeholder. Only plain assistant text is surfaced; raw tool payloads, JSON envelopes and
- * other technical details are intentionally ignored, and harnesses that do not stream
- * structured text simply resolve to `null` so the caller keeps its existing behavior.
+ * placeholder. Only concrete, safe activity is surfaced; raw tool payloads, JSON envelopes,
+ * and private reasoning are intentionally ignored. When no concrete activity is known, this
+ * resolves to `null` so the caller keeps the browser's rotating generic thinking state.
  *
  * @param logText - Raw runtime log content.
  * @returns Latest human-readable activity snippet, or `null` when none can be resolved.

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedExternalSources.d.ts

@@ -0,0 +1,18 @@
+import type { AgentMessageTouchedExternalSource } from './AgentMessageTouchedExternalSource';
+/**
+ * Resolves which sources outside the agent one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a source counts as touched when the
+ * harness reached it in a tool invocation — calling an integration, fetching a web address,
+ * searching the web, or running a network client in the shell. Only tool payloads are inspected:
+ * tool results and assistant narration are ignored so a service merely mentioned in the
+ * conversation is never reported, and addresses of the machine the agent runs on are dropped
+ * because they are internal.
+ *
+ * @param options - Raw runtime log content of one answered message.
+ * @returns Touched external sources without duplicates, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function resolveAgentMessageTouchedExternalSources(options: {
+    readonly logText: string | null | undefined;
+}): ReadonlyArray<AgentMessageTouchedExternalSource>;

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedExternalSources.test.d.ts

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

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedProjectNames.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolves which projects one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a project counts as touched when the
+ * harness named it in a tool invocation — reading, searching, running, or editing files inside
+ * `projects/<project-name>/`. Only tool payloads are inspected: tool results and assistant
+ * narration are ignored so a project merely mentioned in the conversation is never reported.
+ *
+ * Every candidate is matched against the projects that really exist, which both filters prompt
+ * placeholders such as `projects/<project-name>/` and keeps the reported names canonical.
+ *
+ * @param options - Raw runtime log content and the project directory names of the agent.
+ * @returns Touched project names in the canonical spelling, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function resolveAgentMessageTouchedProjectNames(options: {
+    readonly logText: string | null | undefined;
+    readonly knownProjectNames: ReadonlyArray<string>;
+}): ReadonlyArray<string>;

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedProjectNames.test.d.ts

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

package/esm/src/utils/agents/terminalAgentAvatarVisual.d.ts

@@ -75,9 +75,12 @@ export type CreateTerminalAgentAvatarVisualOptions = {
      */
     readonly colorDepth?: AsciiArtColorDepth;
     /**
-     * Platform-specific canvas factory used to rasterize the visual.
+     * Platform-specific canvas factory used to rasterize pixel-based visuals.
+     *
+     * Character-based visuals such as `AsciiOctopus` paint the terminal grid directly, so they
+     * render without any canvas; a pixel-based visual renders an empty frame when it is missing.
      */
-    readonly createCanvas: CreateCanvasForAsciiArt;
+    readonly createCanvas?: CreateCanvasForAsciiArt;
 };
 /**
  * Resolves the built-in avatar visual selected for terminal rendering of one agent source.

package/esm/src/utils/ascii-art/convertImageDataToAsciiArt.d.ts

@@ -62,6 +62,12 @@ export type ConvertImageDataToAsciiArtOptions = {
      */
     readonly alphaThreshold?: number;
 };
+/**
+ * Default alpha channel value below which a cell is rendered as terminal background.
+ *
+ * @private within the repository
+ */
+export declare const DEFAULT_ALPHA_THRESHOLD = 32;
 /**
  * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
  *

package/esm/src/utils/ascii-art/createAnsiColorCode.d.ts

@@ -0,0 +1,46 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+/**
+ * ANSI escape sequence that resets all colors and attributes.
+ *
+ * @private within the repository
+ */
+export declare const ANSI_RESET = "\u001B[0m";
+/**
+ * One opaque 24-bit color which should be written into an ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export type AnsiRgbColor = {
+    /**
+     * Red channel in the range `[0, 255]`.
+     */
+    readonly red: number;
+    /**
+     * Green channel in the range `[0, 255]`.
+     */
+    readonly green: number;
+    /**
+     * Blue channel in the range `[0, 255]`.
+     */
+    readonly blue: number;
+};
+/**
+ * Creates the ANSI escape code that sets the foreground color of following characters.
+ *
+ * @param color Color painted onto the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export declare function createAnsiForegroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;
+/**
+ * Creates the ANSI escape code that sets the background color of following characters.
+ *
+ * @param color Color painted behind the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export declare function createAnsiBackgroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;

package/esm/src/utils/files/findFilesByGlob.d.ts

@@ -0,0 +1,28 @@
+import { type GlobOptionsWithFileTypesUnset } from 'glob';
+import type { string_filename } from '../../types/string_filename';
+/**
+ * Options of `findFilesByGlob`
+ *
+ * Note: These are the options of `glob` itself, only `ignore` also accepts a readonly array
+ *       @see https://www.npmjs.com/package/glob#options
+ *
+ * @private internal type of `findFilesByGlob`
+ */
+export type FindFilesByGlobOptions = Omit<GlobOptionsWithFileTypesUnset, 'ignore'> & {
+    /**
+     * Glob patterns which are excluded from the result
+     */
+    readonly ignore?: string | ReadonlyArray<string>;
+};
+/**
+ * Finds all filenames matching a glob pattern
+ *
+ * Note: This is the single place where `glob` is used, so that every caller gets the same shape of results
+ *       on every operating system - POSIX separators and a stable order - which `glob` itself does not guarantee
+ *
+ * @param pattern Glob pattern to match, for example `./src/**\/*.ts`
+ * @param options Options passed to `glob`
+ * @returns Matching filenames with `/` separators, sorted alphabetically
+ * @private within the repository
+ */
+export declare function findFilesByGlob(pattern: string, options?: FindFilesByGlobOptions): Promise<Array<string_filename>>;

package/esm/src/utils/misc/debounce.d.ts

@@ -1,7 +1,9 @@
 import type { TODO_any } from '../organization/TODO_any';
 /**
- * Handles debounce.
+ * Creates a debounced function that runs after calls have been quiet for the given delay.
  *
  * @public exported from `@promptbook/utils`
  */
-export declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): (...args: Parameters<T>) => void;
+export declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};

package/esm/src/utils/misc/debounce.test.d.ts

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

package/esm/src/utils/misc/emojis.d.ts

@@ -10,9 +10,10 @@ import type { string_char_emoji } from '../../types/typeAliasEmoji';
  */
 export declare const EMOJIS_IN_CATEGORIES: Record<string, ReadonlyArray<string_char_emoji>>;
 /**
- * All possible emoji chars like "🍆", "🍡", "🍤"...
+ * Curated repository catalogue of emoji and legacy pictographic symbols.
  *
- * @deprecated Use /\p{Extended_Pictographic}/ instead
+ * Code that needs to generate a valid Unicode emoji should apply its own validation
+ * to this catalogue rather than assume every entry is an emoji.
  *
  * @private within the repository
  */

package/esm/src/utils/random/$generateBookBoilerplate.test.d.ts

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

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-4`).
+ * It follows semantic versioning (e.g., `0.114.0-49`).
  *
  * @generated
  */