@levu/snap 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-02-24
+
+### Added
+- **New Components**: Added `spinner` component for loading states during long-running operations
+- **New Components**: Added `password` component for secure text input
+- **New Terminal Features**: Added structured logging with `log.info()`, `log.success()`, `log.warn()`, `log.error()` utilities
+- **Documentation**: Comprehensive Getting Started guide with installation and quick start examples
+- **Documentation**: SnapArgs documentation - type-safe argument reading helpers
+- **Documentation**: SnapHelp documentation - schema-driven help generation
+- **Documentation**: SnapRuntime documentation - standardized action result helpers
+- **Documentation**: SnapTui documentation - typed TUI flow definitions and components
+- **Documentation**: SnapTerminal documentation - terminal output and logging helpers
+- **Documentation**: Integration examples demonstrating common patterns
+- **Examples**: Full example project in `example/` directory
+- **Tests**: Added comprehensive test coverage for new components and documentation examples
+
+### Changed
+- Enhanced `TerminalOutput` interface with `info()`, `success()`, and `warn()` methods
+- Updated `.gitignore` with comprehensive Node.js package patterns
+- Removed `.idea/` folder from git tracking
+
+### Fixed
+- Fixed issue where users couldn't discover available components (now fully documented)
+
+## [0.1.1] - 2025-02-10
+
+### Added
+- Initial release of Snap framework
+- Contract-first TypeScript framework for terminal workflows
+- Core contracts: ActionContract, ModuleContract, HelpContract, TuiContract
+- CLI runners: multi-module, single-module, and submodule support
+- DX helpers: SnapArgs, SnapHelp, SnapRuntime, SnapTui, SnapTerminal
+- TUI components: text, confirm, select, multiselect, cancel, group
+- Help system with deterministic, text-only output

package/README.md

@@ -19,6 +19,7 @@ For module/tool authors, Snap also exposes optional DX helper groups:
 - Enforces action triad at registration: `tui + commandline + help`
 - Uses one runtime engine for TUI and CLI paths
 - Uses Clack-powered prompt adapters for interactive TUI (`select`, `text`, `confirm`, `multiselect`)
+- Text prompts support clipboard paste and multiline input for pasting multiple lines
 - Supports workflow transitions: `next`, `back`, `jump`, `exit`
 - Supports resume checkpoints for interrupted flows
 - Produces stable help output hierarchy:
@@ -52,5 +53,29 @@ npm run dev -- system node-info
 
 ## For module authors
 
-- `docs/module-authoring-guide.md`
-- `docs/help-contract-spec.md`
+### Documentation
+
+- **[Getting Started](./docs/getting-started.md)** - Quick start guide
+- **[Module Authoring Guide](./docs/module-authoring-guide.md)** - Core concepts
+- **[Help Contract Spec](./docs/help-contract-spec.md)** - Help format specification
+
+### DX Helper References
+
+- **[SnapArgs](./docs/snap-args.md)** - Type-safe argument reading
+- **[SnapHelp](./docs/snap-help.md)** - Schema-driven help generation
+- **[SnapRuntime](./docs/snap-runtime.md)** - Standardized action results
+- **[SnapTui](./docs/snap-tui.md)** - Typed TUI flow definitions
+- **[SnapTerminal](./docs/snap-terminal.md)** - Terminal output helpers
+
+### Additional Resources
+
+- **[Integration Examples](./docs/integration-examples.md)** - Common patterns
+- **[Component Reference](./docs/component-reference.md)** - All components and gaps
+
+### Examples
+
+See [`examples/`](./examples/) for working code examples:
+- `basic-module.ts` - Minimal module structure
+- `advanced-flow.ts` - Multi-step workflows
+- `dx-helpers.ts` - All DX helpers in action
+- `custom-prompt.ts` - Custom prompts with validation

package/dist/dx/terminal/index.d.ts

@@ -1,2 +1,3 @@
 export type { TerminalOutput } from './output.js';
-export { createTerminalOutput } from './output.js';
+export { createTerminalOutput, log } from './output.js';
+export { intro, outro, cancel } from './intro-outro.js';

package/dist/dx/terminal/index.js

@@ -1 +1,3 @@
-export { createTerminalOutput } from './output.js';
+export { createTerminalOutput, log } from './output.js';
+// Intro/outro/cancel utilities
+export { intro, outro, cancel } from './intro-outro.js';

package/dist/dx/terminal/intro-outro.d.ts

