@promptbook/cli 0.113.0-4 → 0.113.0-8

package/umd/scripts/find-refactor-candidates/find-refactor-candidates.d.ts

@@ -15,4 +15,11 @@ export type FindRefactorCandidatesOptions = {
      * Aggressiveness level used to score candidate files.
      */
     readonly level?: RefactorCandidateLevel;
+    /**
+     * Maximum number of refactor prompts to create in this run.
+     *
+     * When more candidates are found than this limit, only the most important ones (by severity)
+     * are turned into prompts. When omitted, a prompt is created for every candidate.
+     */
+    readonly limit?: number;
 };

package/umd/scripts/find-refactor-candidates/selectMostImportantRefactorCandidates.d.ts

@@ -0,0 +1,12 @@
+import type { RefactorCandidate } from './RefactorCandidate';
+/**
+ * Keeps at most `limit` refactor candidates, preferring the most important ones.
+ *
+ * When there are more candidates than `limit`, only the highest-severity candidates are kept
+ * (ties broken by relative path for determinism). When `limit` is `undefined` or there are fewer
+ * candidates than the limit, every candidate is returned. The original input order is preserved
+ * among the kept candidates, so `limit` acts purely as a filter and never reorders prompts.
+ *
+ * @private function of findRefactorCandidates
+ */
+export declare function selectMostImportantRefactorCandidates(candidates: ReadonlyArray<RefactorCandidate>, limit: number | undefined): ReadonlyArray<RefactorCandidate>;

package/umd/scripts/run-codex-prompts/common/resolveCoderAgent.d.ts

@@ -0,0 +1,20 @@
+import type { string_book } from '../../../src/book-2.0/agent-source/string_book';
+/**
+ * Agent data resolved from the optional `--agent` book file.
+ */
+export type ResolvedCoderAgent = {
+    /**
+     * Raw source of the agent `.book` file.
+     */
+    readonly agentSource: string_book;
+    /**
+     * Compiled system message injected into each coding prompt.
+     */
+    readonly systemMessage: string;
+};
+/**
+ * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+ *
+ * Returns `undefined` when no agent path is provided.
+ */
+export declare function resolveCoderAgent(agentPath: string | undefined, currentWorkingDirectory: string): Promise<ResolvedCoderAgent | undefined>;

package/umd/scripts/run-codex-prompts/ui/CoderRunUiState.d.ts

