@dedesfr/prompter 0.6.15 → 0.7.0

package/src/core/completions/command-registry.ts

@@ -0,0 +1,382 @@
+import { CommandDefinition, FlagDefinition } from './types.js';
+
+/**
+ * Common flags used across multiple commands
+ */
+const COMMON_FLAGS = {
+  json: {
+    name: 'json',
+    description: 'Output as JSON',
+  } as FlagDefinition,
+  jsonValidation: {
+    name: 'json',
+    description: 'Output validation results as JSON',
+  } as FlagDefinition,
+  strict: {
+    name: 'strict',
+    description: 'Enable strict validation mode',
+  } as FlagDefinition,
+  noInteractive: {
+    name: 'no-interactive',
+    description: 'Disable interactive prompts',
+  } as FlagDefinition,
+  type: {
+    name: 'type',
+    description: 'Specify item type when ambiguous',
+    takesValue: true,
+    values: ['change', 'spec'],
+  } as FlagDefinition,
+} as const;
+
+/**
+ * Registry of all Prompter CLI commands with their flags and metadata.
+ * This registry is used to generate shell completion scripts.
+ */
+export const COMMAND_REGISTRY: CommandDefinition[] = [
+  {
+    name: 'init',
+    description: 'Initialize Prompter in your project',
+    acceptsPositional: true,
+    positionalType: 'path',
+    flags: [
+      {
+        name: 'tools',
+        description: 'Configure AI tools non-interactively (e.g., "all", "none", or comma-separated tool IDs)',
+        takesValue: true,
+      },
+    ],
+  },
+  {
+    name: 'update',
+    description: 'Update Prompter instruction files',
+    acceptsPositional: true,
+    positionalType: 'path',
+    flags: [],
+  },
+  {
+    name: 'list',
+    description: 'List items (changes by default, or specs with --specs)',
+    flags: [
+      {
+        name: 'specs',
+        description: 'List specs instead of changes',
+      },
+      {
+        name: 'changes',
+        description: 'List changes explicitly (default)',
+      },
+    ],
+  },
+  {
+    name: 'view',
+    description: 'Display an interactive dashboard of specs and changes',
+    flags: [],
+  },
+  {
+    name: 'validate',
+    description: 'Validate changes and specs',
+    acceptsPositional: true,
+    positionalType: 'change-or-spec-id',
+    flags: [
+      {
+        name: 'all',
+        description: 'Validate all changes and specs',
+      },
+      {
+        name: 'changes',
+        description: 'Validate all changes',
+      },
+      {
+        name: 'specs',
+        description: 'Validate all specs',
+      },
+      COMMON_FLAGS.type,
+      COMMON_FLAGS.strict,
+      COMMON_FLAGS.jsonValidation,
+      {
+        name: 'concurrency',
+        description: 'Max concurrent validations (defaults to env PROMPTER_CONCURRENCY or 6)',
+        takesValue: true,
+      },
+      COMMON_FLAGS.noInteractive,
+    ],
+  },
+  {
+    name: 'show',
+    description: 'Show a change or spec',
+    acceptsPositional: true,
+    positionalType: 'change-or-spec-id',
+    flags: [
+      COMMON_FLAGS.json,
+      COMMON_FLAGS.type,
+      COMMON_FLAGS.noInteractive,
+      {
+        name: 'deltas-only',
+        description: 'Show only deltas (JSON only, change-specific)',
+      },
+      {
+        name: 'requirements-only',
+        description: 'Alias for --deltas-only (deprecated, change-specific)',
+      },
+      {
+        name: 'requirements',
+        description: 'Show only requirements, exclude scenarios (JSON only, spec-specific)',
+      },
+      {
+        name: 'no-scenarios',
+        description: 'Exclude scenario content (JSON only, spec-specific)',
+      },
+      {
+        name: 'requirement',
+        short: 'r',
+        description: 'Show specific requirement by ID (JSON only, spec-specific)',
+        takesValue: true,
+      },
+    ],
+  },
+  {
+    name: 'archive',
+    description: 'Archive a completed change and update main specs',
+    acceptsPositional: true,
+    positionalType: 'change-id',
+    flags: [
+      {
+        name: 'yes',
+        short: 'y',
+        description: 'Skip confirmation prompts',
+      },
+      {
+        name: 'skip-specs',
+        description: 'Skip spec update operations',
+      },
+      {
+        name: 'no-validate',
+        description: 'Skip validation (not recommended)',
+      },
+    ],
+  },
+  {
+    name: 'feedback',
+    description: 'Submit feedback about Prompter',
+    acceptsPositional: true,
+    flags: [
+      {
+        name: 'body',
+        description: 'Detailed description for the feedback',
+        takesValue: true,
+      },
+    ],
+  },
+  {
+    name: 'change',
+    description: 'Manage Prompter change proposals (deprecated)',
+    flags: [],
+    subcommands: [
+      {
+        name: 'show',
+        description: 'Show a change proposal',
+        acceptsPositional: true,
+        positionalType: 'change-id',
+        flags: [
+          COMMON_FLAGS.json,
+          {
+            name: 'deltas-only',
+            description: 'Show only deltas (JSON only)',
+          },
+          {
+            name: 'requirements-only',
+            description: 'Alias for --deltas-only (deprecated)',
+          },
+          COMMON_FLAGS.noInteractive,
+        ],
+      },
+      {
+        name: 'list',
+        description: 'List all active changes (deprecated)',
+        flags: [
+          COMMON_FLAGS.json,
+          {
+            name: 'long',
+            description: 'Show id and title with counts',
+          },
+        ],
+      },
+      {
+        name: 'validate',
+        description: 'Validate a change proposal',
+        acceptsPositional: true,
+        positionalType: 'change-id',
+        flags: [
+          COMMON_FLAGS.strict,
+          COMMON_FLAGS.jsonValidation,
+          COMMON_FLAGS.noInteractive,
+        ],
+      },
+    ],
+  },
+  {
+    name: 'spec',
+    description: 'Manage Prompter specifications',
+    flags: [],
+    subcommands: [
+      {
+        name: 'show',
+        description: 'Show a specification',
+        acceptsPositional: true,
+        positionalType: 'spec-id',
+        flags: [
+          COMMON_FLAGS.json,
+          {
+            name: 'requirements',
+            description: 'Show only requirements, exclude scenarios (JSON only)',
+          },
+          {
+            name: 'no-scenarios',
+            description: 'Exclude scenario content (JSON only)',
+          },
+          {
+            name: 'requirement',
+            short: 'r',
+            description: 'Show specific requirement by ID (JSON only)',
+            takesValue: true,
+          },
+          COMMON_FLAGS.noInteractive,
+        ],
+      },
+      {
+        name: 'list',
+        description: 'List all specifications',
+        flags: [
+          COMMON_FLAGS.json,
+          {
+            name: 'long',
+            description: 'Show id and title with counts',
+          },
+        ],
+      },
+      {
+        name: 'validate',
+        description: 'Validate a specification',
+        acceptsPositional: true,
+        positionalType: 'spec-id',
+        flags: [
+          COMMON_FLAGS.strict,
+          COMMON_FLAGS.jsonValidation,
+          COMMON_FLAGS.noInteractive,
+        ],
+      },
+    ],
+  },
+  {
+    name: 'completion',
+    description: 'Manage shell completions for Prompter CLI',
+    flags: [],
+    subcommands: [
+      {
+        name: 'generate',
+        description: 'Generate completion script for a shell (outputs to stdout)',
+        acceptsPositional: true,
+        positionalType: 'shell',
+        flags: [],
+      },
+      {
+        name: 'install',
+        description: 'Install completion script for a shell',
+        acceptsPositional: true,
+        positionalType: 'shell',
+        flags: [
+          {
+            name: 'verbose',
+            description: 'Show detailed installation output',
+          },
+        ],
+      },
+      {
+        name: 'uninstall',
+        description: 'Uninstall completion script for a shell',
+        acceptsPositional: true,
+        positionalType: 'shell',
+        flags: [
+          {
+            name: 'yes',
+            short: 'y',
+            description: 'Skip confirmation prompts',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    name: 'config',
+    description: 'View and modify global Prompter configuration',
+    flags: [
+      {
+        name: 'scope',
+        description: 'Config scope (only "global" supported currently)',
+        takesValue: true,
+        values: ['global'],
+      },
+    ],
+    subcommands: [
+      {
+        name: 'path',
+        description: 'Show config file location',
+        flags: [],
+      },
+      {
+        name: 'list',
+        description: 'Show all current settings',
+        flags: [
+          COMMON_FLAGS.json,
+        ],
+      },
+      {
+        name: 'get',
+        description: 'Get a specific value (raw, scriptable)',
+        acceptsPositional: true,
+        flags: [],
+      },
+      {
+        name: 'set',
+        description: 'Set a value (auto-coerce types)',
+        acceptsPositional: true,
+        flags: [
+          {
+            name: 'string',
+            description: 'Force value to be stored as string',
+          },
+          {
+            name: 'allow-unknown',
+            description: 'Allow setting unknown keys',
+          },
+        ],
+      },
+      {
+        name: 'unset',
+        description: 'Remove a key (revert to default)',
+        acceptsPositional: true,
+        flags: [],
+      },
+      {
+        name: 'reset',
+        description: 'Reset configuration to defaults',
+        flags: [
+          {
+            name: 'all',
+            description: 'Reset all configuration (required)',
+          },
+          {
+            name: 'yes',
+            short: 'y',
+            description: 'Skip confirmation prompts',
+          },
+        ],
+      },
+      {
+        name: 'edit',
+        description: 'Open config in $EDITOR',
+        flags: [],
+      },
+    ],
+  },
+];

package/src/core/completions/completion-provider.ts

@@ -0,0 +1,128 @@
+import { getActiveChangeIds, getSpecIds } from '../../utils/item-discovery.js';
+
+/**
+ * Cache entry for completion data
+ */
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+}
+
+/**
+ * Provides dynamic completion suggestions for Prompter items (changes and specs).
+ * Implements a 2-second cache to avoid excessive file system operations during
+ * tab completion.
+ */
+export class CompletionProvider {
+  private readonly cacheTTL: number;
+  private changeCache: CacheEntry<string[]> | null = null;
+  private specCache: CacheEntry<string[]> | null = null;
+
+  /**
+   * Creates a new completion provider
+   *
+   * @param cacheTTLMs - Cache time-to-live in milliseconds (default: 2000ms)
+   * @param projectRoot - Project root directory (default: process.cwd())
+   */
+  constructor(
+    private readonly cacheTTLMs: number = 2000,
+    private readonly projectRoot: string = process.cwd()
+  ) {
+    this.cacheTTL = cacheTTLMs;
+  }
+
+  /**
+   * Get all active change IDs for completion
+   *
+   * @returns Array of change IDs
+   */
+  async getChangeIds(): Promise<string[]> {
+    const now = Date.now();
+
+    // Check if cache is valid
+    if (this.changeCache && now - this.changeCache.timestamp < this.cacheTTL) {
+      return this.changeCache.data;
+    }
+
+    // Fetch fresh data
+    const changeIds = await getActiveChangeIds(this.projectRoot);
+
+    // Update cache
+    this.changeCache = {
+      data: changeIds,
+      timestamp: now,
+    };
+
+    return changeIds;
+  }
+
+  /**
+   * Get all spec IDs for completion
+   *
+   * @returns Array of spec IDs
+   */
+  async getSpecIds(): Promise<string[]> {
+    const now = Date.now();
+
+    // Check if cache is valid
+    if (this.specCache && now - this.specCache.timestamp < this.cacheTTL) {
+      return this.specCache.data;
+    }
+
+    // Fetch fresh data
+    const specIds = await getSpecIds(this.projectRoot);
+
+    // Update cache
+    this.specCache = {
+      data: specIds,
+      timestamp: now,
+    };
+
+    return specIds;
+  }
+
+  /**
+   * Get both change and spec IDs for completion
+   *
+   * @returns Object with changeIds and specIds arrays
+   */
+  async getAllIds(): Promise<{ changeIds: string[]; specIds: string[] }> {
+    const [changeIds, specIds] = await Promise.all([
+      this.getChangeIds(),
+      this.getSpecIds(),
+    ]);
+
+    return { changeIds, specIds };
+  }
+
+  /**
+   * Clear all cached data
+   */
+  clearCache(): void {
+    this.changeCache = null;
+    this.specCache = null;
+  }
+
+  /**
+   * Get cache statistics for debugging
+   *
+   * @returns Cache status information
+   */
+  getCacheStats(): {
+    changeCache: { valid: boolean; age?: number };
+    specCache: { valid: boolean; age?: number };
+  } {
+    const now = Date.now();
+
+    return {
+      changeCache: {
+        valid: this.changeCache !== null && now - this.changeCache.timestamp < this.cacheTTL,
+        age: this.changeCache ? now - this.changeCache.timestamp : undefined,
+      },
+      specCache: {
+        valid: this.specCache !== null && now - this.specCache.timestamp < this.cacheTTL,
+        age: this.specCache ? now - this.specCache.timestamp : undefined,
+      },
+    };
+  }
+}

package/src/core/completions/generators/bash-generator.ts

@@ -0,0 +1,191 @@
+import { CompletionGenerator, CommandDefinition, FlagDefinition } from '../types.js';
+import { BASH_DYNAMIC_HELPERS } from '../templates/bash-templates.js';
+
+/**
+ * Generates Bash completion scripts for the Prompter CLI.
+ * Follows Bash completion conventions using complete builtin and COMPREPLY array.
+ */
+export class BashGenerator implements CompletionGenerator {
+  readonly shell = 'bash' as const;
+
+  /**
+   * Generate a Bash completion script
+   *
+   * @param commands - Command definitions to generate completions for
+   * @returns Bash completion script as a string
+   */
+  generate(commands: CommandDefinition[]): string {
+    // Build command list for top-level completions
+    const commandList = commands.map(c => this.escapeCommandName(c.name)).join(' ');
+
+    // Build command cases using push() for loop clarity
+    const caseLines: string[] = [];
+    for (const cmd of commands) {
+      caseLines.push(`    ${cmd.name})`);
+      caseLines.push(...this.generateCommandCase(cmd, '      '));
+      caseLines.push('      ;;');
+    }
+    const commandCases = caseLines.join('\n');
+
+    // Dynamic completion helpers from template
+    const helpers = BASH_DYNAMIC_HELPERS;
+
+    // Assemble final script with template literal
+    return `# Bash completion script for Prompter CLI
+# Auto-generated - do not edit manually
+
+_prompter_completion() {
+  local cur prev words cword
+
+  # Use _init_completion if available (from bash-completion package)
+  # The -n : option prevents colons from being treated as word separators
+  # (important for spec/change IDs that may contain colons)
+  # Otherwise, fall back to manual initialization
+  if declare -F _init_completion >/dev/null 2>&1; then
+    _init_completion -n : || return
+  else
+    # Manual fallback when bash-completion is not installed
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    words=("\${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+  fi
+
+  local cmd="\${words[1]}"
+  local subcmd="\${words[2]}"
+
+  # Top-level commands
+  if [[ $cword -eq 1 ]]; then
+    local commands="${commandList}"
+    COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+    return 0
+  fi
+
+  # Command-specific completion
+  case "$cmd" in
+${commandCases}
+  esac
+
+  return 0
+}
+
+${helpers}
+complete -F _prompter_completion prompter
+`;
+  }
+
+  /**
+   * Generate completion case logic for a command
+   */
+  private generateCommandCase(cmd: CommandDefinition, indent: string): string[] {
+    const lines: string[] = [];
+
+    // Handle subcommands
+    if (cmd.subcommands && cmd.subcommands.length > 0) {
+      // First, check if user is typing a flag for the parent command
+      if (cmd.flags.length > 0) {
+        lines.push(`${indent}if [[ "$cur" == -* ]]; then`);
+        const flags = cmd.flags.map(f => {
+          const parts: string[] = [];
+          if (f.short) parts.push(`-${f.short}`);
+          parts.push(`--${f.name}`);
+          return parts.join(' ');
+        }).join(' ');
+        lines.push(`${indent}  local flags="${flags}"`);
+        lines.push(`${indent}  COMPREPLY=($(compgen -W "$flags" -- "$cur"))`);
+        lines.push(`${indent}  return 0`);
+        lines.push(`${indent}fi`);
+        lines.push('');
+      }
+
+      lines.push(`${indent}if [[ $cword -eq 2 ]]; then`);
+      lines.push(`${indent}  local subcommands="` + cmd.subcommands.map(s => this.escapeCommandName(s.name)).join(' ') + '"');
+      lines.push(`${indent}  COMPREPLY=($(compgen -W "$subcommands" -- "$cur"))`);
+      lines.push(`${indent}  return 0`);
+      lines.push(`${indent}fi`);
+      lines.push('');
+      lines.push(`${indent}case "$subcmd" in`);
+
+      for (const subcmd of cmd.subcommands) {
+        lines.push(`${indent}  ${subcmd.name})`);
+        lines.push(...this.generateArgumentCompletion(subcmd, indent + '    '));
+        lines.push(`${indent}    ;;`);
+      }
+
+      lines.push(`${indent}esac`);
+    } else {
+      // No subcommands, just complete arguments
+      lines.push(...this.generateArgumentCompletion(cmd, indent));
+    }
+
+    return lines;
+  }
+
+  /**
+   * Generate argument completion (flags and positional arguments)
+   */
+  private generateArgumentCompletion(cmd: CommandDefinition, indent: string): string[] {
+    const lines: string[] = [];
+
+    // Check for flag completion
+    if (cmd.flags.length > 0) {
+      lines.push(`${indent}if [[ "$cur" == -* ]]; then`);
+      const flags = cmd.flags.map(f => {
+        const parts: string[] = [];
+        if (f.short) parts.push(`-${f.short}`);
+        parts.push(`--${f.name}`);
+        return parts.join(' ');
+      }).join(' ');
+      lines.push(`${indent}  local flags="${flags}"`);
+      lines.push(`${indent}  COMPREPLY=($(compgen -W "$flags" -- "$cur"))`);
+      lines.push(`${indent}  return 0`);
+      lines.push(`${indent}fi`);
+      lines.push('');
+    }
+
+    // Handle positional completions
+    if (cmd.acceptsPositional) {
+      lines.push(...this.generatePositionalCompletion(cmd.positionalType, indent));
+    }
+
+    return lines;
+  }
+
+  /**
+   * Generate positional argument completion based on type
+   */
+  private generatePositionalCompletion(positionalType: string | undefined, indent: string): string[] {
+    const lines: string[] = [];
+
+    switch (positionalType) {
+      case 'change-id':
+        lines.push(`${indent}_prompter_complete_changes`);
+        break;
+      case 'spec-id':
+        lines.push(`${indent}_prompter_complete_specs`);
+        break;
+      case 'change-or-spec-id':
+        lines.push(`${indent}_prompter_complete_items`);
+        break;
+      case 'shell':
+        lines.push(`${indent}local shells="zsh bash fish powershell"`);
+        lines.push(`${indent}COMPREPLY=($(compgen -W "$shells" -- "$cur"))`);
+        break;
+      case 'path':
+        lines.push(`${indent}COMPREPLY=($(compgen -f -- "$cur"))`);
+        break;
+    }
+
+    return lines;
+  }
+
+
+  /**
+   * Escape command/subcommand names for safe use in Bash scripts
+   */
+  private escapeCommandName(name: string): string {
+    // Escape shell metacharacters to prevent command injection
+    return name.replace(/["\$`\\]/g, '\\$&');
+  }
+}