# Shell Completions for Wasot

This guide explains how shell completions work and how to install them for the `wasot` [CLI](./cli.md) tool. For CLI design principles, see [CLI design](./cli_design.md).

## Table of Contents

- [What Are Shell Completions?](#what-are-shell-completions)
- [How Completions Work](#how-completions-work)
- [Generating Completions](#generating-completions)
- [Installation by Shell](#installation-by-shell)
  - [Bash](#bash)
  - [Zsh](#zsh)
  - [Fish](#fish)
  - [PowerShell](#powershell)
  - [Elvish](#elvish)
- [Verifying Installation](#verifying-installation)
- [Troubleshooting](#troubleshooting)

## What Are Shell Completions?

Shell completions (also called tab completions) allow you to press `Tab` while typing a command to automatically complete:

- **Subcommands**: `wasot to<Tab>` → shows `to-binary`, `to-jsonl`, `to-sqlite`, `to-wasot`, `to-yaml-test`
- **Options**: `wasot to-jsonl --<Tab>` → shows `--output`, `--help`
- **Arguments**: Context-aware suggestions for file paths, values, etc.

This dramatically speeds up CLI usage and helps discover available commands without consulting documentation.

## How Completions Work

Shell completions work through a cooperation between your shell and completion scripts:

1. **You type a partial command** and press `Tab`
2. **The shell invokes the completion script** for that command
3. **The script analyzes the current input** (command, subcommand, flags already used)
4. **It returns possible completions** to the shell
5. **The shell displays or auto-completes** based on the matches

Wasot uses [clap_complete](https://docs.rs/clap_complete) to generate these scripts automatically from its CLI definition. This ensures completions stay in sync with the actual CLI interface.

### Static vs Dynamic Completions

Wasot generates **static completions** - shell scripts that contain all the completion logic. These are:
- Fast (no process spawning on each `Tab`)
- Work offline
- Need regeneration when wasot is updated with new commands

## Generating Completions

Use the `completions` subcommand to generate completion scripts:

```bash
# See available shells
wasot completions --help

# Generate for your shell
wasot completions bash
wasot completions zsh
wasot completions fish
wasot completions powershell
wasot completions elvish
```

The script is printed to stdout, so redirect it to a file for installation.

## Installation by Shell

### Bash

Bash completions are typically stored in `/etc/bash_completion.d/` (system-wide) or `~/.local/share/bash-completion/completions/` (user).

```bash
# Option 1: User installation (recommended)
mkdir -p ~/.local/share/bash-completion/completions
wasot completions bash > ~/.local/share/bash-completion/completions/wasot

# Option 2: System-wide installation (requires root)
sudo wasot completions bash > /etc/bash_completion.d/wasot
```

For the completions to work, ensure bash-completion is installed and sourced:

```bash
# On Debian/Ubuntu
sudo apt install bash-completion

# On Fedora/RHEL
sudo dnf install bash-completion

# On macOS (with Homebrew)
brew install bash-completion@2
```

Add to your `~/.bashrc` if not already present:

```bash
# For Linux
if [ -f /etc/bash_completion ]; then
    . /etc/bash_completion
fi

# For macOS with Homebrew
[[ -r "/opt/homebrew/etc/profile.d/bash_completion.sh" ]] && . "/opt/homebrew/etc/profile.d/bash_completion.sh"
```

Reload your shell:

```bash
source ~/.bashrc
# or start a new terminal
```

### Zsh

Zsh completions go in a directory listed in your `$fpath`.

```bash
# Option 1: User installation with Oh My Zsh
wasot completions zsh > ~/.oh-my-zsh/completions/_wasot

# Option 2: User installation without Oh My Zsh
mkdir -p ~/.zsh/completions
wasot completions zsh > ~/.zsh/completions/_wasot

# Add to ~/.zshrc (if using Option 2):
fpath=(~/.zsh/completions $fpath)

# Option 3: System-wide installation
sudo wasot completions zsh > /usr/local/share/zsh/site-functions/_wasot
```

Enable completion system in `~/.zshrc` if not already:

```zsh
autoload -Uz compinit && compinit
```

Rebuild the completion cache and reload:

```bash
rm -f ~/.zcompdump
source ~/.zshrc
# or start a new terminal
```

### Fish

Fish has a dedicated completions directory:

```bash
# User installation
mkdir -p ~/.config/fish/completions
wasot completions fish > ~/.config/fish/completions/wasot.fish

# System-wide installation
sudo wasot completions fish > /usr/share/fish/vendor_completions.d/wasot.fish
```

Fish automatically loads completions from these directories - no configuration needed. Start a new shell or run:

```fish
source ~/.config/fish/completions/wasot.fish
```

### PowerShell

For PowerShell, add the completions to your profile:

```powershell
# Generate the completions
wasot completions powershell > wasot_completions.ps1

# Find your profile location
echo $PROFILE

# Add to your profile (create if it doesn't exist)
# Option 1: Append to profile
wasot completions powershell >> $PROFILE

# Option 2: Source from separate file
# Add this line to your $PROFILE:
# . /path/to/wasot_completions.ps1
```

Reload PowerShell or run:

```powershell
. $PROFILE
```

### Elvish

For Elvish shell:

```bash
# User installation
mkdir -p ~/.elvish/lib
wasot completions elvish > ~/.elvish/lib/wasot.elv

# Add to ~/.elvish/rc.elv:
use wasot
```

## Verifying Installation

After installation, test that completions work:

```bash
# Type 'wasot ' and press Tab - should show all subcommands
wasot <Tab>

# Type 'wasot to-' and press Tab - should show to-* commands
wasot to-<Tab>

# Type 'wasot to-jsonl --' and press Tab - should show options
wasot to-jsonl --<Tab>
```

Expected completions for `wasot <Tab>`:

```
base36-bench    demo            facade          from-binary
from-sqlite     links           links-demo      list-actions
listen-demo     pretty          protobuf-listener  random
select          to-binary       to-jsonl        to-sqlite
to-wasot        to-yaml-test    validate        xml-listener
completions     convert         fast-random     get-document-id
help
```

## Troubleshooting

### Completions not working at all

1. **Check the file exists** in the correct location
2. **Check file permissions** - should be readable (`chmod 644`)
3. **Verify shell configuration** is sourcing completions
4. **Start a new terminal** - some shells cache completion state

### Partial completions or errors

1. **Regenerate completions** after updating wasot:
   ```bash
   wasot completions <your-shell> > /path/to/completion/file
   ```

2. **Check for shell version compatibility** - older shells may have issues

### Bash-specific issues

```bash
# Check if bash-completion is loaded
type _init_completion 2>/dev/null && echo "bash-completion is loaded"

# Check if wasot completion is registered
complete -p wasot 2>/dev/null || echo "wasot completion not registered"
```

### Zsh-specific issues

```zsh
# Rebuild completion cache
rm -f ~/.zcompdump*
compinit

# Check fpath includes your completions directory
echo $fpath | tr ' ' '\n' | grep -E "(completions|zsh)"

# Verify the completion file is found
whence -v _wasot
```

### Fish-specific issues

```fish
# Check if completion file is recognized
complete --do-complete "wasot "

# List wasot completions
complete -c wasot
```

## Keeping Completions Updated

When you update wasot to a new version with new commands or options, regenerate the completions:

```bash
# Example for zsh
wasot completions zsh > ~/.zsh/completions/_wasot
rm -f ~/.zcompdump
source ~/.zshrc
```

Consider adding this to your wasot update workflow or creating an alias:

```bash
alias update-wasot-completions='wasot completions zsh > ~/.zsh/completions/_wasot && rm -f ~/.zcompdump'
```
