diff --git a/src/content/docs/tab/api/core.mdx b/src/content/docs/tab/api/core.mdx
deleted file mode 100644
index fc6ab57..0000000
--- a/src/content/docs/tab/api/core.mdx
+++ /dev/null
@@ -1,402 +0,0 @@
----
-title: Core API
-description: Complete API reference for the Tab core package
----
-
-This page provides the complete API reference for the Tab core package, including all classes, methods, types, and interfaces.
-
-## Classes
-
-### RootCommand
-
-The main class for managing command and option completions. This is the primary entry point for defining your CLI structure.
-
-```ts
-import { RootCommand } from '@bomb.sh/tab';
-
-const t = new RootCommand();
-```
-
-#### Methods
-
-##### command
-
-Adds a command with optional description and returns a Command instance for further configuration.
-
-**Parameters:**
-- `name` (string): The command name
-- `description` (string, optional): Command description
-
-**Returns:** Command - A Command instance for chaining
-
-**Example:**
-```ts
-// Simple command
-const devCmd = t.command('dev', 'Start development server');
-
-// Nested command
-const buildCmd = t.command('dev build', 'Build project');
-```
-
-##### option
-
-Adds a global option to the root command.
-
-**Parameters:**
-- `name` (string): The option name (e.g., 'config' for '--config')
-- `description` (string): Option description
-- `handler` (OptionHandler, optional): Function that provides completion suggestions
-- `alias` (string, optional): Short flag alias (e.g., 'c' for '--config')
-
-**Returns:** RootCommand - For method chaining
-
-**Example:**
-```ts
-t.option('config', 'Use specified config file', function(complete) {
- complete('vite.config.ts', 'Vite config file');
- complete('vite.config.js', 'Vite config file');
-}, 'c');
-```
-
-##### argument
-
-Adds a positional argument to the root command.
-
-**Parameters:**
-- `name` (string): The argument name
-- `handler` (ArgumentHandler, optional): Function that provides completion suggestions
-- `variadic` (boolean, optional): Whether this is a variadic argument (default: false)
-
-**Returns:** RootCommand - For method chaining
-
-**Example:**
-```ts
-t.argument('project', function(complete) {
- complete('my-app', 'My application');
- complete('my-lib', 'My library');
-});
-```
-
-##### parse
-
-Parses command line arguments and outputs completion suggestions to stdout.
-
-**Parameters:**
-- `args` (string[]): Command line arguments
-
-**Example:**
-```ts
-const separatorIndex = process.argv.indexOf('--');
-const completionArgs = separatorIndex !== -1 ? process.argv.slice(separatorIndex + 1) : [];
-t.parse(completionArgs);
-```
-
-##### setup
-
-Generates shell completion scripts.
-
-**Parameters:**
-- `name` (string): CLI tool name
-- `executable` (string): Executable path for the CLI tool
-- `shell` (string): Target shell ('zsh', 'bash', 'fish', 'powershell')
-
-**Example:**
-```ts
-t.setup('my-cli', process.execPath, 'zsh');
-```
-
-### Command
-
-Represents a command with its options and arguments.
-
-```ts
-const cmd = t.command('dev', 'Start development server');
-```
-
-#### Methods
-
-##### option
-
-Adds an option to this command.
-
-**Parameters:**
-- `name` (string): The option name (e.g., 'p' for '--port')
-- `description` (string): Option description
-- `handler` (OptionHandler, optional): Function that provides completion suggestions
-- `alias` (string, optional): Short flag alias (e.g., 'p' for '--port')
-
-**Returns:** Command - For method chaining
-
-**Example:**
-```ts
-cmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
-}, 'p');
-```
-
-##### argument
-
-Adds a positional argument to this command.
-
-**Parameters:**
-- `name` (string): The argument name
-- `handler` (ArgumentHandler, optional): Function that provides completion suggestions
-- `variadic` (boolean, optional): Whether this is a variadic argument (default: false)
-
-**Returns:** Command - For method chaining
-
-**Example:**
-```ts
-cmd.argument('entry', function(complete) {
- complete('src/main.ts', 'Main entry point');
- complete('src/index.ts', 'Index entry point');
-});
-```
-
-## Types
-
-### OptionHandler
-
-Function type for option completion handlers.
-
-```ts
-type OptionHandler = (
- this: Option,
- complete: Complete,
- options: OptionsMap
-) => void;
-```
-
-**Parameters:**
-- `this`: The Option instance
-- `complete`: Function to call with completion suggestions
-- `options`: Map of all options for this command
-
-**Example:**
-```ts
-const handler: OptionHandler = function(complete) {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
-};
-```
-
-### ArgumentHandler
-
-Function type for argument completion handlers.
-
-```ts
-type ArgumentHandler = (
- this: Argument,
- complete: Complete,
- options: OptionsMap
-) => void;
-```
-
-**Parameters:**
-- `this`: The Argument instance
-- `complete`: Function to call with completion suggestions
-- `options`: Map of all options for this command
-
-**Example:**
-```ts
-const handler: ArgumentHandler = function(complete) {
- complete('src/main.ts', 'Main entry point');
- complete('src/index.ts', 'Index entry point');
-};
-```
-
-### Complete
-
-Function type for providing completion suggestions.
-
-```ts
-type Complete = (value: string, description: string) => void;
-```
-
-**Parameters:**
-- `value` (string): The completion value
-- `description` (string): Description of the completion
-
-**Example:**
-```ts
-function(complete) {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
-}
-```
-
-### Completion
-
-Object representing a completion suggestion.
-
-```ts
-type Completion = {
- value: string;
- description?: string;
-};
-```
-
-**Properties:**
-- `value` (string): The completion value
-- `description` (string, optional): Description of the completion
-
-**Example:**
-```ts
-const completion: Completion = {
- value: '3000',
- description: 'Development port'
-};
-```
-
-## Constants
-
-### ShellCompDirective
-
-Bit map representing different behaviors the shell can be instructed to have.
-
-```ts
-export const ShellCompDirective = {
- ShellCompDirectiveError: 1 << 0,
- ShellCompDirectiveNoSpace: 1 << 1,
- ShellCompDirectiveNoFileComp: 1 << 2,
- ShellCompDirectiveFilterFileExt: 1 << 3,
- ShellCompDirectiveFilterDirs: 1 << 4,
- ShellCompDirectiveKeepOrder: 1 << 5,
- shellCompDirectiveMaxValue: 1 << 6,
- ShellCompDirectiveDefault: 0,
-};
-```
-
-## Complete Example
-
-Here's a complete example showing all the core API features:
-
-```ts
-#!/usr/bin/env node
-import { RootCommand } from '@bomb.sh/tab';
-
-const t = new RootCommand();
-
-// Add global options
-t.option('config', 'Use specified config file', function(complete) {
- complete('vite.config.ts', 'Vite config file');
- complete('vite.config.js', 'Vite config file');
-}, 'c');
-
-t.option('mode', 'Set env mode', function(complete) {
- complete('development', 'Development mode');
- complete('production', 'Production mode');
-}, 'm');
-
-// Add root command argument
-t.argument('project', function(complete) {
- complete('my-app', 'My application');
- complete('my-lib', 'My library');
-});
-
-// Add commands with completions
-const devCmd = t.command('dev', 'Start development server');
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
-}, 'p');
-
-devCmd.option('host', 'Hostname', function(complete) {
- complete('localhost', 'Localhost');
- complete('0.0.0.0', 'All interfaces');
-}, 'H');
-
-devCmd.option('verbose', 'Enable verbose logging', 'v');
-
-// Add nested commands
-t.command('dev build', 'Build project');
-t.command('dev start', 'Start development server');
-
-// Add command with arguments
-t.command('copy', 'Copy files')
- .argument('source', function(complete) {
- complete('src/', 'Source directory');
- complete('dist/', 'Distribution directory');
- })
- .argument('destination', function(complete) {
- complete('build/', 'Build output');
- complete('release/', 'Release directory');
- });
-
-// Add command with variadic arguments
-t.command('lint', 'Lint project')
- .argument('files', function(complete) {
- complete('main.ts', 'Main file');
- complete('src/', 'Source directory');
- }, true); // true = variadic argument
-
-// Handle completion requests
-if (process.argv[2] === 'complete') {
- const shell = process.argv[3];
- if (shell && ['zsh', 'bash', 'fish', 'powershell'].includes(shell)) {
- t.setup('my-cli', process.execPath, shell);
- } else {
- // Parse completion arguments (everything after --)
- const separatorIndex = process.argv.indexOf('--');
- const completionArgs = separatorIndex !== -1 ? process.argv.slice(separatorIndex + 1) : [];
- t.parse(completionArgs);
- }
-} else {
- // Regular CLI usage
- console.log('My CLI Tool');
- console.log('Use "complete" command for shell completion');
-}
-```
-
-## Advanced Usage
-
-### Context-Aware Completions
-
-Make your completions responsive to what the user is typing:
-
-```ts
-devCmd.option('port', 'Port number', function(complete) {
- // Check if user is typing a specific port
- if (this.toComplete?.startsWith('30')) {
- complete('3000', 'Development port');
- return;
- }
-
- complete('3000', 'Development port');
- complete('8080', 'Production port');
- complete('9000', 'Alternative port');
-}, 'p');
-```
-
-### Dynamic Completions
-
-Load completions from external sources:
-
-```ts
-devCmd.option('config', 'Config file', async function(complete) {
- try {
- const files = await fs.readdir('.');
- const configFiles = files.filter(f => f.includes('config'));
- configFiles.forEach(file => complete(file, `Config file: ${file}`));
- } catch (error) {
- // Fallback completions
- complete('vite.config.ts', 'Vite config file');
- }
-});
-```
-
-### Boolean Options
-
-For boolean flags, you don't need a handler:
-
-```ts
-devCmd.option('verbose', 'Enable verbose logging', 'v');
-devCmd.option('quiet', 'Suppress output');
-```
-
-## Next Steps
-
-- Learn about [Framework Adapters](/docs/tab/guides/adapters/) for easier integration
-- Check out [Examples](/docs/tab/guides/examples/) for practical use cases
-- Explore [Best Practices](/docs/tab/guides/best-practices/) for effective implementations
\ No newline at end of file
diff --git a/src/content/docs/tab/basics/getting-started.mdx b/src/content/docs/tab/basics/getting-started.mdx
deleted file mode 100644
index e0654f9..0000000
--- a/src/content/docs/tab/basics/getting-started.mdx
+++ /dev/null
@@ -1,233 +0,0 @@
----
-title: Getting Started
-description: Learn how to add shell autocompletions to your CLI with Tab
----
-
-import { Tabs, TabItem } from '@astrojs/starlight/components';
-
-Tab provides shell autocompletions for JavaScript CLI tools, making your CLI feel as polished as native tools like git. This guide will walk you through adding autocompletions to your CLI tool.
-
-## Installation
-
-Install Tab using your preferred package manager:
-
-
-
- ```bash
- npm install @bomb.sh/tab
- ```
-
-
- ```bash
- pnpm add @bomb.sh/tab
- ```
-
-
- ```bash
- yarn add @bomb.sh/tab
- ```
-
-
-
-## Basic Usage
-
-Here's a simple example of how to add autocompletions to your CLI:
-
-```ts
-import { RootCommand } from '@bomb.sh/tab';
-
-const t = new RootCommand();
-
-// Add global options
-t.option('config', 'Use specified config file', function(complete) {
- complete('vite.config.ts', 'Vite config file');
- complete('vite.config.js', 'Vite config file');
-}, 'c');
-
-// Add commands with completions
-const devCmd = t.command('dev', 'Start development server');
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
-}, 'p');
-
-devCmd.option('host', 'Hostname', function(complete) {
- complete('localhost', 'Localhost');
- complete('0.0.0.0', 'All interfaces');
-}, 'H');
-
-// Add positional arguments
-t.command('copy', 'Copy files')
- .argument('source', function(complete) {
- complete('src/', 'Source directory');
- complete('dist/', 'Distribution directory');
- })
- .argument('destination', function(complete) {
- complete('build/', 'Build output');
- complete('release/', 'Release directory');
- });
-
-// Handle completion requests
-if (process.argv[2] === 'complete') {
- const shell = process.argv[3];
- if (shell && ['zsh', 'bash', 'fish', 'powershell'].includes(shell)) {
- t.setup('my-cli', process.execPath, shell);
- } else {
- // Parse completion arguments (everything after --)
- const separatorIndex = process.argv.indexOf('--');
- const completionArgs = separatorIndex !== -1 ? process.argv.slice(separatorIndex + 1) : [];
- t.parse(completionArgs);
- }
-} else {
- // Regular CLI usage
- console.log('My CLI Tool');
- console.log('Use "complete" command for shell completion');
-}
-```
-
-## Understanding the API
-
-### RootCommand Class
-
-The `RootCommand` class is the main entry point for defining your CLI structure:
-
-```ts
-const t = new RootCommand();
-```
-
-### Adding Commands
-
-Use the `command()` method to add commands with descriptions:
-
-```ts
-const devCmd = t.command('dev', 'Start development server');
-```
-
-### Adding Options
-
-Add options to commands with completion handlers:
-
-```ts
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
-}, 'p'); // Short flag alias
-```
-
-### Adding Arguments
-
-Add positional arguments with completion handlers:
-
-```ts
-t.command('copy', 'Copy files')
- .argument('source', function(complete) {
- complete('src/', 'Source directory');
- complete('dist/', 'Distribution directory');
- });
-```
-
-### Variadic Arguments
-
-For commands that accept multiple arguments:
-
-```ts
-t.command('lint', 'Lint project')
- .argument('files', function(complete) {
- complete('main.ts', 'Main file');
- complete('src/', 'Source directory');
- }, true); // true = variadic argument
-```
-
-## Shell Setup
-
-After adding Tab to your CLI, users need to set up shell completion. Here are the recommended approaches for different shells:
-
-### Zsh
-
-```bash
-# Generate completion script
-my-cli complete zsh > ~/completion-for-my-cli.zsh
-
-# Add to your .zshrc
-echo 'source ~/completion-for-my-cli.zsh' >> ~/.zshrc
-```
-
-### Bash
-
-```bash
-# Generate completion script
-my-cli complete bash > ~/.bash_completion.d/my-cli
-
-# Add to your .bashrc
-echo 'source ~/.bash_completion.d/my-cli' >> ~/.bashrc
-```
-
-### Fish
-
-```bash
-# Generate completion script
-my-cli complete fish > ~/.config/fish/completions/my-cli.fish
-```
-
-### PowerShell
-
-```powershell
-# Generate completion script
-my-cli complete powershell > $PROFILE.CurrentUserAllHosts
-```
-
-## Package Manager Integration
-
-Tab also provides a standalone CLI tool that enhances package manager completions with automatic CLI discovery:
-
-### Installing the Tab CLI
-
-```bash
-npm install -g @bomb.sh/tab
-```
-
-### Setting Up Package Manager Completions
-
-```bash
-# For pnpm
-tab pnpm zsh > ~/.zsh_completions/tab-pnpm.zsh
-echo 'source ~/.zsh_completions/tab-pnpm.zsh' >> ~/.zshrc
-
-# For npm
-tab npm zsh > ~/.zsh_completions/tab-npm.zsh
-echo 'source ~/.zsh_completions/tab-npm.zsh' >> ~/.zshrc
-
-# For yarn
-tab yarn zsh > ~/.zsh_completions/tab-yarn.zsh
-echo 'source ~/.zsh_completions/tab-yarn.zsh' >> ~/.zshrc
-
-# For bun
-tab bun zsh > ~/.zsh_completions/tab-bun.zsh
-echo 'source ~/.zsh_completions/tab-bun.zsh' >> ~/.zshrc
-```
-
-This provides enhanced completions for all CLI tools that support Tab completions, automatically detecting and providing completions for tools like Vite, TypeScript, and any other Tab-compatible CLI.
-
-## How It Works
-
-Tab works by adding a `complete` command to your CLI that generates shell-specific completion scripts. When users type `my-cli complete zsh`, Tab generates a completion script that the shell can source.
-
-The completion script communicates with your CLI through the autocompletion server. When users press Tab, the shell calls your CLI with special arguments, and Tab returns the appropriate completions.
-
-### Autocompletion Server
-
-Your CLI becomes an autocompletion server when you add Tab. The server responds to completion requests with suggestions and ends its output with `:{Number}` to indicate the number of completions.
-
-For example:
-```bash
-my-cli complete -- --po
---port Port number
-:0
-```
-
-## Next Steps
-
-- Learn about [Framework Adapters](/docs/tab/guides/adapters/) for easier integration with CAC, Citty, and Commander.js
-- Explore [Package Manager Integration](/docs/tab/guides/package-managers/) for enhanced completions
-- Check out [Best Practices](/docs/tab/guides/best-practices/) for implementing effective autocompletions
-- Check out the [API Reference](/docs/tab/api/core/) for detailed documentation
\ No newline at end of file
diff --git a/src/content/docs/tab/guides/adapters.mdx b/src/content/docs/tab/guides/adapters.mdx
deleted file mode 100644
index 89bf523..0000000
--- a/src/content/docs/tab/guides/adapters.mdx
+++ /dev/null
@@ -1,327 +0,0 @@
----
-title: Adapters
-description: Use Tab with popular CLI frameworks like CAC, Citty, and Commander.js
----
-
-Tab provides adapters for popular CLI frameworks to make integration even easier. These adapters automatically extract commands and options from your CLI framework and allow you to add custom completion handlers.
-
-## CAC Adapter
-
-The CAC adapter automatically detects commands and options from your CAC instance and provides completion handlers for customization.
-
-```ts
-import cac from 'cac';
-import tab from '@bomb.sh/tab/cac';
-
-const cli = cac('my-cli');
-
-cli.command('dev', 'Start dev server').option('port ', 'Specify port');
-cli.command('build', 'Build for production').option('mode ', 'Build mode');
-
-const completion = await 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 = (complete) => {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
-};
-
-// Configure build mode completions
-const buildCommandCompletion = completion.commands.get('build');
-const modeOptionCompletion = buildCommandCompletion.options.get('mode');
-modeOptionCompletion.handler = (complete) => {
- complete('development', 'Development build');
- complete('production', 'Production build');
-};
-
-cli.parse();
-```
-
-### How the CAC Adapter Works
-
-The CAC adapter:
-
-1. **Extracts Commands**: Automatically detects all commands defined with `cli.command()`
-2. **Extracts Options**: Identifies options defined with `.option()` for each command
-3. **Provides Handlers**: Gives you access to completion handlers for each command and option
-4. **Maintains Structure**: Preserves the command hierarchy and option relationships
-
-## Citty Adapter
-
-The Citty adapter works with Citty's command definitions and provides a similar interface for adding completions.
-
-```ts
-import { defineCommand, createMain } from 'citty';
-import tab from '@bomb.sh/tab/citty';
-
-const main = defineCommand({
- meta: {
- name: 'my-cli',
- description: 'My CLI tool',
- },
-});
-
-const devCommand = defineCommand({
- meta: {
- name: 'dev',
- description: 'Start dev server',
- },
- args: {
- port: { type: 'string', description: 'Specify port' },
- host: { type: 'string', description: 'Specify host' },
- },
-});
-
-const buildCommand = defineCommand({
- meta: {
- name: 'build',
- description: 'Build for production',
- },
- args: {
- mode: { type: 'string', description: 'Build mode' },
- },
-});
-
-main.subCommands = {
- dev: devCommand,
- build: buildCommand,
-};
-
-const completion = await tab(main);
-
-// Configure completions
-const devCommandCompletion = completion.commands.get('dev');
-if (devCommandCompletion) {
- const portOptionCompletion = devCommandCompletion.options.get('port');
- if (portOptionCompletion) {
- portOptionCompletion.handler = (complete) => {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
- };
- }
-}
-
-const cli = createMain(main);
-cli();
-```
-
-### How the Citty Adapter Works
-
-The Citty adapter:
-
-1. **Processes Command Definitions**: Analyzes the command structure defined with `defineCommand()`
-2. **Extracts Arguments**: Identifies arguments defined in the `args` object
-3. **Handles Subcommands**: Recursively processes nested subcommands
-4. **Provides Type Safety**: Leverages Citty's type system for better completion accuracy
-
-## Commander Adapter
-
-The Commander adapter works with Commander.js and provides completion handlers for its command structure.
-
-```ts
-import { Command } from 'commander';
-import tab from '@bomb.sh/tab/commander';
-
-const program = new Command();
-
-program
- .name('my-cli')
- .description('My CLI tool');
-
-program
- .command('dev')
- .description('Start development server')
- .option('-p, --port ', 'Specify port')
- .option('-h, --host ', 'Specify host');
-
-program
- .command('build')
- .description('Build for production')
- .option('-m, --mode ', 'Build mode');
-
-const completion = tab(program);
-
-// Configure completions
-const devCommandCompletion = completion.commands.get('dev');
-if (devCommandCompletion) {
- const portOptionCompletion = devCommandCompletion.options.get('port');
- if (portOptionCompletion) {
- portOptionCompletion.handler = (complete) => {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
- };
- }
-}
-
-program.parse();
-```
-
-### How the Commander Adapter Works
-
-The Commander adapter:
-
-1. **Processes Commands**: Analyzes the command structure defined with `program.command()`
-2. **Extracts Options**: Identifies options defined with `.option()`
-3. **Handles Aliases**: Automatically processes short and long option aliases
-4. **Maintains Hierarchy**: Preserves the command hierarchy and option relationships
-
-## Configuration
-
-All adapters support a configuration object to customize completion behavior:
-
-```ts
-import { CompletionConfig } from '@bomb.sh/tab';
-
-const config: CompletionConfig = {
- handler: async (previousArgs, toComplete, endsWithSpace) => {
- // Default handler for all commands
- return [];
- },
- options: {
- port: {
- handler: async () => {
- return [
- { value: '3000', description: 'Development port' },
- { value: '8080', description: 'Production port' },
- ];
- },
- },
- },
- subCommands: {
- dev: {
- handler: async () => {
- return [
- { value: 'dev', description: 'Development mode' },
- ];
- },
- options: {
- port: {
- handler: async () => {
- return [
- { value: '3000', description: 'Dev port' },
- ];
- },
- },
- },
- },
- },
-};
-
-// Use with any adapter
-const completion = await tab(cli, config);
-```
-
-## Best Practices
-
-### 1. Error Handling
-
-Always handle errors gracefully in your completion handlers:
-
-```ts
-portOptionCompletion.handler = async () => {
- try {
- // Expensive operation
- const results = await getPorts();
- return results.map(port => ({
- value: port.toString(),
- description: `Port ${port}`
- }));
- } catch (error) {
- // Return empty array instead of throwing
- console.error('Error in completion handler:', error);
- return [];
- }
-};
-```
-
-### 2. Context-Aware Completions
-
-Make your completions responsive to what the user is typing:
-
-```ts
-portOptionCompletion.handler = async (previousArgs, toComplete, endsWithSpace) => {
- if (toComplete.startsWith('30')) {
- return [
- { value: '3000', description: 'Development port' },
- ];
- }
-
- return [
- { value: '3000', description: 'Development port' },
- { value: '8080', description: 'Production port' },
- { value: '9000', description: 'Alternative port' },
- ];
-};
-```
-
-### 3. Performance Optimization
-
-Cache expensive operations and limit results:
-
-```ts
-let cachedPorts: Item[] | null = null;
-
-portOptionCompletion.handler = async () => {
- if (cachedPorts) {
- return cachedPorts;
- }
-
- const ports = await getAvailablePorts();
- cachedPorts = ports.slice(0, 20).map(port => ({
- value: port.toString(),
- description: `Port ${port}`
- }));
-
- return cachedPorts;
-};
-```
-
-### 4. Framework-Specific Considerations
-
-#### CAC
-
-- CAC automatically handles option parsing, so your completion handlers should focus on providing relevant suggestions
-- Use the option name as defined in your CAC command (e.g., `--port ` becomes `--port`)
-
-#### Citty
-
-- Citty's type system provides better type safety for completions
-- Arguments defined in the `args` object are automatically converted to options
-- Subcommands are processed recursively
-
-#### Commander.js
-
-- Commander.js supports both short and long option aliases
-- The adapter automatically handles both forms
-- Commands can have multiple aliases
-
-## Integration with Shell Setup
-
-After setting up your adapter, you still need to handle shell completion setup:
-
-```ts
-// Add this to your CLI entry point
-if (process.argv[2] === 'complete') {
- const shell = process.argv[3];
- if (shell && ['zsh', 'bash', 'fish', 'powershell'].includes(shell)) {
- // Generate shell completion script
- const script = generateCompletionScript(shell, 'my-cli', process.execPath);
- console.log(script);
- } else {
- // Handle completion requests
- const separatorIndex = process.argv.indexOf('--');
- const completionArgs = separatorIndex !== -1 ? process.argv.slice(separatorIndex + 1) : [];
- await completion.parse(completionArgs);
- }
-}
-```
-
-## Next Steps
-
-- Learn about [Best Practices](/docs/tab/guides/best-practices/) for effective autocompletions
-- Check out [Examples](/docs/tab/guides/examples/) for practical use cases
-- Explore the [API Reference](/docs/tab/api/core/) for advanced usage
\ No newline at end of file
diff --git a/src/content/docs/tab/guides/best-practices.mdx b/src/content/docs/tab/guides/best-practices.mdx
deleted file mode 100644
index 44e786a..0000000
--- a/src/content/docs/tab/guides/best-practices.mdx
+++ /dev/null
@@ -1,485 +0,0 @@
----
-title: Best Practices
-description: Learn best practices for implementing effective autocompletions with Tab
----
-
-This guide covers best practices for implementing effective autocompletions with Tab, including performance optimization, user experience considerations, and common patterns.
-
-## General Best Practices
-
-### 1. Provide Meaningful Descriptions
-
-Always include descriptive text for your completions to help users understand what each option does:
-
-```ts
-// Good
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port (default)');
- complete('8080', 'Production port');
- complete('9000', 'Alternative port');
-}, 'p');
-
-// Avoid
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', '');
- complete('8080', '');
-}, 'p');
-```
-
-### 2. Use Context-Aware Completions
-
-Make your completions responsive to what the user is typing:
-
-```ts
-devCmd.option('mode', 'Build mode', function(complete) {
- // If user is typing 'dev', suggest development
- if (this.toComplete?.startsWith('dev')) {
- complete('development', 'Development mode');
- return;
- }
-
- // If user is typing 'prod', suggest production
- if (this.toComplete?.startsWith('prod')) {
- complete('production', 'Production mode');
- return;
- }
-
- // Default suggestions
- complete('development', 'Development mode');
- complete('production', 'Production mode');
- complete('staging', 'Staging mode');
-});
-```
-
-### 3. Handle Errors Gracefully
-
-Always handle errors in your completion handlers to prevent crashes:
-
-```ts
-devCmd.option('config', 'Config file', async function(complete) {
- try {
- const files = await fs.readdir('.');
- const configFiles = files.filter(f => f.includes('config'));
- configFiles.forEach(file => complete(file, `Config file: ${file}`));
- } catch (error) {
- // Provide fallback completions instead of failing
- complete('vite.config.ts', 'Vite config file');
- complete('vite.config.js', 'Vite config file');
- }
-});
-```
-
-### 4. Optimize Performance
-
-Cache expensive operations and limit results to maintain responsiveness:
-
-```ts
-let cachedScripts: string[] | null = null;
-
-t.command('run', 'Run scripts')
- .argument('script', async function(complete) {
- if (cachedScripts) {
- cachedScripts.forEach(script => complete(script, `Run ${script} script`));
- return;
- }
-
- try {
- const packageJson = JSON.parse(await fs.readFile('package.json', 'utf8'));
- const scripts = Object.keys(packageJson.scripts || {});
- cachedScripts = scripts.slice(0, 20); // Limit to 20 scripts
- cachedScripts.forEach(script => complete(script, `Run ${script} script`));
- } catch (error) {
- // Fallback completions
- complete('dev', 'Start development server');
- complete('build', 'Build for production');
- }
- });
-```
-
-## Command Structure Best Practices
-
-### 1. Use Consistent Naming
-
-Follow consistent naming conventions for commands and options:
-
-```ts
-// Good - consistent with common CLI patterns
-t.command('dev', 'Start development server');
-t.command('build', 'Build for production');
-t.command('deploy', 'Deploy application');
-
-// Avoid - inconsistent naming
-t.command('start-dev', 'Start development server');
-t.command('build-prod', 'Build for production');
-t.command('deploy-app', 'Deploy application');
-```
-
-### 2. Group Related Commands
-
-Organize related commands logically:
-
-```ts
-// Development commands
-t.command('dev', 'Start development server');
-t.command('dev build', 'Build in development mode');
-t.command('dev test', 'Run tests in development mode');
-
-// Production commands
-t.command('build', 'Build for production');
-t.command('deploy', 'Deploy to production');
-t.command('deploy staging', 'Deploy to staging');
-```
-
-### 3. Use Short Aliases Sparingly
-
-Provide short aliases only for commonly used options:
-
-```ts
-// Good - short aliases for common options
-devCmd.option('port', 'Port number', handler, 'p');
-devCmd.option('host', 'Host address', handler, 'h');
-devCmd.option('verbose', 'Enable verbose logging', 'v');
-
-// Avoid - too many short aliases
-devCmd.option('config', 'Config file', handler, 'c');
-devCmd.option('mode', 'Build mode', handler, 'm');
-devCmd.option('output', 'Output directory', handler, 'o');
-devCmd.option('source', 'Source directory', handler, 's');
-```
-
-## Option Design Best Practices
-
-### 1. Use Boolean Flags Appropriately
-
-Use boolean flags for simple on/off options:
-
-```ts
-// Good - boolean flags for simple options
-devCmd.option('verbose', 'Enable verbose logging', 'v');
-devCmd.option('quiet', 'Suppress output', 'q');
-devCmd.option('watch', 'Watch for changes', 'w');
-
-// Good - value options for complex data
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
-}, 'p');
-```
-
-### 2. Provide Sensible Defaults
-
-When possible, provide sensible default values in your suggestions:
-
-```ts
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port (default)');
- complete('8080', 'Production port');
- complete('9000', 'Alternative port');
-}, 'p');
-```
-
-### 3. Use Descriptive Option Names
-
-Choose option names that clearly indicate their purpose:
-
-```ts
-// Good - descriptive names
-devCmd.option('output-dir', 'Output directory', handler);
-devCmd.option('source-map', 'Generate source maps', handler);
-
-// Avoid - ambiguous names
-devCmd.option('output', 'Output directory', handler);
-devCmd.option('map', 'Generate source maps', handler);
-```
-
-## Argument Design Best Practices
-
-### 1. Use Variadic Arguments for File Lists
-
-Use variadic arguments when users might want to specify multiple files:
-
-```ts
-// Good - variadic argument for multiple files
-t.command('lint', 'Lint files')
- .argument('files', function(complete) {
- complete('src/', 'Source directory');
- complete('tests/', 'Tests directory');
- complete('*.ts', 'TypeScript files');
- }, true); // true = variadic argument
-```
-
-### 2. Provide Contextual Suggestions
-
-Make argument suggestions contextual to the command:
-
-```ts
-t.command('copy', 'Copy files')
- .argument('source', function(complete) {
- // Suggest source locations
- complete('src/', 'Source directory');
- complete('dist/', 'Distribution directory');
- complete('public/', 'Public assets');
- })
- .argument('destination', function(complete) {
- // Suggest destination locations
- complete('build/', 'Build output');
- complete('release/', 'Release directory');
- complete('backup/', 'Backup location');
- });
-```
-
-## Package Manager Integration Best Practices
-
-### 1. Test CLI Compatibility
-
-When building CLI tools, test that they work with Tab's package manager integration:
-
-```bash
-# Test if your CLI supports Tab completions
-my-cli complete -- --help
-
-# Expected output format:
---help Show help information
-:0
-```
-
-### 2. Follow the Tab Protocol
-
-Ensure your CLI follows the Tab completion protocol:
-
-```ts
-// In your CLI entry point
-if (process.argv[2] === 'complete') {
- const shell = process.argv[3];
- if (shell && ['zsh', 'bash', 'fish', 'powershell'].includes(shell)) {
- t.setup('my-cli', process.execPath, shell);
- } else {
- const separatorIndex = process.argv.indexOf('--');
- const completionArgs = separatorIndex !== -1 ? process.argv.slice(separatorIndex + 1) : [];
- t.parse(completionArgs);
- }
-}
-```
-
-### 3. Provide Comprehensive Completions
-
-For package manager integration, provide completions for all major commands:
-
-```ts
-// Example: Comprehensive pnpm completions
-const addCmd = t.command('add', 'Install packages');
-addCmd.option('save-dev', 'Save to devDependencies', 'D');
-addCmd.option('save-optional', 'Save to optionalDependencies', 'O');
-addCmd.option('global', 'Install globally', 'g');
-
-const runCmd = t.command('run', 'Run scripts');
-runCmd.argument('script', async function(complete) {
- try {
- const packageJson = JSON.parse(await fs.readFile('package.json', 'utf8'));
- const scripts = Object.keys(packageJson.scripts || {});
- scripts.forEach(script => complete(script, `Run ${script} script`));
- } catch (error) {
- // Fallback completions
- complete('dev', 'Start development server');
- complete('build', 'Build for production');
- }
-}, true);
-```
-
-## Performance Best Practices
-
-### 1. Cache Expensive Operations
-
-Cache results of expensive operations to improve responsiveness:
-
-```ts
-let cachedDependencies: string[] | null = null;
-
-t.command('remove', 'Remove packages')
- .argument('package', async function(complete) {
- if (cachedDependencies) {
- cachedDependencies.forEach(dep => complete(dep, 'Installed package'));
- return;
- }
-
- try {
- const packageJson = JSON.parse(await fs.readFile('package.json', 'utf8'));
- const deps = {
- ...packageJson.dependencies,
- ...packageJson.devDependencies,
- };
- cachedDependencies = Object.keys(deps);
- cachedDependencies.forEach(dep => complete(dep, 'Installed package'));
- } catch (error) {
- // Fallback completions
- complete('react', 'React library');
- complete('typescript', 'TypeScript compiler');
- }
- });
-```
-
-### 2. Limit Result Sets
-
-Limit the number of completions to maintain performance:
-
-```ts
-devCmd.option('config', 'Config file', async function(complete) {
- try {
- const files = await fs.readdir('.');
- const configFiles = files.filter(f => f.includes('config'));
- // Limit to 10 results for performance
- configFiles.slice(0, 10).forEach(file => complete(file, `Config file: ${file}`));
- } catch (error) {
- complete('vite.config.ts', 'Vite config file');
- }
-});
-```
-
-### 3. Use Async Operations Sparingly
-
-Only use async operations when necessary:
-
-```ts
-// Good - sync operations for simple completions
-devCmd.option('mode', 'Build mode', function(complete) {
- complete('development', 'Development mode');
- complete('production', 'Production mode');
- complete('staging', 'Staging mode');
-});
-
-// Good - async operations for dynamic data
-devCmd.option('config', 'Config file', async function(complete) {
- const files = await fs.readdir('.');
- const configFiles = files.filter(f => f.includes('config'));
- configFiles.forEach(file => complete(file, `Config file: ${file}`));
-});
-```
-
-## User Experience Best Practices
-
-### 1. Provide Progressive Disclosure
-
-Start with common options and provide more specific ones as users type:
-
-```ts
-devCmd.option('mode', 'Build mode', function(complete) {
- if (this.toComplete?.startsWith('dev')) {
- complete('development', 'Development mode');
- return;
- }
-
- if (this.toComplete?.startsWith('prod')) {
- complete('production', 'Production mode');
- return;
- }
-
- // Show all options initially
- complete('development', 'Development mode');
- complete('production', 'Production mode');
- complete('staging', 'Staging mode');
- complete('test', 'Test mode');
-});
-```
-
-### 2. Use Consistent Descriptions
-
-Maintain consistent description formatting:
-
-```ts
-// Good - consistent formatting
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port (default)');
- complete('8080', 'Production port');
- complete('9000', 'Alternative port');
-}, 'p');
-
-// Avoid - inconsistent formatting
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'dev port');
- complete('8080', 'Production port');
- complete('9000', 'alt port');
-}, 'p');
-```
-
-### 3. Provide Helpful Defaults
-
-Include default values in descriptions when helpful:
-
-```ts
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port (default)');
- complete('8080', 'Production port');
-}, 'p');
-
-devCmd.option('host', 'Host address', function(complete) {
- complete('localhost', 'Localhost (default)');
- complete('0.0.0.0', 'All interfaces');
-}, 'h');
-```
-
-## Testing Best Practices
-
-### 1. Test Completions Manually
-
-Regularly test your completions to ensure they work correctly:
-
-```bash
-# Test command completions
-my-cli complete -- "dev"
-
-# Test option completions
-my-cli complete -- "dev --port"
-
-# Test argument completions
-my-cli complete -- "copy src/"
-
-# Test with package managers
-pnpm my-cli complete -- "dev --port"
-```
-
-### 2. Test Error Scenarios
-
-Test how your completions handle error conditions:
-
-```ts
-// Test with missing files
-devCmd.option('config', 'Config file', async function(complete) {
- try {
- const files = await fs.readdir('.');
- const configFiles = files.filter(f => f.includes('config'));
- configFiles.forEach(file => complete(file, `Config file: ${file}`));
- } catch (error) {
- // Ensure fallback completions work
- complete('vite.config.ts', 'Vite config file');
- complete('vite.config.js', 'Vite config file');
- }
-});
-```
-
-### 3. Test Performance
-
-Monitor completion performance, especially for async operations:
-
-```ts
-// Add timing for performance monitoring
-devCmd.option('config', 'Config file', async function(complete) {
- const start = Date.now();
- try {
- const files = await fs.readdir('.');
- const configFiles = files.filter(f => f.includes('config'));
- configFiles.forEach(file => complete(file, `Config file: ${file}`));
- } catch (error) {
- complete('vite.config.ts', 'Vite config file');
- }
- const duration = Date.now() - start;
- if (duration > 100) {
- console.warn(`Slow completion: ${duration}ms`);
- }
-});
-```
-
-## Next Steps
-
-- Check out [Examples](/docs/tab/guides/examples/) for practical use cases
-- Explore the [API Reference](/docs/tab/api/core/) for advanced usage
-- Learn about [Package Manager Integration](/docs/tab/guides/package-managers/) for enhanced completions
\ No newline at end of file
diff --git a/src/content/docs/tab/guides/examples.mdx b/src/content/docs/tab/guides/examples.mdx
deleted file mode 100644
index bbc880f..0000000
--- a/src/content/docs/tab/guides/examples.mdx
+++ /dev/null
@@ -1,443 +0,0 @@
----
-title: Examples
-description: Practical examples of using Tab with different CLI frameworks and scenarios
----
-
-This guide provides practical examples of using Tab with different CLI frameworks and common scenarios you might encounter when building CLI tools.
-
-## Basic CLI with Core API
-
-A simple CLI tool with basic autocompletions:
-
-```ts
-#!/usr/bin/env node
-import { RootCommand } from '@bomb.sh/tab';
-
-const t = new RootCommand();
-
-// Add global options
-t.option('config', 'Use specified config file', function(complete) {
- complete('vite.config.ts', 'Vite config file');
- complete('vite.config.js', 'Vite config file');
-}, 'c');
-
-t.option('mode', 'Set env mode', function(complete) {
- complete('development', 'Development mode');
- complete('production', 'Production mode');
-}, 'm');
-
-// Add root command argument
-t.argument('project', function(complete) {
- complete('my-app', 'My application');
- complete('my-lib', 'My library');
-});
-
-// Add commands with completions
-const devCmd = t.command('dev', 'Start development server');
-devCmd.option('port', 'Port number', function(complete) {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
-}, 'p');
-
-devCmd.option('host', 'Host address', function(complete) {
- complete('localhost', 'Local development');
- complete('0.0.0.0', 'All interfaces');
-}, 'h');
-
-devCmd.option('verbose', 'Enable verbose logging', 'v');
-
-// Add build command
-const buildCmd = t.command('build', 'Build for production');
-buildCmd.option('mode', 'Build mode', function(complete) {
- complete('development', 'Development build');
- complete('production', 'Production build');
-});
-
-buildCmd.option('out-dir', 'Output directory', function(complete) {
- complete('dist/', 'Distribution directory');
- complete('build/', 'Build directory');
-});
-
-// Add command with arguments
-t.command('copy', 'Copy files')
- .argument('source', function(complete) {
- complete('src/', 'Source directory');
- complete('dist/', 'Distribution directory');
- })
- .argument('destination', function(complete) {
- complete('build/', 'Build output');
- complete('release/', 'Release directory');
- });
-
-// Handle completion requests
-if (process.argv[2] === 'complete') {
- const shell = process.argv[3];
- if (shell && ['zsh', 'bash', 'fish', 'powershell'].includes(shell)) {
- t.setup('my-cli', process.execPath, shell);
- } else {
- // Parse completion arguments (everything after --)
- const separatorIndex = process.argv.indexOf('--');
- const completionArgs = separatorIndex !== -1 ? process.argv.slice(separatorIndex + 1) : [];
- t.parse(completionArgs);
- }
-} else {
- // Regular CLI usage
- console.log('My CLI Tool');
- console.log('Use "complete" command for shell completion');
-}
-```
-
-## CAC Framework Example
-
-A more complex CLI using CAC with Tab integration:
-
-```ts
-#!/usr/bin/env node
-import cac from 'cac';
-import tab from '@bomb.sh/tab/cac';
-
-const cli = cac('my-cli');
-
-// Define commands
-cli.command('dev', 'Start development server')
- .option('--port ', 'Specify port', { default: 3000 })
- .option('--host ', 'Specify host', { default: 'localhost' })
- .option('--config ', 'Config file')
- .action((options) => {
- console.log('Starting dev server...', options);
- });
-
-cli.command('build', 'Build for production')
- .option('--mode ', 'Build mode', { default: 'production' })
- .option('--out-dir ', 'Output directory')
- .action((options) => {
- console.log('Building...', options);
- });
-
-cli.command('deploy', 'Deploy application')
- .option('--env ', 'Deployment environment')
- .option('--region ', 'Deployment region')
- .action((options) => {
- console.log('Deploying...', options);
- });
-
-// Initialize Tab completion
-const completion = await tab(cli);
-
-// Configure custom completions
-const devCommandCompletion = completion.commands.get('dev');
-if (devCommandCompletion) {
- const portOptionCompletion = devCommandCompletion.options.get('port');
- if (portOptionCompletion) {
- portOptionCompletion.handler = (complete) => {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
- };
- }
-
- const configOptionCompletion = devCommandCompletion.options.get('config');
- if (configOptionCompletion) {
- configOptionCompletion.handler = (complete) => {
- complete('vite.config.ts', 'Vite config file');
- complete('vite.config.js', 'Vite config file');
- };
- }
-}
-
-const buildCommandCompletion = completion.commands.get('build');
-if (buildCommandCompletion) {
- const modeOptionCompletion = buildCommandCompletion.options.get('mode');
- if (modeOptionCompletion) {
- modeOptionCompletion.handler = (complete) => {
- complete('development', 'Development build');
- complete('production', 'Production build');
- };
- }
-}
-
-cli.parse();
-```
-
-## Citty Framework Example
-
-A CLI using Citty with Tab integration:
-
-```ts
-#!/usr/bin/env node
-import { defineCommand, createMain } from 'citty';
-import tab from '@bomb.sh/tab/citty';
-
-const main = defineCommand({
- meta: {
- name: 'my-cli',
- description: 'My CLI tool',
- },
-});
-
-const devCommand = defineCommand({
- meta: {
- name: 'dev',
- description: 'Start development server',
- },
- args: {
- port: { type: 'string', description: 'Specify port' },
- host: { type: 'string', description: 'Specify host' },
- config: { type: 'string', description: 'Config file' },
- },
-});
-
-const buildCommand = defineCommand({
- meta: {
- name: 'build',
- description: 'Build for production',
- },
- args: {
- mode: { type: 'string', description: 'Build mode' },
- outDir: { type: 'string', description: 'Output directory' },
- },
-});
-
-const deployCommand = defineCommand({
- meta: {
- name: 'deploy',
- description: 'Deploy application',
- },
- args: {
- env: { type: 'string', description: 'Deployment environment' },
- region: { type: 'string', description: 'Deployment region' },
- },
-});
-
-main.subCommands = {
- dev: devCommand,
- build: buildCommand,
- deploy: deployCommand,
-};
-
-const completion = await tab(main);
-
-// Configure completions
-const devCommandCompletion = completion.commands.get('dev');
-if (devCommandCompletion) {
- const portOptionCompletion = devCommandCompletion.options.get('port');
- if (portOptionCompletion) {
- portOptionCompletion.handler = (complete) => {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
- };
- }
-}
-
-const cli = createMain(main);
-cli();
-```
-
-## Commander.js Example
-
-A CLI using Commander.js with Tab integration:
-
-```ts
-#!/usr/bin/env node
-import { Command } from 'commander';
-import tab from '@bomb.sh/tab/commander';
-
-const program = new Command();
-
-program
- .name('my-cli')
- .description('My CLI tool')
- .version('1.0.0');
-
-program
- .command('dev')
- .description('Start development server')
- .option('-p, --port ', 'Specify port')
- .option('-h, --host ', 'Specify host')
- .option('-c, --config ', 'Config file')
- .action((options) => {
- console.log('Starting dev server...', options);
- });
-
-program
- .command('build')
- .description('Build for production')
- .option('-m, --mode ', 'Build mode')
- .option('-o, --out-dir ', 'Output directory')
- .action((options) => {
- console.log('Building...', options);
- });
-
-program
- .command('deploy')
- .description('Deploy application')
- .option('-e, --env ', 'Deployment environment')
- .option('-r, --region ', 'Deployment region')
- .action((options) => {
- console.log('Deploying...', options);
- });
-
-const completion = tab(program);
-
-// Configure completions
-const devCommandCompletion = completion.commands.get('dev');
-if (devCommandCompletion) {
- const portOptionCompletion = devCommandCompletion.options.get('port');
- if (portOptionCompletion) {
- portOptionCompletion.handler = (complete) => {
- complete('3000', 'Development port');
- complete('8080', 'Production port');
- };
- }
-}
-
-program.parse();
-```
-
-## Advanced Examples
-
-### Dynamic File Completions
-
-Load completions from the file system:
-
-```ts
-import { readdir } from 'fs/promises';
-import { RootCommand } from '@bomb.sh/tab';
-
-const t = new RootCommand();
-
-t.command('build', 'Build project')
- .option('config', 'Config file', async function(complete) {
- try {
- const files = await readdir('.');
- const configFiles = files.filter(f =>
- f.includes('config') && (f.endsWith('.js') || f.endsWith('.ts'))
- );
- configFiles.forEach(file => complete(file, `Config file: ${file}`));
- } catch (error) {
- // Fallback completions
- complete('vite.config.ts', 'Vite config file');
- complete('vite.config.js', 'Vite config file');
- }
- });
-```
-
-### Context-Aware Completions
-
-Provide different completions based on context:
-
-```ts
-const t = new RootCommand();
-
-t.command('deploy', 'Deploy application')
- .option('env', 'Environment', function(complete) {
- // Check if user is typing a specific environment
- if (this.toComplete?.startsWith('prod')) {
- complete('production', 'Production environment');
- return;
- }
-
- complete('development', 'Development environment');
- complete('staging', 'Staging environment');
- complete('production', 'Production environment');
- })
- .option('region', 'Region', function(complete) {
- // Provide region completions based on environment
- const env = this.command?.options?.get('--env')?.value;
-
- if (env === 'production') {
- complete('us-east-1', 'US East (N. Virginia)');
- complete('us-west-2', 'US West (Oregon)');
- complete('eu-west-1', 'Europe (Ireland)');
- } else {
- complete('us-east-1', 'US East (N. Virginia)');
- complete('eu-west-1', 'Europe (Ireland)');
- }
- });
-```
-
-### Package.json Script Completions
-
-Dynamically load completions from package.json:
-
-```ts
-import { readFile } from 'fs/promises';
-import { RootCommand } from '@bomb.sh/tab';
-
-const t = new RootCommand();
-
-t.command('run', 'Run scripts')
- .argument('script', async function(complete) {
- try {
- const packageJson = JSON.parse(await readFile('package.json', 'utf8'));
- const scripts = Object.keys(packageJson.scripts || {});
- scripts.forEach(script => complete(script, `Run ${script} script`));
- } catch (error) {
- // Fallback completions
- complete('dev', 'Start development server');
- complete('build', 'Build for production');
- complete('test', 'Run tests');
- }
- });
-```
-
-### Workspace Completions
-
-Handle monorepo workspace completions:
-
-```ts
-import { readFile, readdir } from 'fs/promises';
-import { RootCommand } from '@bomb.sh/tab';
-
-const t = new RootCommand();
-
-t.command('workspace', 'Workspace commands')
- .option('filter', 'Filter workspaces', async function(complete) {
- try {
- const packageJson = JSON.parse(await readFile('package.json', 'utf8'));
- const workspaces = packageJson.workspaces || [];
-
- // Get workspace names
- const workspaceNames = [];
- for (const workspace of workspaces) {
- if (workspace.includes('*')) {
- // Handle glob patterns
- const dir = workspace.replace('/*', '');
- const items = await readdir(dir);
- workspaceNames.push(...items);
- } else {
- workspaceNames.push(workspace);
- }
- }
-
- workspaceNames.forEach(name => complete(name, `Workspace: ${name}`));
- } catch (error) {
- // Fallback completions
- complete('packages/*', 'All packages');
- complete('apps/*', 'All applications');
- }
- });
-```
-
-## Testing Completions
-
-Test your completions manually:
-
-```bash
-# Test command completions
-my-cli complete -- "dev"
-
-# Test option completions
-my-cli complete -- "dev --port"
-
-# Test argument completions
-my-cli complete -- "copy src/"
-
-# Generate shell completion script
-my-cli complete zsh
-```
-
-## Next Steps
-
-- Learn about [Framework Adapters](/docs/tab/guides/adapters/) for easier integration
-- Check out [Best Practices](/docs/tab/guides/best-practices/) for effective autocompletions
-- Explore the [API Reference](/docs/tab/api/core/) for advanced usage
\ No newline at end of file
diff --git a/src/content/docs/tab/guides/package-managers.mdx b/src/content/docs/tab/guides/package-managers.mdx
deleted file mode 100644
index e9cccc3..0000000
--- a/src/content/docs/tab/guides/package-managers.mdx
+++ /dev/null
@@ -1,261 +0,0 @@
----
-title: Package Manager Integration
-description: Enhanced completions for npm, pnpm, yarn, and bun with automatic CLI discovery
----
-
-Tab provides a standalone CLI tool that enhances package manager completions with automatic discovery of CLI tools that support Tab completions. This guide focuses on the advanced features and unique capabilities of Tab's package manager integration.
-
-## Quick Setup
-
-For basic setup instructions, see the [Getting Started](/docs/tab/basics/getting-started/) guide. Here's the minimal setup:
-
-```bash
-# Install and configure
-npm install -g @bomb.sh/tab
-tab pnpm zsh > ~/.zsh_completions/tab-pnpm.zsh
-echo 'source ~/.zsh_completions/tab-pnpm.zsh' >> ~/.zshrc
-```
-
-## Advanced Features
-
-### Automatic CLI Discovery
-
-Tab automatically detects and provides completions for CLI tools in your project:
-
-```bash
-# Tab automatically discovers and provides completions for:
-pnpm vite dev --port # ← Vite completions
-pnpm tsc --target # ← TypeScript completions
-pnpm eslint --ext # ← ESLint completions
-pnpm jest --config # ← Jest completions
-```
-
-The discovery process:
-1. **Scans** `node_modules/.bin/` for available CLI tools
-2. **Tests** each tool for Tab compatibility (has a `complete` command)
-3. **Provides** completions automatically for compatible tools
-
-### Tab-Compatible CLIs
-
-A CLI tool is "Tab-compatible" if it follows the Tab protocol:
-
-```bash
-# Test compatibility
-my-cli complete -- --help
-
-# Expected output:
---help Show help information
-:0
-```
-
-### Dynamic Script Completions
-
-Tab reads your `package.json` to provide intelligent completions:
-
-```bash
-# Automatically suggests scripts from package.json
-pnpm run # Shows: dev, build, test, lint, etc.
-
-# Suggests dependencies for add/remove commands
-pnpm add # Shows installed packages
-pnpm remove # Shows installed packages
-```
-
-### Workspace Support
-
-Enhanced completions for monorepo setups:
-
-```bash
-# Workspace filtering
-pnpm --filter my-app run build
-pnpm --filter "packages/*" run test
-pnpm --filter "!packages/docs" run lint
-
-# Tab provides workspace-aware completions for:
-# - Workspace names
-# - Workspace patterns
-# - Workspace-specific scripts
-```
-
-### Context-Aware Completions
-
-Completions adapt based on your project context:
-
-```bash
-# In a TypeScript project
-pnpm tsc --target # Shows: es2020, es2021, es2022, etc.
-
-# In a Vite project
-pnpm vite build --mode # Shows: development, production, etc.
-
-# In a React project
-pnpm create-react-app # Shows: my-app, my-component, etc.
-```
-
-## Package Manager Specific Features
-
-### pnpm Enhancements
-
-```bash
-# Enhanced workspace commands
-pnpm workspace # Shows workspace commands
-pnpm --filter # Shows workspace names and patterns
-
-# Advanced install options
-pnpm add --save-dev # Shows dependency types
-pnpm install --frozen-lockfile # Shows install options
-```
-
-### npm Enhancements
-
-```bash
-# Config management
-npm config get # Shows config keys
-npm config set # Shows config keys
-
-# Package management
-npm install --save-dev # Shows dependency types
-npm run # Shows scripts with descriptions
-```
-
-### yarn Enhancements
-
-```bash
-# Workspace operations
-yarn workspace # Shows workspace commands
-yarn workspaces # Shows workspace operations
-
-# Cache management
-yarn cache # Shows cache operations
-yarn cache list # Shows cached packages
-```
-
-### bun Enhancements
-
-```bash
-# Runtime commands
-bun run # Shows scripts
-bun x # Shows available binaries
-
-# Development features
-bun dev # Shows dev commands
-bun test # Shows test options
-```
-
-## Configuration
-
-### Environment Variables
-
-```bash
-# Debug mode for troubleshooting
-export DEBUG=1
-
-# Custom timeout for slow completions
-export TAB_COMPLETION_TIMEOUT=3000
-
-# Disable automatic discovery (fallback to basic completions)
-export TAB_DISABLE_DISCOVERY=1
-```
-
-### Performance Optimization
-
-For large projects, you can optimize performance:
-
-```bash
-# Increase timeout for projects with many dependencies
-export TAB_COMPLETION_TIMEOUT=5000
-
-# Cache completions (experimental)
-export TAB_CACHE_COMPLETIONS=1
-```
-
-## Troubleshooting
-
-### Common Issues
-
-#### Completions are slow
-```bash
-# Increase timeout
-export TAB_COMPLETION_TIMEOUT=3000
-
-# Check for slow CLI tools
-DEBUG=1 tab pnpm complete -- --help
-```
-
-#### Some CLIs don't show completions
-```bash
-# Test CLI compatibility
-my-cli complete -- --help
-
-# Check if CLI follows Tab protocol
-# Should output completions ending with :{number}
-```
-
-#### Workspace completions not working
-```bash
-# Verify workspace configuration
-cat package.json | grep workspaces
-
-# Check workspace structure
-ls packages/ # Should show workspace directories
-```
-
-### Debug Mode
-
-Enable detailed logging:
-
-```bash
-# Full debug output
-DEBUG=1 tab pnpm complete -- --help
-
-# Check discovery process
-DEBUG=1 tab pnpm complete -- vite dev
-```
-
-## Advanced Usage
-
-### Custom Completion Handlers
-
-For advanced users, you can extend Tab's completion handlers by modifying the source:
-
-```bash
-# The completion handlers are in:
-# tab/bin/completion-handlers.ts
-# tab/bin/package-manager-completion.ts
-```
-
-### Integration with Other Tools
-
-Tab works alongside other completion tools:
-
-```bash
-# Use with existing pnpm completions
-source <(pnpm completion)
-
-# Tab enhances existing completions
-# rather than replacing them
-```
-
-## Best Practices
-
-### 1. Use Consistent Package Manager
-Stick to one package manager per project for the best experience.
-
-### 2. Keep CLI Tools Updated
-Regularly update your CLI tools to ensure Tab compatibility.
-
-### 3. Test in Your Projects
-```bash
-# Test completions in your specific projects
-tab pnpm complete -- --help
-pnpm vite complete -- --help
-```
-
-### 4. Share with Team
-Share your Tab setup to ensure consistent experience across your team.
-
-## Next Steps
-
-- Learn about [Framework Adapters](/docs/tab/guides/adapters/) for building Tab-compatible CLIs
-- Check out [Best Practices](/docs/tab/guides/best-practices/) for effective autocompletions
-- Explore the [API Reference](/docs/tab/api/core/) for building your own CLI tools
diff --git a/src/content/docs/tab/index.mdx b/src/content/docs/tab/index.mdx
index 65ad634..891521f 100644
--- a/src/content/docs/tab/index.mdx
+++ b/src/content/docs/tab/index.mdx
@@ -3,91 +3,231 @@ title: Tab
description: Shell autocompletions for JavaScript CLI tools
---
-import { CardGrid, Card } from '@astrojs/starlight/components';
+Shell autocompletions are largely missing in the JavaScript CLI ecosystem. tab provides a simple API for adding autocompletions to any JavaScript CLI tool.
-Tab is a powerful tool that brings shell autocompletions to JavaScript CLI tools. Inspired by tools like git and their excellent autocompletion experience, Tab makes the same functionality available for any JavaScript CLI project.
+Additionally, tab supports autocompletions for `pnpm`, `npm`, `yarn`, and `bun`.
-## Features
+Modern CLI libraries like [Gunshi](https://github.com/kazupon/gunshi) include tab completion natively in their core.
-
+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.
-
- Seamless integration with zsh, bash, fish, and PowerShell. Get native autocompletion experience for your CLI tools.
-
+tab solves this complexity by providing autocompletions that work consistently across `zsh`, `bash`, `fish`, and `powershell`.
-
- Built-in adapters for popular CLI frameworks including CAC, Citty, and Commander.js for easy integration.
-
+## Installation
-
- Built-in completions for npm, pnpm, yarn, and bun with automatic CLI discovery and completion detection.
-
+```bash
+npm install @bomb.sh/tab
+# or
+pnpm add @bomb.sh/tab
+# or
+yarn add @bomb.sh/tab
+# or
+bun add @bomb.sh/tab
+```
-
- Full TypeScript support with type-safe completion handlers and autocomplete suggestions.
-
+## Quick Start
-
- Define custom completion logic for commands and options with dynamic suggestions based on context.
-
+Add autocompletions to your CLI tool:
-
- Simple installation and configuration with minimal code changes to add autocompletion to your CLI.
-
+```typescript
+import t from '@bomb.sh/tab';
-
+// 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');
+});
-## Quick Start
+// 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);
+ }
+}
+```
+
+Test your completions:
+
+```bash
+node my-cli.js complete -- dev --port=
+# Output: --port=3000 Development port
+# --port=8080 Production port
+```
+
+Install for users:
+
+```bash
+# One-time setup
+source <(my-cli complete zsh)
+
+# Permanent setup
+my-cli complete zsh > ~/.my-cli-completion.zsh
+echo 'source ~/.my-cli-completion.zsh' >> ~/.zshrc
+```
+
+## Package Manager Completions
-### For CLI Tool Authors
+As mentioned earlier, tab provides completions for package managers as well:
-Add shell autocompletions to your CLI in just a few lines:
+```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
+```
+
+Example in action:
+
+```bash
+pnpm install --reporter=
+# Shows: append-only, default, ndjson, silent
+
+yarn add --emoji=
+# Shows: true, false
+```
-```ts
-import { RootCommand, script } from '@bomb.sh/tab';
+## Framework Adapters
-const t = new RootCommand();
+tab provides adapters for popular JavaScript CLI frameworks.
-// Add commands with completions
-t.command('dev', 'Start development server')
- .option('port', 'Port number', function(complete) {
+### CAC Integration
+
+```typescript
+import cac from 'cac';
+import tab from '@bomb.sh/tab/cac';
+
+const cli = cac('my-cli');
+
+// Define your CLI
+cli
+ .command('dev', 'Start dev server')
+ .option('--port ', 'Specify port')
+ .option('--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');
- }, 'p');
+ };
+}
-// Handle completion requests
-if (process.argv[2] === 'complete') {
- const shell = process.argv[3];
- if (shell && ['zsh', 'bash', 'fish', 'powershell'].includes(shell)) {
- t.setup('my-cli', process.execPath, shell);
- } else {
- const separatorIndex = process.argv.indexOf('--');
- const completionArgs = separatorIndex !== -1 ? process.argv.slice(separatorIndex + 1) : [];
- t.parse(completionArgs);
- }
+cli.parse();
+```
+
+### Citty Integration
+
+```typescript
+import { defineCommand, createMain } from 'citty';
+import tab from '@bomb.sh/tab/citty';
+
+const main = defineCommand({
+ 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' },
+ },
+ }),
+ },
+});
+
+// Initialize tab completions
+const completion = await tab(main);
+
+// 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();
```
-### For End Users
+### Commander.js Integration
+
+```typescript
+import { Command } from 'commander';
+import tab from '@bomb.sh/tab/commander';
+
+const program = new Command('my-cli');
+program.version('1.0.0');
+
+// Define commands
+program
+ .command('serve')
+ .description('Start the server')
+ .option('-p, --port ', 'port to use', '3000')
+ .option('-H, --host ', 'host to use', 'localhost')
+ .action((options) => {
+ console.log('Starting server...');
+ });
+
+// Initialize tab completions
+const completion = tab(program);
+
+// 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');
+ };
+}
-Get enhanced package manager completions with automatic CLI discovery:
+program.parse();
+```
+
+## How It Works
+
+tab uses a standardized completion protocol that any CLI can implement:
```bash
-# Install tab CLI
-npm install -g @bomb.sh/tab
+# Generate shell completion script
+my-cli complete zsh
-# Generate completions for your preferred package manager
-tab pnpm zsh > ~/.zsh_completions/tab-pnpm.zsh
-echo 'source ~/.zsh_completions/tab-pnpm.zsh' >> ~/.zshrc
+# Parse completion request (called by shell)
+my-cli complete -- install --port=""
+```
-# Now you get enhanced completions for all CLI tools!
-pnpm vite dev --port # ← Tab completion works here
+**Output Format:**
+
+```
+--port=3000 Development port
+--port=8080 Production port
+:4
```
-## What's Next?
+## Contributing
+
+We welcome contributions! tab's architecture makes it easy to add support for new package managers or CLI frameworks.
+
+## Acknowledgments
+
+tab was inspired by the great [Cobra](https://github.com/spf13/cobra/) project, which set the standard for CLI tooling in the Go ecosystem.
+
+## Adoption Support
-- [Getting Started](/docs/tab/basics/getting-started/) - Learn how to add autocompletions to your CLI
-- [Framework Adapters](/docs/tab/guides/adapters/) - Use Tab with CAC, Citty, and Commander.js
-- [Package Manager Integration](/docs/tab/guides/package-managers/) - Enhanced completions for npm, pnpm, yarn, and bun
-- [Best Practices](/docs/tab/guides/best-practices/) - Learn best practices for implementing autocompletions
-- [API Reference](/docs/tab/api/core/) - Detailed API documentation
\ No newline at end of file
+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.