@promptbook/cli 0.114.0-5 → 0.114.0-50

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

@@ -1,5 +1,7 @@
 import { spaceTrim } from 'spacetrim';
 import { UnexpectedError } from '../../errors/UnexpectedError';
+import type { AnsiRgbColor } from './createAnsiColorCode';
+import { ANSI_RESET, createAnsiBackgroundColorCode, createAnsiForegroundColorCode } from './createAnsiColorCode';
 
 /**
  * Color depth of the ANSI escape codes emitted by the ASCII-art conversion.
@@ -75,11 +77,11 @@ export type ConvertImageDataToAsciiArtOptions = {
 };
 
 /**
- * Default alpha channel value below which a half-cell is rendered as terminal background.
+ * Default alpha channel value below which a cell is rendered as terminal background.
  *
  * @private within the repository
  */
-const DEFAULT_ALPHA_THRESHOLD = 32;
+export const DEFAULT_ALPHA_THRESHOLD = 32;
 
 /**
  * Number of channels per pixel in an RGBA buffer.
@@ -102,57 +104,12 @@ const UPPER_HALF_BLOCK = '▀'; // <- ▀
  */
 const LOWER_HALF_BLOCK = '▄'; // <- ▄
 
-/**
- * ANSI escape sequence that resets all colors and attributes.
- *
- * @private within the repository
- */
-const ANSI_RESET = '\u001b[0m';
-
-/**
- * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
- *
- * @private within the repository
- */
-const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
-
-/**
- * Gray level above which an achromatic color maps to the pure white color-cube entry.
- *
- * @private within the repository
- */
-const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
-
-/**
- * Index of pure white inside the 6×6×6 ANSI color cube.
- *
- * @private within the repository
- */
-const ANSI_256_WHITE_INDEX = 231;
-
-/**
- * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
- *
- * @private within the repository
- */
-const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
-
-/**
- * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
- *
- * @private within the repository
- */
-const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
-
 /**
  * Area-averaged color of one half of a character cell.
  *
  * @private helper of `convertImageDataToAsciiArt`
  */
