@socketsecurity/lib 1.0.4 → 1.1.0

package/dist/stdio/progress.d.ts

@@ -1,14 +1,56 @@
 export interface ProgressBarOptions {
-    width?: number;
-    // Template: ':bar :percent :current/:total :eta'.
-    format?: string;
-    complete?: string;
-    incomplete?: string;
-    head?: string;
-    clear?: boolean;
-    renderThrottle?: number;
-    stream?: NodeJS.WriteStream;
-    color?: 'cyan' | 'green' | 'yellow' | 'blue' | 'magenta';
+    /**
+     * Width of the progress bar in characters.
+     * @default 40
+     */
+    width?: number | undefined;
+    /**
+     * Format template for progress bar display.
+     * Available tokens: `:bar`, `:percent`, `:current`, `:total`, `:elapsed`, `:eta`.
+     * Custom tokens can be passed via the `tokens` parameter in `update()` or `tick()`.
+     * @default ':bar :percent :current/:total'
+     * @example
+     * ```ts
+     * format: ':bar :percent :current/:total :eta'
+     * ```
+     */
+    format?: string | undefined;
+    /**
+     * Character(s) to use for completed portion of bar.
+     * @default '█'
+     */
+    complete?: string | undefined;
+    /**
+     * Character(s) to use for incomplete portion of bar.
+     * @default '░'
+     */
+    incomplete?: string | undefined;
+    /**
+     * Character(s) to use for the head of the progress bar.
+     * @default ''
+     */
+    head?: string | undefined;
+    /**
+     * Clear the progress bar when complete.
+     * @default false
+     */
+    clear?: boolean | undefined;
+    /**
+     * Minimum time between renders in milliseconds.
+     * ~60fps = 16ms throttle.
+     * @default 16
+     */
+    renderThrottle?: number | undefined;
+    /**
+     * Stream to write progress bar output to.
+     * @default process.stderr
+     */
+    stream?: NodeJS.WriteStream | undefined;
+    /**
+     * Color to apply to the completed portion of the bar.
+     * @default 'cyan'
+     */
+    color?: 'cyan' | 'green' | 'yellow' | 'blue' | 'magenta' | undefined;
 }
 export declare class ProgressBar {
     private current;
@@ -19,13 +61,50 @@ export declare class ProgressBar {
     private options;
     private terminated;
     private lastDrawnWidth;
+    /**
+     * Create a new progress bar instance.
+     *
+     * @param total - Total number of units for the progress bar
+     * @param options - Configuration options for the progress bar
+     *
+     * @example
+     * ```ts
+     * const bar = new ProgressBar(100, {
+     *   width: 50,
+     *   format: ':bar :percent :current/:total :eta',
+     *   color: 'green'
+     * })
+     * ```
+     */
     constructor(total: number, options?: ProgressBarOptions);
     /**
-     * Update progress and redraw bar.
+     * Update progress to a specific value and redraw the bar.
+     * Updates are throttled to prevent excessive rendering (default ~60fps).
+     *
+     * @param current - Current progress value (will be clamped to total)
+     * @param tokens - Optional custom tokens to replace in format string
+     *
+     * @example
+     * ```ts
+     * bar.update(50)
+     * bar.update(75, { status: 'Processing...' })
+     * ```
      */
     update(current: number, tokens?: Record<string, unknown>): void;
     /**
-     * Increment progress by amount.
+     * Increment progress by a specified amount.
+     * Convenience method for `update(current + amount)`.
+     *
+     * @param amount - Amount to increment by
+     * @param tokens - Optional custom tokens to replace in format string
+     * @default amount 1
+     *
+     * @example
+     * ```ts
+     * bar.tick() // Increment by 1
+     * bar.tick(5) // Increment by 5
+     * bar.tick(1, { file: 'data.json' })
+     * ```
      */
     tick(amount?: number, tokens?: Record<string, unknown>): void;
     /**
@@ -41,11 +120,29 @@ export declare class ProgressBar {
      */
     private formatTime;
     /**
-     * Terminate the progress bar.
+     * Terminate the progress bar and optionally clear it.
+     * Called automatically when progress reaches 100%.
+     * If `clear` option is true, removes the bar from terminal.
+     * Otherwise, moves to next line to preserve the final state.
      */
     terminate(): void;
 }
 /**
- * Create a simple progress indicator without a bar.
+ * Create a simple progress indicator without a graphical bar.
+ * Returns a formatted string showing progress as percentage and fraction.
+ *
+ * @param current - Current progress value
+ * @param total - Total progress value
+ * @param label - Optional label prefix
+ * @returns Formatted progress indicator string
+ *
+ * @example
+ * ```ts
+ * createProgressIndicator(50, 100)
+ * // Returns: '[50%] 50/100'
+ *
+ * createProgressIndicator(3, 10, 'Files')
+ * // Returns: 'Files: [30%] 3/10'
+ * ```
  */
-export declare function createProgressIndicator(current: number, total: number, label?: string): string;
+export declare function createProgressIndicator(current: number, total: number, label?: string | undefined): string;

package/dist/stdio/progress.js

@@ -43,6 +43,21 @@ class ProgressBar {
   options;
   terminated = false;
   lastDrawnWidth = 0;
+  /**
+   * Create a new progress bar instance.
+   *
+   * @param total - Total number of units for the progress bar
+   * @param options - Configuration options for the progress bar
+   *
+   * @example
+   * ```ts
+   * const bar = new ProgressBar(100, {
+   *   width: 50,
+   *   format: ':bar :percent :current/:total :eta',
+   *   color: 'green'
+   * })
+   * ```
+   */
   constructor(total, options) {
     this.total = total;
     this.startTime = Date.now();
@@ -62,7 +77,17 @@ class ProgressBar {
     };
   }
   /**
-   * Update progress and redraw bar.
+   * Update progress to a specific value and redraw the bar.
+   * Updates are throttled to prevent excessive rendering (default ~60fps).
+   *
+   * @param current - Current progress value (will be clamped to total)
+   * @param tokens - Optional custom tokens to replace in format string
+   *
+   * @example
+   * ```ts
+   * bar.update(50)
+   * bar.update(75, { status: 'Processing...' })
+   * ```
    */
   update(current, tokens) {
     if (this.terminated) {
@@ -80,7 +105,19 @@ class ProgressBar {
     }
   }
   /**
-   * Increment progress by amount.
+   * Increment progress by a specified amount.
+   * Convenience method for `update(current + amount)`.
+   *
+   * @param amount - Amount to increment by
+   * @param tokens - Optional custom tokens to replace in format string
+   * @default amount 1
+   *
+   * @example
+   * ```ts
+   * bar.tick() // Increment by 1
+   * bar.tick(5) // Increment by 5
+   * bar.tick(1, { file: 'data.json' })
+   * ```
    */
   tick(amount = 1, tokens) {
     this.update(this.current + amount, tokens);
@@ -139,7 +176,10 @@ class ProgressBar {
     return `${minutes}m${remainingSeconds}s`;
   }
   /**
-   * Terminate the progress bar.
+   * Terminate the progress bar and optionally clear it.
+   * Called automatically when progress reaches 100%.
+   * If `clear` option is true, removes the bar from terminal.
+   * Otherwise, moves to next line to preserve the final state.
    */
   terminate() {
     if (this.terminated) {

package/dist/stdio/progress.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/stdio/progress.ts"],
-  "sourcesContent": ["/**\n * Progress bar utilities for CLI applications.\n * Provides various progress indicators including bars, percentages, and spinners.\n */\n\nimport colors from '../external/yoctocolors-cjs'\nimport { repeatString, stripAnsi } from '../strings'\n\nexport interface ProgressBarOptions {\n  width?: number\n  // Template: ':bar :percent :current/:total :eta'.\n  format?: string\n  complete?: string\n  incomplete?: string\n  head?: string\n  clear?: boolean\n  renderThrottle?: number\n  stream?: NodeJS.WriteStream\n  color?: 'cyan' | 'green' | 'yellow' | 'blue' | 'magenta'\n}\n\nexport class ProgressBar {\n  private current: number = 0\n  private total: number\n  private startTime: number\n  private lastRender: number = 0\n  private stream: NodeJS.WriteStream\n  private options: Required<ProgressBarOptions>\n  private terminated: boolean = false\n  private lastDrawnWidth: number = 0\n\n  constructor(total: number, options?: ProgressBarOptions) {\n    this.total = total\n    this.startTime = Date.now()\n    this.stream = options?.stream || process.stderr\n    this.options = {\n      width: 40,\n      format: ':bar :percent :current/:total',\n      complete: '\u2588',\n      incomplete: '\u2591',\n      head: '',\n      clear: false,\n      // ~60fps.\n      renderThrottle: 16,\n      stream: this.stream,\n      color: 'cyan',\n      ...options,\n    }\n  }\n\n  /**\n   * Update progress and redraw bar.\n   */\n  update(current: number, tokens?: Record<string, unknown>): void {\n    if (this.terminated) {\n      return\n    }\n\n    this.current = Math.min(current, this.total)\n\n    // Throttle rendering\n    const now = Date.now()\n    if (\n      now - this.lastRender < this.options.renderThrottle &&\n      this.current < this.total\n    ) {\n      return\n    }\n    this.lastRender = now\n\n    this.render(tokens)\n\n    if (this.current >= this.total) {\n      this.terminate()\n    }\n  }\n\n  /**\n   * Increment progress by amount.\n   */\n  tick(amount: number = 1, tokens?: Record<string, unknown>): void {\n    this.update(this.current + amount, tokens)\n  }\n\n  /**\n   * Render the progress bar.\n   */\n  private render(tokens?: Record<string, unknown>): void {\n    const colorFn = colors[this.options.color] || ((s: string) => s)\n\n    // Calculate values\n    const percent = Math.floor((this.current / this.total) * 100)\n    const elapsed = Date.now() - this.startTime\n    const eta =\n      this.current === 0\n        ? 0\n        : (elapsed / this.current) * (this.total - this.current)\n\n    // Build bar\n    const availableWidth = this.options.width\n    const filledWidth = Math.floor((this.current / this.total) * availableWidth)\n    const emptyWidth = availableWidth - filledWidth\n\n    const filled = repeatString(this.options.complete, filledWidth)\n    const empty = repeatString(this.options.incomplete, emptyWidth)\n    const bar = colorFn(filled) + empty\n\n    // Format output\n    let output = this.options.format\n    output = output.replace(':bar', bar)\n    output = output.replace(':percent', `${percent}%`)\n    output = output.replace(':current', String(this.current))\n    output = output.replace(':total', String(this.total))\n    output = output.replace(':elapsed', this.formatTime(elapsed))\n    output = output.replace(':eta', this.formatTime(eta))\n\n    // Replace custom tokens\n    if (tokens) {\n      for (const [key, value] of Object.entries(tokens)) {\n        output = output.replace(`:${key}`, String(value))\n      }\n    }\n\n    // Clear line and write\n    this.clearLine()\n    this.stream.write(output)\n    this.lastDrawnWidth = stripAnsi(output).length\n  }\n\n  /**\n   * Clear the current line.\n   */\n  private clearLine(): void {\n    if (this.stream.isTTY) {\n      this.stream.cursorTo(0)\n      this.stream.clearLine(0)\n    } else if (this.lastDrawnWidth > 0) {\n      this.stream.write(`\\r${repeatString(' ', this.lastDrawnWidth)}\\r`)\n    }\n  }\n\n  /**\n   * Format time in seconds to human readable.\n   */\n  private formatTime(ms: number): string {\n    const seconds = Math.round(ms / 1000)\n    if (seconds < 60) {\n      return `${seconds}s`\n    }\n    const minutes = Math.floor(seconds / 60)\n    const remainingSeconds = seconds % 60\n    return `${minutes}m${remainingSeconds}s`\n  }\n\n  /**\n   * Terminate the progress bar.\n   */\n  terminate(): void {\n    if (this.terminated) {\n      return\n    }\n    this.terminated = true\n\n    if (this.options.clear) {\n      this.clearLine()\n    } else {\n      this.stream.write('\\n')\n    }\n  }\n}\n\n/**\n * Create a simple progress indicator without a bar.\n */\nexport function createProgressIndicator(\n  current: number,\n  total: number,\n  label?: string,\n): string {\n  const percent = Math.floor((current / total) * 100)\n  const progress = `${current}/${total}`\n\n  let output = ''\n  if (label) {\n    output += `${label}: `\n  }\n\n  output += `${colors.cyan(`[${percent}%]`)} ${progress}`\n\n  return output\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * @fileoverview Progress bar utilities for CLI applications.\n * Provides various progress indicators including bars, percentages, and spinners.\n */\n\nimport colors from '../external/yoctocolors-cjs'\nimport { repeatString, stripAnsi } from '../strings'\n\nexport interface ProgressBarOptions {\n  /**\n   * Width of the progress bar in characters.\n   * @default 40\n   */\n  width?: number | undefined\n  /**\n   * Format template for progress bar display.\n   * Available tokens: `:bar`, `:percent`, `:current`, `:total`, `:elapsed`, `:eta`.\n   * Custom tokens can be passed via the `tokens` parameter in `update()` or `tick()`.\n   * @default ':bar :percent :current/:total'\n   * @example\n   * ```ts\n   * format: ':bar :percent :current/:total :eta'\n   * ```\n   */\n  format?: string | undefined\n  /**\n   * Character(s) to use for completed portion of bar.\n   * @default '\u2588'\n   */\n  complete?: string | undefined\n  /**\n   * Character(s) to use for incomplete portion of bar.\n   * @default '\u2591'\n   */\n  incomplete?: string | undefined\n  /**\n   * Character(s) to use for the head of the progress bar.\n   * @default ''\n   */\n  head?: string | undefined\n  /**\n   * Clear the progress bar when complete.\n   * @default false\n   */\n  clear?: boolean | undefined\n  /**\n   * Minimum time between renders in milliseconds.\n   * ~60fps = 16ms throttle.\n   * @default 16\n   */\n  renderThrottle?: number | undefined\n  /**\n   * Stream to write progress bar output to.\n   * @default process.stderr\n   */\n  stream?: NodeJS.WriteStream | undefined\n  /**\n   * Color to apply to the completed portion of the bar.\n   * @default 'cyan'\n   */\n  color?: 'cyan' | 'green' | 'yellow' | 'blue' | 'magenta' | undefined\n}\n\nexport class ProgressBar {\n  private current: number = 0\n  private total: number\n  private startTime: number\n  private lastRender: number = 0\n  private stream: NodeJS.WriteStream\n  private options: Required<ProgressBarOptions>\n  private terminated: boolean = false\n  private lastDrawnWidth: number = 0\n\n  /**\n   * Create a new progress bar instance.\n   *\n   * @param total - Total number of units for the progress bar\n   * @param options - Configuration options for the progress bar\n   *\n   * @example\n   * ```ts\n   * const bar = new ProgressBar(100, {\n   *   width: 50,\n   *   format: ':bar :percent :current/:total :eta',\n   *   color: 'green'\n   * })\n   * ```\n   */\n  constructor(total: number, options?: ProgressBarOptions) {\n    this.total = total\n    this.startTime = Date.now()\n    this.stream = options?.stream || process.stderr\n    this.options = {\n      width: 40,\n      format: ':bar :percent :current/:total',\n      complete: '\u2588',\n      incomplete: '\u2591',\n      head: '',\n      clear: false,\n      // ~60fps.\n      renderThrottle: 16,\n      stream: this.stream,\n      color: 'cyan',\n      ...options,\n    }\n  }\n\n  /**\n   * Update progress to a specific value and redraw the bar.\n   * Updates are throttled to prevent excessive rendering (default ~60fps).\n   *\n   * @param current - Current progress value (will be clamped to total)\n   * @param tokens - Optional custom tokens to replace in format string\n   *\n   * @example\n   * ```ts\n   * bar.update(50)\n   * bar.update(75, { status: 'Processing...' })\n   * ```\n   */\n  update(current: number, tokens?: Record<string, unknown>): void {\n    if (this.terminated) {\n      return\n    }\n\n    this.current = Math.min(current, this.total)\n\n    // Throttle rendering\n    const now = Date.now()\n    if (\n      now - this.lastRender < this.options.renderThrottle &&\n      this.current < this.total\n    ) {\n      return\n    }\n    this.lastRender = now\n\n    this.render(tokens)\n\n    if (this.current >= this.total) {\n      this.terminate()\n    }\n  }\n\n  /**\n   * Increment progress by a specified amount.\n   * Convenience method for `update(current + amount)`.\n   *\n   * @param amount - Amount to increment by\n   * @param tokens - Optional custom tokens to replace in format string\n   * @default amount 1\n   *\n   * @example\n   * ```ts\n   * bar.tick() // Increment by 1\n   * bar.tick(5) // Increment by 5\n   * bar.tick(1, { file: 'data.json' })\n   * ```\n   */\n  tick(amount: number = 1, tokens?: Record<string, unknown>): void {\n    this.update(this.current + amount, tokens)\n  }\n\n  /**\n   * Render the progress bar.\n   */\n  private render(tokens?: Record<string, unknown>): void {\n    const colorFn = colors[this.options.color] || ((s: string) => s)\n\n    // Calculate values\n    const percent = Math.floor((this.current / this.total) * 100)\n    const elapsed = Date.now() - this.startTime\n    const eta =\n      this.current === 0\n        ? 0\n        : (elapsed / this.current) * (this.total - this.current)\n\n    // Build bar\n    const availableWidth = this.options.width\n    const filledWidth = Math.floor((this.current / this.total) * availableWidth)\n    const emptyWidth = availableWidth - filledWidth\n\n    const filled = repeatString(this.options.complete, filledWidth)\n    const empty = repeatString(this.options.incomplete, emptyWidth)\n    const bar = colorFn(filled) + empty\n\n    // Format output\n    let output = this.options.format\n    output = output.replace(':bar', bar)\n    output = output.replace(':percent', `${percent}%`)\n    output = output.replace(':current', String(this.current))\n    output = output.replace(':total', String(this.total))\n    output = output.replace(':elapsed', this.formatTime(elapsed))\n    output = output.replace(':eta', this.formatTime(eta))\n\n    // Replace custom tokens\n    if (tokens) {\n      for (const [key, value] of Object.entries(tokens)) {\n        output = output.replace(`:${key}`, String(value))\n      }\n    }\n\n    // Clear line and write\n    this.clearLine()\n    this.stream.write(output)\n    this.lastDrawnWidth = stripAnsi(output).length\n  }\n\n  /**\n   * Clear the current line.\n   */\n  private clearLine(): void {\n    if (this.stream.isTTY) {\n      this.stream.cursorTo(0)\n      this.stream.clearLine(0)\n    } else if (this.lastDrawnWidth > 0) {\n      this.stream.write(`\\r${repeatString(' ', this.lastDrawnWidth)}\\r`)\n    }\n  }\n\n  /**\n   * Format time in seconds to human readable.\n   */\n  private formatTime(ms: number): string {\n    const seconds = Math.round(ms / 1000)\n    if (seconds < 60) {\n      return `${seconds}s`\n    }\n    const minutes = Math.floor(seconds / 60)\n    const remainingSeconds = seconds % 60\n    return `${minutes}m${remainingSeconds}s`\n  }\n\n  /**\n   * Terminate the progress bar and optionally clear it.\n   * Called automatically when progress reaches 100%.\n   * If `clear` option is true, removes the bar from terminal.\n   * Otherwise, moves to next line to preserve the final state.\n   */\n  terminate(): void {\n    if (this.terminated) {\n      return\n    }\n    this.terminated = true\n\n    if (this.options.clear) {\n      this.clearLine()\n    } else {\n      this.stream.write('\\n')\n    }\n  }\n}\n\n/**\n * Create a simple progress indicator without a graphical bar.\n * Returns a formatted string showing progress as percentage and fraction.\n *\n * @param current - Current progress value\n * @param total - Total progress value\n * @param label - Optional label prefix\n * @returns Formatted progress indicator string\n *\n * @example\n * ```ts\n * createProgressIndicator(50, 100)\n * // Returns: '[50%] 50/100'\n *\n * createProgressIndicator(3, 10, 'Files')\n * // Returns: 'Files: [30%] 3/10'\n * ```\n */\nexport function createProgressIndicator(\n  current: number,\n  total: number,\n  label?: string | undefined,\n): string {\n  const percent = Math.floor((current / total) * 100)\n  const progress = `${current}/${total}`\n\n  let output = ''\n  if (label) {\n    output += `${label}: `\n  }\n\n  output += `${colors.cyan(`[${percent}%]`)} ${progress}`\n\n  return output\n}\n"],
+  "mappings": "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",
   "names": ["colors"]
 }

package/dist/stdio/prompts.d.ts

@@ -1,25 +1,59 @@
 // Type definitions
+/**
+ * Choice option for select and search prompts.
+ *
+ * @template Value - Type of the choice value
+ */
 export interface Choice<Value = unknown> {
+    /** The value returned when this choice is selected */
     value: Value;
+    /** Whether this choice is disabled, or a reason string */
     disabled?: boolean | string | undefined;
+    /** Additional description text shown below the choice */
     description?: string | undefined;
+    /** Display name for the choice (defaults to value.toString()) */
     name?: string | undefined;
+    /** Short text shown after selection (defaults to name) */
     short?: string | undefined;
 }
-// Duplicated from @inquirer/type - InquirerContext
-// This is the minimal context interface used by Inquirer prompts
+/**
+ * Context for inquirer prompts.
+ * Minimal context interface used by Inquirer prompts.
+ * Duplicated from `@inquirer/type` - InquirerContext.
+ */
 interface InquirerContext {
+    /** Abort signal for cancelling the prompt */
     signal?: AbortSignal | undefined;
+    /** Input stream (defaults to process.stdin) */
     input?: NodeJS.ReadableStream | undefined;
+    /** Output stream (defaults to process.stdout) */
     output?: NodeJS.WritableStream | undefined;
+    /** Clear the prompt from terminal when done */
     clearPromptOnDone?: boolean | undefined;
 }
+/**
+ * Extended context with spinner support.
+ * Allows passing a spinner instance to be managed during prompts.
+ */
 export type Context = import('../objects').Remap<InquirerContext & {
+    /** Optional spinner to stop/start during prompt display */
     spinner?: import('../spinner').Spinner | undefined;
 }>;
-// Duplicated from @inquirer/select - Separator
-// A separator object used in select/checkbox prompts to create visual separators
-// This type definition ensures the Separator type is available in published packages
+/**
+ * Separator for visual grouping in select/checkbox prompts.
+ * Creates a non-selectable visual separator line.
+ * Duplicated from `@inquirer/select` - Separator.
+ * This type definition ensures the Separator type is available in published packages.
+ *
+ * @example
+ * import { Separator } from './prompts'
+ *
+ * const choices = [
+ *   { name: 'Option 1', value: 1 },
+ *   new Separator(),
+ *   { name: 'Option 2', value: 2 }
+ * ]
+ */
 declare class SeparatorType {
     readonly separator: string;
     readonly type: 'separator';
@@ -28,6 +62,16 @@ declare class SeparatorType {
 export type Separator = SeparatorType;
 /**
  * Wrap an inquirer prompt with spinner handling and signal injection.
+ * Automatically stops/starts spinners during prompt display and injects abort signals.
+ * Trims string results and handles cancellation gracefully.
+ *
+ * @template T - Type of the prompt result
+ * @param inquirerPrompt - The inquirer prompt function to wrap
+ * @returns Wrapped prompt function with spinner and signal handling
+ *
+ * @example
+ * const myPrompt = wrapPrompt(rawInquirerPrompt)
+ * const result = await myPrompt({ message: 'Enter name:' })
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function wrapPrompt<T = unknown>(inquirerPrompt: (...args: unknown[]) => Promise<T>): (...args: unknown[]) => Promise<T | undefined>;
@@ -38,9 +82,55 @@ declare const searchRaw: any;
 declare const selectRaw: any;
 declare const ActualSeparator: any;
 // c8 ignore stop
+/**
+ * Prompt for a yes/no confirmation.
+ * Wrapped with spinner handling and abort signal support.
+ *
+ * @example
+ * const answer = await confirm({ message: 'Continue?' })
+ * if (answer) { // user confirmed }
+ */
 export declare const confirm: typeof confirmRaw;
+/**
+ * Prompt for text input.
+ * Wrapped with spinner handling and abort signal support.
+ * Result is automatically trimmed.
+ *
+ * @example
+ * const name = await input({ message: 'Enter your name:' })
+ */
 export declare const input: typeof inputRaw;
+/**
+ * Prompt for password input (hidden characters).
+ * Wrapped with spinner handling and abort signal support.
+ *
+ * @example
+ * const token = await password({ message: 'Enter API token:' })
+ */
 export declare const password: typeof passwordRaw;
+/**
+ * Prompt with searchable/filterable choices.
+ * Wrapped with spinner handling and abort signal support.
+ *
+ * @example
+ * const result = await search({
+ *   message: 'Select a package:',
+ *   source: async (input) => fetchPackages(input)
+ * })
+ */
 export declare const search: typeof searchRaw;
+/**
+ * Prompt to select from a list of choices.
+ * Wrapped with spinner handling and abort signal support.
+ *
+ * @example
+ * const choice = await select({
+ *   message: 'Choose an option:',
+ *   choices: [
+ *     { name: 'Option 1', value: 'opt1' },
+ *     { name: 'Option 2', value: 'opt2' }
+ *   ]
+ * })
+ */
 export declare const select: typeof selectRaw;
 export { ActualSeparator as Separator };

package/dist/stdio/prompts.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/stdio/prompts.ts"],
-  "sourcesContent": ["/**\n * @fileoverview User prompt utilities for interactive scripts.\n * Provides inquirer.js integration with spinner support and context handling.\n */\n\nimport { getAbortSignal, getSpinner } from '#constants/process'\n\nconst abortSignal = getAbortSignal()\nconst spinner = getSpinner()\n\n// Type definitions\n\nexport interface Choice<Value = unknown> {\n  value: Value\n  disabled?: boolean | string | undefined\n  description?: string | undefined\n  name?: string | undefined\n  short?: string | undefined\n}\n\n// Duplicated from @inquirer/type - InquirerContext\n// This is the minimal context interface used by Inquirer prompts\ninterface InquirerContext {\n  signal?: AbortSignal | undefined\n  input?: NodeJS.ReadableStream | undefined\n  output?: NodeJS.WritableStream | undefined\n  clearPromptOnDone?: boolean | undefined\n}\n\nexport type Context = import('../objects').Remap<\n  InquirerContext & {\n    spinner?: import('../spinner').Spinner | undefined\n  }\n>\n\n// Duplicated from @inquirer/select - Separator\n// A separator object used in select/checkbox prompts to create visual separators\n// This type definition ensures the Separator type is available in published packages\ndeclare class SeparatorType {\n  readonly separator: string\n  readonly type: 'separator'\n  constructor(separator?: string)\n}\n\nexport type Separator = SeparatorType\n\n/**\n * Wrap an inquirer prompt with spinner handling and signal injection.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function wrapPrompt<T = unknown>(\n  inquirerPrompt: (...args: unknown[]) => Promise<T>,\n): (...args: unknown[]) => Promise<T | undefined> {\n  return async (...args) => {\n    const origContext = (args.length > 1 ? args[1] : undefined) as\n      | Context\n      | undefined\n    const { spinner: contextSpinner, ...contextWithoutSpinner } =\n      origContext ?? ({} as Context)\n    const spinnerInstance =\n      contextSpinner !== undefined ? contextSpinner : spinner\n    const signal = abortSignal\n    if (origContext) {\n      args[1] = {\n        signal,\n        ...contextWithoutSpinner,\n      }\n    } else {\n      args[1] = { signal }\n    }\n    const wasSpinning = !!spinnerInstance?.isSpinning\n    spinnerInstance?.stop()\n    let result: unknown\n    try {\n      result = await inquirerPrompt(...args)\n    } catch (e) {\n      if (e instanceof TypeError) {\n        throw e\n      }\n    }\n    if (wasSpinning) {\n      spinnerInstance.start()\n    }\n    return (typeof result === 'string' ? result.trim() : result) as\n      | T\n      | undefined\n  }\n}\n\n// c8 ignore start - Third-party inquirer library requires and exports not testable in isolation.\nconst confirmExport = /*@__PURE__*/ require('../external/@inquirer/confirm')\nconst inputExport = /*@__PURE__*/ require('../external/@inquirer/input')\nconst passwordExport = /*@__PURE__*/ require('../external/@inquirer/password')\nconst searchExport = /*@__PURE__*/ require('../external/@inquirer/search')\nconst selectExport = /*@__PURE__*/ require('../external/@inquirer/select')\nconst confirmRaw = confirmExport.default ?? confirmExport\nconst inputRaw = inputExport.default ?? inputExport\nconst passwordRaw = passwordExport.default ?? passwordExport\nconst searchRaw = searchExport.default ?? searchExport\nconst selectRaw = selectExport.default ?? selectExport\nconst ActualSeparator = selectExport.Separator\n// c8 ignore stop\n\nexport const confirm: typeof confirmRaw = wrapPrompt(confirmRaw)\nexport const input: typeof inputRaw = wrapPrompt(inputRaw)\nexport const password: typeof passwordRaw = wrapPrompt(passwordRaw)\nexport const search: typeof searchRaw = wrapPrompt(searchRaw)\nexport const select: typeof selectRaw = wrapPrompt(selectRaw)\nexport { ActualSeparator as Separator }\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,qBAA2C;AAE3C,MAAM,kBAAc,+BAAe;AACnC,MAAM,cAAU,2BAAW;AAAA;AA0CpB,SAAS,WACd,gBACgD;AAChD,SAAO,UAAU,SAAS;AACxB,UAAM,cAAe,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI;AAGjD,UAAM,EAAE,SAAS,gBAAgB,GAAG,sBAAsB,IACxD,eAAgB,CAAC;AACnB,UAAM,kBACJ,mBAAmB,SAAY,iBAAiB;AAClD,UAAM,SAAS;AACf,QAAI,aAAa;AACf,WAAK,CAAC,IAAI;AAAA,QACR;AAAA,QACA,GAAG;AAAA,MACL;AAAA,IACF,OAAO;AACL,WAAK,CAAC,IAAI,EAAE,OAAO;AAAA,IACrB;AACA,UAAM,cAAc,CAAC,CAAC,iBAAiB;AACvC,qBAAiB,KAAK;AACtB,QAAI;AACJ,QAAI;AACF,eAAS,MAAM,eAAe,GAAG,IAAI;AAAA,IACvC,SAAS,GAAG;AACV,UAAI,aAAa,WAAW;AAC1B,cAAM;AAAA,MACR;AAAA,IACF;AACA,QAAI,aAAa;AACf,sBAAgB,MAAM;AAAA,IACxB;AACA,WAAQ,OAAO,WAAW,WAAW,OAAO,KAAK,IAAI;AAAA,EAGvD;AACF;AAGA,MAAM,gBAA8B,QAAQ,+BAA+B;AAC3E,MAAM,cAA4B,QAAQ,6BAA6B;AACvE,MAAM,iBAA+B,QAAQ,gCAAgC;AAC7E,MAAM,eAA6B,QAAQ,8BAA8B;AACzE,MAAM,eAA6B,QAAQ,8BAA8B;AACzE,MAAM,aAAa,cAAc,WAAW;AAC5C,MAAM,WAAW,YAAY,WAAW;AACxC,MAAM,cAAc,eAAe,WAAW;AAC9C,MAAM,YAAY,aAAa,WAAW;AAC1C,MAAM,YAAY,aAAa,WAAW;AAC1C,MAAM,kBAAkB,aAAa;AAG9B,MAAM,UAA6B,2BAAW,UAAU;AACxD,MAAM,QAAyB,2BAAW,QAAQ;AAClD,MAAM,WAA+B,2BAAW,WAAW;AAC3D,MAAM,SAA2B,2BAAW,SAAS;AACrD,MAAM,SAA2B,2BAAW,SAAS;",
+  "sourcesContent": ["/**\n * @fileoverview User prompt utilities for interactive scripts.\n * Provides inquirer.js integration with spinner support and context handling.\n */\n\nimport { getAbortSignal, getSpinner } from '#constants/process'\n\nconst abortSignal = getAbortSignal()\nconst spinner = getSpinner()\n\n// Type definitions\n\n/**\n * Choice option for select and search prompts.\n *\n * @template Value - Type of the choice value\n */\nexport interface Choice<Value = unknown> {\n  /** The value returned when this choice is selected */\n  value: Value\n  /** Whether this choice is disabled, or a reason string */\n  disabled?: boolean | string | undefined\n  /** Additional description text shown below the choice */\n  description?: string | undefined\n  /** Display name for the choice (defaults to value.toString()) */\n  name?: string | undefined\n  /** Short text shown after selection (defaults to name) */\n  short?: string | undefined\n}\n\n/**\n * Context for inquirer prompts.\n * Minimal context interface used by Inquirer prompts.\n * Duplicated from `@inquirer/type` - InquirerContext.\n */\ninterface InquirerContext {\n  /** Abort signal for cancelling the prompt */\n  signal?: AbortSignal | undefined\n  /** Input stream (defaults to process.stdin) */\n  input?: NodeJS.ReadableStream | undefined\n  /** Output stream (defaults to process.stdout) */\n  output?: NodeJS.WritableStream | undefined\n  /** Clear the prompt from terminal when done */\n  clearPromptOnDone?: boolean | undefined\n}\n\n/**\n * Extended context with spinner support.\n * Allows passing a spinner instance to be managed during prompts.\n */\nexport type Context = import('../objects').Remap<\n  InquirerContext & {\n    /** Optional spinner to stop/start during prompt display */\n    spinner?: import('../spinner').Spinner | undefined\n  }\n>\n\n/**\n * Separator for visual grouping in select/checkbox prompts.\n * Creates a non-selectable visual separator line.\n * Duplicated from `@inquirer/select` - Separator.\n * This type definition ensures the Separator type is available in published packages.\n *\n * @example\n * import { Separator } from './prompts'\n *\n * const choices = [\n *   { name: 'Option 1', value: 1 },\n *   new Separator(),\n *   { name: 'Option 2', value: 2 }\n * ]\n */\ndeclare class SeparatorType {\n  readonly separator: string\n  readonly type: 'separator'\n  constructor(separator?: string)\n}\n\nexport type Separator = SeparatorType\n\n/**\n * Wrap an inquirer prompt with spinner handling and signal injection.\n * Automatically stops/starts spinners during prompt display and injects abort signals.\n * Trims string results and handles cancellation gracefully.\n *\n * @template T - Type of the prompt result\n * @param inquirerPrompt - The inquirer prompt function to wrap\n * @returns Wrapped prompt function with spinner and signal handling\n *\n * @example\n * const myPrompt = wrapPrompt(rawInquirerPrompt)\n * const result = await myPrompt({ message: 'Enter name:' })\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function wrapPrompt<T = unknown>(\n  inquirerPrompt: (...args: unknown[]) => Promise<T>,\n): (...args: unknown[]) => Promise<T | undefined> {\n  return async (...args) => {\n    const origContext = (args.length > 1 ? args[1] : undefined) as\n      | Context\n      | undefined\n    const { spinner: contextSpinner, ...contextWithoutSpinner } =\n      origContext ?? ({} as Context)\n    const spinnerInstance =\n      contextSpinner !== undefined ? contextSpinner : spinner\n    const signal = abortSignal\n    if (origContext) {\n      args[1] = {\n        signal,\n        ...contextWithoutSpinner,\n      }\n    } else {\n      args[1] = { signal }\n    }\n    const wasSpinning = !!spinnerInstance?.isSpinning\n    spinnerInstance?.stop()\n    let result: unknown\n    try {\n      result = await inquirerPrompt(...args)\n    } catch (e) {\n      if (e instanceof TypeError) {\n        throw e\n      }\n    }\n    if (wasSpinning) {\n      spinnerInstance.start()\n    }\n    return (typeof result === 'string' ? result.trim() : result) as\n      | T\n      | undefined\n  }\n}\n\n// c8 ignore start - Third-party inquirer library requires and exports not testable in isolation.\nconst confirmExport = /*@__PURE__*/ require('../external/@inquirer/confirm')\nconst inputExport = /*@__PURE__*/ require('../external/@inquirer/input')\nconst passwordExport = /*@__PURE__*/ require('../external/@inquirer/password')\nconst searchExport = /*@__PURE__*/ require('../external/@inquirer/search')\nconst selectExport = /*@__PURE__*/ require('../external/@inquirer/select')\nconst confirmRaw = confirmExport.default ?? confirmExport\nconst inputRaw = inputExport.default ?? inputExport\nconst passwordRaw = passwordExport.default ?? passwordExport\nconst searchRaw = searchExport.default ?? searchExport\nconst selectRaw = selectExport.default ?? selectExport\nconst ActualSeparator = selectExport.Separator\n// c8 ignore stop\n\n/**\n * Prompt for a yes/no confirmation.\n * Wrapped with spinner handling and abort signal support.\n *\n * @example\n * const answer = await confirm({ message: 'Continue?' })\n * if (answer) { // user confirmed }\n */\nexport const confirm: typeof confirmRaw = wrapPrompt(confirmRaw)\n\n/**\n * Prompt for text input.\n * Wrapped with spinner handling and abort signal support.\n * Result is automatically trimmed.\n *\n * @example\n * const name = await input({ message: 'Enter your name:' })\n */\nexport const input: typeof inputRaw = wrapPrompt(inputRaw)\n\n/**\n * Prompt for password input (hidden characters).\n * Wrapped with spinner handling and abort signal support.\n *\n * @example\n * const token = await password({ message: 'Enter API token:' })\n */\nexport const password: typeof passwordRaw = wrapPrompt(passwordRaw)\n\n/**\n * Prompt with searchable/filterable choices.\n * Wrapped with spinner handling and abort signal support.\n *\n * @example\n * const result = await search({\n *   message: 'Select a package:',\n *   source: async (input) => fetchPackages(input)\n * })\n */\nexport const search: typeof searchRaw = wrapPrompt(searchRaw)\n\n/**\n * Prompt to select from a list of choices.\n * Wrapped with spinner handling and abort signal support.\n *\n * @example\n * const choice = await select({\n *   message: 'Choose an option:',\n *   choices: [\n *     { name: 'Option 1', value: 'opt1' },\n *     { name: 'Option 2', value: 'opt2' }\n *   ]\n * })\n */\nexport const select: typeof selectRaw = wrapPrompt(selectRaw)\n\nexport { ActualSeparator as Separator }\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,qBAA2C;AAE3C,MAAM,kBAAc,+BAAe;AACnC,MAAM,cAAU,2BAAW;AAAA;AAsFpB,SAAS,WACd,gBACgD;AAChD,SAAO,UAAU,SAAS;AACxB,UAAM,cAAe,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI;AAGjD,UAAM,EAAE,SAAS,gBAAgB,GAAG,sBAAsB,IACxD,eAAgB,CAAC;AACnB,UAAM,kBACJ,mBAAmB,SAAY,iBAAiB;AAClD,UAAM,SAAS;AACf,QAAI,aAAa;AACf,WAAK,CAAC,IAAI;AAAA,QACR;AAAA,QACA,GAAG;AAAA,MACL;AAAA,IACF,OAAO;AACL,WAAK,CAAC,IAAI,EAAE,OAAO;AAAA,IACrB;AACA,UAAM,cAAc,CAAC,CAAC,iBAAiB;AACvC,qBAAiB,KAAK;AACtB,QAAI;AACJ,QAAI;AACF,eAAS,MAAM,eAAe,GAAG,IAAI;AAAA,IACvC,SAAS,GAAG;AACV,UAAI,aAAa,WAAW;AAC1B,cAAM;AAAA,MACR;AAAA,IACF;AACA,QAAI,aAAa;AACf,sBAAgB,MAAM;AAAA,IACxB;AACA,WAAQ,OAAO,WAAW,WAAW,OAAO,KAAK,IAAI;AAAA,EAGvD;AACF;AAGA,MAAM,gBAA8B,QAAQ,+BAA+B;AAC3E,MAAM,cAA4B,QAAQ,6BAA6B;AACvE,MAAM,iBAA+B,QAAQ,gCAAgC;AAC7E,MAAM,eAA6B,QAAQ,8BAA8B;AACzE,MAAM,eAA6B,QAAQ,8BAA8B;AACzE,MAAM,aAAa,cAAc,WAAW;AAC5C,MAAM,WAAW,YAAY,WAAW;AACxC,MAAM,cAAc,eAAe,WAAW;AAC9C,MAAM,YAAY,aAAa,WAAW;AAC1C,MAAM,YAAY,aAAa,WAAW;AAC1C,MAAM,kBAAkB,aAAa;AAW9B,MAAM,UAA6B,2BAAW,UAAU;AAUxD,MAAM,QAAyB,2BAAW,QAAQ;AASlD,MAAM,WAA+B,2BAAW,WAAW;AAY3D,MAAM,SAA2B,2BAAW,SAAS;AAerD,MAAM,SAA2B,2BAAW,SAAS;",
   "names": []
 }

package/dist/stdio/stderr.d.ts

@@ -1,47 +1,150 @@
 /**
- * Standard error stream utilities.
+ * @fileoverview Standard error stream utilities.
  * Provides utilities for writing to stderr with formatting and control.
  */
 // Get the actual stderr stream
 declare const stderr: NodeJS.WriteStream;
 /**
- * Write an error line to stderr.
+ * Write a line to stderr with trailing newline.
+ * Used for error messages, warnings, and diagnostic output.
+ *
+ * @param text - Text to write
+ * @default text ''
+ *
+ * @example
+ * ```ts
+ * writeErrorLine('Error: File not found')
+ * writeErrorLine() // Write empty line
+ * ```
  */
 export declare function writeErrorLine(text?: string): void;
 /**
- * Write error text to stderr without newline.
+ * Write text to stderr without adding a newline.
+ *
+ * @param text - Text to write
+ *
+ * @example
+ * ```ts
+ * writeError('Downloading...')
+ * // Later update progress
+ * ```
  */
 export declare function writeError(text: string): void;
 /**
  * Clear the current line on stderr.
+ * Only works in TTY environments.
+ *
+ * @example
+ * ```ts
+ * writeError('Processing...')
+ * clearLine()
+ * writeError('Done!')
+ * ```
  */
 export declare function clearLine(): void;
 /**
- * Move cursor to position on stderr.
+ * Move cursor to specific position on stderr.
+ * Only works in TTY environments.
+ *
+ * @param x - Column position (0-based)
+ * @param y - Row position (0-based, optional)
+ *
+ * @example
+ * ```ts
+ * cursorTo(0) // Move to start of line
+ * cursorTo(10, 5) // Move to column 10, row 5
+ * ```
  */
-export declare function cursorTo(x: number, y?: number): void;
+export declare function cursorTo(x: number, y?: number | undefined): void;
 /**
- * Check if stderr is a TTY.
+ * Check if stderr is connected to a TTY (terminal).
+ *
+ * @returns `true` if stderr is a TTY, `false` if piped/redirected
+ *
+ * @example
+ * ```ts
+ * if (isTTY()) {
+ *   // Show colored error messages
+ * } else {
+ *   // Use plain text
+ * }
+ * ```
  */
 export declare function isTTY(): boolean;
 /**
- * Get terminal columns for stderr.
+ * Get the number of columns (width) in the terminal.
+ *
+ * @returns Terminal width in characters
+ * @default 80
+ *
+ * @example
+ * ```ts
+ * const width = getColumns()
+ * console.error(`Terminal is ${width} characters wide`)
+ * ```
  */
 export declare function getColumns(): number;
 /**
- * Get terminal rows for stderr.
+ * Get the number of rows (height) in the terminal.
+ *
+ * @returns Terminal height in lines
+ * @default 24
+ *
+ * @example
+ * ```ts
+ * const height = getRows()
+ * console.error(`Terminal is ${height} lines tall`)
+ * ```
  */
 export declare function getRows(): number;
 /**
- * Write a warning to stderr with formatting.
+ * Write a formatted warning message to stderr.
+ *
+ * @param message - Warning message text
+ * @param prefix - Prefix label for the warning
+ * @default prefix 'Warning'
+ *
+ * @example
+ * ```ts
+ * writeWarning('Deprecated API usage')
+ * // Output: 'Warning: Deprecated API usage'
+ *
+ * writeWarning('Invalid config', 'Config')
+ * // Output: 'Config: Invalid config'
+ * ```
  */
 export declare function writeWarning(message: string, prefix?: string): void;
 /**
- * Write an error to stderr with formatting.
+ * Write a formatted error message to stderr.
+ *
+ * @param message - Error message text
+ * @param prefix - Prefix label for the error
+ * @default prefix 'Error'
+ *
+ * @example
+ * ```ts
+ * writeErrorFormatted('File not found')
+ * // Output: 'Error: File not found'
+ *
+ * writeErrorFormatted('Connection failed', 'Network')
+ * // Output: 'Network: Connection failed'
+ * ```
  */
 export declare function writeErrorFormatted(message: string, prefix?: string): void;
 /**
- * Write stack trace to stderr.
+ * Write an error's stack trace to stderr.
+ * Falls back to formatted error message if no stack is available.
+ *
+ * @param error - Error object to write
+ *
+ * @example
+ * ```ts
+ * try {
+ *   throw new Error('Something went wrong')
+ * } catch (err) {
+ *   writeStackTrace(err as Error)
+ * }
+ * ```
  */
 export declare function writeStackTrace(error: Error): void;
 // Export the raw stream for advanced usage

package/dist/stdio/stderr.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/stdio/stderr.ts"],
-  "sourcesContent": ["/**\n * Standard error stream utilities.\n * Provides utilities for writing to stderr with formatting and control.\n */\n\n// Get the actual stderr stream\nconst stderr: NodeJS.WriteStream = process.stderr\n\n/**\n * Write an error line to stderr.\n */\nexport function writeErrorLine(text: string = ''): void {\n  stderr.write(`${text}\\n`)\n}\n\n/**\n * Write error text to stderr without newline.\n */\nexport function writeError(text: string): void {\n  stderr.write(text)\n}\n\n/**\n * Clear the current line on stderr.\n */\nexport function clearLine(): void {\n  if (stderr.isTTY) {\n    stderr.cursorTo(0)\n    stderr.clearLine(0)\n  }\n}\n\n/**\n * Move cursor to position on stderr.\n */\nexport function cursorTo(x: number, y?: number): void {\n  if (stderr.isTTY) {\n    stderr.cursorTo(x, y)\n  }\n}\n\n/**\n * Check if stderr is a TTY.\n */\nexport function isTTY(): boolean {\n  return stderr.isTTY || false\n}\n\n/**\n * Get terminal columns for stderr.\n */\nexport function getColumns(): number {\n  return stderr.columns || 80\n}\n\n/**\n * Get terminal rows for stderr.\n */\nexport function getRows(): number {\n  return stderr.rows || 24\n}\n\n/**\n * Write a warning to stderr with formatting.\n */\nexport function writeWarning(\n  message: string,\n  prefix: string = 'Warning',\n): void {\n  const formatted = `${prefix}: ${message}`\n  writeErrorLine(formatted)\n}\n\n/**\n * Write an error to stderr with formatting.\n */\nexport function writeErrorFormatted(\n  message: string,\n  prefix: string = 'Error',\n): void {\n  const formatted = `${prefix}: ${message}`\n  writeErrorLine(formatted)\n}\n\n/**\n * Write stack trace to stderr.\n */\nexport function writeStackTrace(error: Error): void {\n  if (error.stack) {\n    writeErrorLine(error.stack)\n  } else {\n    writeErrorFormatted(error.message)\n  }\n}\n\n// Export the raw stream for advanced usage\nexport { stderr }\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,MAAM,SAA6B,QAAQ;AAKpC,SAAS,eAAe,OAAe,IAAU;AACtD,SAAO,MAAM,GAAG,IAAI;AAAA,CAAI;AAC1B;AAKO,SAAS,WAAW,MAAoB;AAC7C,SAAO,MAAM,IAAI;AACnB;AAKO,SAAS,YAAkB;AAChC,MAAI,OAAO,OAAO;AAChB,WAAO,SAAS,CAAC;AACjB,WAAO,UAAU,CAAC;AAAA,EACpB;AACF;AAKO,SAAS,SAAS,GAAW,GAAkB;AACpD,MAAI,OAAO,OAAO;AAChB,WAAO,SAAS,GAAG,CAAC;AAAA,EACtB;AACF;AAKO,SAAS,QAAiB;AAC/B,SAAO,OAAO,SAAS;AACzB;AAKO,SAAS,aAAqB;AACnC,SAAO,OAAO,WAAW;AAC3B;AAKO,SAAS,UAAkB;AAChC,SAAO,OAAO,QAAQ;AACxB;AAKO,SAAS,aACd,SACA,SAAiB,WACX;AACN,QAAM,YAAY,GAAG,MAAM,KAAK,OAAO;AACvC,iBAAe,SAAS;AAC1B;AAKO,SAAS,oBACd,SACA,SAAiB,SACX;AACN,QAAM,YAAY,GAAG,MAAM,KAAK,OAAO;AACvC,iBAAe,SAAS;AAC1B;AAKO,SAAS,gBAAgB,OAAoB;AAClD,MAAI,MAAM,OAAO;AACf,mBAAe,MAAM,KAAK;AAAA,EAC5B,OAAO;AACL,wBAAoB,MAAM,OAAO;AAAA,EACnC;AACF;",
+  "sourcesContent": ["/**\n * @fileoverview Standard error stream utilities.\n * Provides utilities for writing to stderr with formatting and control.\n */\n\n// Get the actual stderr stream\nconst stderr: NodeJS.WriteStream = process.stderr\n\n/**\n * Write a line to stderr with trailing newline.\n * Used for error messages, warnings, and diagnostic output.\n *\n * @param text - Text to write\n * @default text ''\n *\n * @example\n * ```ts\n * writeErrorLine('Error: File not found')\n * writeErrorLine() // Write empty line\n * ```\n */\nexport function writeErrorLine(text: string = ''): void {\n  stderr.write(`${text}\\n`)\n}\n\n/**\n * Write text to stderr without adding a newline.\n *\n * @param text - Text to write\n *\n * @example\n * ```ts\n * writeError('Downloading...')\n * // Later update progress\n * ```\n */\nexport function writeError(text: string): void {\n  stderr.write(text)\n}\n\n/**\n * Clear the current line on stderr.\n * Only works in TTY environments.\n *\n * @example\n * ```ts\n * writeError('Processing...')\n * clearLine()\n * writeError('Done!')\n * ```\n */\nexport function clearLine(): void {\n  if (stderr.isTTY) {\n    stderr.cursorTo(0)\n    stderr.clearLine(0)\n  }\n}\n\n/**\n * Move cursor to specific position on stderr.\n * Only works in TTY environments.\n *\n * @param x - Column position (0-based)\n * @param y - Row position (0-based, optional)\n *\n * @example\n * ```ts\n * cursorTo(0) // Move to start of line\n * cursorTo(10, 5) // Move to column 10, row 5\n * ```\n */\nexport function cursorTo(x: number, y?: number | undefined): void {\n  if (stderr.isTTY) {\n    stderr.cursorTo(x, y)\n  }\n}\n\n/**\n * Check if stderr is connected to a TTY (terminal).\n *\n * @returns `true` if stderr is a TTY, `false` if piped/redirected\n *\n * @example\n * ```ts\n * if (isTTY()) {\n *   // Show colored error messages\n * } else {\n *   // Use plain text\n * }\n * ```\n */\nexport function isTTY(): boolean {\n  return stderr.isTTY || false\n}\n\n/**\n * Get the number of columns (width) in the terminal.\n *\n * @returns Terminal width in characters\n * @default 80\n *\n * @example\n * ```ts\n * const width = getColumns()\n * console.error(`Terminal is ${width} characters wide`)\n * ```\n */\nexport function getColumns(): number {\n  return stderr.columns || 80\n}\n\n/**\n * Get the number of rows (height) in the terminal.\n *\n * @returns Terminal height in lines\n * @default 24\n *\n * @example\n * ```ts\n * const height = getRows()\n * console.error(`Terminal is ${height} lines tall`)\n * ```\n */\nexport function getRows(): number {\n  return stderr.rows || 24\n}\n\n/**\n * Write a formatted warning message to stderr.\n *\n * @param message - Warning message text\n * @param prefix - Prefix label for the warning\n * @default prefix 'Warning'\n *\n * @example\n * ```ts\n * writeWarning('Deprecated API usage')\n * // Output: 'Warning: Deprecated API usage'\n *\n * writeWarning('Invalid config', 'Config')\n * // Output: 'Config: Invalid config'\n * ```\n */\nexport function writeWarning(\n  message: string,\n  prefix: string = 'Warning',\n): void {\n  const formatted = `${prefix}: ${message}`\n  writeErrorLine(formatted)\n}\n\n/**\n * Write a formatted error message to stderr.\n *\n * @param message - Error message text\n * @param prefix - Prefix label for the error\n * @default prefix 'Error'\n *\n * @example\n * ```ts\n * writeErrorFormatted('File not found')\n * // Output: 'Error: File not found'\n *\n * writeErrorFormatted('Connection failed', 'Network')\n * // Output: 'Network: Connection failed'\n * ```\n */\nexport function writeErrorFormatted(\n  message: string,\n  prefix: string = 'Error',\n): void {\n  const formatted = `${prefix}: ${message}`\n  writeErrorLine(formatted)\n}\n\n/**\n * Write an error's stack trace to stderr.\n * Falls back to formatted error message if no stack is available.\n *\n * @param error - Error object to write\n *\n * @example\n * ```ts\n * try {\n *   throw new Error('Something went wrong')\n * } catch (err) {\n *   writeStackTrace(err as Error)\n * }\n * ```\n */\nexport function writeStackTrace(error: Error): void {\n  if (error.stack) {\n    writeErrorLine(error.stack)\n  } else {\n    writeErrorFormatted(error.message)\n  }\n}\n\n// Export the raw stream for advanced usage\nexport { stderr }\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,MAAM,SAA6B,QAAQ;AAepC,SAAS,eAAe,OAAe,IAAU;AACtD,SAAO,MAAM,GAAG,IAAI;AAAA,CAAI;AAC1B;AAaO,SAAS,WAAW,MAAoB;AAC7C,SAAO,MAAM,IAAI;AACnB;AAaO,SAAS,YAAkB;AAChC,MAAI,OAAO,OAAO;AAChB,WAAO,SAAS,CAAC;AACjB,WAAO,UAAU,CAAC;AAAA,EACpB;AACF;AAeO,SAAS,SAAS,GAAW,GAA8B;AAChE,MAAI,OAAO,OAAO;AAChB,WAAO,SAAS,GAAG,CAAC;AAAA,EACtB;AACF;AAgBO,SAAS,QAAiB;AAC/B,SAAO,OAAO,SAAS;AACzB;AAcO,SAAS,aAAqB;AACnC,SAAO,OAAO,WAAW;AAC3B;AAcO,SAAS,UAAkB;AAChC,SAAO,OAAO,QAAQ;AACxB;AAkBO,SAAS,aACd,SACA,SAAiB,WACX;AACN,QAAM,YAAY,GAAG,MAAM,KAAK,OAAO;AACvC,iBAAe,SAAS;AAC1B;AAkBO,SAAS,oBACd,SACA,SAAiB,SACX;AACN,QAAM,YAAY,GAAG,MAAM,KAAK,OAAO;AACvC,iBAAe,SAAS;AAC1B;AAiBO,SAAS,gBAAgB,OAAoB;AAClD,MAAI,MAAM,OAAO;AACf,mBAAe,MAAM,KAAK;AAAA,EAC5B,OAAO;AACL,wBAAoB,MAAM,OAAO;AAAA,EACnC;AACF;",
   "names": []
 }