feat: add short flag support for CLI options and enhance completion handling

Author: dreyfus92

demo.cac.ts

@@ -10,8 +10,8 @@ cli
 
 cli
   .command('dev', 'Start dev server')
-  .option('--host [host]', `Specify hostname`)
-  .option('--port <port>', `Specify port`)
+  .option('-H, --host [host]', `Specify hostname`)
+  .option('-p, --port <port>', `Specify port`)
   .action((options) => {});
 
 cli.command('dev build', 'Build project').action((options) => {});

src/cac.ts

@@ -39,11 +39,15 @@ export default function tab(instance: CAC): Completion {
 
     // Add command options
     for (const option of [...instance.globalCommand.options, ...cmd.options]) {
+      // Extract short flag from the name if it exists (e.g., "-c, --config" -> "c")
+      const shortFlag = option.name.match(/^-([a-zA-Z]), --/)?.[1];
+      
       completion.addOption(
         commandName,
-        `--${option.name}`,
+        `--${option.name.replace(/^-[a-zA-Z], --/, '')}`, // Remove the short flag part if it exists
         option.description || '',
-        async () => []
+        async () => [],
+        shortFlag
       );
     }
   }

src/citty.ts

@@ -65,13 +65,19 @@ async function handleSubCommands<T extends ArgsDef = ArgsDef>(
         if (conf.type === 'positional') {
           continue;
         }
+        // Extract alias from the config if it exists
+        const shortFlag = typeof conf === 'object' && 'alias' in conf ? 
+          (Array.isArray(conf.alias) ? conf.alias[0] : conf.alias) : 
+          undefined;
+        
         completion.addOption(
           name,
           `--${argName}`,
           conf.description ?? '',
           async (previousArgs, toComplete, endsWithSpace) => {
             return [];
-          }
+          },
+          shortFlag
         );
       }
     }

src/index.ts