-type HalfCellColor = {
-    readonly red: number;
-    readonly green: number;
-    readonly blue: number;
+type HalfCellColor = AnsiRgbColor & {
     readonly isOpaque: boolean;
 };
 
@@ -231,15 +188,15 @@ export function convertImageDataToAsciiArt(options: ConvertImageDataToAsciiArtOp
 
             if (topHalfColor.isOpaque && bottomHalfColor.isOpaque) {
                 character = UPPER_HALF_BLOCK;
-                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
-                nextBackgroundCode = createBackgroundColorCode(bottomHalfColor, colorDepth);
+                nextForegroundCode = createAnsiForegroundColorCode(topHalfColor, colorDepth);
+                nextBackgroundCode = createAnsiBackgroundColorCode(bottomHalfColor, colorDepth);
             } else if (topHalfColor.isOpaque) {
                 character = UPPER_HALF_BLOCK;
-                nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                nextForegroundCode = createAnsiForegroundColorCode(topHalfColor, colorDepth);
                 nextBackgroundCode = undefined;
             } else if (bottomHalfColor.isOpaque) {
                 character = LOWER_HALF_BLOCK;
-                nextForegroundCode = createForegroundColorCode(bottomHalfColor, colorDepth);
+                nextForegroundCode = createAnsiForegroundColorCode(bottomHalfColor, colorDepth);
                 nextBackgroundCode = undefined;
             } else {
                 character = ' ';
@@ -337,60 +294,3 @@ function computeHalfCellColor(
         isOpaque: true,
     };
 }
-
-/**
- * Creates the ANSI escape code that sets the foreground color of following characters.
- *
- * @private helper of `convertImageDataToAsciiArt`
- */
-function createForegroundColorCode(color: HalfCellColor, colorDepth: AsciiArtColorDepth): string {
-    if (colorDepth === 'TRUE_COLOR') {
-        return `\u001b[38;2;${color.red};${color.green};${color.blue}m`;
-    }
-
-    return `\u001b[38;5;${mapColorToAnsi256(color)}m`;
-}
-
-/**
- * Creates the ANSI escape code that sets the background color of following characters.
- *
- * @private helper of `convertImageDataToAsciiArt`
- */
-function createBackgroundColorCode(color: HalfCellColor, colorDepth: AsciiArtColorDepth): string {
-    if (colorDepth === 'TRUE_COLOR') {
-        return `\u001b[48;2;${color.red};${color.green};${color.blue}m`;
-    }
-
-    return `\u001b[48;5;${mapColorToAnsi256(color)}m`;
-}
-
-/**
- * Maps a 24-bit color onto the closest entry of the 256-color ANSI palette.
- *
- * Uses the 6×6×6 color cube (entries 16-231) and the grayscale ramp (entries 232-255).
- *
- * @private helper of `convertImageDataToAsciiArt`
- */
-function mapColorToAnsi256(color: HalfCellColor): number {
-    const { red, green, blue } = color;
-
-    // Note: Prefer the finer grayscale ramp when the color is (nearly) achromatic
-    const maxChannel = Math.max(red, green, blue);
-    const minChannel = Math.min(red, green, blue);
-    if (maxChannel - minChannel < ANSI_256_ACHROMATIC_CHANNEL_SPREAD) {
-        const gray = Math.round((red + green + blue) / 3);
-        if (gray < 4) {
-            return 16; // <- Note: Pure black lives in the color cube
-        }
-        if (gray > ANSI_256_NEAR_WHITE_GRAY_LEVEL) {
-            return ANSI_256_WHITE_INDEX; // <- Note: Pure white lives in the color cube
-        }
-        return 232 + Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN);
-    }
-
-    const redIndex = Math.round((red / 255) * 5);
-    const greenIndex = Math.round((green / 255) * 5);
-    const blueIndex = Math.round((blue / 255) * 5);
-
-    return 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
-}

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

@@ -0,0 +1,132 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * ANSI escape sequence that resets all colors and attributes.
+ *
+ * @private within the repository
+ */
+export const ANSI_RESET = '\u001b[0m';
+
+/**
+ * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
+ *
+ * @private within the repository
+ */
+const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
+
+/**
+ * Gray level above which an achromatic color maps to the pure white color-cube entry.
+ *
+ * @private within the repository
+ */
+const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
+
+/**
+ * Index of pure white inside the 6×6×6 ANSI color cube.
+ *
+ * @private within the repository
+ */
+const ANSI_256_WHITE_INDEX = 231;
+
+/**
+ * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
+ *
+ * @private within the repository
+ */
+const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
+
+/**
+ * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
+ *
+ * @private within the repository
+ */
+const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
+
+/**
+ * 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 function createAnsiForegroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string {
+    if (colorDepth === 'TRUE_COLOR') {
+        return `\u001b[38;2;${color.red};${color.green};${color.blue}m`;
+    }
+
+    return `\u001b[38;5;${mapColorToAnsi256(color)}m`;
+}
+
+/**
+ * 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 function createAnsiBackgroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string {
+    if (colorDepth === 'TRUE_COLOR') {
+        return `\u001b[48;2;${color.red};${color.green};${color.blue}m`;
+    }
+
+    return `\u001b[48;5;${mapColorToAnsi256(color)}m`;
+}
+
+/**
+ * Maps a 24-bit color onto the closest entry of the 256-color ANSI palette.
+ *
+ * Uses the 6×6×6 color cube (entries 16-231) and the grayscale ramp (entries 232-255).
+ *
+ * @private helper of `createAnsiForegroundColorCode` and `createAnsiBackgroundColorCode`
+ */
+function mapColorToAnsi256(color: AnsiRgbColor): number {
+    const { red, green, blue } = color;
+
+    // Note: Prefer the finer grayscale ramp when the color is (nearly) achromatic
+    const maxChannel = Math.max(red, green, blue);
+    const minChannel = Math.min(red, green, blue);
+    if (maxChannel - minChannel < ANSI_256_ACHROMATIC_CHANNEL_SPREAD) {
+        const gray = Math.round((red + green + blue) / 3);
+        if (gray < 4) {
+            return 16; // <- Note: Pure black lives in the color cube
+        }
+        if (gray > ANSI_256_NEAR_WHITE_GRAY_LEVEL) {
+            return ANSI_256_WHITE_INDEX; // <- Note: Pure white lives in the color cube
+        }
+        return 232 + Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN);
+    }
+
+    const redIndex = Math.round((red / 255) * 5);
+    const greenIndex = Math.round((green / 255) * 5);
+    const blueIndex = Math.round((blue / 255) * 5);
+
+    return 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
+}

package/src/utils/execCommand/$execCommand.ts

@@ -107,8 +107,9 @@ export function $execCommand(options: ExecCommandOptions): Promise<$side_effect
                 }
             };
 
+            // `exit` can arrive before the stdout/stderr pipes finish. Git metadata and hook diagnostics
+            // must be complete before a following repository inspection uses the command's result.
             commandProcess.on('close', finishWithCode);
