@build-astron-co/nimbus 0.2.0 → 0.4.0

package/dist/src/wizard/ui.js

@@ -0,0 +1,453 @@
+/**
+ * CLI UI Components
+ *
+ * Provides styled output utilities for the interactive wizard
+ */
+// ANSI color codes
+const colors = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    italic: '\x1b[3m',
+    underline: '\x1b[4m',
+    // Foreground colors
+    black: '\x1b[30m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    white: '\x1b[37m',
+    gray: '\x1b[90m',
+    // Bright foreground colors
+    brightRed: '\x1b[91m',
+    brightGreen: '\x1b[92m',
+    brightYellow: '\x1b[93m',
+    brightBlue: '\x1b[94m',
+    brightMagenta: '\x1b[95m',
+    brightCyan: '\x1b[96m',
+    brightWhite: '\x1b[97m',
+    // Background colors
+    bgRed: '\x1b[41m',
+    bgGreen: '\x1b[42m',
+    bgYellow: '\x1b[43m',
+    bgBlue: '\x1b[44m',
+};
+// Box drawing characters
+const boxChars = {
+    single: {
+        topLeft: '┌',
+        topRight: '┐',
+        bottomLeft: '└',
+        bottomRight: '┘',
+        horizontal: '─',
+        vertical: '│',
+        teeLeft: '├',
+        teeRight: '┤',
+        teeTop: '┬',
+        teeBottom: '┴',
+        cross: '┼',
+    },
+    double: {
+        topLeft: '╔',
+        topRight: '╗',
+        bottomLeft: '╚',
+        bottomRight: '╝',
+        horizontal: '═',
+        vertical: '║',
+        teeLeft: '╠',
+        teeRight: '╣',
+        teeTop: '╦',
+        teeBottom: '╩',
+        cross: '╬',
+    },
+    rounded: {
+        topLeft: '╭',
+        topRight: '╮',
+        bottomLeft: '╰',
+        bottomRight: '╯',
+        horizontal: '─',
+        vertical: '│',
+        teeLeft: '├',
+        teeRight: '┤',
+        teeTop: '┬',
+        teeBottom: '┴',
+        cross: '┼',
+    },
+    heavy: {
+        topLeft: '┏',
+        topRight: '┓',
+        bottomLeft: '┗',
+        bottomRight: '┛',
+        horizontal: '━',
+        vertical: '┃',
+        teeLeft: '┣',
+        teeRight: '┫',
+        teeTop: '┳',
+        teeBottom: '┻',
+        cross: '╋',
+    },
+};
+/**
+ * CLI UI utilities for the wizard
+ */
+export class WizardUI {
+    terminalWidth;
+    spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    spinnerInterval;
+    constructor() {
+        this.terminalWidth = process.stdout.columns || 80;
+    }
+    // ==================== Color Helpers ====================
+    color(text, colorName) {
+        return `${colors[colorName]}${text}${colors.reset}`;
+    }
+    bold(text) {
+        return `${colors.bold}${text}${colors.reset}`;
+    }
+    dim(text) {
+        return `${colors.dim}${text}${colors.reset}`;
+    }
+    // ==================== Icons ====================
+    get icons() {
+        return {
+            success: this.color('✓', 'green'),
+            error: this.color('✗', 'red'),
+            warning: this.color('⚠', 'yellow'),
+            info: this.color('ℹ', 'blue'),
+            question: this.color('?', 'cyan'),
+            pointer: this.color('❯', 'cyan'),
+            circle: '○',
+            circleFilled: '●',
+            checkbox: '☐',
+            checkboxChecked: '☑',
+            radioOn: '◉',
+            radioOff: '○',
+            arrowRight: '→',
+            arrowLeft: '←',
+            arrowUp: '↑',
+            arrowDown: '↓',
+        };
+    }
+    // ==================== Output Methods ====================
+    /**
+     * Print a line to stdout
+     */
+    print(text = '') {
+        process.stdout.write(`${text}\n`);
+    }
+    /**
+     * Print without newline
+     */
+    write(text) {
+        process.stdout.write(text);
+    }
+    /**
+     * Clear the current line
+     */
+    clearLine() {
+        process.stdout.write('\r\x1b[K');
+    }
+    /**
+     * Move cursor up n lines
+     */
+    cursorUp(n = 1) {
+        process.stdout.write(`\x1b[${n}A`);
+    }
+    /**
+     * Print a blank line
+     */
+    newLine() {
+        this.print();
+    }
+    // ==================== Message Types ====================
+    success(message) {
+        this.print(`  ${this.icons.success} ${message}`);
+    }
+    error(message) {
+        this.print(`  ${this.icons.error} ${this.color(message, 'red')}`);
+    }
+    warning(message) {
+        this.print(`  ${this.icons.warning} ${this.color(message, 'yellow')}`);
+    }
+    info(message) {
+        this.print(`  ${this.icons.info} ${message}`);
+    }
+    // ==================== Box Drawing ====================
+    /**
+     * Draw a box around content
+     */
+    box(config) {
+        const chars = boxChars[config.style || 'rounded'];
+        const padding = config.padding ?? 1;
+        const width = config.width || this.terminalWidth - 4;
+        const innerWidth = width - 2;
+        const lines = Array.isArray(config.content) ? config.content : config.content.split('\n');
+        // Top border
+        let topBorder = chars.topLeft + chars.horizontal.repeat(innerWidth) + chars.topRight;
+        if (config.title) {
+            const titleText = ` ${config.title} `;
+            const titleStart = Math.floor((innerWidth - titleText.length) / 2);
+            topBorder =
+                chars.topLeft +
+                    chars.horizontal.repeat(titleStart) +
+                    (config.titleColor ? this.color(titleText, config.titleColor) : titleText) +
+                    chars.horizontal.repeat(innerWidth - titleStart - titleText.length) +
+                    chars.topRight;
+        }
+        this.print(config.borderColor ? this.color(topBorder, config.borderColor) : topBorder);
+        // Padding top
+        for (let i = 0; i < padding; i++) {
+            this.print((config.borderColor
+                ? this.color(chars.vertical, config.borderColor)
+                : chars.vertical) +
+                ' '.repeat(innerWidth) +
+                (config.borderColor
+                    ? this.color(chars.vertical, config.borderColor)
+                    : chars.vertical));
+        }
+        // Content
+        for (const line of lines) {
+            const paddedLine = ' '.repeat(padding) +
+                line +
+                ' '.repeat(Math.max(0, innerWidth - padding * 2 - line.length));
+            this.print((config.borderColor
+                ? this.color(chars.vertical, config.borderColor)
+                : chars.vertical) +
+                paddedLine.substring(0, innerWidth) +
+                (config.borderColor
+                    ? this.color(chars.vertical, config.borderColor)
+                    : chars.vertical));
+        }
+        // Padding bottom
+        for (let i = 0; i < padding; i++) {
+            this.print((config.borderColor
+                ? this.color(chars.vertical, config.borderColor)
+                : chars.vertical) +
+                ' '.repeat(innerWidth) +
+                (config.borderColor
+                    ? this.color(chars.vertical, config.borderColor)
+                    : chars.vertical));
+        }
+        // Bottom border
+        const bottomBorder = chars.bottomLeft + chars.horizontal.repeat(innerWidth) + chars.bottomRight;
+        this.print(config.borderColor ? this.color(bottomBorder, config.borderColor) : bottomBorder);
+    }
+    /**
+     * Draw a header box for the wizard
+     */
+    header(title, subtitle) {
+        const content = subtitle ? [title, this.dim(subtitle)] : [title];
+        this.box({
+            content,
+            style: 'rounded',
+            borderColor: 'cyan',
+            padding: 1,
+        });
+        this.newLine();
+    }
+    // ==================== Table ====================
+    /**
+     * Draw a table
+     */
+    table(config) {
+        const _chars = boxChars.single;
+        const colWidths = [];
+        // Calculate column widths
+        for (const col of config.columns) {
+            let maxWidth = col.header.length;
+            for (const row of config.data) {
+                const value = String(row[col.key] ?? '');
+                maxWidth = Math.max(maxWidth, value.length);
+            }
+            colWidths.push(col.width || Math.min(maxWidth + 2, 40));
+        }
+        // Draw header
+        const headerRow = config.columns
+            .map((col, i) => {
+            const text = col.header.padEnd(colWidths[i]);
+            return this.bold(text);
+        })
+            .join(' │ ');
+        const separator = colWidths.map(w => '─'.repeat(w)).join('─┼─');
+        if (config.title) {
+            this.print(this.bold(config.title));
+        }
+        this.print(`┌─${colWidths.map(w => '─'.repeat(w)).join('─┬─')}─┐`);
+        this.print(`│ ${headerRow} │`);
+        this.print(`├─${separator}─┤`);
+        // Draw rows
+        for (let i = 0; i < config.data.length; i++) {
+            const row = config.data[i];
+            const cells = config.columns.map((col, j) => {
+                let value = row[col.key];
+                if (col.formatter) {
+                    value = col.formatter(value);
+                }
+                const text = String(value ?? '').padEnd(colWidths[j]);
+                return text;
+            });
+            const prefix = config.showRowNumbers ? `${(i + 1).toString().padStart(3)}. ` : '';
+            this.print(`│ ${prefix}${cells.join(' │ ')} │`);
+        }
+        this.print(`└─${colWidths.map(w => '─'.repeat(w)).join('─┴─')}─┘`);
+    }
+    // ==================== Progress ====================
+    /**
+     * Draw a progress bar
+     */
+    progressBar(current, total, config) {
+        const barWidth = 40;
+        const percentage = Math.round((current / total) * 100);
+        const filled = Math.round((current / total) * barWidth);
+        const empty = barWidth - filled;
+        const bar = this.color('█'.repeat(filled), 'green') + this.dim('░'.repeat(empty));
+        const status = config.showPercentage ? ` ${percentage}%` : ` ${current}/${total}`;
+        this.clearLine();
+        this.write(`  ${config.message} ${bar}${status}`);
+    }
+    /**
+     * Complete progress bar
+     */
+    progressComplete(message) {
+        this.clearLine();
+        this.print(`  ${this.icons.success} ${message}`);
+    }
+    // ==================== Spinner ====================
+    /**
+     * Start a spinner
+     */
+    startSpinner(config) {
+        let frameIndex = 0;
+        this.spinnerInterval = setInterval(() => {
+            const frame = this.color(this.spinnerFrames[frameIndex], 'cyan');
+            this.clearLine();
+            this.write(`  ${frame} ${config.message}`);
+            frameIndex = (frameIndex + 1) % this.spinnerFrames.length;
+        }, 80);
+    }
+    /**
+     * Update spinner message
+     */
+    updateSpinner(message) {
+        // The spinner loop will pick up the new message
+        // For now, just update the display
+        if (this.spinnerInterval) {
+            this.clearLine();
+            const frame = this.color(this.spinnerFrames[0], 'cyan');
+            this.write(`  ${frame} ${message}`);
+        }
+    }
+    /**
+     * Stop spinner with success
+     */
+    stopSpinnerSuccess(message) {
+        if (this.spinnerInterval) {
+            clearInterval(this.spinnerInterval);
+            this.spinnerInterval = undefined;
+        }
+        this.clearLine();
+        this.print(`  ${this.icons.success} ${message}`);
+    }
+    /**
+     * Stop spinner with failure
+     */
+    stopSpinnerFail(message) {
+        if (this.spinnerInterval) {
+            clearInterval(this.spinnerInterval);
+            this.spinnerInterval = undefined;
+        }
+        this.clearLine();
+        this.print(`  ${this.icons.error} ${this.color(message, 'red')}`);
+    }
+    // ==================== Diff Display ====================
+    /**
+     * Display a side-by-side diff
+     */
+    sideBySideDiff(config) {
+        const halfWidth = Math.floor((this.terminalWidth - 3) / 2);
+        const chars = boxChars.single;
+        const originalLines = config.original.split('\n');
+        const modifiedLines = config.modified.split('\n');
+        const maxLines = Math.max(originalLines.length, modifiedLines.length);
+        if (config.title) {
+            this.print(this.bold(config.title));
+        }
+        // Header
+        this.print(chars.topLeft +
+            chars.horizontal.repeat(halfWidth) +
+            chars.teeTop +
+            chars.horizontal.repeat(halfWidth) +
+            chars.topRight);
+        const leftHeader = ' CURRENT CODE'.padEnd(halfWidth);
+        const rightHeader = ' SUGGESTED IMPROVEMENTS'.padEnd(halfWidth);
+        this.print(chars.vertical +
+            this.color(leftHeader, 'yellow') +
+            chars.vertical +
+            this.color(rightHeader, 'green') +
+            chars.vertical);
+        this.print(chars.teeLeft +
+            chars.horizontal.repeat(halfWidth) +
+            chars.cross +
+            chars.horizontal.repeat(halfWidth) +
+            chars.teeRight);
+        // Content
+        for (let i = 0; i < maxLines; i++) {
+            const leftLine = (originalLines[i] || '').substring(0, halfWidth - 2).padEnd(halfWidth);
+            const rightLine = (modifiedLines[i] || '').substring(0, halfWidth - 2).padEnd(halfWidth);
+            const isDifferent = originalLines[i] !== modifiedLines[i];
+            this.print(chars.vertical +
+                (isDifferent ? this.color(leftLine, 'red') : leftLine) +
+                chars.vertical +
+                (isDifferent ? this.color(rightLine, 'green') : rightLine) +
+                chars.vertical);
+        }
+        // Footer
+        this.print(chars.bottomLeft +
+            chars.horizontal.repeat(halfWidth) +
+            chars.teeBottom +
+            chars.horizontal.repeat(halfWidth) +
+            chars.bottomRight);
+    }
+    // ==================== Selection Display ====================
+    /**
+     * Display options (for reference, actual selection uses readline)
+     */
+    displayOptions(options, selectedIndex) {
+        for (let i = 0; i < options.length; i++) {
+            const opt = options[i];
+            const isSelected = i === selectedIndex;
+            const prefix = isSelected ? this.icons.pointer : ' ';
+            const icon = isSelected ? this.icons.radioOn : this.icons.radioOff;
+            let line = `  ${prefix} ${icon} ${opt.label}`;
+            if (opt.disabled) {
+                line = this.dim(`${line} (${opt.disabledReason || 'unavailable'})`);
+            }
+            else if (isSelected) {
+                line = this.color(line, 'cyan');
+            }
+            this.print(line);
+            if (opt.description && isSelected) {
+                this.print(this.dim(`      ${opt.description}`));
+            }
+        }
+    }
+    // ==================== Dividers ====================
+    /**
+     * Print a horizontal divider
+     */
+    divider(char = '─') {
+        this.print(this.dim(char.repeat(this.terminalWidth)));
+    }
+    /**
+     * Print a section header
+     */
+    section(title) {
+        this.newLine();
+        this.print(this.bold(this.color(title, 'cyan')));
+        this.divider();
+    }
+}
+// Export singleton instance
+export const ui = new WizardUI();