@@ -75,6 +75,7 @@ type Handler = (
 type Option = {
   description: string;
   handler: Handler;
+  alias?: string;
 };
 
 type Command = {
@@ -117,13 +118,14 @@ export class Completion {
     command: string,
     option: string,
     description: string,
-    handler: Handler
+    handler: Handler,
+    alias?: string
   ) {
     const cmd = this.commands.get(command);
     if (!cmd) {
       throw new Error(`Command ${command} not found.`);
     }
-    cmd.options.set(option, { description, handler });
+    cmd.options.set(option, { description, handler, alias });
     return option;
   }
 
@@ -233,7 +235,12 @@ export class Completion {
     toComplete: string,
     endsWithSpace: boolean
   ): boolean {
-    return lastPrevArg?.startsWith('--') || toComplete.startsWith('--');
+    return (
+      lastPrevArg?.startsWith('--') ||
+      lastPrevArg?.startsWith('-') ||
+      toComplete.startsWith('--') ||
+      toComplete.startsWith('-')
+    );
   }
 
   private shouldCompleteCommands(
@@ -255,17 +262,29 @@ export class Completion {
     let valueToComplete = toComplete;
 
     if (toComplete.includes('=')) {
-      // Handle --flag=value case
+      // Handle --flag=value or -f=value case
       const parts = toComplete.split('=');
       flagName = parts[0];
       valueToComplete = parts[1] || '';
-    } else if (lastPrevArg?.startsWith('--')) {
-      // Handle --flag value case
+    } else if (lastPrevArg?.startsWith('-')) {
+      // Handle --flag value or -f value case
       flagName = lastPrevArg;
     }
 
     if (flagName) {
-      const option = command.options.get(flagName);
+      // Try to find the option by long name or alias
+      let option = command.options.get(flagName);
+      if (!option) {
+        // If not found by direct match, try to find by alias
+        for (const [name, opt] of command.options) {
+          if (opt.alias && `-${opt.alias}` === flagName) {
+            option = opt;
+            flagName = name; // Use the long name for completion
+            break;
+          }
+        }
+      }
+      
       if (option) {
         const suggestions = await option.handler(
           previousArgs,
@@ -286,9 +305,21 @@ export class Completion {
     }
 
     // Handle flag name completion
-    if (toComplete.startsWith('--')) {
+    if (toComplete.startsWith('-')) {
+      const isShortFlag = toComplete.startsWith('-') && !toComplete.startsWith('--');
+      
       for (const [name, option] of command.options) {
-        if (name.startsWith(toComplete)) {
+        // For short flags (-), only show aliases
+        if (isShortFlag) {
+          if (option.alias && `-${option.alias}`.startsWith(toComplete)) {
+            this.completions.push({
+              value: `-${option.alias}`,
+              description: option.description,
+            });
+          }
+        }
+        // For long flags (--), show the full names
+        else if (name.startsWith(toComplete)) {
           this.completions.push({
             value: name,
             description: option.description,

tests/__snapshots__/cli.test.ts.snap

@@ -6,6 +6,16 @@ exports[`cli completion tests for cac > cli option completion tests > should com
 "
 `;
 
+exports[`cli completion tests for cac > cli option completion tests > should complete option for partial input '{ partial: '-H', expected: '-H' }' 1`] = `
+":4
+"
+`;
+
+exports[`cli completion tests for cac > cli option completion tests > should complete option for partial input '{ partial: '-p', expected: '-p' }' 1`] = `
+":4
+"
+`;
+
 exports[`cli completion tests for cac > cli option exclusion tests > should not suggest already specified option '{ specified: '--config', shouldNotContain: '--config' }' 1`] = `
 ":4
 "
@@ -74,6 +84,29 @@ index.ts	Index file
 "
 `;
 
+exports[`cli completion tests for cac > short flag handling > should handle global short flags 1`] = `
+":4
+"
+`;
+
+exports[`cli completion tests for cac > short flag handling > should handle short flag value completion 1`] = `
+":4
+"
+`;
+
+exports[`cli completion tests for cac > short flag handling > should handle short flag with equals sign 1`] = `
+":4
+"
+`;
+
+exports[`cli completion tests for cac > short flag handling > should not show duplicate options when short flag is used 1`] = `
+"--config	Use specified config file
+--mode	Set env mode
+--logLevel	info | warn | error | silent
+:4
+"
+`;
+
 exports[`cli completion tests for cac > should complete cli options 1`] = `
 "dev	Start dev server
 lint	Lint project
@@ -87,6 +120,16 @@ exports[`cli completion tests for citty > cli option completion tests > should c
 "
 `;
 
+exports[`cli completion tests for citty > cli option completion tests > should complete option for partial input '{ partial: '-H', expected: '-H' }' 1`] = `
+":4
+"
+`;
+
+exports[`cli completion tests for citty > cli option completion tests > should complete option for partial input '{ partial: '-p', expected: '-p' }' 1`] = `
+":4
+"
+`;
+
 exports[`cli completion tests for citty > cli option exclusion tests > should not suggest already specified option '{ specified: '--config', shouldNotContain: '--config' }' 1`] = `
 ":4
 "
@@ -135,6 +178,29 @@ exports[`cli completion tests for citty > edge case completions for end with spa
 "
 `;
 
+exports[`cli completion tests for citty > short flag handling > should handle global short flags 1`] = `
+":4
+"
+`;
+
+exports[`cli completion tests for citty > short flag handling > should handle short flag value completion 1`] = `
+":4
+"
+`;
+
+exports[`cli completion tests for citty > short flag handling > should handle short flag with equals sign 1`] = `
+":4
+"
+`;
+
+exports[`cli completion tests for citty > short flag handling > should not show duplicate options when short flag is used 1`] = `
+"--config	Use specified config file
+--mode	Set env mode
+--logLevel	info | warn | error | silent
+:4
+"
+`;
+
 exports[`cli completion tests for citty > should complete cli options 1`] = `
 "dev	Start dev server
 lint	Lint project

tests/cli.test.ts

@@ -25,7 +25,11 @@ describe.each(cliTools)('cli completion tests for %s', (cliTool) => {
   });
 
   describe('cli option completion tests', () => {
-    const optionTests = [{ partial: '--p', expected: '--port' }];
+    const optionTests = [
+      { partial: '--p', expected: '--port' },
+      { partial: '-p', expected: '-p' },  // Test short flag completion
+      { partial: '-H', expected: '-H' },  // Test another short flag completion
+    ];
 
     test.each(optionTests)(
       "should complete option for partial input '%s'",
@@ -100,6 +104,32 @@ describe.each(cliTools)('cli completion tests for %s', (cliTool) => {
     });
   });
 
+  describe('short flag handling', () => {
+    it('should handle short flag value completion', async () => {
+      const command = `${commandPrefix} dev -p `;
+      const output = await runCommand(command);
+      expect(output).toMatchSnapshot();
+    });
+
+    it('should handle short flag with equals sign', async () => {
+      const command = `${commandPrefix} dev -p=3`;
+      const output = await runCommand(command);
+      expect(output).toMatchSnapshot();
+    });
+
+    it('should handle global short flags', async () => {
+      const command = `${commandPrefix} -c `;
+      const output = await runCommand(command);
+      expect(output).toMatchSnapshot();
+    });
+
+    it('should not show duplicate options when short flag is used', async () => {
+      const command = `${commandPrefix} -c vite.config.js --`;
+      const output = await runCommand(command);
+      expect(output).toMatchSnapshot();
+    });
+  });
+
   // single positional command: `lint [file]`
   // vite ""
   // -> src/