@bomb.sh/tab 0.0.3 → 0.0.4

package/README.md

@@ -1,169 +1,174 @@
+![tab CLI autocompletions demo](assets/preview.gif)
+
 # tab
 
-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.
+Shell autocompletions are largely missing in the JavaScript CLI ecosystem. tab provides a simple API for adding autocompletions to any JavaScript CLI tool.
 
-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.
+Additionally, tab supports autocompletions for `pnpm`, `npm`, `yarn`, and `bun`.
 
-## Examples
+As CLI tooling authors, if we can spare our users a second or two by not checking documentation or writing the `-h` flag, we're doing them a huge favor. The unconscious mind loves hitting the [TAB] key and always expects feedback. When nothing happens, it breaks the user's flow - a frustration apparent across the whole JavaScript CLI tooling ecosystem.
 
-Check out the [examples directory](./examples) for complete examples of using Tab with different command-line frameworks:
+tab solves this complexity by providing autocompletions that work consistently across `zsh`, `bash`, `fish`, and `powershell`.
 
-- [CAC](./examples/demo.cac.ts)
-- [Citty](./examples/demo.citty.ts)
-- [Commander.js](./examples/demo.commander.ts)
+## Installation
 
-## Usage
+```bash
+npm install @bomb.sh/tab
+# or
+pnpm add @bomb.sh/tab
+# or
+yarn add @bomb.sh/tab
+# or
+bun add @bomb.sh/tab
+```
 
-```ts
-import { Completion, script } from '@bomb.sh/tab';
+## Quick Start
 
-const name = 'my-cli';
-const completion = new Completion();
+Add autocompletions to your CLI tool:
 
-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' },
-    ];
-  }
-);
-
-completion.addOption(
-  'start',
-  '--port',
-  'Specify the port number',
-  async (previousArgs, toComplete, endsWithSpace) => {
-    return [
-      { value: '3000', description: 'Development port' },
-      { value: '8080', description: 'Production port' },
-    ];
-  }
-);
+```typescript
+import t from '@bomb.sh/tab';
 
-// 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);
+// Define your CLI structure
+const devCmd = t.command('dev', 'Start development server');
+devCmd.option('port', 'Specify port', (complete) => {
+  complete('3000', 'Development port');
+  complete('8080', 'Production port');
+});
+
+// Handle completion requests
+if (process.argv[2] === 'complete') {
+  const shell = process.argv[3];
+  if (shell === '--') {
+    const args = process.argv.slice(4);
+    t.parse(args);
+  } else {
+    t.setup('my-cli', 'node my-cli.js', shell);
+  }
 }
 ```
 
-Now your user can run `source <(my-cli complete zsh)` and they will get completions for the `my-cli` command using the [autocompletion server](#autocompletion-server).
+Test your completions:
 
-## Adapters
+```bash
+node my-cli.js complete -- dev --port=<TAB>
+# Output: --port=3000  Development port
+#         --port=8080  Production port
+```
 
-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.
+Install for users:
 
-### `@bomb.sh/tab/cac`
+```bash
+# One-time setup
+source <(my-cli complete zsh)
 
-```ts
-import cac from 'cac';
-import tab from '@bomb.sh/tab/cac';
+# Permanent setup
+my-cli complete zsh > ~/.my-cli-completion.zsh
+echo 'source ~/.my-cli-completion.zsh' >> ~/.zshrc
+```
 
-const cli = cac('my-cli');
+## Package Manager Completions
 
-cli.command('dev', 'Start dev server').option('--port <port>', 'Specify port');
+As mentioned earlier, tab provides completions for package managers as well:
 
-const completion = tab(cli);
+```bash
+# Generate and install completion scripts
+npx @bomb.sh/tab pnpm zsh > ~/.pnpm-completion.zsh && echo 'source ~/.pnpm-completion.zsh' >> ~/.zshrc
+npx @bomb.sh/tab npm bash > ~/.npm-completion.bash && echo 'source ~/.npm-completion.bash' >> ~/.bashrc
+npx @bomb.sh/tab yarn fish > ~/.config/fish/completions/yarn.fish
+npx @bomb.sh/tab bun powershell > ~/.bun-completion.ps1 && echo '. ~/.bun-completion.ps1' >> $PROFILE
+```
 
-// Get the dev command completion handler
-const devCommandCompletion = completion.commands.get('dev');
+Example in action:
 
-// 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' },
-  ];
-};
+```bash
+pnpm install --reporter=<TAB>
+# Shows: append-only, default, ndjson, silent
 
-cli.parse();
+yarn add --emoji=<TAB>
+# Shows: true, false
 ```
 
-Now autocompletion will be available for any specified command and option in your cac instance. If your user writes `my-cli dev --po`, they will get suggestions for the `--port` option. Or if they write `my-cli d` they will get suggestions for the `dev` command.
+## Framework Adapters
+
+tab provides adapters for popular JavaScript CLI frameworks.
+
+### CAC Integration
+
+```typescript
+import cac from 'cac';
+import tab from '@bomb.sh/tab/cac';
+
+const cli = cac('my-cli');
 
-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.
+// Define your CLI
+cli
+  .command('dev', 'Start dev server')
+  .option('--port <port>', 'Specify port')
+  .option('--host <host>', 'Specify host');
+
+// Initialize tab completions
+const completion = await tab(cli);
+
+// Add custom completions for option values
+const devCommand = completion.commands.get('dev');
+const portOption = devCommand?.options.get('port');
+if (portOption) {
+  portOption.handler = (complete) => {
+    complete('3000', 'Development port');
+    complete('8080', 'Production port');
+  };
+}
 
-### `@bomb.sh/tab/citty`
+cli.parse();
+```
+
+### Citty Integration
 
