feat(args): support exclusive and value_hint

.changeset/serious-apples-hang.md

@@ -0,0 +1,5 @@
+---
+'archons': patch
+---
+
+Support `exclusive` field for arguments

.changeset/thin-avocados-destroy.md

@@ -0,0 +1,5 @@
+---
+'archons': patch
+---
+
+Support set `value_hint` for arguments

__test__/exclusive.spec.ts

@@ -0,0 +1,11 @@
+import test from 'ava'
+import { spawnSync } from 'child_process'
+
+test('exclusive', (t) => {
+  const exclusive = spawnSync('node', [`examples/exclusive.cjs`, '--config', 'config.json'])
+  const should_fail = spawnSync('node', [`examples/exclusive.cjs`, '--config', 'config.json', '--other', 'other'])
+  t.is(exclusive.error, undefined)
+  t.is(exclusive.stderr.length, 0)
+  t.deepEqual(exclusive.status ?? 0, 0)
+  t.not(should_fail.stderr.length, 0)
+})

examples/exclusive.cts

@@ -0,0 +1,21 @@
+import { Context, defineCommand, run } from '../index'
+
+const main = defineCommand({
+  meta: {
+    name: 'test',
+  },
+  options: {
+    config: {
+      type: 'option',
+      exclusive: true,
+    },
+    other: {
+      type: 'option',
+    },
+  },
+  callback: async (ctx: Context) => {
+    console.log(ctx)
+  },
+})
+
+run(main)

index.d.ts

@@ -121,6 +121,25 @@ export interface CommandOption {
   shortAlias?: Array<string>
   /** Hidden short option aliases */
   hiddenShortAlias?: Array<string>
+  /**
+   * Value hint for shell completion
+   *
+   * Provide the shell a hint about how to complete this argument.
+   *
+   * **Warning**: this will implicitly set `action` to `set`.
+   */
+  valueHint?:
+    | 'any_path'
+    | 'file'
+    | 'dir'
+    | 'executable'
+    | 'cmd_name'
+    | 'cmd'
+    | 'cmd_with_args'
+    | 'url'
+    | 'username'
+    | 'hostname'
+    | 'email'
   /** Option description */
   help?: string
   /**
@@ -159,6 +178,12 @@ export interface CommandOption {
    * This argument is mutually exclusive with the specified arguments.
    */
   conflictsWith?: Array<string>
+  /**
+   * Exclusive argument
+   *
+   * This argument must be passed alone; it conflicts with all other arguments.
+   */
+  exclusive?: boolean
   /**
    * Hide default value in help output
    *

package.json

@@ -50,9 +50,9 @@
     "watch": "node scripts/watch.mjs",
     "artifacts": "napi artifacts",
     "bench": "node --import @swc-node/register/esm-register benchmark/bench.ts",
-    "build": "napi build --platform --release",
+    "build": "napi build --platform --release --pipe 'prettier -w'",
     "build:examples": "tsc -p examples",
-    "build:debug": "napi build --platform",
+    "build:debug": "napi build --platform --pipe 'prettier -w'",
     "format": "run-p format:prettier format:rs format:toml",
     "format:prettier": "prettier . -w",
     "format:toml": "taplo format",

src/resolver.rs

@@ -90,6 +90,23 @@ pub(crate) fn resolve_parser(
   }
 }
 
+pub(crate) fn resolve_value_hint(value_hint: &str) -> clap::builder::ValueHint {
+  match value_hint {
+    "any_path" => clap::builder::ValueHint::AnyPath,
+    "file" => clap::builder::ValueHint::FilePath,
+    "dir" => clap::builder::ValueHint::DirPath,
+    "executable" => clap::builder::ValueHint::ExecutablePath,
+    "cmd_name" => clap::builder::ValueHint::CommandName,
+    "cmd" => clap::builder::ValueHint::CommandString,
+    "cmd_with_args" => clap::builder::ValueHint::CommandWithArguments,
+    "url" => clap::builder::ValueHint::Url,
+    "username" => clap::builder::ValueHint::Username,
+    "hostname" => clap::builder::ValueHint::Hostname,
+    "email" => clap::builder::ValueHint::EmailAddress,
+    _ => panic!("Unsupported value_hint: {:?}", value_hint),
+  }
+}
+
 pub(crate) fn resolve_command_options(
   clap: clap::Command,
   meta: &HashMap<String, CommandOption>,
@@ -129,6 +146,9 @@ pub(crate) fn resolve_command_options(
             .collect::<Vec<char>>();
           arg = arg.short_aliases(hidden_short_alias);
         }
+        if let Some(value_hint) = &opt.value_hint {
+          arg = arg.value_hint(resolve_value_hint(value_hint.as_str()));
+        }
         if let Some(help) = &opt.help {
           arg = arg.help(help);
         }
@@ -147,6 +167,9 @@ pub(crate) fn resolve_command_options(
         if let Some(global) = opt.global {
           arg = arg.global(global);
         }
+        if let Some(exclusive) = opt.exclusive {
+          arg = arg.exclusive(exclusive);
+        }
         if let Some(conflicts_with) = &opt.conflicts_with {
           arg = arg.conflicts_with_all(conflicts_with);
         }

src/types.rs

@@ -108,6 +108,24 @@ pub struct CommandOption {
   pub short_alias: Option<Vec<String>>,
   /// Hidden short option aliases
   pub hidden_short_alias: Option<Vec<String>>,
+  /// Value hint for shell completion
+  ///
+  /// Provide the shell a hint about how to complete this argument.
+  ///
+  /// **Warning**: this will implicitly set `action` to `set`.
+  #[napi(ts_type = r#"
+    | 'any_path'
+    | 'file'
+    | 'dir'
+    | 'executable'
+    | 'cmd_name'
+    | 'cmd'
+    | 'cmd_with_args'
+    | 'url'
+    | 'username'
+    | 'hostname'
+    | 'email'"#)]
+  pub value_hint: Option<String>,
   /// Option description
   pub help: Option<&'static str>,
   /// Required argument
@@ -136,6 +154,10 @@ pub struct CommandOption {
   ///
   /// This argument is mutually exclusive with the specified arguments.
   pub conflicts_with: Option<Vec<&'static str>>,
+  /// Exclusive argument
+  ///
+  /// This argument must be passed alone; it conflicts with all other arguments.
+  pub exclusive: Option<bool>,
   /// Hide default value in help output
   ///
   /// Do not display the default value of the argument in the help message.