@revealui/mcp 0.0.1-pre.0 → 0.1.0

package/dist/scripts/lib/args.js

@@ -0,0 +1,304 @@
+/**
+ * Lightweight Argument Parser
+ *
+ * Type-safe argument parsing for CLI scripts with support for
+ * positional args, flags, and auto-generated help text.
+ *
+ * @dependencies
+ * - scripts/lib/errors.ts - ErrorCode enum and ScriptError class
+ *
+ * @example
+ * ```typescript
+ * const parser = defineArgs({
+ *   name: 'workflow',
+ *   description: 'Workflow management CLI',
+ *   args: [
+ *     { name: 'json', short: 'j', type: 'boolean', description: 'Output JSON' },
+ *     { name: 'id', short: 'i', type: 'string', description: 'Workflow ID' },
+ *   ],
+ *   commands: ['status', 'list', 'create', 'delete'],
+ * })
+ *
+ * const args = parseArgs(process.argv.slice(2), parser)
+ * // args.command: 'status' | 'list' | ...
+ * // args.flags.json: boolean
+ * // args.flags.id: string | undefined
+ * // args.positional: string[]
+ * ```
+ */
+import { ErrorCode, ScriptError } from './errors.js';
+// =============================================================================
+// Parser Implementation
+// =============================================================================
+/**
+ * Define an argument parser configuration
+ */
+export function defineArgs(config) {
+    return {
+        config,
+        parse: (argv) => parseArgs(argv, config),
+        generateHelp: (command) => generateHelp(config, command),
+    };
+}
+/**
+ * Parse command-line arguments
+ */
+export function parseArgs(argv, config) {
+    const result = {
+        command: undefined,
+        positional: [],
+        flags: {},
+        help: false,
+        _raw: argv,
+    };
+    // Build lookup maps for flags
+    const argsByName = new Map();
+    const argsByShort = new Map();
+    const commands = new Set(config.commands?.map((c) => c.name) ?? []);
+    // Add global args
+    for (const arg of config.args ?? []) {
+        argsByName.set(arg.name, arg);
+        if (arg.short) {
+            argsByShort.set(arg.short, arg);
+        }
+        // Set defaults
+        if (arg.default !== undefined) {
+            result.flags[arg.name] = arg.default;
+        }
+        else if (arg.type === 'boolean') {
+            result.flags[arg.name] = false;
+        }
+    }
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        // Check for help flags
+        if (token === '--help' || token === '-h') {
+            result.help = true;
+            i++;
+            continue;
+        }
+        // Long flag: --name or --name=value
+        if (token.startsWith('--')) {
+            const eqIndex = token.indexOf('=');
+            let name;
+            let value;
+            if (eqIndex !== -1) {
+                name = token.slice(2, eqIndex);
+                value = token.slice(eqIndex + 1);
+            }
+            else {
+                name = token.slice(2);
+            }
+            const argDef = argsByName.get(name);
+            if (argDef) {
+                result.flags[name] = parseValue(argDef, value, argv, i);
+                if (argDef.type !== 'boolean' && value === undefined) {
+                    i++; // Skip next token (consumed as value)
+                }
+            }
+            else {
+                // Unknown flag - store as string
+                if (value !== undefined) {
+                    result.flags[name] = value;
+                }
+                else if (argv[i + 1] && !argv[i + 1].startsWith('-')) {
+                    result.flags[name] = argv[++i];
+                }
+                else {
+                    result.flags[name] = true;
+                }
+            }
+            i++;
+            continue;
+        }
+        // Short flag: -j or -i value
+        if (token.startsWith('-') && token.length > 1) {
+            const short = token.slice(1);
+            // Handle combined short flags like -jv
+            if (short.length > 1 && !argsByShort.has(short)) {
+                for (const char of short) {
+                    const argDef = argsByShort.get(char);
+                    if (argDef && argDef.type === 'boolean') {
+                        result.flags[argDef.name] = true;
+                    }
+                }
+                i++;
+                continue;
+            }
+            const argDef = argsByShort.get(short);
+            if (argDef) {
+                result.flags[argDef.name] = parseValue(argDef, undefined, argv, i);
+                if (argDef.type !== 'boolean') {
+                    i++; // Skip next token (consumed as value)
+                }
+            }
+            else {
+                // Unknown short flag
+                if (argv[i + 1] && !argv[i + 1].startsWith('-')) {
+                    result.flags[short] = argv[++i];
+                }
+                else {
+                    result.flags[short] = true;
+                }
+            }
+            i++;
+            continue;
+        }
+        // Positional argument
+        if (result.command === undefined && commands.has(token)) {
+            // First positional matches a command
+            result.command = token;
+            // Add command-specific args to lookup
+            const commandDef = config.commands?.find((c) => c.name === token);
+            if (commandDef?.args) {
+                for (const arg of commandDef.args) {
+                    argsByName.set(arg.name, arg);
+                    if (arg.short) {
+                        argsByShort.set(arg.short, arg);
+                    }
+                    if (arg.default !== undefined) {
+                        result.flags[arg.name] = arg.default;
+                    }
+                    else if (arg.type === 'boolean') {
+                        result.flags[arg.name] = false;
+                    }
+                }
+            }
+        }
+        else {
+            result.positional.push(token);
+        }
+        i++;
+    }
+    return result;
+}
+/**
+ * Parse a value based on argument type
+ */
+function parseValue(argDef, inlineValue, argv, currentIndex) {
+    if (argDef.type === 'boolean') {
+        if (inlineValue !== undefined) {
+            return inlineValue.toLowerCase() === 'true' || inlineValue === '1';
+        }
+        return true;
+    }
+    const value = inlineValue ?? argv[currentIndex + 1];
+    if (value === undefined || value.startsWith('-')) {
+        if (argDef.required) {
+            throw new ScriptError(`Argument --${argDef.name} requires a value`, ErrorCode.VALIDATION_ERROR);
+        }
+        return argDef.default;
+    }
+    if (argDef.type === 'number') {
+        const num = Number(value);
+        if (Number.isNaN(num)) {
+            throw new ScriptError(`Argument --${argDef.name} must be a number, got: ${value}`, ErrorCode.VALIDATION_ERROR);
+        }
+        return num;
+    }
+    return value;
+}
+// =============================================================================
+// Help Generation
+// =============================================================================
+/**
+ * Generate help text for the CLI
+ */
+export function generateHelp(config, command) {
+    const lines = [];
+    // Header
+    lines.push(config.name);
+    lines.push('');
+    lines.push(config.description);
+    lines.push('');
+    // Usage
+    const positionalStr = config.positionalNames?.map((n) => `<${n}>`).join(' ') ?? '';
+    if (config.commands?.length) {
+        lines.push('Usage:');
+        lines.push(`  ${config.name} <command> [options] ${positionalStr}`);
+        lines.push('');
+    }
+    else {
+        lines.push('Usage:');
+        lines.push(`  ${config.name} [options] ${positionalStr}`);
+        lines.push('');
+    }
+    // Commands
+    if (config.commands?.length && !command) {
+        lines.push('Commands:');
+        const maxLen = Math.max(...config.commands.map((c) => c.name.length));
+        for (const cmd of config.commands) {
+            lines.push(`  ${cmd.name.padEnd(maxLen + 2)} ${cmd.description}`);
+        }
+        lines.push('');
+    }
+    // Command-specific help
+    if (command) {
+        const cmdDef = config.commands?.find((c) => c.name === command);
+        if (cmdDef) {
+            lines.push(`Command: ${command}`);
+            lines.push(`  ${cmdDef.description}`);
+            lines.push('');
+            if (cmdDef.args?.length) {
+                lines.push('Command Options:');
+                lines.push(...formatArgs(cmdDef.args));
+                lines.push('');
+            }
+        }
+    }
+    // Global options
+    if (config.args?.length) {
+        lines.push('Options:');
+        lines.push(...formatArgs(config.args));
+        lines.push('');
+    }
+    // Built-in options
+    lines.push('  -h, --help       Show this help message');
+    return lines.join('\n');
+}
+/**
+ * Format argument definitions for help text
+ */
+function formatArgs(args) {
+    const lines = [];
+    for (const arg of args) {
+        const short = arg.short ? `-${arg.short}, ` : '    ';
+        const long = `--${arg.name}`;
+        const typeHint = arg.type !== 'boolean' ? ` <${arg.type}>` : '';
+        const defaultHint = arg.default !== undefined ? ` (default: ${arg.default})` : '';
+        const requiredHint = arg.required ? ' (required)' : '';
+        lines.push(`  ${short}${long}${typeHint}${defaultHint}${requiredHint}`);
+        lines.push(`        ${arg.description}`);
+    }
+    return lines;
+}
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+/**
+ * Validate required arguments are present
+ */
+export function validateRequiredArgs(args, config) {
+    const missing = [];
+    const allArgs = [
+        ...(config.args ?? []),
+        ...(args.command ? (config.commands?.find((c) => c.name === args.command)?.args ?? []) : []),
+    ];
+    for (const arg of allArgs) {
+        if (arg.required && args.flags[arg.name] === undefined) {
+            missing.push(arg.name);
+        }
+    }
+    return { valid: missing.length === 0, missing };
+}
+/**
+ * Get a typed flag value with proper narrowing
+ */
+export function getFlag(args, name, defaultValue) {
+    const value = args.flags[name];
+    if (value === undefined)
+        return defaultValue;
+    return value;
+}
+//# sourceMappingURL=args.js.map

