fix(completions): stop Fish completions falling back to filenames (#1199)

* fix(completions): suppress filesystem fallback in Fish completions

* fix(completions): force files back on for path positionals in Fish

Fish never restores filesystem completion once a matching rule sets
--no-files, so a path positional needs an explicit --force-files rule.
Without it, `openspec store register <TAB>` lost file completion because
the sibling subcommand rules in the same context now carry -f.

Also drop retired "context store" vocabulary from the test fixtures.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(completions): preserve workset member paths in fish

* fix(completions): force Fish path fallback

* fix(completions): harden Fish option handling

* fix(completions): scope Fish path fallback

* fix(completions): match Fish command paths exactly

* fix(completions): skip parent options in Fish paths

---------

Co-authored-by: Clay Good <hi@claygood.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: 3 people

.changeset/fish-completion-no-file-fallback.md

@@ -0,0 +1,5 @@
+---
+'@fission-ai/openspec': patch
+---
+
+Improve Fish completions so command, subcommand, flag, and indexed positional completions no longer fall back to filesystem suggestions unless the target is a real path.

src/core/completions/command-registry.ts

@@ -291,6 +291,7 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
             name: 'path',
             description: 'Directory to use for the store',
             takesValue: true,
+            completionType: 'path',
           },
           {
             name: 'init-git',
@@ -383,6 +384,7 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
         name: 'code-workspace',
         description: 'Also write a VS Code workspace file for the set',
         takesValue: true,
+        completionType: 'path',
       },
       {
         name: 'force',
@@ -414,6 +416,7 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
             description:
               'Member folder as <path> or <name>=<path>; repeatable, first is the primary',
             takesValue: true,
+            completionType: 'path',
           },
           {
             name: 'tool',

src/core/completions/generators/fish-generator.ts

@@ -15,36 +15,31 @@ export class FishGenerator implements CompletionGenerator {
    * @returns Fish completion script as a string
    */
   generate(commands: CommandDefinition[]): string {
-    // Build top-level commands using push() for loop clarity
     const topLevelLines: string[] = [];
     for (const cmd of commands) {
       topLevelLines.push(`# ${cmd.name} command`);
       topLevelLines.push(
-        `complete -c openspec -n '__fish_openspec_no_subcommand' -a '${cmd.name}' -d '${this.escapeDescription(cmd.description)}'`
+        `complete -c openspec -n '__fish_openspec_no_subcommand' -f -a '${cmd.name}' -d '${this.escapeDescription(cmd.description)}'`
       );
     }
     const topLevelCommands = topLevelLines.join('\n');
 
-    // Build command-specific completions using push() for loop clarity
     const commandCompletionLines: string[] = [];
     for (const cmd of commands) {
       commandCompletionLines.push(...this.generateCommandCompletions(cmd));
       commandCompletionLines.push('');
     }
     const commandCompletions = commandCompletionLines.join('\n');
 
-    // Static helper functions from template
     const helperFunctions = FISH_STATIC_HELPERS;
-
-    // Dynamic completion helpers from template
     const dynamicHelpers = FISH_DYNAMIC_HELPERS;
 
-    // Assemble final script with template literal
     return `# Fish completion script for OpenSpec CLI
 # Auto-generated - do not edit manually
 
 ${helperFunctions}
 ${dynamicHelpers}
+complete -c openspec -l no-color -f -d 'Disable color output'
 ${topLevelCommands}
 
 ${commandCompletions}`;
@@ -56,43 +51,67 @@ ${commandCompletions}`;
   private generateCommandCompletions(cmd: CommandDefinition): string[] {
     const lines: string[] = [];
 
-    // If command has subcommands
     if (cmd.subcommands && cmd.subcommands.length > 0) {
-      // Add subcommand completions
+      const commandCondition = this.commandPathCondition([cmd.name]);
+      const parentValueFlags = this.collectValueFlags(cmd.flags);
+      const noSubcommandCondition = cmd.subcommands
+        .map((subcmd) => `not ${this.commandPathCondition([cmd.name, subcmd.name], parentValueFlags)}`)
+        .join('; and ');
       for (const subcmd of cmd.subcommands) {
         lines.push(
-          `complete -c openspec -n '__fish_openspec_using_subcommand ${cmd.name}; and not __fish_openspec_using_subcommand ${subcmd.name}' -a '${subcmd.name}' -d '${this.escapeDescription(subcmd.description)}'`
+          `complete -c openspec -n '${commandCondition}; and ${noSubcommandCondition}' -f -a '${subcmd.name}' -d '${this.escapeDescription(subcmd.description)}'`
         );
       }
       lines.push('');
 
-      // Add flags for parent command
       for (const flag of cmd.flags) {
-        lines.push(...this.generateFlagCompletion(flag, `__fish_openspec_using_subcommand ${cmd.name}`));
+        lines.push(...this.generateFlagCompletion(flag, commandCondition));
       }
 
-      // Add completions for each subcommand
       for (const subcmd of cmd.subcommands) {
+        const subcommandCondition = this.commandPathCondition([cmd.name, subcmd.name], parentValueFlags);
         lines.push(`# ${cmd.name} ${subcmd.name} flags`);
+        lines.push(`complete -c openspec -n '${subcommandCondition}' -f`);
         for (const flag of subcmd.flags) {
-          lines.push(...this.generateFlagCompletion(flag, `__fish_openspec_using_subcommand ${cmd.name}; and __fish_openspec_using_subcommand ${subcmd.name}`));
+          lines.push(...this.generateFlagCompletion(flag, subcommandCondition));
         }
 
-        // Add positional completions for subcommand
-        if (subcmd.acceptsPositional) {
-          lines.push(...this.generatePositionalCompletion(subcmd.positionalType, `__fish_openspec_using_subcommand ${cmd.name}; and __fish_openspec_using_subcommand ${subcmd.name}`));
+        if (subcmd.positionals?.length) {
+          lines.push(
+            ...this.generateIndexedPositionalCompletions(
+              subcmd.positionals,
+              subcommandCondition,
+              this.collectValueFlags(cmd.flags, subcmd.flags),
+              2
+            )
+          );
+        } else if (subcmd.acceptsPositional) {
+          lines.push(
+            ...this.generatePositionalCompletion(
+              subcmd.positionalType,
+              subcommandCondition
+            )
+          );
         }
       }
     } else {
-      // Command without subcommands
       lines.push(`# ${cmd.name} flags`);
+      lines.push(`complete -c openspec -n '__fish_openspec_using_command_path ${cmd.name}' -f`);
       for (const flag of cmd.flags) {
-        lines.push(...this.generateFlagCompletion(flag, `__fish_openspec_using_subcommand ${cmd.name}`));
+        lines.push(...this.generateFlagCompletion(flag, `__fish_openspec_using_command_path ${cmd.name}`));
       }
 
-      // Add positional completions
-      if (cmd.acceptsPositional) {
-        lines.push(...this.generatePositionalCompletion(cmd.positionalType, `__fish_openspec_using_subcommand ${cmd.name}`));
+      if (cmd.positionals?.length) {
+        lines.push(
+          ...this.generateIndexedPositionalCompletions(
+            cmd.positionals,
+            `__fish_openspec_using_command_path ${cmd.name}`,
+            this.collectValueFlags(cmd.flags),
+            1
+          )
+        );
+      } else if (cmd.acceptsPositional) {
+        lines.push(...this.generatePositionalCompletion(cmd.positionalType, `__fish_openspec_using_command_path ${cmd.name}`));
       }
     }
 
@@ -104,44 +123,31 @@ ${commandCompletions}`;
    */
   private generateFlagCompletion(flag: FlagDefinition, condition: string): string[] {
     const lines: string[] = [];
-    const longFlag = `--${flag.name}`;
-    const shortFlag = flag.short ? `-${flag.short}` : undefined;
+    const description = this.escapeDescription(flag.description);
+    const shortFlag = flag.short ? `-s ${flag.short} ` : '';
+    const flagOptions = `${shortFlag}-l ${flag.name}`;
 
     if (flag.takesValue && flag.values) {
-      // Flag with enum values
       for (const value of flag.values) {
-        if (shortFlag) {
-          lines.push(
-            `complete -c openspec -n '${condition}' -s ${flag.short} -l ${flag.name} -a '${value}' -d '${this.escapeDescription(flag.description)}'`
-          );
-        } else {
-          lines.push(
-            `complete -c openspec -n '${condition}' -l ${flag.name} -a '${value}' -d '${this.escapeDescription(flag.description)}'`
-          );
-        }
-      }
-    } else if (flag.takesValue) {
-      // Flag that takes a value but no specific values defined
-      if (shortFlag) {
-        lines.push(
-          `complete -c openspec -n '${condition}' -s ${flag.short} -l ${flag.name} -r -d '${this.escapeDescription(flag.description)}'`
-        );
-      } else {
         lines.push(
-          `complete -c openspec -n '${condition}' -l ${flag.name} -r -d '${this.escapeDescription(flag.description)}'`
+          `complete -c openspec -n '${condition}' ${flagOptions} -r -f -a '${value}' -d '${description}'`
         );
       }
-    } else {
-      // Boolean flag
-      if (shortFlag) {
-        lines.push(
-          `complete -c openspec -n '${condition}' -s ${flag.short} -l ${flag.name} -d '${this.escapeDescription(flag.description)}'`
-        );
-      } else {
+    } else if (flag.takesValue) {
+      lines.push(`complete -c openspec -n '${condition}' ${flagOptions} -r -f -d '${description}'`);
+      if (flag.completionType === 'path') {
+        const optionNames = [`--${flag.name}`, ...(flag.short ? [`-${flag.short}`] : [])];
         lines.push(
-          `complete -c openspec -n '${condition}' -l ${flag.name} -d '${this.escapeDescription(flag.description)}'`
+          `complete -c openspec -n '${condition}; and __fish_openspec_completing_option_value ${optionNames.join(' ')}' ${flagOptions} -r -F -d '${description}'`
         );
+        if (flag.short) {
+          lines.push(
+            `complete -c openspec -n '${condition}' ${flagOptions} -r -f -a '(__fish_openspec_complete_attached_short_path -${flag.short})' -d '${description}'`
+          );
+        }
       }
+    } else {
+      lines.push(`complete -c openspec -n '${condition}' ${flagOptions} -f -d '${description}'`);
     }
 
     return lines;
@@ -170,22 +176,73 @@ ${commandCompletions}`;
         lines.push(`complete -c openspec -n '${condition}' -a 'zsh bash fish powershell' -f`);
         break;
       case 'path':
-        // Fish automatically completes files, no need to specify
+        // -F re-enables filesystem completion: sibling rules in the same
+        // context carry -f, and Fish never restores files without --force-files.
+        lines.push(`complete -c openspec -n '${condition}' -F`);
         break;
+      default:
+        lines.push(`complete -c openspec -n '${condition}' -f`);
+        break;
+    }
+
+    return lines;
+  }
+
+  /**
+   * Generate indexed positional completions.
+   */
+  private generateIndexedPositionalCompletions(
+    positionals: NonNullable<CommandDefinition['positionals']>,
+    condition: string,
+    valueFlags: string[],
+    depth: number
+  ): string[] {
+    const lines: string[] = [];
+
+    for (const [index, positional] of positionals.entries()) {
+      const indexCondition = `${condition}; and __fish_openspec_positional_index ${index} ${depth}${valueFlags.length ? ` ${valueFlags.join(' ')}` : ''}`;
+      lines.push(...this.generatePositionalCompletion(positional.type, indexCondition));
     }
 
     return lines;
   }
 
+  /**
+   * Collect the long and short names for flags that consume the next token.
+   */
+  private collectValueFlags(...flagGroups: FlagDefinition[][]): string[] {
+    const flags = new Set<string>();
+
+    for (const group of flagGroups) {
+      for (const flag of group) {
+        if (!flag.takesValue) {
+          continue;
+        }
+
+        flags.add(`--${flag.name}`);
+        if (flag.short) {
+          flags.add(`-${flag.short}`);
+        }
+      }
+    }
+
+    return [...flags];
+  }
+
+  /**
+   * Build a Fish condition that matches command words in their actual slots.
+   */
+  private commandPathCondition(path: string[], valueFlags: string[] = []): string {
+    const valueFlagArguments = valueFlags.length ? ` -- ${valueFlags.join(' ')}` : '';
+    return `__fish_openspec_using_command_path ${path.join(' ')}${valueFlagArguments}`;
+  }
 
   /**
    * Escape description text for Fish
    */
   private escapeDescription(description: string): string {
     return description
-      .replace(/\\/g, '\\\\')  // Backslashes first
-      .replace(/'/g, "\\'")    // Single quotes
-      .replace(/\$/g, '\\$')   // Dollar signs (prevents $())
-      .replace(/`/g, '\\`');   // Backticks
+      .replace(/\\/g, '\\\\') // Backslashes first
+      .replace(/'/g, "\\'"); // Single quotes
   }
 }