@promptbook/types 0.112.0-73 → 0.112.0-79

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

@@ -0,0 +1,65 @@
+/**
+ * File status returned by project configuration bootstrapping helpers.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export type ProjectInitializationStatus = 'created' | 'updated' | 'unchanged';
+/**
+ * Minimal environment variable descriptor used for additive `.env` initialization.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export type ProjectEnvVariableDefinition = {
+    readonly name: string;
+};
+/**
+ * Result of one additive `.env` initialization attempt.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export type EnsureProjectEnvFileResult = {
+    readonly envFileStatus: ProjectInitializationStatus;
+    readonly initializedEnvVariableNames: ReadonlyArray<string>;
+};
+/**
+ * Options required to append missing variables into a project `.env`.
+ */
+type EnsureProjectEnvFileOptions<TEnvVariable extends ProjectEnvVariableDefinition> = {
+    readonly projectPath: string;
+    readonly emptyFileContent: string;
+    readonly envVariables: ReadonlyArray<TEnvVariable>;
+    readonly buildMissingEnvVariablesBlock: (envVariables: ReadonlyArray<TEnvVariable>) => string;
+};
+/**
+ * Options required to append missing rules into a project `.gitignore`.
+ */
+type EnsureProjectGitignoreFileOptions = {
+    readonly projectPath: string;
+    readonly blockHeader: string;
+    readonly rules: ReadonlyArray<string>;
+};
+/**
+ * Ensures `.env` exists and appends only still-missing variable definitions.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function ensureProjectEnvFile<TEnvVariable extends ProjectEnvVariableDefinition>({ projectPath, emptyFileContent, envVariables, buildMissingEnvVariablesBlock, }: EnsureProjectEnvFileOptions<TEnvVariable>): Promise<EnsureProjectEnvFileResult>;
+/**
+ * Ensures `.gitignore` contains all required project initialization rules.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function ensureProjectGitignoreFile({ projectPath, blockHeader, rules, }: EnsureProjectGitignoreFileOptions): Promise<ProjectInitializationStatus>;
+/**
+ * Reads one text file when it exists, otherwise returns `undefined`.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function readTextFileIfExists(path: string): Promise<string | undefined>;
+/**
+ * Appends one text block to existing file content while preserving readable newlines.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function appendBlock(currentContent: string, blockToAppend: string): string;
+export {};

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

@@ -6,6 +6,24 @@ import type { ThinkingLevel } from '../coder/ThinkingLevel';
  * @private internal utility of `promptbookCli`
  */
 export declare const PROMPT_RUNNER_AGENT_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+/**
+ * Environment variable used as the default runner identifier when `--agent` is omitted.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PTBK_AGENT_ENV = "PTBK_AGENT";
+/**
+ * Environment variable used as the default runner model when `--model` is omitted.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PTBK_MODEL_ENV = "PTBK_MODEL";
+/**
+ * Environment variable used as the default runner thinking level when `--thinking-level` is omitted.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PTBK_THINKING_LEVEL_ENV = "PTBK_THINKING_LEVEL";
 /**
  * Runner identifier supported by Promptbook CLI agent orchestration commands.
  *
@@ -29,6 +47,12 @@ export type PromptRunnerCliOptions = {
     readonly autoPush: boolean;
     readonly autoPull: boolean;
 };
+/**
+ * Commander option bag for runner selection plus terminal/runtime switches shared with server orchestration.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptRunnerSelectionCliOptions = Pick<PromptRunnerCliOptions, 'agent' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'>;
 /**
  * Normalized runner options used by runner-backed CLI commands.
  *
@@ -46,6 +70,12 @@ export type NormalizedPromptRunnerCliOptions = {
     readonly autoPush: boolean;
     readonly autoPull: boolean;
 };
+/**
+ * Normalized runner selection plus terminal/runtime switches shared with server orchestration.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedPromptRunnerSelectionCliOptions = Pick<NormalizedPromptRunnerCliOptions, 'agentName' | 'model' | 'noUi' | 'thinkingLevel' | 'allowCredits'>;
 /**
  * Description block shared by runner-backed CLI commands.
  *
@@ -70,6 +100,12 @@ export declare const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION: string;
  * @private internal utility of `promptbookCli`
  */
 export declare function addPromptRunnerSelectionOptions(command: Program): void;
+/**
+ * Registers shared runner terminal/runtime flags on a command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addPromptRunnerRuntimeOptions(command: Program): void;
 /**
  * Registers shared runner execution flags on a command.
  *
@@ -84,3 +120,11 @@ export declare function addPromptRunnerExecutionOptions(command: Program): void;
 export declare function normalizePromptRunnerCliOptions(cliOptions: PromptRunnerCliOptions, options: {
     readonly isAgentRequired: boolean;
 }): NormalizedPromptRunnerCliOptions;
+/**
+ * Converts Commander runner selection/runtime flags into the normalized runner shape.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizePromptRunnerSelectionCliOptions(cliOptions: PromptRunnerSelectionCliOptions, options: {
+    readonly isAgentRequired: boolean;
+}): NormalizedPromptRunnerSelectionCliOptions;

package/umd/src/cli/common/$deprecateCliCommand.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Marks one CLI command as deprecated while keeping it available for existing callers.
+ *
+ * @private utility of CLI
+ */
+export declare function $deprecateCliCommand(command: Command, deprecationMessage: string): $side_effect;

package/umd/src/cli/common/$deprecateCliCommand.test.d.ts

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

package/umd/src/utils/color/Color.d.ts

@@ -2,6 +2,7 @@ import type { string_color } from '../../types/string_person_fullname';
 import type { string_url_image } from '../../types/string_url_image';
 import type { WithTake } from '../take/interfaces/ITakeChain';
 import { CSS_COLORS } from './css-colors';