-            commandProcess.on('exit', finishWithCode);
             commandProcess.on('disconnect', () => {
                 // Note: Unexpected disconnection should always result in rejection
                 reject(new Error(`Command "${humanReadableCommand}" disconnected`));

package/src/utils/files/findFilesByGlob.ts

@@ -0,0 +1,46 @@
+import { glob, 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 async function findFilesByGlob(
+    pattern: string,
+    options: FindFilesByGlobOptions = {},
+): Promise<Array<string_filename>> {
+    const { ignore, ...restOptions } = options;
+
+    const matchedFilenames = await glob(pattern, {
+        ...restOptions,
+        ignore: typeof ignore === 'string' || ignore === undefined ? ignore : [...ignore],
+    });
+
+    return matchedFilenames
+        .map((matchedFilename) => matchedFilename.split('\\').join('/'))
+        .sort((filenameA, filenameB) => filenameA.localeCompare(filenameB, 'en'));
+}
+
+// Note: Not [~🟢~] because it is not directly dependent on `fs`, same as `listAllFiles`

package/src/utils/misc/debounce.ts

@@ -1,14 +1,35 @@
 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 function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number) {
+export function debounce<T extends (...args: TODO_any[]) => void>(
+    fn: T,
+    delay: number,
+): ((...args: Parameters<T>) => void) & { cancel: () => void } {
     let timeout: ReturnType<typeof setTimeout> | null = null;
-    return (...args: Parameters<T>) => {
-        if (timeout) clearTimeout(timeout);
-        timeout = setTimeout(() => fn(...args), delay);
+
+    const cancel = () => {
+        if (timeout === null) {
+            return;
+        }
+
+        clearTimeout(timeout);
+        timeout = null;
     };
+
+    const debounced = (...args: Parameters<T>) => {
+        cancel();
+
+        timeout = setTimeout(() => {
+            timeout = null;
+            fn(...args);
+        }, delay);
+    };
+
+    debounced.cancel = cancel;
+
+    return debounced;
 }

package/src/utils/misc/emojis.ts

@@ -114,14 +114,14 @@ export const EMOJIS_IN_CATEGORIES: Record<string, ReadonlyArray<string_char_emoj
 };
 
 /**
- * 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
  */
 export const EMOJIS: Set<string_char_emoji> = new Set(Object.values(EMOJIS_IN_CATEGORIES).flat());
 
-// TODO: [💴] DRY - just one version of emojis.ts
 // TODO: Mirror from Collboard or some common package
 // Note: [💞] Ignore a discrepancy between file name and entity name

package/src/utils/random/$generateBookBoilerplate.ts

@@ -73,7 +73,7 @@ export function $generateBookBoilerplate(options?: GenerateBookBoilerplateOption
                 ${agentName}
     
                 
-                PERSONA ${block(personaDescription!)}
+                GOAL ${block(personaDescription!)}
                 ${block(initialRules.map((rule) => `RULE ${rule}`).join('\n'))}
                 CLOSED
             `,

package/src/version.ts

@@ -16,11 +16,11 @@ export const BOOK_LANGUAGE_VERSION: string_semantic_version = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-export const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version = '0.114.0-5';
+export const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version = '0.114.0-50';
 
 /**
  * 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
  */

package/src/versions.txt

@@ -1183,3 +1183,45 @@
 0.114.0-3
 0.114.0-4
 0.114.0-5
+0.114.0-6
+0.114.0-8
+0.114.0-9
+0.114.0-10
+0.114.0-12
+0.114.0-13
+0.114.0-14
+0.114.0-15
+0.114.0-16
+0.114.0-17
+0.114.0-18
+0.114.0-19
+0.114.0-20
+0.114.0-21
+0.114.0-22
+0.114.0-23
+0.114.0-24
+0.114.0-25
+0.114.0-26
+0.114.0-27
+0.114.0-28
+0.114.0-29
+0.114.0-30
+0.114.0-31
+0.114.0-32
+0.114.0-33
+0.114.0-34
+0.114.0-35
+0.114.0-36
+0.114.0-37
+0.114.0-38
+0.114.0-39
+0.114.0-40
+0.114.0-42
+0.114.0-43
+0.114.0-44
+0.114.0-45
+0.114.0-46
+0.114.0-47
+0.114.0-48
+0.114.0-49
+0.114.0-50

package/umd/apps/agents-server/src/constants/federatedAgentImport.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Metadata key storing the comma-separated federated server URL list.
+ *
+ * @private shared Agents Server constant
+ */
+export declare const FEDERATED_SERVERS_METADATA_KEY: "FEDERATED_SERVERS";
 /**
  * Metadata key storing the delay between retry attempts when importing federated agent books.
  *