@wundr.io/cli 1.0.12 → 1.0.14

package/dist/framework/command-registry.js

@@ -0,0 +1,734 @@
+"use strict";
+/**
+ * Command Registry - Auto-discovery, registration, and Commander.js integration.
+ *
+ * The registry is the central hub that:
+ * 1. Discovers CommandDefinition files from the commands/ directory
+ * 2. Validates definitions at registration time
+ * 3. Builds a Commander.js program from registered definitions
+ * 4. Provides lookup for shell completion generation
+ * 5. Supports legacy command wrapping for incremental migration
+ *
+ * @module framework/command-registry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandRegistry = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const commander_1 = require("commander");
+const command_interface_1 = require("./command-interface");
+// ---------------------------------------------------------------------------
+// Command Registry
+// ---------------------------------------------------------------------------
+class CommandRegistry {
+    commands = new Map();
+    globalHooks = [];
+    options;
+    constructor(options = {}) {
+        this.options = {
+            strict: options.strict ?? false,
+            commandsDir: options.commandsDir ?? path.join(__dirname, '..', 'commands'),
+            filePattern: options.filePattern ?? /\.(command)\.(ts|js)$/,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Registration
+    // -------------------------------------------------------------------------
+    /**
+     * Register a single command definition.
+     *
+     * @param definition - The command to register
+     * @param hooks - Optional lifecycle hooks for this command
+     * @throws Error in strict mode if command name is already registered
+     */
+    register(definition, hooks = []) {
+        const name = definition.name;
+        if (this.commands.has(name)) {
+            if (this.options.strict) {
+                throw new Error(`Command "${name}" is already registered. ` +
+                    `Disable strict mode or use a different name.`);
+            }
+            // Non-strict: warn and overwrite
+            console.warn(chalk_1.default.yellow(`[registry] Overwriting existing command: ${name}`));
+        }
+        // Validate the definition at registration time
+        this.validateDefinition(definition);
+        this.commands.set(name, {
+            definition,
+            hooks,
+            registeredAt: new Date(),
+        });
+        // Recursively register subcommands
+        if (definition.subcommands) {
+            for (const sub of definition.subcommands) {
+                // Prefix subcommand names with parent for flat lookup
+                const qualifiedName = `${name}:${sub.name}`;
+                const qualifiedSub = { ...sub, name: qualifiedName };
+                this.register(qualifiedSub, hooks);
+            }
+        }
+    }
+    /**
+     * Register a command module (definition + hooks bundle).
+     */
+    registerModule(mod) {
+        this.register(mod.command, mod.hooks);
+    }
+    /**
+     * Register a global hook that runs for all commands.
+     */
+    registerGlobalHook(hook) {
+        this.globalHooks.push(hook);
+    }
+    /**
+     * Remove a registered command.
+     */
+    unregister(name) {
+        return this.commands.delete(name);
+    }
+    // -------------------------------------------------------------------------
+    // Auto-Discovery
+    // -------------------------------------------------------------------------
+    /**
+     * Discover and register commands from a directory.
+     *
+     * Scans the directory for files matching the configured pattern.
+     * Each file should export either:
+     * - A `module` property conforming to `CommandModule`
+     * - A `command` property conforming to `CommandDefinition`
+     * - A default export conforming to `CommandDefinition`
+     *
+     * @param directory - Directory to scan. Defaults to configured commandsDir.
+     * @returns Number of commands discovered and registered.
+     */
+    async discoverCommands(directory) {
+        const dir = directory ?? this.options.commandsDir;
+        let count = 0;
+        if (!fs.existsSync(dir)) {
+            console.warn(chalk_1.default.yellow(`[registry] Commands directory not found: ${dir}`));
+            return 0;
+        }
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile()) {
+                continue;
+            }
+            // Check file pattern
+            if (!this.options.filePattern.test(entry.name)) {
+                continue;
+            }
+            const filePath = path.join(dir, entry.name);
+            try {
+                const exported = await this.loadModule(filePath);
+                if (exported.module && typeof exported.module === 'object') {
+                    // CommandModule export
+                    const mod = exported.module;
+                    if (mod.command &&
+                        mod.command.name &&
+                        typeof mod.command.execute === 'function') {
+                        this.registerModule(mod);
+                        count++;
+                    }
+                }
+                else if (exported.command && typeof exported.command === 'object') {
+                    // Direct CommandDefinition export
+                    const def = exported.command;
+                    if (def.name && typeof def.execute === 'function') {
+                        this.register(def);
+                        count++;
+                    }
+                }
+                else if (exported.default && typeof exported.default === 'object') {
+                    // Default export
+                    const def = exported.default;
+                    if (def.name && typeof def.execute === 'function') {
+                        this.register(def);
+                        count++;
+                    }
+                }
+            }
+            catch (error) {
+                console.warn(chalk_1.default.yellow(`[registry] Failed to load command from ${entry.name}: ` +
+                    `${error instanceof Error ? error.message : String(error)}`));
+            }
+        }
+        return count;
+    }
+    // -------------------------------------------------------------------------
+    // Multi-Directory Discovery
+    // -------------------------------------------------------------------------
+    /**
+     * Discover commands from multiple directories.
+     *
+     * @param directories - Array of directory paths to scan
+     * @returns Total number of commands discovered
+     */
+    async discoverFromDirectories(directories) {
+        let total = 0;
+        for (const dir of directories) {
+            total += await this.discoverCommands(dir);
+        }
+        return total;
+    }
+    // -------------------------------------------------------------------------
+    // Lookup
+    // -------------------------------------------------------------------------
+    /**
+     * Get a registered command by name.
+     */
+    get(name) {
+        return this.commands.get(name)?.definition;
+    }
+    /**
+     * Find a command by name or alias.
+     * Searches direct name first, then aliases.
+     */
+    findByNameOrAlias(nameOrAlias) {
+        // Direct name lookup
+        const direct = this.commands.get(nameOrAlias);
+        if (direct)
+            return direct.definition;
+        // Search aliases
+        for (const registered of Array.from(this.commands.values())) {
+            const { definition } = registered;
+            if (definition.aliases && definition.aliases.includes(nameOrAlias)) {
+                return definition;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Check if a command is registered.
+     */
+    has(name) {
+        return this.commands.has(name);
+    }
+    /**
+     * List all registered commands, optionally filtered by category.
+     */
+    list(category) {
+        const all = Array.from(this.commands.values()).map(r => r.definition);
+        if (category) {
+            return all.filter(cmd => cmd.category === category);
+        }
+        return all;
+    }
+    /**
+     * List all registered command names.
+     */
+    names() {
+        return Array.from(this.commands.keys());
+    }
+    /**
+     * Get commands grouped by category.
+     */
+    grouped() {
+        const groups = new Map();
+        for (const registered of Array.from(this.commands.values())) {
+            const cat = registered.definition.category ?? 'uncategorized';
+            const existing = groups.get(cat) ?? [];
+            existing.push(registered.definition);
+            groups.set(cat, existing);
+        }
+        return groups;
+    }
+    /**
+     * Get all command names for shell completion.
+     */
+    getCompletionWords() {
+        const words = [];
+        for (const registered of Array.from(this.commands.values())) {
+            if (registered.definition.hidden) {
+                continue;
+            }
+            words.push(registered.definition.name);
+            if (registered.definition.aliases) {
+                words.push(...registered.definition.aliases);
+            }
+        }
+        return words.sort();
+    }
+    // -------------------------------------------------------------------------
+    // Commander.js Integration
+    // -------------------------------------------------------------------------
+    /**
+     * Build a Commander.js program from all registered commands.
+     *
+     * This is the bridge between the registry's CommandDefinition world
+     * and Commander.js's imperative API. Call this once after all commands
+     * are registered.
+     *
+     * @param program - The root Commander.js Command instance
+     * @param contextFactory - Factory that creates a CommandContext for each invocation
+     */
+    buildProgram(program, contextFactory) {
+        for (const registered of Array.from(this.commands.values())) {
+            const { definition, hooks } = registered;
+            // Skip qualified subcommand names (they are handled by their parent)
+            if (definition.name.includes(':')) {
+                continue;
+            }
+            // Check for legacy factory
+            const legacyFactory = definition._legacyFactory;
+            if (legacyFactory) {
+                // Legacy command: add the pre-built Commander.Command directly
+                program.addCommand(legacyFactory());
+                continue;
+            }
+            // Build a new Commander.Command from the definition
+            const cmd = this.buildCommand(definition, hooks, contextFactory);
+            program.addCommand(cmd);
+        }
+    }
+    /**
+     * Build a single Commander.Command from a CommandDefinition.
+     */
+    buildCommand(definition, hooks, contextFactory) {
+        const cmd = new commander_1.Command(definition.name);
+        cmd.description(definition.description);
+        // Aliases
+        if (definition.aliases) {
+            for (const alias of definition.aliases) {
+                cmd.alias(alias);
+            }
+        }
+        // Hidden - Commander.js doesn't expose hideHelp, so we use the internal approach
+        if (definition.hidden) {
+            cmd._hidden = true;
+        }
+        // Arguments
+        if (definition.arguments) {
+            for (const arg of definition.arguments) {
+                const spec = arg.required
+                    ? arg.variadic
+                        ? `<${arg.name}...>`
+                        : `<${arg.name}>`
+                    : arg.variadic
+                        ? `[${arg.name}...]`
+                        : `[${arg.name}]`;
+                cmd.argument(spec, arg.description, arg.defaultValue);
+            }
+        }
+        // Options
+        if (definition.options) {
+            for (const opt of definition.options) {
+                if (opt.required) {
+                    cmd.requiredOption(opt.flags, opt.description, opt.defaultValue);
+                }
+                else {
+                    cmd.option(opt.flags, opt.description, opt.defaultValue);
+                }
+                if (opt.choices) {
+                    // Commander.js doesn't have built-in choices on options;
+                    // we handle this in validation instead.
+                }
+            }
+        }
+        // Examples in help text
+        if (definition.examples && definition.examples.length > 0) {
+            const examplesText = definition.examples
+                .map(ex => `  ${chalk_1.default.green(ex.command)}  ${chalk_1.default.gray(ex.description)}`)
+                .join('\n');
+            cmd.addHelpText('after', `\n${chalk_1.default.gray('Examples:')}\n${examplesText}\n`);
+        }
+        // Subcommands
+        if (definition.subcommands) {
+            for (const sub of definition.subcommands) {
+                const subCmd = this.buildCommand(sub, hooks, contextFactory);
+                cmd.addCommand(subCmd);
+            }
+        }
+        // Action handler
+        cmd.action(async (...actionArgs) => {
+            // Commander passes positional args first, then options object, then the Command
+            const commanderCmd = actionArgs[actionArgs.length - 1];
+            const options = actionArgs[actionArgs.length - 2];
+            // Build positional args map
+            const args = {};
+            if (definition.arguments) {
+                for (let i = 0; i < definition.arguments.length; i++) {
+                    const argDef = definition.arguments[i];
+                    if (argDef) {
+                        args[argDef.name] = actionArgs[i];
+                    }
+                }
+            }
+            // Merge environment variable defaults into options
+            if (definition.options) {
+                for (const opt of definition.options) {
+                    if (opt.envVar) {
+                        const optName = this.flagsToOptionName(opt.flags);
+                        if (options[optName] === undefined && process.env[opt.envVar]) {
+                            options[optName] = process.env[opt.envVar];
+                        }
+                    }
+                }
+            }
+            // Create execution context
+            const rootOpts = commanderCmd.parent?.opts() ?? commanderCmd.opts();
+            const globalOpts = {
+                verbose: !!rootOpts['verbose'],
+                quiet: !!rootOpts['quiet'],
+                json: !!rootOpts['json'] || !!options['json'],
+                noColor: !!rootOpts['noColor'],
+                dryRun: !!rootOpts['dryRun'] || !!options['dryRun'],
+                config: rootOpts['config'],
+            };
+            const context = contextFactory(globalOpts);
+            try {
+                // Run pre-validate hooks
+                const allHooks = [...this.globalHooks, ...hooks];
+                await this.runHooks('preValidate', allHooks, definition, context);
+                // Validate
+                let validation = (0, command_interface_1.validationOk)();
+                if (definition.validate) {
+                    validation = await definition.validate(args, options, context);
+                }
+                // Validate option choices
+                if (definition.options) {
+                    for (const opt of definition.options) {
+                        if (opt.choices) {
+                            const optName = this.flagsToOptionName(opt.flags);
+                            const value = options[optName];
+                            if (value !== undefined && !opt.choices.includes(String(value))) {
+                                validation = {
+                                    valid: false,
+                                    errors: [
+                                        ...validation.errors,
+                                        {
+                                            field: optName,
+                                            message: `Invalid value "${value}" for --${optName}. Allowed: ${opt.choices.join(', ')}`,
+                                            suggestion: `Use one of: ${opt.choices.join(', ')}`,
+                                        },
+                                    ],
+                                };
+                            }
+                        }
+                    }
+                }
+                // Validate option conflicts
+                if (definition.options) {
+                    for (const opt of definition.options) {
+                        if (opt.conflicts) {
+                            const optName = this.flagsToOptionName(opt.flags);
+                            if (options[optName] !== undefined) {
+                                for (const conflictName of opt.conflicts) {
+                                    if (options[conflictName] !== undefined) {
+                                        validation = {
+                                            valid: false,
+                                            errors: [
+                                                ...validation.errors,
+                                                {
+                                                    field: optName,
+                                                    message: `Option --${optName} conflicts with --${conflictName}`,
+                                                    suggestion: `Use either --${optName} or --${conflictName}, not both`,
+                                                },
+                                            ],
+                                        };
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                // Run post-validate hooks
+                await this.runHooks('postValidate', allHooks, definition, context);
+                if (!validation.valid) {
+                    for (const err of validation.errors) {
+                        console.error(chalk_1.default.red(`Validation error [${err.field}]: ${err.message}`));
+                        if (err.suggestion) {
+                            console.error(chalk_1.default.yellow(`  Suggestion: ${err.suggestion}`));
+                        }
+                    }
+                    process.exitCode = 1;
+                    return;
+                }
+                // Run pre-execute hooks
+                await this.runHooks('preExecute', allHooks, definition, context);
+                // Execute
+                const result = await definition.execute(args, options, context);
+                // Run post-execute hooks
+                await this.runHooks('postExecute', allHooks, definition, context, result);
+                // Handle result
+                this.handleResult(result, context);
+            }
+            catch (error) {
+                // Attempt rollback
+                if (definition.rollback && error instanceof Error) {
+                    try {
+                        await definition.rollback(error, context);
+                    }
+                    catch (rollbackError) {
+                        context.logger.error(`Rollback failed: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+                    }
+                }
+                // Format error output
+                if (error instanceof Error) {
+                    if (globalOpts.verbose) {
+                        console.error(chalk_1.default.red(`\nCommand "${definition.name}" failed:`));
+                        console.error(chalk_1.default.red(error.message));
+                        if (error.stack) {
+                            console.error(chalk_1.default.gray(error.stack));
+                        }
+                    }
+                    else {
+                        console.error(chalk_1.default.red(`Error: ${error.message}`));
+                        console.error(chalk_1.default.gray(`Run with --verbose for details`));
+                    }
+                }
+                else {
+                    console.error(chalk_1.default.red(`Error: ${String(error)}`));
+                }
+                process.exitCode = 1;
+            }
+        });
+        return cmd;
+    }
+    // -------------------------------------------------------------------------
+    // Shell Completion Generation
+    // -------------------------------------------------------------------------
+    /**
+     * Generate a bash completion script.
+     */
+    generateBashCompletion(programName = 'wundr') {
+        const commands = this.getCompletionWords();
+        return `
+# Bash completion for ${programName}
+# Generated by @wundr/cli framework
+
+_${programName}_completions() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local commands="${commands.join(' ')}"
+  local global_opts="--verbose --quiet --json --no-color --dry-run --config --help --version"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "\${commands} \${global_opts}" -- "\${cur}") )
+  else
+    local cmd="\${COMP_WORDS[1]}"
+    case "\${cmd}" in
+${this.generateBashCaseClauses()}
+      *)
+        COMPREPLY=( $(compgen -W "\${global_opts}" -- "\${cur}") )
+        ;;
+    esac
+  fi
+}
+
+complete -F _${programName}_completions ${programName}
+`.trim();
+    }
+    /**
+     * Generate a zsh completion script.
+     */
+    generateZshCompletion(programName = 'wundr') {
+        const commands = this.list()
+            .filter(cmd => !cmd.hidden && !cmd.name.includes(':'))
+            .map(cmd => `'${cmd.name}:${cmd.description.replace(/'/g, '')}'`)
+            .join('\n    ');
+        return `
+#compdef ${programName}
+# Zsh completion for ${programName}
+# Generated by @wundr/cli framework
+
+_${programName}() {
+  local -a commands
+  commands=(
+    ${commands}
+  )
+
+  _arguments -C \\
+    '--verbose[Enable verbose logging]' \\
+    '--quiet[Suppress output]' \\
+    '--json[Output as JSON]' \\
+    '--no-color[Disable colored output]' \\
+    '--dry-run[Show what would be done]' \\
+    '--config[Specify config file]:file:_files' \\
+    '-h[Show help]' \\
+    '-v[Show version]' \\
+    '1:command:->command' \\
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe -t commands 'command' commands
+      ;;
+    args)
+      case $words[1] in
+${this.generateZshCaseClauses()}
+      esac
+      ;;
+  esac
+}
+
+_${programName}
+`.trim();
+    }
+    // -------------------------------------------------------------------------
+    // Private Helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Load a module from a file path. Handles both ESM and CJS.
+     */
+    async loadModule(filePath) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            return require(filePath);
+        }
+        catch {
+            // Fall back to dynamic import for ESM
+            return await Promise.resolve(`${filePath}`).then(s => tslib_1.__importStar(require(s)));
+        }
+    }
+    /**
+     * Validate a command definition at registration time.
+     */
+    validateDefinition(definition) {
+        if (!definition.name || typeof definition.name !== 'string') {
+            throw new Error('Command definition must have a non-empty name');
+        }
+        if (!definition.description || typeof definition.description !== 'string') {
+            throw new Error(`Command "${definition.name}" must have a description`);
+        }
+        if (typeof definition.execute !== 'function') {
+            throw new Error(`Command "${definition.name}" must have an execute function`);
+        }
+        // Validate arguments don't have duplicates
+        if (definition.arguments) {
+            const names = new Set();
+            for (const arg of definition.arguments) {
+                if (names.has(arg.name)) {
+                    throw new Error(`Command "${definition.name}" has duplicate argument name: ${arg.name}`);
+                }
+                names.add(arg.name);
+            }
+        }
+    }
+    /**
+     * Run hooks for a specific phase.
+     */
+    async runHooks(phase, hooks, command, context, result) {
+        const matching = hooks.filter(h => {
+            if (h.phase !== phase)
+                return false;
+            if (h.commands && !h.commands.includes(command.name))
+                return false;
+            return true;
+        });
+        for (const hook of matching) {
+            const shouldContinue = await hook.handler(command, context, result);
+            if (shouldContinue === false &&
+                (phase === 'preValidate' || phase === 'preExecute')) {
+                throw new Error(`Command "${command.name}" aborted by ${phase} hook`);
+            }
+        }
+    }
+    /**
+     * Handle a CommandResult by formatting output appropriately.
+     */
+    handleResult(result, context) {
+        if (result.exitCode !== 0) {
+            if (result.message) {
+                console.error(chalk_1.default.red(result.message));
+            }
+            process.exitCode = result.exitCode;
+            return;
+        }
+        // Warnings
+        if (result.warnings && result.warnings.length > 0) {
+            for (const warning of result.warnings) {
+                console.error(chalk_1.default.yellow(`Warning: ${warning}`));
+            }
+        }
+        // JSON mode: output data directly
+        if (context.globalOptions.json && result.data !== undefined) {
+            const output = typeof result.data === 'string'
+                ? result.data
+                : JSON.stringify(result.data, null, 2);
+            console.log(output);
+            return;
+        }
+        // Quiet mode: no message output
+        if (context.globalOptions.quiet) {
+            return;
+        }
+        // Normal mode: output message
+        if (result.message) {
+            console.log(result.message);
+        }
+    }
+    /**
+     * Convert Commander.js flag specification to a camelCase option name.
+     * e.g., '-p, --port <number>' -> 'port'
+     * e.g., '--dry-run' -> 'dryRun'
+     */
+    flagsToOptionName(flags) {
+        const match = flags.match(/--([a-z-]+)/);
+        if (!match || !match[1])
+            return flags;
+        return match[1].replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+    }
+    /**
+     * Generate bash case clauses for subcommand completion.
+     */
+    generateBashCaseClauses() {
+        const clauses = [];
+        for (const registered of Array.from(this.commands.values())) {
+            const { definition } = registered;
+            if (definition.hidden || definition.name.includes(':'))
+                continue;
+            const subNames = [];
+            const optFlags = [];
+            if (definition.subcommands) {
+                for (const sub of definition.subcommands) {
+                    subNames.push(sub.name);
+                }
+            }
+            if (definition.options) {
+                for (const opt of definition.options) {
+                    const longMatch = opt.flags.match(/--[a-z-]+/);
+                    if (longMatch)
+                        optFlags.push(longMatch[0]);
+                }
+            }
+            const words = [...subNames, ...optFlags].join(' ');
+            if (words) {
+                clauses.push(`      ${definition.name})\n        COMPREPLY=( $(compgen -W "${words}" -- "\${cur}") )\n        ;;`);
+            }
+        }
+        return clauses.join('\n');
+    }
+    /**
+     * Generate zsh case clauses for subcommand completion.
+     */
+    generateZshCaseClauses() {
+        const clauses = [];
+        for (const registered of Array.from(this.commands.values())) {
+            const { definition } = registered;
+            if (definition.hidden || definition.name.includes(':'))
+                continue;
+            const args = [];
+            if (definition.subcommands) {
+                const subs = definition.subcommands
+                    .map(s => `'${s.name}:${s.description.replace(/'/g, '')}'`)
+                    .join(' ');
+                args.push(`_values 'subcommand' ${subs}`);
+            }
+            if (definition.options) {
+                for (const opt of definition.options) {
+                    const longMatch = opt.flags.match(/--([a-z-]+)/);
+                    if (longMatch) {
+                        args.push(`'--${longMatch[1]}[${opt.description.replace(/'/g, '')}]'`);
+                    }
+                }
+            }
+            if (args.length > 0) {
+                clauses.push(`        ${definition.name})\n          _arguments ${args.join(' \\\n            ')}\n          ;;`);
+            }
+        }
+        return clauses.join('\n');
+    }
+}
+exports.CommandRegistry = CommandRegistry;
+//# sourceMappingURL=command-registry.js.map