+import { ColorValue } from './ColorValue';
 /**
  * Color object represents an RGB color with alpha channel
  *
@@ -9,11 +10,7 @@ import { CSS_COLORS } from './css-colors';
  *
  * @public exported from `@promptbook/color`
  */
-export declare class Color {
-    readonly red: number;
-    readonly green: number;
-    readonly blue: number;
-    readonly alpha: number;
+export declare class Color extends ColorValue {
     /**
      * Creates a new Color instance from miscellaneous formats
      * - It can receive Color instance and just return the same instance
@@ -117,43 +114,6 @@ export declare class Color {
      * @param alpha number from 0 (transparent) to 255 (opaque)
      */
     private constructor();
-    /**
-     * Shortcut for `red` property
-     * Number from 0 to 255
-     * @alias red
-     */
-    get r(): number;
-    /**
-     * Shortcut for `green` property
-     * Number from 0 to 255
-     * @alias green
-     */
-    get g(): number;
-    /**
-     * Shortcut for `blue` property
-     * Number from 0 to 255
-     * @alias blue
-     */
-    get b(): number;
-    /**
-     * Shortcut for `alpha` property
-     * Number from 0 (transparent) to 255 (opaque)
-     * @alias alpha
-     */
-    get a(): number;
-    /**
-     * Shortcut for `alpha` property
-     * Number from 0 (transparent) to 255 (opaque)
-     * @alias alpha
-     */
-    get opacity(): number;
-    /**
-     * Shortcut for 1-`alpha` property
-     */
-    get transparency(): number;
-    clone(): WithTake<Color>;
-    toString(): string_color;
-    toHex(): string_color;
-    toRgb(): string_color;
-    toHsl(): string_color;
+    protected createColor(red: number, green: number, blue: number, alpha: number): Color;
+    private static fromColorChannels;
 }

package/umd/src/utils/color/ColorValue.d.ts

@@ -0,0 +1,55 @@
+import type { string_color } from '../../types/string_person_fullname';
+import type { WithTake } from '../take/interfaces/ITakeChain';
+import type { Color } from './Color';
+/**
+ * Shared immutable channel storage and serialization helpers for `Color`.
+ *
+ * @private base class of Color
+ */
+export declare abstract class ColorValue {
+    readonly red: number;
+    readonly green: number;
+    readonly blue: number;
+    readonly alpha: number;
+    protected constructor(red: number, green: number, blue: number, alpha?: number);
+    /**
+     * Shortcut for `red` property
+     * Number from 0 to 255
+     * @alias red
+     */
+    get r(): number;
+    /**
+     * Shortcut for `green` property
+     * Number from 0 to 255
+     * @alias green
+     */
+    get g(): number;
+    /**
+     * Shortcut for `blue` property
+     * Number from 0 to 255
+     * @alias blue
+     */
+    get b(): number;
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get a(): number;
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get opacity(): number;
+    /**
+     * Shortcut for 1-`alpha` property
+     */
+    get transparency(): number;
+    clone(): WithTake<Color>;
+    toString(): string_color;
+    toHex(): string_color;
+    toRgb(): string_color;
+    toHsl(): string_color;
+    protected abstract createColor(red: number, green: number, blue: number, alpha: number): Color;
+}

package/umd/src/utils/color/isHexColorString.d.ts

@@ -0,0 +1,10 @@
+import type { string_color } from '../../types/string_person_fullname';
+/**
+ * Checks if the given value is a valid hex color string
+ *
+ * @param value - value to check
+ * @returns true if the value is a valid hex color string (e.g., `#009edd`, `#fff`, etc.)
+ *
+ * @private function of Color
+ */
+export declare function isHexColorString(value: unknown): value is string_color;

package/umd/src/utils/color/parseColorString.d.ts

@@ -0,0 +1,11 @@
+import type { string_color } from '../../types/string_person_fullname';
+import type { ColorChannelSet } from './parsers/ColorChannelSet';
+/**
+ * Parses a supported color string into RGBA channels.
+ *
+ * @param color as a string for example `#009edd`, `rgb(0,158,221)`, `rgb(0%,62%,86.7%)`, `hsl(197.1,100%,43.3%)`, `red`, `darkgrey`,...
+ * @returns RGBA channel values.
+ *
+ * @private function of Color
+ */
+export declare function parseColorString(color: string_color): ColorChannelSet;

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.112.0-72`).
+ * It follows semantic versioning (e.g., `0.112.0-78`).
  *
  * @generated
  */

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

@@ -1,6 +0,0 @@
-/**
- * Appends one text block to existing file content while preserving readable newlines.
- *
- * @private function of `initializeCoderProjectConfiguration`
- */
-export declare function appendBlock(currentContent: string, blockToAppend: string): string;

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

@@ -1,6 +0,0 @@
-/**
- * Reads one text file when it exists, otherwise returns `undefined`.
- *
- * @private function of `initializeCoderProjectConfiguration`
- */
-export declare function readTextFileIfExists(path: string): Promise<string | undefined>;

package/umd/src/cli/cli-commands/coder/appendBlock.d.ts

@@ -1,6 +0,0 @@
-/**
- * Appends one text block to existing file content while preserving readable newlines.
- *
- * @private function of `initializeCoderProjectConfiguration`
- */
-export declare function appendBlock(currentContent: string, blockToAppend: string): string;

package/umd/src/cli/cli-commands/coder/readTextFileIfExists.d.ts

@@ -1,6 +0,0 @@
-/**
- * Reads one text file when it exists, otherwise returns `undefined`.
- *
- * @private function of `initializeCoderProjectConfiguration`
- */
-export declare function readTextFileIfExists(path: string): Promise<string | undefined>;