# Shell Completion for Theater CLI

This directory contains enhanced shell completion scripts for the Theater CLI that provide:

- **Static completions** for commands, options, and known values
- **Dynamic completions** for actor IDs, manifests, and other runtime data
- **Context-aware suggestions** based on the current command

## Features

### 🚀 **Smart Actor ID Completion**
- Automatically completes running actor IDs from the connected server
- Falls back to stored actor IDs when server is unavailable
- Works with commands like `stop`, `state`, `inspect`, `message`, etc.

### 📁 **File-aware Completion**
- Completes `.toml` manifest files for `start` and `build` commands
- Suggests appropriate file types based on context

### 🎯 **Context-sensitive Suggestions**
- Template names for `create` command (`basic`, `http`)
- Shell types for `completion` command (`bash`, `zsh`, `fish`, etc.)
- Channel operations (`open`)

## Installation

### Bash

```bash
# Option 1: Install to user completion directory
theater completion bash > ~/.local/share/bash-completion/completions/theater

# Option 2: Add to your ~/.bashrc
echo 'eval "$(theater completion bash)"' >> ~/.bashrc

# Option 3: Use the enhanced completion (recommended)
curl -o ~/.local/share/bash-completion/completions/theater \
  https://raw.githubusercontent.com/your-repo/theater/main/crates/theater-cli/completions/theater.bash
```

### Zsh

```zsh
# Option 1: Install to completion directory
theater completion zsh > ~/.local/share/zsh/site-functions/_theater

# Option 2: Add to your ~/.zshrc
echo 'eval "$(theater completion zsh)"' >> ~/.zshrc

# Option 3: Use the enhanced completion (recommended)
curl -o ~/.local/share/zsh/site-functions/_theater \
  https://raw.githubusercontent.com/your-repo/theater/main/crates/theater-cli/completions/theater.zsh
```

### Fish

```fish
# Option 1: Install to fish completions
theater completion fish > ~/.config/fish/completions/theater.fish

# Option 2: Use the enhanced completion (recommended)
curl -o ~/.config/fish/completions/theater.fish \
  https://raw.githubusercontent.com/your-repo/theater/main/crates/theater-cli/completions/theater.fish
```

### PowerShell

```powershell
# Add to your PowerShell profile
theater completion powershell | Out-String | Invoke-Expression
```

## Usage Examples

Once installed, you'll get intelligent completions:

```bash
# Complete commands
theater <TAB>
# → build, channel, create, events, inspect, list, message, start, state, stop, subscribe

# Complete actor IDs (dynamically fetched from server)
theater stop <TAB>
# → actor-123, actor-456, my-http-server, ...

# Complete templates
theater create <TAB>
# → basic, http

# Complete manifest files
theater spawn <TAB>
# → manifest.toml, examples/basic.toml, ...

# Complete channel operations
theater channel <TAB>
# → open

theater channel open <TAB>
# → actor-123, actor-456, my-http-server, ...
```

## How It Works

### Static Completions
Generated by clap's built-in completion system, providing basic command and option completions.

### Dynamic Completions
The enhanced completion scripts use a hidden `theater dynamic-completion` command that:

1. **Analyzes the current command line** to understand context
2. **Connects to the theater server** to fetch live actor IDs
3. **Falls back gracefully** to stored data when server is unavailable
4. **Provides contextual suggestions** based on the command being completed

### Performance
Dynamic completions are designed to be fast:
- Network requests timeout quickly if server is unavailable
- Results are cached within the shell session
- Fallback data is used when possible

## Troubleshooting

### Completions Not Working

1. **Verify installation:**
   ```bash
   # Check if completion file exists
   ls ~/.local/share/bash-completion/completions/theater
   ```

2. **Restart your shell** or source the completion:
   ```bash
   source ~/.bashrc  # for bash
   source ~/.zshrc   # for zsh
   ```

3. **Check theater CLI is in PATH:**
   ```bash
   which theater
   ```

### Dynamic Completions Not Working

1. **Test the dynamic completion command:**
   ```bash
   theater dynamic-completion "theater stop " "act"
   ```

2. **Check server connectivity:**
   ```bash
   theater list  # Should show running actors
   ```

3. **Enable verbose mode** to see debug output:
   ```bash
   theater -v dynamic-completion "theater stop " "act"
   ```

### Slow Completions

- Dynamic completions may be slower when the server is unresponsive
- Consider using cached/stored completions in development scripts
- The timeout is set to be very short (< 1 second) to avoid blocking

## Advanced Usage

### Custom Server Address
You can specify a different server address for completions:

```bash
# This won't work directly in shell completion, but shows the concept
theater dynamic-completion --address 192.168.1.100:9000 "theater stop " "act"
```

### Integration with Development Workflows

For development environments, you might want to create wrapper scripts:

```bash
#!/bin/bash
# dev-theater - wrapper that always connects to dev server
exec theater --address dev-server:9000 "$@"
```

Then install completions for the wrapper:

```bash
# Copy the completion and modify for your wrapper
cp ~/.local/share/bash-completion/completions/theater \   
   ~/.local/share/bash-completion/completions/dev-theater

# Edit the file to replace 'theater' with 'dev-theater'
```

## Contributing

To improve the completion system:

1. **Static completions** - Modify the clap command definitions
2. **Dynamic completions** - Update `src/commands/dynamic_completion.rs`
3. **Shell scripts** - Enhance the completion scripts in this directory

### Adding New Completions

To add completion for a new command:

1. **Add the command to the static list** in `get_command_completions()`
2. **Add dynamic logic** in `generate_dynamic_completions()` if needed
3. **Update shell scripts** to handle the new command pattern
4. **Test across all supported shells**

### Testing Completions

```bash
# Test static completions
theater completion bash > /tmp/test-completion
source /tmp/test-completion

# Test dynamic completions
theater dynamic-completion "theater stop " "test"
theater dynamic-completion "theater channel open " "my-"
```

## Shell-Specific Notes

### Bash
- Uses `complete -F` for programmable completion
- Supports `COMP_LINE` and `COMP_POINT` for context
- Fallback to file completion when appropriate

### Zsh
- Uses `_arguments` for sophisticated completion
- Supports descriptions alongside completions
- Better handling of subcommand completion

### Fish
- Uses `complete -c` syntax
- Function-based dynamic completions
- Excellent built-in caching

### PowerShell
- Tab completion via `Register-ArgumentCompleter`
- Different syntax but same underlying logic

## Future Enhancements

- **Completion caching** to improve performance
- **Configuration-aware completions** (different servers, profiles)
- **Smart filtering** based on actor types or states
- **Integration with shell history** for recently used actors
- **Completion for actor properties** (ports, versions, etc.)

## For Developers

If you have multiple versions of theater installed and completions aren't working:

```bash
# For zsh, clear any cached completions:
unfunction _theater 2>/dev/null
autoload -U compinit && compinit -D

# For bash, reload completions:
source ~/.bashrc

# For fish, restart fish or run:
fish_update_completions
```

---

> 💡 **Tip**: Use `theater completion --help` to see all available options and installation instructions.