@@ -0,0 +1,4 @@
+import type { Writable } from 'node:stream';
+export declare const intro: (message: string, stdout?: Writable) => void;
+export declare const outro: (message: string, stdout?: Writable) => void;
+export declare const cancel: (message: string, stdout?: Writable) => void;

package/dist/dx/terminal/intro-outro.js

@@ -0,0 +1,44 @@
+const boxChars = {
+    topLeft: '┌',
+    topRight: '┐',
+    bottomLeft: '└',
+    bottomRight: '┘',
+    horizontal: '─',
+    vertical: '│',
+    left: ' '
+};
+const renderBox = (message, leftChar, rightChar, stream) => {
+    const padding = 1;
+    const lines = message.split('\n');
+    const maxLength = Math.max(...lines.map((line) => line.length));
+    stream.write(`${leftChar}${boxChars.horizontal}${' '.repeat(maxLength + padding * 2)}${boxChars.horizontal}${rightChar}\n`);
+    for (const line of lines) {
+        stream.write(`${boxChars.vertical} ${line.padEnd(maxLength + padding)} ${boxChars.vertical}\n`);
+    }
+    stream.write(`${leftChar === '┌' ? boxChars.bottomLeft : leftChar}${boxChars.horizontal}${' '.repeat(maxLength + padding * 2)}${boxChars.horizontal}${rightChar === '┐' ? boxChars.topRight : rightChar}\n`);
+};
+export const intro = (message, stdout = process.stdout) => {
+    if (!message) {
+        stdout.write('\n');
+        return;
+    }
+    renderBox(message, boxChars.topLeft, boxChars.topRight, stdout);
+};
+export const outro = (message, stdout = process.stdout) => {
+    if (!message) {
+        stdout.write('\n');
+        return;
+    }
+    stdout.write('\n');
+    renderBox(message, boxChars.bottomLeft, boxChars.bottomRight, stdout);
+    stdout.write('\n');
+};
+export const cancel = (message, stdout = process.stdout) => {
+    if (!message) {
+        stdout.write('\n');
+        return;
+    }
+    stdout.write('\n');
+    renderBox(message, boxChars.bottomLeft, boxChars.bottomRight, stdout);
+    stdout.write('\n');
+};

package/dist/dx/terminal/output.d.ts

@@ -3,5 +3,17 @@ export interface TerminalOutput {
     line(message: string): void;
     lines(messages: readonly string[]): void;
     error(message: string): void;
+    info(message: string): void;
+    success(message: string): void;
+    warn(message: string): void;
 }
