docs

Author: Aslemammad

README.md

@@ -2,29 +2,160 @@
 
 # tab
 
-- [x] zsh test in git
+Shell autocompletions are largely missing in the javascript cli ecosystem. This tool is an attempt to make autocompletions come out of the box for any cli tool. 
 
-```zsh
-source <(pnpm tsx demo.ts complete zsh)
+Tools like git and their autocompletion experience inspired us to build this tool and make the same ability available for any javascript cli project. Developers love hitting the tab key, hence why they prefer tabs over spaces. 
+
+```ts
+import { Completion, script } from "@bombsh/tab";
+
+const name = "vite"
+const completion = new Completion()
+
+completion.addCommand("start", "Start the application", async (previousArgs, toComplete, endsWithSpace) => {
+  // suggestions
+  return [
+    { value: "dev", description: "Start in development mode" },
+    { value: "prod", description: "Start in production mode" }
+  ]
+})
 
-vite # rest of the completions
+completion.addOption("start", "--port", "Specify the port number", async (previousArgs, toComplete, endsWithSpace) => {
+  return [
+    { value: "3000", description: "Development port" },
+    { value: "8080", description: "Production port" }
+  ]
+})
 
-pnpm tsx demo.ts complete -- --po
+
+// a way of getting the executable path to pass to the shell autocompletion script
+function quoteIfNeeded(path: string) {
+  return path.includes(" ") ? `'${path}'` : path;
+}
+const execPath = process.execPath;
+const processArgs = process.argv.slice(1);
+const quotedExecPath = quoteIfNeeded(execPath);
+const quotedProcessArgs = processArgs.map(quoteIfNeeded);
+const quotedProcessExecArgs = process.execArgv.map(quoteIfNeeded);
+const x = `${quotedExecPath} ${quotedProcessExecArgs.join(" ")} ${quotedProcessArgs[0]}`;
+
+if (process.argv[2] === "--") {
+  // autocompletion logic
+  await completion.parse(process.argv.slice(2), "start") // TODO: remove "start"
+} else {
+  // process.argv[2] can be "zsh", "bash", "fish", "powershell"
+  script(process.argv[2], name, x)
+}
 ```
 
-- [x] tests vitest (this should mostly test the completions array, e.g. logs)
-- [x] powershell completions generation
-- [x] citty support `@bomsh/tab/citty`
-- [] `@bombsh/tab`
+Now your user can run `source <(vite complete zsh)` and they will get completions for the `vite` command using the [autocompletion server](#autocompletion-server).
 
-- [] fish
-- [] bash
+## Adapters
+
+Since we are heavy users of tools like `cac` and `citty`, we have created adapters for both of them. Ideally, tab would be integrated internally into these tools, but for now, this is a good compromise.
+
+### `@bombsh/tab/cac`
 
 ```ts
-const completion = new Completion()
-completion.addCommand()
-completion.addOption()
+import cac from "cac";
+import tab from "@bombsh/tab/cac";
+
+const cli = cac("vite");
+
+cli
+  .command("dev", "Start dev server")
+  .option("--port <port>", "Specify port");
+
+const completion = tab(cli);
+
+// Get the dev command completion handler
+const devCommandCompletion = completion.commands.get("dev");
+
+// Get and configure the port option completion handler
+const portOptionCompletion = devCommandCompletion.options.get("--port");
+portOptionCompletion.handler = async (previousArgs, toComplete, endsWithSpace) => {
+  return [
+    { value: "3000", description: "Development port" },
+    { value: "8080", description: "Production port" }
+  ]
+}
+
+cli.parse();
+```
+Now autocompletion will be available for any specified command and option in your cac instance. If your user writes `vite dev --po`, they will get suggestions for the `--port` option. Or if they write `vite d` they will get suggestions for the `dev` command.
+
+Suggestions are missing in the adapters since yet cac or citty do not have a way to provide suggestions (tab just came out!), we'd have to provide them manually. Mutations do not hurt in this situation.
+
+### `@bombsh/tab/citty`
+
+```ts
+import citty, { defineCommand, createMain } from "citty";
+import tab from "@bombsh/tab/citty";
+
+const main = defineCommand({
+  meta: {
+    name: "vite",
+    description: "Vite CLI tool",
+  },
+});
+
+const devCommand = defineCommand({
+  meta: {
+    name: "dev",
+    description: "Start dev server",
+  },
+  args: {
+    port: { type: "string", description: "Specify port" },
+  }
+});
+
+main.subCommands = {
+  dev: devCommand
+};
+
+const completion = await tab(main);
+
+// TODO: addHandler function to export
+const devCommandCompletion = completion.commands.get("dev");
 
-// better name
-completion.parse()
+const portOptionCompletion = devCommandCompletion.options.get("--port");
+
+portOptionCompletion.handler = async (previousArgs, toComplete, endsWithSpace) => {
+  return [
+    { value: "3000", description: "Development port" },
+    { value: "8080", description: "Production port" }
+  ]
+}
+
+const cli = createMain(main);
+cli();
 ```
+
+## Autocompletion Server
+
+By integrating tab into your cli, your cli would have a new command called `complete`. This is where all the magic happens. And the shell would contact this command to get completions. That's why we call it the autocompletion server.
+
+```zsh
+vite complete -- --po
+--port  Specify the port number   
+:0 
+```
+
+The autocompletion server can be a standard to identify whether a package provides autocompletions. Whether running `tool complete --` would result in an output that ends with `:{Number}` (matching the pattern `/:\d+$/`).
+
+In situations like `vite dev --po` you'd have autocompletions! But in the case of `pnpm vite dev --po` which is what most of us use, tab does not inject autocompletions for a tool like pnpm. 
+
+Since pnpm already has its own autocompletion [script](https://pnpm.io/completion), this provides the opportunity to check whether a package provides autocompletions and use those autocompletions if available.
+
+This would also have users avoid injecting autocompletions in their shell config for any tool that provides its own autocompletion script, since pnpm would already support proxying the autocompletions out of the box.
+
+Other package managers like `npm` and `yarn` can decide whether to support this or not too for more universal support. 
+
+## Inspiration 
+- git
+- [cobra](https://github.com/spf13/cobra/blob/main/shell_completions.go)
+
+
+## TODO
+- [] fish
+- [] bash

src/index.ts

@@ -1,3 +1,8 @@
+import * as zsh from "./zsh";
+import * as bash from "./bash";
+import * as fish from "./fish";
+import * as powershell from "./powershell";
+
 // ShellCompRequestCmd is the name of the hidden command that is used to request
 // completion results from the program. It is used by the shell completion scripts.
 export const ShellCompRequestCmd: string = "__complete";
@@ -208,3 +213,31 @@ export class Completion {
         console.log(`:${directive}`);
     }
 }
+
+export function script(shell: "zsh" | "bash" | "fish" | "powershell", name: string, x: string) {
+    switch (shell) {
+      case "zsh": {
+        const script = zsh.generate(name, x);
+        console.log(script);
+        break;
+      }
+      case "bash": {
+        const script = bash.generate(name, x);
+        console.log(script);
+        break;
+      }
+      case "fish": {
+        const script = fish.generate(name, x);
+        console.log(script);
+        break;
+      }
+      case "powershell": {
+        const script = powershell.generate(name, x);
+        console.log(script);
+        break;
+      }
+      default: {
+        throw new Error(`Unsupported shell: ${shell}`);
+      }
+    }
+}