package/dist/src/wizard/wizard.js

@@ -0,0 +1,227 @@
+/**
+ * Interactive Wizard Framework
+ *
+ * Provides a step-based wizard system for complex CLI workflows
+ */
+import { ui } from './ui';
+/**
+ * Interactive Wizard for guiding users through multi-step processes
+ */
+export class Wizard {
+    config;
+    context;
+    completedSteps = [];
+    cancelled = false;
+    stepHistory = [];
+    contextSnapshots = new Map();
+    currentStepIndex = 0;
+    constructor(config) {
+        this.config = config;
+        this.context = { ...config.initialContext };
+    }
+    /**
+     * Run the wizard
+     */
+    async run() {
+        this.emit({ type: 'wizard:start' });
+        try {
+            // Display header
+            ui.header(this.config.title, this.config.description);
+            const steps = this.config.steps;
+            this.currentStepIndex = 0;
+            while (this.currentStepIndex < steps.length) {
+                if (this.cancelled) {
+                    break;
+                }
+                const step = steps[this.currentStepIndex];
+                // Check step condition
+                if (step.condition && !step.condition(this.context)) {
+                    this.currentStepIndex++;
+                    continue;
+                }
+                // Save context snapshot before executing step (for back navigation)
+                this.contextSnapshots.set(this.currentStepIndex, { ...this.context });
+                // Execute step
+                const result = await this.runStep(step);
+                if (!result.success) {
+                    if (step.canSkip) {
+                        ui.warning(`Skipping step: ${step.title}`);
+                        this.currentStepIndex++;
+                        continue;
+                    }
+                    throw new Error(result.error || `Step "${step.title}" failed`);
+                }
+                // Merge step data into context
+                if (result.data) {
+                    this.context = { ...this.context, ...result.data };
+                }
+                this.completedSteps.push(step.id);
+                this.stepHistory.push(this.currentStepIndex);
+                // Handle step navigation
+                if (result.skipRemaining) {
+                    break;
+                }
+                if (result.nextStep) {
+                    // Jump to specific step by id
+                    const targetIdx = steps.findIndex(s => s.id === result.nextStep);
+                    if (targetIdx >= 0) {
+                        this.currentStepIndex = targetIdx;
+                        continue;
+                    }
+                }
+                this.currentStepIndex++;
+            }
+            if (this.cancelled) {
+                this.emit({ type: 'wizard:cancel' });
+                return {
+                    success: false,
+                    context: this.context,
+                    completedSteps: this.completedSteps,
+                    error: new Error('Wizard cancelled by user'),
+                };
+            }
+            this.emit({ type: 'wizard:complete', context: this.context });
+            return {
+                success: true,
+                context: this.context,
+                completedSteps: this.completedSteps,
+            };
+        }
+        catch (error) {
+            this.emit({ type: 'wizard:error', error });
+            return {
+                success: false,
+                context: this.context,
+                completedSteps: this.completedSteps,
+                error,
+            };
+        }
+    }
+    /**
+     * Run a single step
+     */
+    async runStep(step) {
+        this.emit({ type: 'step:start', stepId: step.id });
+        // Display step header
+        ui.section(step.title);
+        if (step.description) {
+            ui.print(ui.dim(`  ${step.description}`));
+            ui.newLine();
+        }
+        try {
+            const result = await step.execute(this.context);
+            if (result.success) {
+                this.emit({ type: 'step:complete', stepId: step.id, result });
+            }
+            else {
+                this.emit({
+                    type: 'step:error',
+                    stepId: step.id,
+                    error: new Error(result.error || 'Step failed'),
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            this.emit({ type: 'step:error', stepId: step.id, error });
+            return {
+                success: false,
+                error: error.message,
+            };
+        }
+    }
+    /**
+     * Cancel the wizard
+     */
+    cancel() {
+        this.cancelled = true;
+    }
+    /**
+     * Get current context
+     */
+    getContext() {
+        return { ...this.context };
+    }
+    /**
+     * Update context manually
+     */
+    updateContext(update) {
+        this.context = { ...this.context, ...update };
+    }
+    /**
+     * Go back to the previous step, restoring its context snapshot.
+     * Returns true if navigation succeeded, false if there is no previous step.
+     */
+    goBack() {
+        if (this.stepHistory.length === 0) {
+            return false;
+        }
+        const previousIndex = this.stepHistory.pop();
+        // Restore context snapshot from before the previous step executed
+        const snapshot = this.contextSnapshots.get(previousIndex);
+        if (snapshot) {
+            this.context = { ...snapshot };
+        }
+        // Remove the step from completed steps
+        const step = this.config.steps[previousIndex];
+        const completedIdx = this.completedSteps.lastIndexOf(step.id);
+        if (completedIdx >= 0) {
+            this.completedSteps.splice(completedIdx, 1);
+        }
+        this.currentStepIndex = previousIndex;
+        return true;
+    }
+    /**
+     * Check if back navigation is possible
+     */
+    canGoBack() {
+        return this.stepHistory.length > 0;
+    }
+    /**
+     * Get the current step index (zero-based)
+     */
+    getCurrentStepIndex() {
+        return this.currentStepIndex;
+    }
+    /**
+     * Emit an event
+     */
+    emit(event) {
+        this.config.onEvent?.(event);
+    }
+}
+/**
+ * Create a wizard with the given configuration
+ */
+export function createWizard(config) {
+    return new Wizard(config);
+}
+/**
+ * Step builder helpers
+ */
+export const stepBuilders = {
+    /**
+     * Create a simple step
+     */
+    simple(id, title, execute) {
+        return { id, title, execute };
+    },
+    /**
+     * Create a step with description
+     */
+    withDescription(id, title, description, execute) {
+        return { id, title, description, execute };
+    },
+    /**
+     * Create a conditional step
+     */
+    conditional(id, title, condition, execute) {
+        return { id, title, condition, execute };
+    },
+    /**
+     * Create a skippable step
+     */
+    skippable(id, title, execute) {
+        return { id, title, canSkip: true, execute };
+    },
+};