@dsai-io/tools 0.0.1

package/dist/cli/index.d.ts

@@ -0,0 +1,432 @@
+import { Command } from 'commander';
+
+/**
+ * CLI type definitions
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/cli/types
+ */
+/**
+ * Exit codes for CLI commands
+ *
+ * Follows common conventions:
+ * - 0: Success
+ * - 1: General error
+ * - 2+: Specific error types
+ */
+declare const ExitCode: {
+    /** Successful execution */
+    readonly Success: 0;
+    /** General/unknown error */
+    readonly GeneralError: 1;
+    /** Configuration loading or validation error */
+    readonly ConfigError: 2;
+    /** Token or schema validation error */
+    readonly ValidationError: 3;
+    /** Build process error */
+    readonly BuildError: 4;
+    /** File system I/O error */
+    readonly IOError: 5;
+};
+/**
+ * Global CLI options available to all commands
+ */
+interface GlobalOptions {
+    /** Custom config file path */
+    config?: string;
+    /** Working directory */
+    cwd?: string;
+    /** Enable debug mode - verbose output and stack traces */
+    debug?: boolean;
+    /** Quiet mode - no spinners or colors */
+    quiet?: boolean;
+    /** Dry run - preview changes without writing files */
+    dryRun?: boolean;
+}
+/**
+ * Token build command options
+ */
+interface TokensBuildOptions extends GlobalOptions {
+    /** Platforms to build (comma-separated or 'all') */
+    platforms?: string;
+    /** Watch mode - rebuild on file changes */
+    watch?: boolean;
+    /** Clean output directory before build */
+    clean?: boolean;
+}
+/**
+ * Token validate command options
+ */
+interface TokensValidateOptions extends GlobalOptions {
+    /** Attempt to fix issues automatically */
+    fix?: boolean;
+    /** Strict validation mode */
+    strict?: boolean;
+}
+/**
+ * Token sync command options
+ */
+interface TokensSyncOptions extends GlobalOptions {
+    /** Output format for sync */
+    format?: 'flat' | 'nested';
+}
+/**
+ * Icons build command options
+ */
+interface IconsBuildOptions extends GlobalOptions {
+    /** Output format for icons */
+    format?: 'svg' | 'react' | 'vue';
+    /** Optimize SVGs */
+    optimize?: boolean;
+}
+/**
+ * Init command options
+ */
+interface InitOptions extends GlobalOptions {
+    /** Skip prompts, use defaults */
+    yes?: boolean;
+    /** Template to use */
+    template?: 'minimal' | 'full' | 'enterprise';
+}
+/**
+ * Logger interface for CLI output
+ */
+interface Logger {
+    /** Log a general message */
+    log(message: string): void;
+    /** Log an info message with icon */
+    info(message: string): void;
+    /** Log a success message with icon */
+    success(message: string): void;
+    /** Log a warning message with icon */
+    warn(message: string): void;
+    /** Log an error message with icon */
+    error(message: string): void;
+    /** Log a debug message (only in debug mode) */
+    debug(message: string): void;
+}
+/**
+ * Spinner interface for progress indication
+ */
+interface Spinner {
+    /** Start spinner with text */
+    start(text: string): void;
+    /** Stop spinner (optionally update text) */
+    stop(text?: string): void;
+    /** Stop with success state */
+    succeed(text?: string): void;
+    /** Stop with failure state */
+    fail(text?: string): void;
+    /** Stop with warning state */
+    warn(text?: string): void;
+    /** Stop with info state */
+    info(text?: string): void;
+}
+/**
+ * CLI context passed to commands
+ *
+ * Contains resolved values and utility instances
+ */
+interface CLIContext {
+    /** Resolved working directory (absolute path) */
+    cwd: string;
+    /** Package version */
+    version: string;
+    /** Debug mode enabled */
+    debug: boolean;
+    /** Quiet mode enabled */
+    quiet: boolean;
+    /** Logger instance */
+    logger: Logger;
+    /** Spinner instance */
+    spinner: Spinner;
+}
+/**
+ * Generic command handler function
+ */
+type CommandHandler<T extends GlobalOptions = GlobalOptions> = (options: T, context: CLIContext) => Promise<void>;
+/**
+ * Build result from token operations
+ */
+interface BuildResult {
+    /** Whether build succeeded */
+    success: boolean;
+    /** Number of files written */
+    filesWritten: number;
+    /** List of output files */
+    files?: Array<{
+        path: string;
+        size?: number;
+    }>;
+    /** Any errors encountered */
+    errors?: Array<{
+        message: string;
+        file?: string;
+    }>;
+}
+/**
+ * Validation result from token validation
+ */
+interface ValidationResult {
+    /** Total number of tokens validated */
+    totalTokens: number;
+    /** Validation errors */
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+    /** Validation warnings */
+    warnings: Array<{
+        path: string;
+        message: string;
+    }>;
+    /** Issues that were automatically fixed */
+    fixed: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+/**
+ * Sync result from token sync
+ */
+interface SyncResult {
+    /** Whether sync succeeded */
+    success: boolean;
+    /** Number of tokens synced */
+    tokenCount: number;
+    /** Output file path */
+    outputPath: string;
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Color utilities for CLI output
+ *
+ * Wraps picocolors with NO_COLOR environment variable support.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/cli/ui/colors
+ */
+/**
+ * Color utilities with NO_COLOR support
+ *
+ * @example
+ * ```typescript
+ * import { colors } from './colors.js';
+ *
+ * console.log(colors.success('Build complete!'));
+ * console.log(colors.error('Something went wrong'));
+ * console.log(colors.path('./dist/tokens.css'));
+ * ```
+ */
+declare const colors: {
+    /** Red text */
+    red: (text: string) => string;
+    /** Green text */
+    green: (text: string) => string;
+    /** Yellow text */
+    yellow: (text: string) => string;
+    /** Blue text */
+    blue: (text: string) => string;
+    /** Magenta text */
+    magenta: (text: string) => string;
+    /** Cyan text */
+    cyan: (text: string) => string;
+    /** Gray/dim text */
+    gray: (text: string) => string;
+    /** White text */
+    white: (text: string) => string;
+    /** Bold text */
+    bold: (text: string) => string;
+    /** Dim text */
+    dim: (text: string) => string;
+    /** Italic text */
+    italic: (text: string) => string;
+    /** Underlined text */
+    underline: (text: string) => string;
+    /** Red background */
+    bgRed: (text: string) => string;
+    /** Green background */
+    bgGreen: (text: string) => string;
+    /** Yellow background */
+    bgYellow: (text: string) => string;
+    /** Blue background */
+    bgBlue: (text: string) => string;
+    /** Error messages - red */
+    error: (text: string) => string;
+    /** Success messages - green */
+    success: (text: string) => string;
+    /** Warning messages - yellow */
+    warning: (text: string) => string;
+    /** Info messages - blue */
+    info: (text: string) => string;
+    /** Muted/secondary text - gray */
+    muted: (text: string) => string;
+    /** Labels - bold cyan */
+    label: (text: string) => string;
+    /** Values - yellow */
+    value: (text: string) => string;
+    /** File paths - underlined cyan */
+    path: (text: string) => string;
+    /** Commands - bold green */
+    command: (text: string) => string;
+    /** Code snippets - dim */
+    code: (text: string) => string;
+    /** Highlight - bold yellow */
+    highlight: (text: string) => string;
+};
+
+/**
+ * Spinner utilities for CLI progress indication
+ *
+ * Wraps ora for consistent spinner behavior with quiet mode support.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/cli/ui/spinner
+ */
+
+/**
+ * Create a spinner instance
+ *
+ * In quiet mode, returns a no-op spinner that does nothing.
+ *
+ * @param quiet - If true, spinner is disabled (no-op)
+ * @returns Spinner instance
+ *
+ * @example
+ * ```typescript
+ * const spinner = createSpinner(false);
+ * spinner.start('Loading configuration...');
+ * // ... do work
+ * spinner.succeed('Configuration loaded!');
+ * ```
+ */
+declare function createSpinner(quiet?: boolean): Spinner;
+
+/**
+ * Logger utilities for CLI output
+ *
+ * Provides consistent logging with icons, colors, and quiet/debug mode support.
+ *
+ * @packageDocumentation
+ * @module @dsai-io/tools/cli/ui/logger
+ */
+
+/**
+ * Logger creation options
+ */
+interface LoggerOptions {
+    /** Quiet mode - minimal output */
+    quiet?: boolean;
+    /** Debug mode - verbose output */
+    debug?: boolean;
+    /** Custom prefix for messages */
+    prefix?: string;
+}
+/**
+ * Create a logger instance
+ *
+ * @param options - Logger options
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ debug: true });
+ * logger.info('Starting build...');
+ * logger.success('Build complete!');
+ * logger.debug('Token count: 123'); // Only shown in debug mode
+ * ```
+ */
+declare function createLogger(options?: LoggerOptions): Logger;
+/**
+ * Format a duration in milliseconds to human-readable string
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted duration string
+ *
+ * @example
+ * ```typescript
+ * formatDuration(500);   // '500ms'
+ * formatDuration(2500);  // '2.50s'
+ * formatDuration(65000); // '1m 5s'
+ * ```
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Format bytes to human-readable string
+ *
+ * @param bytes - Number of bytes
+ * @returns Formatted size string
+ *
+ * @example
+ * ```typescript
+ * formatBytes(0);       // '0 B'
+ * formatBytes(1024);    // '1 KB'
+ * formatBytes(1536000); // '1.46 MB'
+ * ```
+ */
+declare function formatBytes(bytes: number): string;
+/**
+ * Format a count with singular/plural label
+ *
+ * @param count - The count
+ * @param singular - Singular form
+ * @param plural - Plural form (defaults to singular + 's')
+ * @returns Formatted string
+ *
+ * @example
+ * ```typescript
+ * formatCount(1, 'file');    // '1 file'
+ * formatCount(5, 'file');    // '5 files'
+ * formatCount(1, 'entry', 'entries'); // '1 entry'
+ * ```
+ */
+declare function formatCount(count: number, singular: string, plural?: string): string;
+
+/**
+ * CLI module for @dsai-io/tools
+ *
+ * Provides the command-line interface for the dsai-tools package.
+ * Uses Commander.js for command parsing, with spinners and colored output.
+ *
+ * Commands:
+ * - tokens: Build, validate, and sync design tokens
+ * - icons: Generate icon components from SVG files
+ * - init: Initialize configuration in a project
+ * - config: Display resolved configuration
+ *
+ * @example
+ * ```bash
+ * # Build tokens
+ * dsai tokens build
+ *
+ * # Validate tokens
+ * dsai tokens validate
+ *
+ * # Initialize a new project
+ * dsai init --template full
+ *
+ * # Show configuration
+ * dsai config --json
+ * ```
+ */
+
+/**
+ * Configure and run the CLI
+ *
+ * Sets up the Commander program with all commands and parses arguments.
+ *
+ * @param args - Command line arguments (defaults to process.argv)
+ */
+declare function run(args?: string[]): Promise<void>;
+/**
+ * Get the CLI program instance
+ *
+ * Used for testing to access the configured Commander program.
+ *
+ * @returns The Commander program instance
+ */
+declare function getProgram(): Command;
+
+export { type BuildResult, type CLIContext, type CommandHandler, ExitCode, type GlobalOptions, type IconsBuildOptions, type InitOptions, type Logger, type Spinner, type SyncResult, type TokensBuildOptions, type TokensSyncOptions, type TokensValidateOptions, type ValidationResult, colors, createLogger, createSpinner, formatBytes, formatCount, formatDuration, getProgram, run };