-export declare const createTerminalOutput: (stdout?: Writable, stderr?: Writable) => TerminalOutput;
+export interface LogOptions {
+    prefix?: string;
+}
+export declare const createTerminalOutput: (stdout?: Writable, stderr?: Writable, options?: LogOptions) => TerminalOutput;
+export declare const log: {
+    info(message: string): void;
+    success(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+};

package/dist/dx/terminal/output.js

@@ -1,7 +1,20 @@
+const symbols = {
+    info: 'ℹ',
+    success: '✔',
+    warn: '⚠',
+    error: '✖'
+};
 const writeLine = (stream, message) => {
     stream.write(`${message}\n`);
 };
-export const createTerminalOutput = (stdout = process.stdout, stderr = process.stderr) => {
+export const createTerminalOutput = (stdout = process.stdout, stderr = process.stderr, options = {}) => {
+    const formatLog = (symbol, message, color) => {
+        const prefix = options.prefix ?? '';
+        if (color) {
+            return `${prefix}${color}${symbol} \x1b[0m${message}`;
+        }
+        return `${prefix}${symbol} ${message}`;
+    };
     return {
         line(message) {
             writeLine(stdout, message);
@@ -12,7 +25,35 @@ export const createTerminalOutput = (stdout = process.stdout, stderr = process.s
             }
         },
         error(message) {
-            writeLine(stderr, message);
+            writeLine(stderr, formatLog(symbols.error, message, '\x1b[31m')); // Red
+        },
+        info(message) {
+            writeLine(stdout, formatLog(symbols.info, message, '\x1b[34m')); // Blue
+        },
+        success(message) {
+            writeLine(stdout, formatLog(symbols.success, message, '\x1b[32m')); // Green
+        },
+        warn(message) {
+            writeLine(stdout, formatLog(symbols.warn, message, '\x1b[33m')); // Yellow
         }
     };
 };
+// Convenience log functions using default streams
+export const log = {
+    info(message) {
+        const terminal = createTerminalOutput();
+        terminal.info(message);
+    },
+    success(message) {
+        const terminal = createTerminalOutput();
+        terminal.success(message);
+    },
+    warn(message) {
+        const terminal = createTerminalOutput();
+        terminal.warn(message);
+    },
+    error(message) {
+        const terminal = createTerminalOutput();
+        terminal.error(message);
+    }
+};

package/dist/dx/tui/index.d.ts

@@ -2,3 +2,15 @@ export { defineTuiOptions, defineTuiComponent, defineCustomTuiComponent, defineT
 export { defineTuiFlow } from './flow.js';
 export { backToPreviousOnNoResult, formatNoResultMessage } from './no-result.js';
 export type { NoResultBackContext, NoResultBackInput } from './no-result.js';
+export { createSpinner, spinner } from '../../tui/component-adapters/spinner.js';
+export type { Spinner, SpinnerOptions } from '../../tui/component-adapters/spinner.js';
+export { runPasswordPrompt } from '../../tui/component-adapters/password.js';
+export type { PasswordPromptInput } from '../../tui/component-adapters/password.js';
+export { createProgress, progress } from '../../tui/component-adapters/progress.js';
+export type { Progress } from '../../tui/component-adapters/progress.js';
+export { tasks } from '../../tui/component-adapters/tasks.js';
+export type { Task, TasksOptions } from '../../tui/component-adapters/tasks.js';
+export { note } from '../../tui/component-adapters/note.js';
+export type { NoteInput } from '../../tui/component-adapters/note.js';
+export { runAutocompletePrompt } from '../../tui/component-adapters/autocomplete.js';
+export type { AutocompleteInput, AutocompleteOption } from '../../tui/component-adapters/autocomplete.js';

package/dist/dx/tui/index.js

@@ -1,3 +1,15 @@
 export { defineTuiOptions, defineTuiComponent, defineCustomTuiComponent, defineTuiStep, isCustomTuiComponent } from './components.js';
 export { defineTuiFlow } from './flow.js';
 export { backToPreviousOnNoResult, formatNoResultMessage } from './no-result.js';
+// Spinner component for loading states
+export { createSpinner, spinner } from '../../tui/component-adapters/spinner.js';
+// Password component for secure input
+export { runPasswordPrompt } from '../../tui/component-adapters/password.js';
+// Progress component for quantified operations
+export { createProgress, progress } from '../../tui/component-adapters/progress.js';
+// Tasks component for sequential async operations
+export { tasks } from '../../tui/component-adapters/tasks.js';
+// Note component for decorative message boxes
+export { note } from '../../tui/component-adapters/note.js';
+// Autocomplete component for searchable selections
+export { runAutocompletePrompt } from '../../tui/component-adapters/autocomplete.js';

package/dist/index.d.ts

@@ -12,4 +12,10 @@ export { createPromptToolkit } from './tui/prompt-toolkit.js';
 export type { PromptToolkit } from './tui/prompt-toolkit.js';
 export { runCustomPrompt, createCustomPromptRunner } from './tui/custom/index.js';
 export type { CustomPromptInput, CustomPromptRunner } from './tui/custom/index.js';
+export { createSpinner, spinner } from './tui/component-adapters/spinner.js';
+export type { Spinner, SpinnerOptions } from './tui/component-adapters/spinner.js';
+export { runPasswordPrompt } from './tui/component-adapters/password.js';
+export type { PasswordPromptInput } from './tui/component-adapters/password.js';
+export { createMultilineTextPrompt } from './tui/component-adapters/multiline-text.js';
+export type { MultilineTextOptions } from './tui/component-adapters/multiline-text.js';
 export declare const createRegistry: (modules: ModuleContract[]) => ActionRegistry;

package/dist/index.js

@@ -8,6 +8,9 @@ export * as SnapTerminal from './dx/terminal/index.js';
 export * as SnapTui from './dx/tui/index.js';
 export { createPromptToolkit } from './tui/prompt-toolkit.js';
 export { runCustomPrompt, createCustomPromptRunner } from './tui/custom/index.js';
+export { createSpinner, spinner } from './tui/component-adapters/spinner.js';
+export { runPasswordPrompt } from './tui/component-adapters/password.js';
+export { createMultilineTextPrompt } from './tui/component-adapters/multiline-text.js';
 export const createRegistry = (modules) => {
     const registry = new ActionRegistry();
     for (const moduleContract of modules) {

package/dist/tui/component-adapters/autocomplete.d.ts

@@ -0,0 +1,15 @@
+export interface AutocompleteOption {
+    value: string;
+    label: string;
+    hint?: string;
+}
+export interface AutocompleteInput {
+    message: string;
+    options: AutocompleteOption[];
+    placeholder?: string;
+    initialValue?: string;
+    maxItems?: number;
+    required?: boolean;
+    validate?: (value: string) => string | Error | undefined;
+}
+export declare const runAutocompletePrompt: (input: AutocompleteInput) => Promise<string | undefined>;

package/dist/tui/component-adapters/autocomplete.js

@@ -0,0 +1,34 @@
+import { autocomplete as clackAutocomplete } from '@clack/prompts';
+import { isInteractiveTerminal } from './readline-utils.js';
+import { unwrapClackResult } from './cancel.js';
+export const runAutocompletePrompt = async (input) => {
+    if (!isInteractiveTerminal()) {
+        // Non-interactive: return initial value or first option
+        return input.initialValue ?? input.options[0]?.value;
+    }
+    const value = await clackAutocomplete({
+        message: input.message,
+        options: input.options,
+        placeholder: input.placeholder,
+        initialValue: input.initialValue,
+        maxItems: input.maxItems,
+        validate: (raw) => {
+            // Handle string | string[] | undefined from clack
+            const valueToValidate = typeof raw === 'string' ? raw : Array.isArray(raw) ? raw[0] ?? '' : '';
+            if (input.required && !valueToValidate) {
+                return 'This field is required';
+            }
+            if (input.validate) {
+                const validationResult = input.validate(valueToValidate);
+                if (typeof validationResult === 'string') {
+                    return validationResult;
+                }
+                if (validationResult instanceof Error) {
+                    return validationResult.message;
+                }
+            }
+            return undefined;
+        }
+    });
+    return unwrapClackResult(value);
+};

package/dist/tui/component-adapters/multiline-text.d.ts

@@ -0,0 +1,13 @@
+import { Readable } from 'node:stream';
+import { Writable } from 'node:stream';
+export interface MultilineTextOptions {
+    message: string;
+    initialValue?: string;
+    placeholder?: string;
+    validate?: (value: string | undefined) => string | Error | undefined;
+    allowPaste?: boolean;
+    input?: Readable;
+    output?: Writable;
+    signal?: AbortSignal;
+}
+export declare const createMultilineTextPrompt: () => (opts: MultilineTextOptions) => Promise<string | symbol>;

package/dist/tui/component-adapters/multiline-text.js

@@ -0,0 +1,166 @@
+import { createInterface } from 'node:readline';
+import * as pc from 'picocolors';
+export const createMultilineTextPrompt = () => {
+    return async (opts) => {
+        const { message, initialValue = '', placeholder = '', validate, allowPaste = false, input = process.stdin, output = process.stdout, signal, } = opts;
+        // Use standard text prompt for single line paste
+        if (!allowPaste) {
+            const { text: textPrompt } = await import('@clack/prompts');
+            return textPrompt({
+                message,
+                initialValue,
+                placeholder,
+                validate,
+                input,
+                output,
+                signal,
+            });
+        }
+        // For multiline paste support, use a custom readline-based approach
+        return new Promise((resolve, reject) => {
+            const rl = createInterface({
+                input,
+                output,
+                terminal: true,
+            });
+            let value = initialValue;
+            let cancelled = false;
+            const cleanup = () => {
+                rl.close();
+            };
+            const submit = (val) => {
+                cleanup();
+                resolve(val);
+            };
+            const doCancel = () => {
+                cancelled = true;
+                cleanup();
+                const { isCancel: cancelSymbol } = require('@clack/prompts');
+                resolve(cancelSymbol);
+            };
+            // Show instructions
+            output.write(`\n${pc.cyan('○')} ${pc.bold(message)}\n`);
+            if (allowPaste) {
+                output.write(pc.dim(`  Paste support: Ctrl+V to paste (macOS/Linux: Cmd+Shift+V)\n`));
+            }
+            output.write(pc.dim(`  Press Enter twice or Alt+Enter to submit\n`));
+            const lines = value.split('\n');
+            let currentLine = lines.length > 0 ? lines.pop() : '';
+            const showPrompt = () => {
+                output.write(`\n${pc.dim('> ')}${currentLine}`);
+            };
+            showPrompt();
+            // Handle paste from clipboard
+            const handlePaste = async () => {
+                try {
+                    const { execSync } = await import('node:child_process');
+                    const platform = process.platform;
+                    if (platform === 'darwin') {
+                        return execSync('pbpaste', { encoding: 'utf-8' });
+                    }
+                    else if (platform === 'win32') {
+                        return execSync('powershell -command "Get-Clipboard"', { encoding: 'utf-8', shell: true }).trim();
+                    }
+                    else if (platform === 'linux') {
+                        try {
+                            return execSync('xclip -selection clipboard -o', {
+                                encoding: 'utf-8',
+                            });
+                        }
+                        catch {
+                            try {
+                                return execSync('xsel --clipboard --output', {
+                                    encoding: 'utf-8',
+                                });
+                            }
+                            catch {
+                                return '';
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Silent fail if clipboard is unavailable
+                }
+                return '';
+            };
+            let lastEnterTime = 0;
+            const DOUBLE_ENTER_TIMEOUT = 500; // ms
+            rl.on('line', (line) => {
+                if (cancelled)
+                    return;
+                const now = Date.now();
+                // Check for double Enter to submit
+                if (line === '' && now - lastEnterTime < DOUBLE_ENTER_TIMEOUT) {
+                    submit(lines.join('\n') + currentLine);
+                    return;
+                }
+                lastEnterTime = now;
+                if (line.trim() === '') {
+                    // Empty line - add to lines
+                    if (currentLine !== '') {
+                        lines.push(currentLine);
+                        currentLine = '';
+                    }
+                }
+                else {
+                    // Non-empty line
+                    if (currentLine !== '') {
+                        lines.push(currentLine);
+                    }
+                    currentLine = line;
+                }
+                showPrompt();
+            });
+            // Handle SIGINT (Ctrl+C)
+            rl.on('SIGINT', () => {
+                doCancel();
+            });
+            // Handle signal
+            if (signal) {
+                signal.addEventListener('abort', () => {
+                    doCancel();
+                });
+            }
+            // Handle paste via keyboard shortcut
+            if (allowPaste && input.setRawMode) {
+                input.setRawMode(true);
+                input.resume();
+                input.on('keypress', async (str, key) => {
+                    if (cancelled)
+                        return;
+                    // Detect Ctrl+V or Cmd+V for paste
+                    if ((key.ctrl && key.name === 'v') || (key.meta && key.name === 'v')) {
+                        const pasted = await handlePaste();
+                        if (pasted) {
+                            // Clear current line and show pasted content
+                            output.write('\r' + ' '.repeat(process.stdout.columns || 80) + '\r');
+                            const pastedLines = pasted.split('\n');
+                            if (pastedLines.length > 1) {
+                                // Multiline paste
+                                lines.push(...pastedLines.slice(0, -1));
+                                currentLine = pastedLines[pastedLines.length - 1];
+                            }
+                            else {
+                                // Single line paste
+                                currentLine += pasted;
+                            }
+                            output.write(`${pc.dim('> ')}${currentLine}`);
+                        }
+                    }
+                    else if (key.alt && key.name === 'enter') {
+                        // Alt+Enter to submit
+                        submit(lines.join('\n') + currentLine);
+                    }
+                    else if (key.name === 'escape') {
+                        doCancel();
+                    }
+                });
+            }
+            // Handle non-interactive terminal
+            if (!input.isTTY) {
+                submit(initialValue);
+            }
+        });
+    };
+};

package/dist/tui/component-adapters/note.d.ts

@@ -0,0 +1,7 @@
+import type { Writable } from 'node:stream';
+export interface NoteInput {
+    message: string;
+    title?: string;
+    format?: (line: string) => string;
+}
+export declare const note: (input: NoteInput, stdout?: Writable) => void;

package/dist/tui/component-adapters/note.js

@@ -0,0 +1,23 @@
+const boxChars = {
+    topLeft: '╮',
+    topRight: '╯',
+    bottomLeft: '╰',
+    bottomRight: '╯',
+    horizontal: '─',
+    vertical: '│'
+};
+export const note = (input, stdout = process.stdout) => {
+    const { message, title = '', format } = input;
+    const lines = message.split('\n');
+    const formattedLines = format ? lines.map(format) : lines;
+    const maxLength = Math.max(...formattedLines.map((line) => line.length), title.length);
+    const padding = 2;
+    // Top line
+    stdout.write(`${boxChars.vertical} ${title.padEnd(maxLength + padding)} ${boxChars.topLeft}${boxChars.horizontal.repeat(maxLength + padding * 2)}${boxChars.horizontal}\n`);
+    // Message lines
+    for (const line of formattedLines) {
+        stdout.write(`${boxChars.vertical} ${' '.repeat(maxLength + padding)} ${boxChars.vertical} ${line.padEnd(maxLength + padding)} ${boxChars.vertical}\n`);
+    }
+    // Bottom line
+    stdout.write(`${boxChars.horizontal}${boxChars.horizontal.repeat(maxLength + padding * 2)}${boxChars.horizontal}${boxChars.horizontal.repeat(maxLength + padding * 2)}${boxChars.vertical}\n`);
+};

package/dist/tui/component-adapters/password.d.ts

@@ -0,0 +1,7 @@
+export interface PasswordPromptInput {
+    message: string;
+    required?: boolean;
+    validate?: (value: string) => string | Error | undefined;
+    mask?: string;
+}
+export declare const runPasswordPrompt: (input: PasswordPromptInput) => Promise<string>;

package/dist/tui/component-adapters/password.js

@@ -0,0 +1,24 @@
+import { password as clackPassword } from '@clack/prompts';
+import { isInteractiveTerminal } from './readline-utils.js';
+import { unwrapClackResult } from './cancel.js';
+export const runPasswordPrompt = async (input) => {
+    if (!isInteractiveTerminal()) {
+        // For non-interactive terminals, read from stdin in a secure way
+        // or return empty/throw error
+        if (input.required) {
+            throw new Error(`Password required: ${input.message}`);
+        }
+        return '';
+    }
+    const value = await clackPassword({
+        message: input.message,
+        mask: input.mask ?? '•',
+        validate: (raw) => {
+            if (input.required && (!raw || raw.trim().length === 0)) {
+                return `Password is required`;
+            }
+            return input.validate?.(raw ?? '');
+        }
+    });
+    return unwrapClackResult(value);
+};

package/dist/tui/component-adapters/progress.d.ts

@@ -0,0 +1,7 @@
+export interface Progress {
+    start(message: string): void;
+    message(message: string): void;
+    stop(message?: string): void;
+}
+export declare const createProgress: () => Progress;
+export declare const progress: () => Progress;

package/dist/tui/component-adapters/progress.js

@@ -0,0 +1,44 @@
+import { isInteractiveTerminal } from './readline-utils.js';
+export const createProgress = () => {
+    // Non-interactive fallback
+    if (!isInteractiveTerminal()) {
+        let currentMessage = '';
+        return {
+            start(message) {
+                currentMessage = message;
+                process.stdout.write(`${message}...\n`);
+            },
+            message(newMessage) {
+                currentMessage = newMessage;
+                process.stdout.write(`${newMessage}\n`);
+            },
+            stop(finalMessage) {
+                if (finalMessage) {
+                    process.stdout.write(`${finalMessage}\n`);
+                }
+            }
+        };
+    }
+    // Interactive progress using @clack/prompts
+    let progressInstance = null;
+    return {
+        start(message) {
+            // Lazy load progress
+            import('@clack/prompts').then(({ progress }) => {
+                progressInstance = progress();
+                progressInstance.start(message);
+            });
+        },
+        message(newMessage) {
+            if (progressInstance) {
+                progressInstance.message(newMessage);
+            }
+        },
+        stop(finalMessage) {
+            if (progressInstance) {
+                progressInstance.stop(finalMessage);
+            }
+        }
+    };
+};
+export const progress = createProgress;

package/dist/tui/component-adapters/spinner.d.ts

@@ -0,0 +1,21 @@
+export interface SpinnerOptions {
+    message?: string;
+    indicator?: 'dots' | 'timer';
+    onCancel?: () => void;
+    cancelMessage?: string;
+    errorMessage?: string;
+    frames?: string[];
+    delay?: number;
+    styleFrame?: (frame: string) => string;
+}
+export interface Spinner {
+    start(message?: string): void;
+    stop(message?: string): void;
+    cancel(message?: string): void;
+    error(message?: string): void;
+    message(message: string): void;
+    clear(): void;
+    readonly isCancelled: boolean;
+}
+export declare const createSpinner: (options?: SpinnerOptions) => Spinner;
+export declare const spinner: (options?: SpinnerOptions) => Spinner;