@levu/snap 0.1.1 → 0.2.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

@@ -52,5 +52,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,8 @@ 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 declare const createRegistry: (modules: ModuleContract[]) => ActionRegistry;

package/dist/index.js

@@ -8,6 +8,8 @@ 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 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/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,10 @@
+export interface SpinnerOptions {
+    message?: string;
+}
+export interface Spinner {
+    start(message?: string): void;
+    stop(message?: string): void;
+    message(message: string): void;
+}
+export declare const createSpinner: (options?: SpinnerOptions) => Spinner;
+export declare const spinner: (options?: SpinnerOptions) => Spinner;

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

@@ -0,0 +1,48 @@
+import { spinner as clackSpinner } from '@clack/prompts';
+import { isInteractiveTerminal } from './readline-utils.js';
+export const createSpinner = (options = {}) => {
+    // Non-interactive fallback
+    if (!isInteractiveTerminal()) {
+        let currentMessage = options.message ?? '';
+        return {
+            start(message) {
+                currentMessage = message ?? currentMessage;
+                if (currentMessage) {
+                    process.stdout.write(`${currentMessage}...\n`);
+                }
+            },
+            stop(message) {
+                if (message) {
+                    process.stdout.write(`${message}\n`);
+                }
+            },
+            message(newMessage) {
+                currentMessage = newMessage;
+            }
+        };
+    }
+    // Interactive spinner using @clack/prompts
+    const internalSpinner = clackSpinner();
+    return {
+        start(message) {
+            if (message) {
+                internalSpinner.start(message);
+            }
+            else if (options.message) {
+                internalSpinner.start(options.message);
+            }
+        },
+        stop(message) {
+            if (message) {
+                internalSpinner.stop(message);
+            }
+            else {
+                internalSpinner.stop();
+            }
+        },
+        message(newMessage) {
+            internalSpinner.message(newMessage);
+        }
+    };
+};
+export const spinner = createSpinner;

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

@@ -0,0 +1,9 @@
+export interface Task {
+    title: string;
+    task: (message: (msg: string) => void) => Promise<string>;
+}
+export interface TasksOptions {
+    /** Called when a task is cancelled */
+    onCancel?: (results: Record<string, string>) => void;
+}
+export declare const tasks: (taskList: Task[], options?: TasksOptions) => Promise<Record<string, string>>;

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

@@ -0,0 +1,31 @@
+import { isInteractiveTerminal } from './readline-utils.js';
+export const tasks = async (taskList, options = {}) => {
+    const results = {};
+    if (!isInteractiveTerminal()) {
+        // Non-interactive: just run tasks without spinner
+        for (const taskItem of taskList) {
+            try {
+                const result = await taskItem.task(() => { });
+                results[taskItem.title] = result;
+                process.stdout.write(`${taskItem.title}: ${result}\n`);
+            }
+            catch (error) {
+                results[taskItem.title] = error instanceof Error ? error.message : String(error);
+            }
+        }
+        return results;
+    }
+    // Import clack dynamically for interactive mode
+    const { tasks: clackTasks } = await import('@clack/prompts');
+    // Wrap tasks to collect results
+    const wrappedTasks = taskList.map((task) => ({
+        ...task,
+        task: async (message) => {
+            const result = await task.task(message);
+            results[task.title] = result;
+            return result;
+        }
+    }));
+    await clackTasks(wrappedTasks, options);
+    return results;
+};