backlog-md/completions/README.md

# Shell Completion Scripts

**Note**: The completion scripts are embedded in the compiled `backlog` binary. These files serve as reference documentation and are used during development (the CLI reads them first if available, otherwise uses the embedded versions).

## Available Shells

### Zsh

**File**: `_backlog`

**Installation**:

1. **Automatic** (recommended):
   ```bash
   backlog completion install --shell zsh
   ```

2. **Manual**:
   ```bash
   # Copy to a directory in your $fpath
   sudo cp _backlog /usr/local/share/zsh/site-functions/_backlog

   # Or add to your custom completions directory
   mkdir -p ~/.zsh/completions
   cp _backlog ~/.zsh/completions/_backlog

   # Add to ~/.zshrc if not already present:
   fpath=(~/.zsh/completions $fpath)
   autoload -Uz compinit && compinit
   ```

3. **Testing without installation**:
   ```bash
   # In your current zsh session
   fpath=(./completions $fpath)
   autoload -Uz compinit && compinit
   ```

**Verification**:
```bash
# Type and press TAB
backlog <TAB>
backlog task <TAB>
```

### Bash

**File**: `backlog.bash`

**Installation**:

1. **Automatic** (recommended):
   ```bash
   backlog completion install --shell bash
   ```

2. **Manual**:
   ```bash
   # Copy to bash-completion directory
   sudo cp backlog.bash /etc/bash_completion.d/backlog

   # Or source in ~/.bashrc
   echo "source /path/to/backlog.bash" >> ~/.bashrc
   source ~/.bashrc
   ```

3. **Testing without installation**:
   ```bash
   # In your current bash session
   source ./completions/backlog.bash
   ```

**Verification**:
```bash
# Type and press TAB
backlog <TAB>
backlog task <TAB>
```

### Fish

**File**: `backlog.fish`

**Installation**:

1. **Automatic** (recommended):
   ```bash
   backlog completion install --shell fish
   ```

2. **Manual**:
   ```bash
   # Copy to fish completions directory
   cp backlog.fish ~/.config/fish/completions/backlog.fish

   # Completions are automatically loaded in new fish sessions
   ```

3. **Testing without installation**:
   ```bash
   # In your current fish session
   source ./completions/backlog.fish
   ```

**Verification**:
```bash
# Type and press TAB
backlog <TAB>
backlog task <TAB>
```

## How It Works

All completion scripts use the same backend:

1. The shell calls the completion function when TAB is pressed
2. The completion function invokes `backlog completion __complete "$BUFFER" "$CURSOR"`
3. The CLI returns a newline-separated list of completions
4. The shell presents these completions to the user

This architecture provides:
- **Dynamic completions**: Task IDs, labels, statuses are read from actual data
- **Consistent behavior**: All shells use the same completion logic
- **Easy maintenance**: Update completion logic once in TypeScript
- **Embedded scripts**: Scripts are built into the binary, no external files needed

## Development

### Testing Completions

**Zsh**:
```bash
# Run automated tests
zsh _backlog.test.zsh

# Or manually verify
zsh
source _backlog
which _backlog
```

**Bash**:
```bash
# Manually verify
bash
source backlog.bash
complete -p backlog
```

**Fish**:
```bash
# Run automated tests
fish backlog.test.fish

# Or manually verify
fish
source backlog.fish
complete -C'backlog '
```

### Adding New Completions

Completions are generated by:
- `/src/completions/helper.ts` - Main completion logic
- `/src/completions/command-structure.ts` - Command parsing
- `/src/completions/data-providers.ts` - Dynamic data (task IDs, labels, etc.)
- `/src/commands/completion.ts` - Embedded shell scripts in `getEmbeddedCompletionScript()`

To update completion scripts:
1. Edit the embedded scripts in `/src/commands/completion.ts`
2. (Optional) Update the reference files in `/completions/` for documentation
3. Rebuild: `bun run build`

## Requirements

- **Zsh**: Version 5.x or higher
- **Bash**: Version 4.x or higher
- **Fish**: Version 3.x or higher

## Troubleshooting

### Completions not working

1. Verify the CLI is in your PATH:
   ```bash
   which backlog
   ```

2. Check completion function is loaded:
   ```bash
   # Zsh
   which _backlog

   # Bash
   complete -p backlog

   # Fish
   complete -C'backlog '
   ```

3. Test the completion backend directly:
   ```bash
   backlog completion __complete "backlog task " 13
   ```
   This should output available subcommands for `backlog task`.

4. Reload your shell configuration:
   ```bash
   # Zsh
   exec zsh

   # Bash
   exec bash

   # Fish
   exec fish
   ```

### Slow completions

If completions feel slow, it may be because:
- Large number of tasks/documents in your backlog
- Network latency (if applicable)
- First completion triggers CLI initialization

The completion system is designed to be fast, but with very large datasets you may notice a slight delay.

## Contributing

When adding new completion features:

1. Update the backend in `/src/completions/`
2. Test with `backlog completion __complete`
3. Verify each shell script still works
4. Update this README if behavior changes