-```ts
-import citty, { defineCommand, createMain } from 'citty';
+```typescript
+import { defineCommand, createMain } from 'citty';
 import tab from '@bomb.sh/tab/citty';
 
 const main = defineCommand({
-  meta: {
-    name: 'my-cli',
-    description: 'My CLI tool',
+  meta: { name: 'my-cli', description: 'My CLI tool' },
+  subCommands: {
+    dev: defineCommand({
+      meta: { name: 'dev', description: 'Start dev server' },
+      args: {
+        port: { type: 'string', description: 'Specify port' },
+        host: { type: 'string', description: 'Specify host' },
+      },
+    }),
   },
 });
 
-const devCommand = defineCommand({
-  meta: {
-    name: 'dev',
-    description: 'Start dev server',
-  },
-  args: {
-    port: { type: 'string', description: 'Specify port' },
-  },
-});
-
-main.subCommands = {
-  dev: devCommand,
-};
-
+// Initialize tab completions
 const completion = await tab(main);
 
-// TODO: addHandler function to export
-const devCommandCompletion = completion.commands.get('dev');
-
-const portOptionCompletion = devCommandCompletion.options.get('--port');
-
-portOptionCompletion.handler = async (
-  previousArgs,
-  toComplete,
-  endsWithSpace
-) => {
-  return [
-    { value: '3000', description: 'Development port' },
-    { value: '8080', description: 'Production port' },
-  ];
-};
+// Add custom completions
+const devCommand = completion.commands.get('dev');
+const portOption = devCommand?.options.get('port');
+if (portOption) {
+  portOption.handler = (complete) => {
+    complete('3000', 'Development port');
+    complete('8080', 'Production port');
+  };
+}
 
 const cli = createMain(main);
 cli();
 ```
 
-### `@bomb.sh/tab/commander`
+### Commander.js Integration
 
-```ts
+```typescript
 import { Command } from 'commander';
 import tab from '@bomb.sh/tab/commander';
 
 const program = new Command('my-cli');
 program.version('1.0.0');
 
-// Add commands
+// Define commands
 program
   .command('serve')
   .description('Start the server')
@@ -173,74 +178,55 @@ program
     console.log('Starting server...');
   });
 
-// Initialize tab completion
+// Initialize tab completions
 const completion = tab(program);
 
-// Configure custom completions
-for (const command of completion.commands.values()) {
-  if (command.name === 'serve') {
-    for (const [option, config] of command.options.entries()) {
-      if (option === '--port') {
-        config.handler = () => {
-          return [
-            { value: '3000', description: 'Default port' },
-            { value: '8080', description: 'Alternative port' },
-          ];
-        };
-      }
-    }
-  }
+// Add custom completions
+const serveCommand = completion.commands.get('serve');
+const portOption = serveCommand?.options.get('port');
+if (portOption) {
+  portOption.handler = (complete) => {
+    complete('3000', 'Default port');
+    complete('8080', 'Alternative port');
+  };
 }
 
 program.parse();
 ```
 
-## Recipe
-
-`source <(my-cli complete zsh)` won't be enough since the user would have to run this command each time they spin up a new shell instance.
-
-We suggest this approach for the end user that you as a maintainer might want to push.
-
-```
-my-cli completion zsh > ~/completion-for-my-cli.zsh
-echo 'source ~/completion-for-my-cli.zsh' >> ~/.zshrc
-```
-
-For other shells:
+tab uses a standardized completion protocol that any CLI can implement:
 
 ```bash
-# Bash
-my-cli complete bash > ~/.bash_completion.d/my-cli
-echo 'source ~/.bash_completion.d/my-cli' >> ~/.bashrc
-
-# Fish
-my-cli complete fish > ~/.config/fish/completions/my-cli.fish
+# Generate shell completion script
+my-cli complete zsh
 
-# PowerShell
-my-cli complete powershell > $PROFILE.CurrentUserAllHosts
+# Parse completion request (called by shell)
+my-cli complete -- install --port=""
 ```
 
-## Autocompletion Server
+**Output Format:**
 
-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
-my-cli complete -- --po
---port  Specify the port number
-:0
 ```
+--port=3000    Development port
+--port=8080    Production port
+:4
+```
+
+## Documentation
 
-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+$/`).
+See [bombshell docs](https://bomb.sh/docs/tab/).
 
-In situations like `my-cli dev --po` you'd have autocompletions! But in the case of `pnpm my-cli dev --po` which is what most of us use, tab does not inject autocompletions for a tool like pnpm.
+## Contributing
 
-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.
+We welcome contributions! tab's architecture makes it easy to add support for new package managers or CLI frameworks.
 
-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.
+## Acknowledgments
 
-Other package managers like `npm` and `yarn` can decide whether to support this or not too for more universal support.
+tab was inspired by the great [Cobra](https://github.com/spf13/cobra/) project, which set the standard for CLI tooling in the Go ecosystem.
 
-## Inspiration
+## Adoption Support
 
-- git
-- [cobra](https://github.com/spf13/cobra/blob/main/shell_completions.go), without cobra, tab would have took 10x longer to build
+We want to make it as easy as possible for the JS ecosystem to enjoy great autocompletions.  
+We at [thundraa](https://thundraa.com) would be happy to help any open source CLI utility adopt tab.
+If you maintain a CLI and would like autocompletions set up for your users, just [drop the details in our _Adopting tab_ discussion](https://github.com/bombshell-dev/tab/discussions/61).  
+We’ll gladly help and even open a PR to get you started.

package/dist/bin/cli.d.ts

@@ -1 +1 @@
-#!/usr/bin/env node
+export { };