Link completion specs to different versions of CLI tools

As CLI tools often change, it's important that users get the right completion spec for the specific version of a CLI tool they are one.

There are two main methods of doing spec versioning:

1. Normal completions handling versions using JS constructs (better for few changes)
2. Diff-versioned specs handled by the autocomplete engine (better for frequently changing CLIs)

Normal completions

1. To get the version, Fig defines a special export called getVersionCommand that allows you to execute a shell command and then return the current version of a user's CLI tool.
2. To return the right completion spec, Fig allows the Fig.Spec type to be a function that takes in a version, and outputs a normal Fig.Spec object.

Example For instance, yarn has major version 1 and major version 2. There are several commands that exist in v1 but not v2 and vice versa.

The completion spec for yarn looks a little like this:

// The completion spec is a function that returns a Fig.spec object
const completionSpec: Fig.Spec = (version: string): Fig.Spec => {
  var global_subcommands: Fig.Subcommand[] = [
    { name: "subcommand_one" },
    { name: "subcommand_two" },
  ];

  var version_one_subcommands: Fig.Subcommand[] = [{ name: "version_one" }];

  var version_two_subcommands: Fig.Subcommand[] = [{ name: "version_two" }];

  if (version === "1.0.0")
    return {
      name: "yarn",
      subcommands: [...global_subcommands, ...version_one_subcommands],
    };
  else
    return {
      name: "yarn",
      subcommands: [...global_subcommands, ...version_two_subcommands],
    };
};

export default completionSpec;

// Function that returns the semantic version for a given CLI tool,
// then used to load up the relevant completion spec.
export const getVersionCommand: Fig.GetVersionCommand = async (
  executeShellCommand: Fig.ExecuteShellCommandFunction
) => {
  const version: string = await executeShellCommand("yarn --version");
  return version;
};

Diff-versioned specs

Diff-versioned specs are mostly updated and edited through the autocomplete-tools CLI, prefer to these docs to learn how to use them.