package/dist/scripts/lib/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../../../scripts/lib/args.ts"],"names":[],"mappings":"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"}

package/dist/scripts/lib/cache.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Build caching utilities for improved performance.
+ *
+ * Provides file-based caching with:
+ * - Content-based cache keys (hashing)
+ * - TTL (time-to-live) support
+ * - Cache statistics and metrics
+ * - Automatic cleanup of stale entries
+ *
+ * @dependencies
+ * - node:crypto - Hash generation for cache keys
+ * - node:fs/promises - File system operations for cache storage
+ * - node:path - Path manipulation utilities
+ * - fast-glob - File pattern matching for cache key generation
+ *
+ * @example
+ * ```typescript
+ * import { BuildCache } from './cache.js'
+ *
+ * const cache = new BuildCache({ ttl: 3600000 }) // 1 hour
+ *
+ * const key = await cache.getCacheKey(['src/**\/*.ts'])
+ * if (await cache.isCached(key)) {
+ *   await cache.restore(key, 'dist/')
+ * } else {
+ *   // Build...
+ *   await cache.save(key, 'dist/')
+ * }
+ *
+ * const stats = cache.getStats()
+ * console.log(`Cache hit rate: ${stats.hitRate}%`)
+ * ```
+ */
+export interface BuildCacheOptions {
+    /**
+     * Cache directory path (relative to project root)
+     * @default '.cache/build'
+     */
+    cacheDir?: string;
+    /**
+     * Time-to-live for cache entries in milliseconds
+     * @default 86400000 (24 hours)
+     */
+    ttl?: number;
+    /**
+     * Enable verbose logging
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Maximum cache size in bytes (0 = unlimited)
+     * @default 1073741824 (1 GB)
+     */
+    maxSize?: number;
+}
+export interface CacheEntry {
+    /** Cache key */
+    key: string;
+    /** Timestamp when cached */
+    timestamp: number;
+    /** Size in bytes */
+    size: number;
+    /** Original source paths */
+    sources: string[];
+    /** Cached destination path */
+    destination: string;
+}
+export interface CacheStats {
+    /** Total cache hits */
+    hits: number;
+    /** Total cache misses */
+    misses: number;
+    /** Cache hit rate percentage */
+    hitRate: number;
+    /** Total cached entries */
+    entries: number;
+    /** Total cache size in bytes */
+    totalSize: number;
+    /** Formatted cache size */
+    formattedSize: string;
+}
+/**
+ * Build cache for improved performance.
+ */
+export declare class BuildCache {
+    private cacheDir;
+    private ttl;
+    private verbose;
+    private maxSize;
+    private stats;
+    private projectRoot;
+    constructor(options?: BuildCacheOptions);
+    /**
+     * Get project root directory.
+     */
+    private getRoot;
+    /**
+     * Get absolute cache directory path.
+     */
+    private getCacheDir;
+    /**
+     * Generate cache key from file patterns.
+     *
+     * Creates a hash of file contents for content-based caching.
+     *
+     * @param patterns - Glob patterns to include
+     * @returns Cache key (SHA256 hash)
+     */
+    getCacheKey(patterns: string[]): Promise<string>;
+    /**
+     * Check if cache entry exists and is valid.
+     *
+     * @param key - Cache key
+     * @returns True if cached and not expired
+     */
+    isCached(key: string): Promise<boolean>;
+    /**
+     * Restore cached files to destination.
+     *
+     * @param key - Cache key
+     * @param dest - Destination directory
+     */
+    restore(key: string, dest: string): Promise<void>;
+    /**
+     * Save files to cache.
+     *
+     * @param key - Cache key
+     * @param source - Source directory to cache
+     * @param sourcePaths - Original source paths (for metadata)
+     */
+    save(key: string, source: string, sourcePaths?: string[]): Promise<void>;
+    /**
+     * Delete cache entry.
+     *
+     * @param key - Cache key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cache entries.
+     */
+    clear(): Promise<void>;
+    /**
+     * Clean up cache entries based on criteria.
+     *
+     * @param options - Cleanup options
+     */
+    cleanup(options?: {
+        /** Remove entries older than this (ms) */
+        olderThan?: number;
+        /** Keep total size under this (bytes) */
+        maxSize?: number;
+    }): Promise<void>;
+    /**
+     * List all cache entries.
+     *
+     * @returns Array of cache entries
+     */
+    listEntries(): Promise<CacheEntry[]>;
+    /**
+     * Get cache statistics.
+     *
+     * @returns Cache stats
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Get total cache size in bytes.
+     */
+    private getTotalSize;
+    /**
+     * Get directory size in bytes.
+     */
+    private getDirectorySize;
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+}
+/**
+ * Create a new build cache instance.
+ *
+ * @param options - Cache options
+ * @returns BuildCache instance
+ */
+export declare function createCache(options?: BuildCacheOptions): BuildCache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/scripts/lib/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../../../scripts/lib/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAaH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,gBAAgB;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,GAAG,CAAQ;IACnB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,WAAW,CAAsB;gBAE7B,OAAO,GAAE,iBAAsB;IAQ3C;;OAEG;YACW,OAAO;IAOrB;;OAEG;YACW,WAAW;IAKzB;;;;;;;OAOG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAoCtD;;;;;OAKG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwC7C;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BvD;;;;;;OAMG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAgDlF;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;;;OAIG;IACG,OAAO,CACX,OAAO,GAAE;QACP,0CAA0C;QAC1C,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,yCAAyC;QACzC,OAAO,CAAC,EAAE,MAAM,CAAA;KACZ,GACL,OAAO,CAAC,IAAI,CAAC;IA6ChB;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IA0B1C;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAgBrC;;OAEG;YACW,YAAY;IAK1B;;OAEG;YACW,gBAAgB;IAuB9B;;OAEG;IACH,UAAU,IAAI,IAAI;CAInB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAEnE"}