@zhuan-ai/zhuanspec 1.3.0

package/dist/core/completions/factory.d.ts

@@ -0,0 +1,51 @@
+import { CompletionGenerator } from './types.js';
+import { InstallationResult } from './installers/zsh-installer.js';
+import { SupportedShell } from '../../utils/shell-detection.js';
+/**
+ * Interface for completion installers
+ */
+export interface CompletionInstaller {
+    install(script: string): Promise<InstallationResult>;
+    uninstall(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
+export type { InstallationResult };
+/**
+ * Factory for creating completion generators and installers
+ * This design makes it easy to add support for additional shells
+ */
+export declare class CompletionFactory {
+    private static readonly SUPPORTED_SHELLS;
+    /**
+     * Create a completion generator for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionGenerator instance
+     * @throws Error if shell is not supported
+     */
+    static createGenerator(shell: SupportedShell): CompletionGenerator;
+    /**
+     * Create a completion installer for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionInstaller instance
+     * @throws Error if shell is not supported
+     */
+    static createInstaller(shell: SupportedShell): CompletionInstaller;
+    /**
+     * Check if a shell is supported
+     *
+     * @param shell - The shell to check
+     * @returns true if the shell is supported
+     */
+    static isSupported(shell: string): shell is SupportedShell;
+    /**
+     * Get list of all supported shells
+     *
+     * @returns Array of supported shell names
+     */
+    static getSupportedShells(): SupportedShell[];
+}
+//# sourceMappingURL=factory.d.ts.map

package/dist/core/completions/factory.js

@@ -0,0 +1,57 @@
+import { ZshGenerator } from './generators/zsh-generator.js';
+import { ZshInstaller } from './installers/zsh-installer.js';
+/**
+ * Factory for creating completion generators and installers
+ * This design makes it easy to add support for additional shells
+ */
+export class CompletionFactory {
+    static SUPPORTED_SHELLS = ['zsh'];
+    /**
+     * Create a completion generator for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionGenerator instance
+     * @throws Error if shell is not supported
+     */
+    static createGenerator(shell) {
+        switch (shell) {
+            case 'zsh':
+                return new ZshGenerator();
+            default:
+                throw new Error(`Unsupported shell: ${shell}`);
+        }
+    }
+    /**
+     * Create a completion installer for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionInstaller instance
+     * @throws Error if shell is not supported
+     */
+    static createInstaller(shell) {
+        switch (shell) {
+            case 'zsh':
+                return new ZshInstaller();
+            default:
+                throw new Error(`Unsupported shell: ${shell}`);
+        }
+    }
+    /**
+     * Check if a shell is supported
+     *
+     * @param shell - The shell to check
+     * @returns true if the shell is supported
+     */
+    static isSupported(shell) {
+        return this.SUPPORTED_SHELLS.includes(shell);
+    }
+    /**
+     * Get list of all supported shells
+     *
+     * @returns Array of supported shell names
+     */
+    static getSupportedShells() {
+        return [...this.SUPPORTED_SHELLS];
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/core/completions/generators/zsh-generator.d.ts

@@ -0,0 +1,58 @@
+import { CompletionGenerator, CommandDefinition } from '../types.js';
+/**
+ * Generates Zsh completion scripts for the ZhuanSpec CLI.
+ * Follows Zsh completion system conventions using the _zhuanspec function.
+ */
+export declare class ZshGenerator implements CompletionGenerator {
+    readonly shell: "zsh";
+    /**
+     * Generate a Zsh completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Zsh completion script as a string
+     */
+    generate(commands: CommandDefinition[]): string;
+    /**
+     * Generate a single completion function
+     *
+     * @param functionName - Name of the completion function
+     * @param varName - Name of the local array variable
+     * @param varLabel - Label for the completion items
+     * @param commandLines - Command line(s) to populate the array
+     * @param comment - Optional comment describing the function
+     */
+    private generateCompletionFunction;
+    /**
+     * Generate dynamic completion helper functions for change and spec IDs
+     */
+    private generateDynamicCompletionHelpers;
+    /**
+     * Generate completion function for a specific command
+     */
+    private generateCommandFunction;
+    /**
+     * Generate completion function for a subcommand
+     */
+    private generateSubcommandFunction;
+    /**
+     * Generate flag specification for _arguments
+     */
+    private generateFlagSpec;
+    /**
+     * Generate positional argument specification
+     */
+    private generatePositionalSpec;
+    /**
+     * Escape special characters in descriptions
+     */
+    private escapeDescription;
+    /**
+     * Escape special characters in values
+     */
+    private escapeValue;
+    /**
+     * Sanitize command names for use in function names
+     */
+    private sanitizeFunctionName;
+}
+//# sourceMappingURL=zsh-generator.d.ts.map

package/dist/core/completions/generators/zsh-generator.js

@@ -0,0 +1,319 @@
+/**
+ * Generates Zsh completion scripts for the ZhuanSpec CLI.
+ * Follows Zsh completion system conventions using the _zhuanspec function.
+ */
+export class ZshGenerator {
+    shell = 'zsh';
+    /**
+     * Generate a Zsh completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Zsh completion script as a string
+     */
+    generate(commands) {
+        const script = [];
+        // Header comment
+        script.push('#compdef zhuanspec');
+        script.push('');
+        script.push('# Zsh completion script for ZhuanSpec CLI');
+        script.push('# Auto-generated - do not edit manually');
+        script.push('');
+        // Main completion function
+        script.push('_zhuanspec() {');
+        script.push('  local context state line');
+        script.push('  typeset -A opt_args');
+        script.push('');
+        // Generate main command argument specification
+        script.push('  local -a commands');
+        script.push('  commands=(');
+        for (const cmd of commands) {
+            const escapedDesc = this.escapeDescription(cmd.description);
+            script.push(`    '${cmd.name}:${escapedDesc}'`);
+        }
+        script.push('  )');
+        script.push('');
+        // Main _arguments call
+        script.push('  _arguments -C \\');
+        script.push('    "1: :->command" \\');
+        script.push('    "*::arg:->args"');
+        script.push('');
+        // Command dispatch logic
+        script.push('  case $state in');
+        script.push('    command)');
+        script.push('      _describe "zhuanspec command" commands');
+        script.push('      ;;');
+        script.push('    args)');
+        script.push('      case $words[1] in');
+        // Generate completion for each command
+        for (const cmd of commands) {
+            script.push(`        ${cmd.name})`);
+            script.push(`          _zhuanspec_${this.sanitizeFunctionName(cmd.name)}`);
+            script.push('          ;;');
+        }
+        script.push('      esac');
+        script.push('      ;;');
+        script.push('  esac');
+        script.push('}');
+        script.push('');
+        // Generate individual command completion functions
+        for (const cmd of commands) {
+            script.push(...this.generateCommandFunction(cmd));
+            script.push('');
+        }
+        // Add dynamic completion helper functions
+        script.push(...this.generateDynamicCompletionHelpers());
+        // Register the completion function
+        script.push('compdef _zhuanspec zhuanspec');
+        script.push('');
+        return script.join('\n');
+    }
+    /**
+     * Generate a single completion function
+     *
+     * @param functionName - Name of the completion function
+     * @param varName - Name of the local array variable
+     * @param varLabel - Label for the completion items
+     * @param commandLines - Command line(s) to populate the array
+     * @param comment - Optional comment describing the function
+     */
+    generateCompletionFunction(functionName, varName, varLabel, commandLines, comment) {
+        const lines = [];
+        if (comment) {
+            lines.push(comment);
+        }
+        lines.push(`${functionName}() {`);
+        lines.push(`  local -a ${varName}`);
+        if (commandLines.length === 1) {
+            lines.push(`  ${commandLines[0]}`);
+        }
+        else {
+            lines.push(`  ${varName}=(`);
+            for (let i = 0; i < commandLines.length; i++) {
+                const suffix = i < commandLines.length - 1 ? ' \\' : '';
+                lines.push(`    ${commandLines[i]}${suffix}`);
+            }
+            lines.push('  )');
+        }
+        lines.push(`  _describe "${varLabel}" ${varName}`);
+        lines.push('}');
+        lines.push('');
+        return lines;
+    }
+    /**
+     * Generate dynamic completion helper functions for change and spec IDs
+     */
+    generateDynamicCompletionHelpers() {
+        const lines = [];
+        lines.push('# Dynamic completion helpers');
+        lines.push('');
+        // Helper function for completing change IDs
+        lines.push('# Use zhuanspec __complete to get available changes');
+        lines.push('_zhuanspec_complete_changes() {');
+        lines.push('  local -a changes');
+        lines.push('  while IFS=$\'\\t\' read -r id desc; do');
+        lines.push('    changes+=("$id:$desc")');
+        lines.push('  done < <(zhuanspec __complete changes 2>/dev/null)');
+        lines.push('  _describe "change" changes');
+        lines.push('}');
+        lines.push('');
+        // Helper function for completing spec IDs
+        lines.push('# Use zhuanspec __complete to get available specs');
+        lines.push('_zhuanspec_complete_specs() {');
+        lines.push('  local -a specs');
+        lines.push('  while IFS=$\'\\t\' read -r id desc; do');
+        lines.push('    specs+=("$id:$desc")');
+        lines.push('  done < <(zhuanspec __complete specs 2>/dev/null)');
+        lines.push('  _describe "spec" specs');
+        lines.push('}');
+        lines.push('');
+        // Helper function for completing both changes and specs
+        lines.push('# Get both changes and specs');
+        lines.push('_zhuanspec_complete_items() {');
+        lines.push('  local -a items');
+        lines.push('  while IFS=$\'\\t\' read -r id desc; do');
+        lines.push('    items+=("$id:$desc")');
+        lines.push('  done < <(zhuanspec __complete changes 2>/dev/null)');
+        lines.push('  while IFS=$\'\\t\' read -r id desc; do');
+        lines.push('    items+=("$id:$desc")');
+        lines.push('  done < <(zhuanspec __complete specs 2>/dev/null)');
+        lines.push('  _describe "item" items');
+        lines.push('}');
+        lines.push('');
+        return lines;
+    }
+    /**
+     * Generate completion function for a specific command
+     */
+    generateCommandFunction(cmd) {
+        const funcName = `_zhuanspec_${this.sanitizeFunctionName(cmd.name)}`;
+        const lines = [];
+        lines.push(`${funcName}() {`);
+        // If command has subcommands, handle them
+        if (cmd.subcommands && cmd.subcommands.length > 0) {
+            lines.push('  local context state line');
+            lines.push('  typeset -A opt_args');
+            lines.push('');
+            lines.push('  local -a subcommands');
+            lines.push('  subcommands=(');
+            for (const subcmd of cmd.subcommands) {
+                const escapedDesc = this.escapeDescription(subcmd.description);
+                lines.push(`    '${subcmd.name}:${escapedDesc}'`);
+            }
+            lines.push('  )');
+            lines.push('');
+            lines.push('  _arguments -C \\');
+            // Add command flags
+            for (const flag of cmd.flags) {
+                lines.push('    ' + this.generateFlagSpec(flag) + ' \\');
+            }
+            lines.push('    "1: :->subcommand" \\');
+            lines.push('    "*::arg:->args"');
+            lines.push('');
+            lines.push('  case $state in');
+            lines.push('    subcommand)');
+            lines.push('      _describe "subcommand" subcommands');
+            lines.push('      ;;');
+            lines.push('    args)');
+            lines.push('      case $words[1] in');
+            for (const subcmd of cmd.subcommands) {
+                lines.push(`        ${subcmd.name})`);
+                lines.push(`          _zhuanspec_${this.sanitizeFunctionName(cmd.name)}_${this.sanitizeFunctionName(subcmd.name)}`);
+                lines.push('          ;;');
+            }
+            lines.push('      esac');
+            lines.push('      ;;');
+            lines.push('  esac');
+        }
+        else {
+            // Command without subcommands
+            lines.push('  _arguments \\');
+            // Add flags
+            for (const flag of cmd.flags) {
+                lines.push('    ' + this.generateFlagSpec(flag) + ' \\');
+            }
+            // Add positional argument completion
+            if (cmd.acceptsPositional) {
+                const positionalSpec = this.generatePositionalSpec(cmd.positionalType);
+                lines.push('    ' + positionalSpec);
+            }
+            else {
+                // Remove trailing backslash from last flag
+                if (lines[lines.length - 1].endsWith(' \\')) {
+                    lines[lines.length - 1] = lines[lines.length - 1].slice(0, -2);
+                }
+            }
+        }
+        lines.push('}');
+        // Generate subcommand functions if they exist
+        if (cmd.subcommands) {
+            for (const subcmd of cmd.subcommands) {
+                lines.push('');
+                lines.push(...this.generateSubcommandFunction(cmd.name, subcmd));
+            }
+        }
+        return lines;
+    }
+    /**
+     * Generate completion function for a subcommand
+     */
+    generateSubcommandFunction(parentName, subcmd) {
+        const funcName = `_zhuanspec_${this.sanitizeFunctionName(parentName)}_${this.sanitizeFunctionName(subcmd.name)}`;
+        const lines = [];
+        lines.push(`${funcName}() {`);
+        lines.push('  _arguments \\');
+        // Add flags
+        for (const flag of subcmd.flags) {
+            lines.push('    ' + this.generateFlagSpec(flag) + ' \\');
+        }
+        // Add positional argument completion
+        if (subcmd.acceptsPositional) {
+            const positionalSpec = this.generatePositionalSpec(subcmd.positionalType);
+            lines.push('    ' + positionalSpec);
+        }
+        else {
+            // Remove trailing backslash from last flag
+            if (lines[lines.length - 1].endsWith(' \\')) {
+                lines[lines.length - 1] = lines[lines.length - 1].slice(0, -2);
+            }
+        }
+        lines.push('}');
+        return lines;
+    }
+    /**
+     * Generate flag specification for _arguments
+     */
+    generateFlagSpec(flag) {
+        const parts = [];
+        // Handle mutually exclusive short and long forms
+        if (flag.short) {
+            parts.push(`'(-${flag.short} --${flag.name})'{-${flag.short},--${flag.name}}'`);
+        }
+        else {
+            parts.push(`'--${flag.name}`);
+        }
+        // Add description
+        const escapedDesc = this.escapeDescription(flag.description);
+        parts.push(`[${escapedDesc}]`);
+        // Add value completion if flag takes a value
+        if (flag.takesValue) {
+            if (flag.values && flag.values.length > 0) {
+                // Provide specific value completions
+                const valueList = flag.values.map(v => this.escapeValue(v)).join(' ');
+                parts.push(`:value:(${valueList})`);
+            }
+            else {
+                // Generic value placeholder
+                parts.push(':value:');
+            }
+        }
+        // Close the quote (needed for both short and long forms)
+        parts.push("'");
+        return parts.join('');
+    }
+    /**
+     * Generate positional argument specification
+     */
+    generatePositionalSpec(positionalType) {
+        switch (positionalType) {
+            case 'change-id':
+                return "'*: :_zhuanspec_complete_changes'";
+            case 'spec-id':
+                return "'*: :_zhuanspec_complete_specs'";
+            case 'change-or-spec-id':
+                return "'*: :_zhuanspec_complete_items'";
+            case 'path':
+                return "'*:path:_files'";
+            case 'shell':
+                return "'*:shell:(zsh)'";
+            default:
+                return "'*: :_default'";
+        }
+    }
+    /**
+     * Escape special characters in descriptions
+     */
+    escapeDescription(desc) {
+        return desc
+            .replace(/\\/g, '\\\\')
+            .replace(/'/g, "\\'")
+            .replace(/\[/g, '\\[')
+            .replace(/]/g, '\\]')
+            .replace(/:/g, '\\:');
+    }
+    /**
+     * Escape special characters in values
+     */
+    escapeValue(value) {
+        return value
+            .replace(/\\/g, '\\\\')
+            .replace(/'/g, "\\'")
+            .replace(/ /g, '\\ ');
+    }
+    /**
+     * Sanitize command names for use in function names
+     */
+    sanitizeFunctionName(name) {
+        return name.replace(/-/g, '_');
+    }
+}
+//# sourceMappingURL=zsh-generator.js.map

package/dist/core/completions/installers/zsh-installer.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Installation result information
+ */
+export interface InstallationResult {
+    success: boolean;
+    installedPath?: string;
+    backupPath?: string;
+    isOhMyZsh: boolean;
+    zshrcConfigured?: boolean;
+    message: string;
+    instructions?: string[];
+}
+/**
+ * Installer for Zsh completion scripts.
+ * Supports both Oh My Zsh and standard Zsh configurations.
+ */
+export declare class ZshInstaller {
+    private readonly homeDir;
+    /**
+     * Markers for .zshrc configuration management
+     */
+    private readonly ZSHRC_MARKERS;
+    constructor(homeDir?: string);
+    /**
+     * Check if Oh My Zsh is installed
+     *
+     * @returns true if Oh My Zsh is detected via $ZSH env var or directory exists
+     */
+    isOhMyZshInstalled(): Promise<boolean>;
+    /**
+     * Get the appropriate installation path for the completion script
+     *
+     * @returns Object with installation path and whether it's Oh My Zsh
+     */
+    getInstallationPath(): Promise<{
+        path: string;
+        isOhMyZsh: boolean;
+    }>;
+    /**
+     * Backup an existing completion file if it exists
+     *
+     * @param targetPath - Path to the file to backup
+     * @returns Path to the backup file, or undefined if no backup was needed
+     */
+    backupExistingFile(targetPath: string): Promise<string | undefined>;
+    /**
+     * Get the path to .zshrc file
+     *
+     * @returns Path to .zshrc
+     */
+    private getZshrcPath;
+    /**
+     * Generate .zshrc configuration content
+     *
+     * @param completionsDir - Directory containing completion scripts
+     * @returns Configuration content
+     */
+    private generateZshrcConfig;
+    /**
+     * Configure .zshrc to enable completions
+     * Only applies to standard Zsh (not Oh My Zsh)
+     *
+     * @param completionsDir - Directory containing completion scripts
+     * @returns true if configured successfully, false otherwise
+     */
+    configureZshrc(completionsDir: string): Promise<boolean>;
+    /**
+     * Check if .zshrc has ZhuanSpec configuration markers
+     *
+     * @returns true if .zshrc exists and has markers
+     */
+    private hasZshrcConfig;
+    /**
+     * Check if fpath configuration is needed for a given directory
+     * Used to verify if Oh My Zsh (or other) completions directory is already in fpath
+     *
+     * @param completionsDir - Directory to check for in fpath
+     * @returns true if configuration is needed, false if directory is already referenced
+     */
+    private needsFpathConfig;
+    /**
+     * Remove .zshrc configuration
+     * Used during uninstallation
+     *
+     * @returns true if removed successfully, false otherwise
+     */
+    removeZshrcConfig(): Promise<boolean>;
+    /**
+     * Install the completion script
+     *
+     * @param completionScript - The completion script content to install
+     * @returns Installation result with status and instructions
+     */
+    install(completionScript: string): Promise<InstallationResult>;
+    /**
+     * Generate Oh My Zsh fpath verification guidance
+     *
+     * @param completionsDir - Custom completions directory path
+     * @returns Array of guidance strings, or undefined if not needed
+     */
+    private generateOhMyZshFpathGuidance;
+    /**
+     * Generate user instructions for enabling completions
+     *
+     * @param isOhMyZsh - Whether Oh My Zsh is being used
+     * @param installedPath - Path where the script was installed
+     * @returns Array of instruction strings
+     */
+    private generateInstructions;
+    /**
+     * Uninstall the completion script
+     *
+     * @returns true if uninstalled successfully, false otherwise
+     */
+    uninstall(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Check if completion script is currently installed
+     *
+     * @returns true if the completion script exists
+     */
+    isInstalled(): Promise<boolean>;
+    /**
+     * Get information about the current installation
+     *
+     * @returns Installation status information
+     */
+    getInstallationInfo(): Promise<{
+        installed: boolean;
+        path?: string;
+        isOhMyZsh?: boolean;
+    }>;
+}
+//# sourceMappingURL=zsh-installer.d.ts.map