@@ -41,6 +41,7 @@ export type { CoderRunProgressSnapshot };
  */
 export declare class CoderRunUiState extends EventEmitter {
     config: CoderRunConfig;
+    agentVisualLines: string[] | undefined;
     currentPromptLabel: string;
     currentScriptPaths: string[];
     currentAttempt: number;
@@ -72,6 +73,10 @@ export declare class CoderRunUiState extends EventEmitter {
      * Replaces the configuration shown in the UI header.
      */
     setConfig(config: CoderRunConfig): void;
+    /**
+     * Replaces the ASCII-art agent visual shown instead of the default brand banner.
+     */
+    setAgentVisualLines(agentVisualLines: ReadonlyArray<string> | undefined): void;
     /**
      * Feeds new prompt statistics from the main loop so the progress bar updates.
      */

package/umd/scripts/run-codex-prompts/ui/buildCoderRunAgentVisual.d.ts

@@ -0,0 +1,29 @@
+import type { string_book } from '../../../src/book-2.0/agent-source/string_book';
+/**
+ * Output width of the coder-run agent visual in terminal character cells.
+ *
+ * @private internal constant of coder run UI
+ */
+export declare const CODER_RUN_AGENT_VISUAL_COLUMNS = 24;
+/**
+ * Output height of the coder-run agent visual in terminal character cells.
+ *
+ * Half of the columns keeps the square avatar visually square in a common terminal font.
+ *
+ * @private internal constant of coder run UI
+ */
+export declare const CODER_RUN_AGENT_VISUAL_ROWS = 12;
+/**
+ * Builds the ANSI ASCII-art visual of the `--agent` book shown above the coder-run dashboard.
+ *
+ * The agent's avatar visual is resolved the same way as on the website - the `META AVATAR`
+ * commitment wins, then the `META VISUAL` commitment, then the shared default visual - and is
+ * rendered dynamically through the shared canvas avatar pipeline into terminal ASCII art.
+ *
+ * The visual is decorative, so any failure (for example when the optional `@napi-rs/canvas`
+ * module is not installed) returns `null` and the caller keeps the default brand banner.
+ *
+ * @param agentSource Source of the `--agent` book file.
+ * @returns ANSI-colored ASCII-art lines or `null` when the visual cannot be rendered.
+ */
+export declare function buildCoderRunAgentVisual(agentSource: string_book): Promise<ReadonlyArray<string> | null>;

package/umd/scripts/run-codex-prompts/ui/buildCoderRunUiFrame.d.ts

@@ -11,6 +11,10 @@ export type BuildCoderRunUiFrameOptions = {
     readonly terminalWidth: number;
     readonly animationFrame: number;
     readonly spinner: string;
+    /**
+     * ANSI ASCII-art lines of the `--agent` avatar visual shown instead of the default brand banner.
+     */
+    readonly agentVisualLines?: readonly string[];
     readonly pauseState: CoderRunPauseState;
     readonly pauseTargetLabel: string;
     readonly config: CoderRunConfig;

package/umd/src/avatars/renderAvatarVisualAsciiArt.d.ts

@@ -0,0 +1,75 @@
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarVisualId } from './types/AvatarVisualDefinition';
+/**
+ * Default output width of the ASCII avatar in terminal character cells.
+ *
+ * @private within the repository
+ */
+export declare const DEFAULT_AVATAR_ASCII_ART_COLUMNS = 32;
+/**
+ * Factory creating a drawable canvas of the requested pixel size.
+ *
+ * In browsers this is typically `document.createElement('canvas')` (with width/height set),
+ * in Node.js an adapter around `createCanvas` of `@napi-rs/canvas` or a compatible library.
+ *
+ * @private within the repository
+ */
+export type CreateCanvasForAsciiArt = (width: number, height: number) => HTMLCanvasElement;
+/**
+ * Options for `renderAvatarVisualAsciiArt`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualAsciiArtOptions = {
+    /**
+     * Stable visual identity of the rendered agent avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+    /**
+     * Built-in avatar visual to render, the same one used on the website.
+     */
+    readonly visualId: AvatarVisualId;
+    /**
+     * Output width in terminal character cells.
+     *
+     * @default `DEFAULT_AVATAR_ASCII_ART_COLUMNS`
+     */
+    readonly columns?: number;
+    /**
+     * Output height in terminal character cells.
+     *
+     * @default `columns / 2` so the square avatar stays visually square in a common terminal font
+     */
+    readonly rows?: number;
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+    /**
+     * Animation timestamp for animated visuals.
+     *
+     * @default `STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS`
+     */
+    readonly timeMs?: number;
+    /**
+     * Platform-specific canvas factory used to rasterize the visual.
+     */
+    readonly createCanvas: CreateCanvasForAsciiArt;
+};
+/**
+ * Renders one built-in avatar visual into ANSI-colored ASCII art for terminal display.
+ *
+ * This is the universal bridge between the canvas avatar visuals shown on the website and
+ * text-based terminal UIs: the visual is rasterized through the exact same `renderAvatarVisual`
+ * pipeline the web uses, then the resulting pixels are converted into colored half-block
+ * characters by `convertImageDataToAsciiArt`.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and the platform canvas factory.
+ * @returns One ANSI-colored string per output row.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualAsciiArt(options: RenderAvatarVisualAsciiArtOptions): ReadonlyArray<string>;

package/umd/src/book-components/Chat/Chat/insertDictationChunk.d.ts

@@ -8,7 +8,7 @@ export declare function insertDictationChunk(params: {
     readonly dictatedText: string;
     readonly selectionStart: number;
     readonly selectionEnd: number;
-    readonly shouldReplaceSelection: boolean;
+    readonly isReplacingSelection: boolean;
 }): {
     nextValue: string;
     start: number;

package/umd/src/book-components/Chat/Chat/insertDictationChunk.test.d.ts

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

package/umd/src/book-components/Chat/Chat/learnDictationDictionary.test.d.ts

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

package/umd/src/book-components/Chat/Chat/refineFinalDictationChunk.test.d.ts

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

package/umd/src/cli/cli-commands/common/createPositiveIntegerOptionParser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a Commander argument parser that accepts only positive 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 positive integer.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function createPositiveIntegerOptionParser(optionName: string): (value: string) => number;

package/umd/src/utils/ascii-art/$detectTerminalAnsiColorDepth.d.ts

@@ -0,0 +1,15 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+/**
+ * Detects the ANSI color depth supported by the current terminal.
+ *
+ * Prefers 24-bit true color when the environment advertises it (modern terminals such as
+ * Windows Terminal, ConEmu, VS Code, mintty, iTerm2, and WezTerm) and falls back to the
+ * portable 256-color palette otherwise.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the process environment
+ *
+ * @returns Color depth usable by `convertImageDataToAsciiArt`
+ *
+ * @private within the repository
+ */
+export declare function $detectTerminalAnsiColorDepth(): AsciiArtColorDepth;

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

@@ -0,0 +1,80 @@
+/**
+ * Color depth of the ANSI escape codes emitted by the ASCII-art conversion.
+ *
+ * - `TRUE_COLOR` emits 24-bit `38;2;r;g;b` / `48;2;r;g;b` sequences
+ * - `ANSI_256` approximates colors on the 256-color ANSI cube for older terminals
+ *
+ * @private within the repository
+ */
+export type AsciiArtColorDepth = 'TRUE_COLOR' | 'ANSI_256';
+/**
+ * Minimal structural subset of the DOM `ImageData` accepted by the ASCII-art conversion.
+ *
+ * Works with browser canvas `ImageData`, `@napi-rs/canvas` image data, or any raw RGBA buffer.
+ *
+ * @private within the repository
+ */
+export type AsciiArtImageData = {
+    /**
+     * Source image width in pixels.
+     */
+    readonly width: number;
+    /**
+     * Source image height in pixels.
+     */
+    readonly height: number;
+    /**
+     * Flat RGBA pixel buffer with 4 bytes per pixel.
+     */
+    readonly data: ArrayLike<number>;
+};
+/**
+ * Options for `convertImageDataToAsciiArt`.
+ *
+ * @private within the repository
+ */
+export type ConvertImageDataToAsciiArtOptions = {
+    /**
+     * Source pixels to convert.
+     */
+    readonly imageData: AsciiArtImageData;
+    /**
+     * Output width in terminal character cells.
+     */
+    readonly columns: number;
+    /**
+     * Output height in terminal character cells.
+     *
+     * Each character cell renders two vertically stacked pixels, so `rows = columns / 2`
+     * keeps a square image visually square in a common terminal font.
+     */
+    readonly rows: number;
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+    /**
+     * Alpha channel value (0-255) below which an averaged half-cell is treated as fully transparent.
+     *
+     * @default 32
+     */
+    readonly alphaThreshold?: number;
+};
+/**
+ * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
+ *
+ * This is the universal image-to-terminal technique used across the repository:
+ * every output character cell covers a rectangular region of source pixels which is
+ * split into a top and bottom half; each half is area-averaged and rendered with
+ * half-block characters (`▀` / `▄`) so one character shows two "pixels" vertically.
+ * Transparent halves keep the terminal background so non-rectangular images
+ * (for example rounded avatar cards) compose naturally into any terminal UI.
+ *
+ * @param options Source pixels, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, each ending with a color reset.
+ *
+ * @private within the repository
+ */
+export declare function convertImageDataToAsciiArt(options: ConvertImageDataToAsciiArtOptions): ReadonlyArray<string>;

package/umd/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.113.0-3`).
+ * It follows semantic versioning (e.g., `0.113.0-5`).
  *
  * @generated
  */

package/esm/scripts/run-codex-prompts/common/resolveAgentSystemMessage.d.ts

@@ -1,6 +0,0 @@
-/**
- * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
- *
- * Returns `undefined` when no agent path is provided.
- */
-export declare function resolveAgentSystemMessage(agentPath: string | undefined, currentWorkingDirectory: string): Promise<string | undefined>;

package/umd/scripts/run-codex-prompts/common/resolveAgentSystemMessage.d.ts

@@ -1,6 +0,0 @@
-/**
- * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
- *
- * Returns `undefined` when no agent path is provided.
- */
-export declare function resolveAgentSystemMessage(agentPath: string | undefined, currentWorkingDirectory: string): Promise<string | undefined>;