feat: add support for carapace macros (#6)

* feat: add support for carapace macros

---------

Co-authored-by: Sebastian Bresin <sebastian.bresin@gmail.com>

Author: cristiand391

README.md

@@ -16,6 +16,7 @@ https://carapace-sh.github.io/carapace-spec/carapace-spec/usage.html
   * Options
   * Exclusive relationships
 * Re-generate spec automatically on plugin install/uninstall
+* Completion overrides (see `Macros` section below)
 
 ## Requirements
  * `carapace-spec`: [dowload the binary for your OS]([url](https://github.com/carapace-sh/carapace-spec/releases)) and put it in your `PATH`
@@ -29,11 +30,53 @@ plugins install @cristiand391/oclif-carapace-spec-plugin
 
 Then run the `carapace-gen` command and follow the instructions to source the spec in your shell.
 
+## Macros
+`carapace-spec` allows to use macros for customizing completion style and values:
+
+https://carapace-sh.github.io/carapace-spec/carapace-spec/macros.html
+
+You can use macros to define custom flag completion logic for dynamic flag values that can't be hard-coded in CLIs like usernames, IDs, etc.
+
+Macros file example for the Salesforce CLI:
+```yaml
+# this node applies to all commands, define here completion logic for flags that repeat themselves in multiple commands.
+persistentFlagsCompletion:
+  target-org: ["$(sf org list auth --json | jq -r '.result[].username')"]
+  target-dev-hub: ["$(sf org list auth --json | jq -r '.result[] | select(.isDevHub) | .username')"]
+  definition-file: ["$files([.json])"]
+  manifest: ["$files([.xml])"]
+  file: ["$files"]
+
+# override flag completion for specific commands.
+# important: command ids need to separated by colons.
+commandOverrides:
+  flags:
+    'project:deploy:start':
+      pre-destructive-changes: ["$files([.xml])"]
+      post-destructive-changes: ["$files([.xml])"]
+    'org:delete:scratch':
+        target-org: ["$(sf org list auth --json | jq -r '.result[] | select(.isScratchOrg) | .username')"]
+    'org:delete:sandbox':
+        target-org: ["$(sf org list auth --json | jq -r '.result[] | select(.isSandbox) | .username')"]
+
+```
+
+It uses the `exec` macro for `--target-org` and `--target-dev-hub` flags to get completion values from a command, and the `files` macro for XML/JSON file completion on specific flags.
+
+### Usage
+
+1. Define a YAML file with completion definitions like in the example above.
+2. Set the `<BIN>_CARAPACE_SPEC_MACROS_FILE` env var to the path to the YAML file.
+3. Run `sf carapace-gen --refresh-cache`.
+   
+> [!NOTE]  
+The `<BIN>` part in the env var in step 2 refers to the name of your oclif CLI. For instance, for the Salesforce CLI (`sf`) the env var should be `SF_CARAPACE_SPEC_MACROS_FILE`.
+
+> [!NOTE]  
+This plugin re-generates the carapace spec everytime you install/uninstall plugins via `plugins install/uninstall`, make sure to set the `<BIN>_CARAPACE_SPEC_MACROS_FILE` env var in your shell RC file so that you don't miss the custom completions when the automatic re-generation happens under the hood.
+
+
 ## Why should I use this instead of `@oclif/plugin-autocomplete`?
 `@oclif/plugin-autocomplete` only supports bash, zsh and powershell while `carapace-spec` supports those + 6 additional shells: https://carapace-sh.github.io/carapace-spec/carapace-spec/usage.html
-Except for flag exclusive relationships, the completion experience is pretty much the same so if you oclif/plugin-autocomplete works for you then you can ignore this.
-
-In the future I plan to add support for injecting custom macros for specific command/flags,see:
-https://carapace-sh.github.io/carapace-spec/carapace-spec/macros/core.html
 
-that would allow users to define dynamic completion logic for flag/arg values without having to touch any code.
+Except for flag exclusive relationships and completion overrides (macros), the completion experience is pretty much the same so if `oclif/plugin-autocomplete` works for you then you can ignore this.

src/commands/carapace-gen.ts

@@ -1,7 +1,7 @@
 import {Command, Flags, Interfaces} from '@oclif/core'
 import {bold,cyan} from 'ansis'
 import * as ejs from 'ejs'
-import {mkdir,writeFile} from 'node:fs/promises'
+import {mkdir,writeFile,readFile} from 'node:fs/promises'
 import YAML, { YAMLMap } from 'yaml'
 
 type YamlCommandNode = {
@@ -23,6 +23,19 @@ type TopicNode = {
 
 type Node = CommandNode | TopicNode
 
+type Macros = {
+  persistentFlagsCompletion?: {
+    [name: string]: string[];
+  };
+  commandOverrides?: {
+    flags?: {
+      [name: string]: {
+        [name: string]: string[];
+      };
+    };
+  };
+};
+
 export default class CarapaceGen extends Command {
   static override description = `Generate a carapace spec file
 
@@ -46,7 +59,13 @@ https://github.com/carapace-sh/carapace-spec`
 
     const commandNodes = this.getCommandNodes()
 
-    await writeFile(specPath, YAML.stringify(this.buildCommandTree(commandNodes)))
+    const macrosFilepath = this.config.scopedEnvVar('CARAPACE_SPEC_MACROS_FILE')
+    const macros = macrosFilepath ? YAML.parse(await readFile(macrosFilepath, 'utf8')) : undefined
+
+    await writeFile(specPath, YAML.stringify(this.buildCommandTree(commandNodes, macros), {
+      // avoid using YAML anchors in completion file, carapace doesn't like them.
+      aliasDuplicateObjects: false
+    }))
 
     if (!flags['refresh-cache']) {
       this.log(`
@@ -65,7 +84,7 @@ https://github.com/carapace-sh/carapace-spec`
     }
   }
 
-  private buildCommandTree(nodes: Node[]) {
+  private buildCommandTree(nodes: Node[], macros: Macros | undefined) {
     const commandTree: {
       name: string,
       description: string;
@@ -145,6 +164,20 @@ https://github.com/carapace-sh/carapace-spec`
               key: flagDef,
               value: node.flags[flagName].summary ?? node.flags[flagName].description ?? ''
             })
+
+            if (macros) {
+              if (macros.persistentFlagsCompletion && Object.hasOwn(macros.persistentFlagsCompletion, flagName)) {
+                completion.flag[flagName] = macros.persistentFlagsCompletion[flagName]
+                hasFlagValueCompletion = true
+              }
+              if (macros.commandOverrides?.flags && Object.hasOwn(macros.commandOverrides.flags, node.id)) {
+                if (Object.hasOwn(macros.commandOverrides.flags[node.id], flagName)) {
+                  completion.flag[flagName] = macros.commandOverrides.flags[node.id][flagName]
+                  hasFlagValueCompletion = true
+                }
+              }
+            }
+            
           }
 
           // add oclif's global help flag