@wundr.io/cli 1.0.0 → 1.0.2-dev.20260530174250.ef0ec927

package/src/framework/completion-exporter.ts

@@ -0,0 +1,383 @@
+/**
+ * Completion Exporter - Tab completion data export for shells.
+ *
+ * Generates shell-specific completion scripts from the command registry.
+ * Supports bash, zsh, fish, and PowerShell.
+ * Also exports raw completion data as JSON for custom integrations.
+ *
+ * @module framework/completion-exporter
+ */
+
+import type { CommandDefinition, CommandCategory } from './command-interface';
+import { CATEGORY_LABELS } from './command-interface';
+import type { CommandRegistry } from './command-registry';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Shell types supported for completion export.
+ */
+export type ShellType = 'bash' | 'zsh' | 'fish' | 'powershell';
+
+/**
+ * Raw completion data structure for custom integrations.
+ */
+export interface CompletionData {
+  programName: string;
+  version: string;
+  commands: CompletionCommand[];
+  globalOptions: CompletionOption[];
+}
+
+/**
+ * Completion data for a single command.
+ */
+export interface CompletionCommand {
+  name: string;
+  description: string;
+  aliases: string[];
+  category?: string;
+  hidden: boolean;
+  arguments: CompletionArgument[];
+  options: CompletionOption[];
+  subcommands: CompletionCommand[];
+}
+
+/**
+ * Completion data for an argument.
+ */
+export interface CompletionArgument {
+  name: string;
+  description: string;
+  required: boolean;
+  variadic: boolean;
+}
+
+/**
+ * Completion data for an option.
+ */
+export interface CompletionOption {
+  long: string;
+  short?: string;
+  description: string;
+  required: boolean;
+  choices?: string[];
+  takesValue: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Completion Exporter
+// ---------------------------------------------------------------------------
+
+export class CompletionExporter {
+  private programName: string;
+
+  constructor(
+    private registry: CommandRegistry,
+    programName: string = 'wundr'
+  ) {
+    this.programName = programName;
+  }
+
+  // -------------------------------------------------------------------------
+  // Shell Script Generation
+  // -------------------------------------------------------------------------
+
+  /**
+   * Generate a completion script for the specified shell.
+   */
+  generate(shell: ShellType): string {
+    switch (shell) {
+      case 'bash':
+        return this.registry.generateBashCompletion(this.programName);
+      case 'zsh':
+        return this.registry.generateZshCompletion(this.programName);
+      case 'fish':
+        return this.generateFishCompletion();
+      case 'powershell':
+        return this.generatePowerShellCompletion();
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Raw Data Export
+  // -------------------------------------------------------------------------
+
+  /**
+   * Export completion data as a JSON-serializable structure.
+   * Useful for custom completion integrations or IDE plugins.
+   */
+  exportData(version: string = '1.0.0'): CompletionData {
+    const commands = this.registry
+      .list()
+      .filter(cmd => !cmd.name.includes(':'))
+      .map(cmd => this.commandToCompletionData(cmd));
+
+    return {
+      programName: this.programName,
+      version,
+      commands,
+      globalOptions: [
+        {
+          long: '--verbose',
+          description: 'Enable verbose logging',
+          required: false,
+          takesValue: false,
+        },
+        {
+          long: '--quiet',
+          description: 'Suppress output',
+          required: false,
+          takesValue: false,
+        },
+        {
+          long: '--json',
+          description: 'Output as JSON',
+          required: false,
+          takesValue: false,
+        },
+        {
+          long: '--no-color',
+          description: 'Disable colored output',
+          required: false,
+          takesValue: false,
+        },
+        {
+          long: '--dry-run',
+          description: 'Show what would be done',
+          required: false,
+          takesValue: false,
+        },
+        {
+          long: '--config',
+          description: 'Specify config file',
+          required: false,
+          takesValue: true,
+        },
+        {
+          long: '--help',
+          short: '-h',
+          description: 'Show help',
+          required: false,
+          takesValue: false,
+        },
+        {
+          long: '--version',
+          short: '-v',
+          description: 'Show version',
+          required: false,
+          takesValue: false,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Export completion data as JSON string.
+   */
+  exportJson(version: string = '1.0.0', pretty: boolean = true): string {
+    const data = this.exportData(version);
+    return pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+  }
+
+  // -------------------------------------------------------------------------
+  // Fish Completion
+  // -------------------------------------------------------------------------
+
+  private generateFishCompletion(): string {
+    const lines: string[] = [];
+
+    lines.push(`# Fish completion for ${this.programName}`);
+    lines.push(`# Generated by @wundr/cli framework`);
+    lines.push('');
+
+    // Disable file completion by default
+    lines.push(`complete -c ${this.programName} -f`);
+    lines.push('');
+
+    // Global options
+    lines.push('# Global options');
+    lines.push(
+      `complete -c ${this.programName} -l verbose -d 'Enable verbose logging'`
+    );
+    lines.push(`complete -c ${this.programName} -l quiet -d 'Suppress output'`);
+    lines.push(`complete -c ${this.programName} -l json -d 'Output as JSON'`);
+    lines.push(
+      `complete -c ${this.programName} -l no-color -d 'Disable colored output'`
+    );
+    lines.push(
+      `complete -c ${this.programName} -l dry-run -d 'Show what would be done'`
+    );
+    lines.push(
+      `complete -c ${this.programName} -l config -d 'Specify config file' -r`
+    );
+    lines.push(`complete -c ${this.programName} -s h -l help -d 'Show help'`);
+    lines.push(
+      `complete -c ${this.programName} -s v -l version -d 'Show version'`
+    );
+    lines.push('');
+
+    // Commands
+    lines.push('# Commands');
+    for (const cmd of this.registry.list()) {
+      if (cmd.hidden || cmd.name.includes(':')) continue;
+
+      const desc = cmd.description.replace(/'/g, "\\'");
+      lines.push(
+        `complete -c ${this.programName} -n '__fish_use_subcommand' -a '${cmd.name}' -d '${desc}'`
+      );
+
+      // Aliases
+      if (cmd.aliases) {
+        for (const alias of cmd.aliases) {
+          lines.push(
+            `complete -c ${this.programName} -n '__fish_use_subcommand' -a '${alias}' -d '${desc}'`
+          );
+        }
+      }
+
+      // Command-specific options
+      if (cmd.options) {
+        for (const opt of cmd.options) {
+          const longMatch = opt.flags.match(/--([a-z-]+)/);
+          const shortMatch = opt.flags.match(/-([a-z]),/);
+          const optDesc = opt.description.replace(/'/g, "\\'");
+
+          let line = `complete -c ${this.programName} -n '__fish_seen_subcommand_from ${cmd.name}'`;
+          if (longMatch) line += ` -l '${longMatch[1]}'`;
+          if (shortMatch) line += ` -s '${shortMatch[1]}'`;
+          line += ` -d '${optDesc}'`;
+
+          if (opt.choices) {
+            line += ` -xa '${opt.choices.join(' ')}'`;
+          } else if (opt.flags.includes('<')) {
+            line += ' -r';
+          }
+
+          lines.push(line);
+        }
+      }
+
+      // Subcommands
+      if (cmd.subcommands) {
+        for (const sub of cmd.subcommands) {
+          const subDesc = sub.description.replace(/'/g, "\\'");
+          lines.push(
+            `complete -c ${this.programName} -n '__fish_seen_subcommand_from ${cmd.name}' ` +
+              `-a '${sub.name}' -d '${subDesc}'`
+          );
+        }
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  // -------------------------------------------------------------------------
+  // PowerShell Completion
+  // -------------------------------------------------------------------------
+
+  private generatePowerShellCompletion(): string {
+    const lines: string[] = [];
+
+    lines.push(`# PowerShell completion for ${this.programName}`);
+    lines.push(`# Generated by @wundr/cli framework`);
+    lines.push('');
+    lines.push(
+      `Register-ArgumentCompleter -CommandName '${this.programName}' -ScriptBlock {`
+    );
+    lines.push('    param($wordToComplete, $commandAst, $cursorPosition)');
+    lines.push('');
+    lines.push('    $commands = @(');
+
+    for (const cmd of this.registry.list()) {
+      if (cmd.hidden || cmd.name.includes(':')) continue;
+      const desc = cmd.description.replace(/'/g, "''");
+      lines.push(`        @{ Name = '${cmd.name}'; Description = '${desc}' }`);
+    }
+
+    lines.push('    )');
+    lines.push('');
+    lines.push('    $globalOptions = @(');
+    lines.push(
+      "        @{ Name = '--verbose'; Description = 'Enable verbose logging' }"
+    );
+    lines.push(
+      "        @{ Name = '--quiet'; Description = 'Suppress output' }"
+    );
+    lines.push("        @{ Name = '--json'; Description = 'Output as JSON' }");
+    lines.push(
+      "        @{ Name = '--no-color'; Description = 'Disable colored output' }"
+    );
+    lines.push(
+      "        @{ Name = '--dry-run'; Description = 'Show what would be done' }"
+    );
+    lines.push(
+      "        @{ Name = '--config'; Description = 'Specify config file' }"
+    );
+    lines.push('    )');
+    lines.push('');
+    lines.push('    $elements = $commandAst.CommandElements');
+    lines.push('    if ($elements.Count -le 2) {');
+    lines.push(
+      '        $items = if ($wordToComplete.StartsWith("-")) { $globalOptions } else { $commands }'
+    );
+    lines.push(
+      '        $items | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {'
+    );
+    lines.push(
+      "            [System.Management.Automation.CompletionResult]::new($_.Name, $_.Name, 'ParameterValue', $_.Description)"
+    );
+    lines.push('        }');
+    lines.push('    }');
+    lines.push('}');
+
+    return lines.join('\n');
+  }
+
+  // -------------------------------------------------------------------------
+  // Private Helpers
+  // -------------------------------------------------------------------------
+
+  private commandToCompletionData(cmd: CommandDefinition): CompletionCommand {
+    return {
+      name: cmd.name,
+      description: cmd.description,
+      aliases: cmd.aliases ?? [],
+      category: cmd.category,
+      hidden: cmd.hidden ?? false,
+      arguments: (cmd.arguments ?? []).map(arg => ({
+        name: arg.name,
+        description: arg.description,
+        required: arg.required ?? false,
+        variadic: arg.variadic ?? false,
+      })),
+      options: (cmd.options ?? []).map(opt => this.parseOptionFlags(opt)),
+      subcommands: (cmd.subcommands ?? []).map(sub =>
+        this.commandToCompletionData(sub)
+      ),
+    };
+  }
+
+  private parseOptionFlags(opt: {
+    flags: string;
+    description: string;
+    required?: boolean;
+    choices?: string[];
+  }): CompletionOption {
+    const longMatch = opt.flags.match(/--([a-z-]+)/);
+    const shortMatch = opt.flags.match(/-([a-z]),/);
+    const takesValue = opt.flags.includes('<') || opt.flags.includes('[');
+
+    return {
+      long: longMatch ? `--${longMatch[1]}` : opt.flags,
+      short: shortMatch ? `-${shortMatch[1]}` : undefined,
+      description: opt.description,
+      required: opt.required ?? false,
+      choices: opt.choices,
+      takesValue,
+    };
+  }
+}