# Runtime completion caching

For commands not covered by build-time generation, inshellah can generate
completions on first tab-press and cache the result.

## Setup

Add an external completer to your nushell config that calls inshellah
on cache miss:

```nu
# ~/.config/nushell/autoload/inshellah-completer.nu

const INSHELLAH_CACHE = ($nu.home-path | path join ".cache" "inshellah")

def inshellah-complete [spans: list<string>] {
    if ($spans | length) == 0 { return [] }
    mkdir $INSHELLAH_CACHE

    let max_depth = [($spans | length) 5] | math min
    mut cmd_spans = []

    for depth in (1..($max_depth)) {
        let candidate = ($spans | first $depth)
        let cache_key = ($candidate | str join "-")
        let cache_file = ($INSHELLAH_CACHE | path join $"($cache_key).nu")

        if ($cache_file | path exists) {
            $cmd_spans = $candidate
            break
        }

        try {
            let result = (run-external "inshellah" "help" ...($candidate) | complete)
            if $result.exit_code == 0 and ($result.stdout | str length) > 10 {
                $result.stdout | save -f $cache_file
                $cmd_spans = $candidate
                break
            }
        }
    }

    if ($cmd_spans | length) > 0 {
        let cache_key = ($cmd_spans | str join "-")
        let cache_file = ($INSHELLAH_CACHE | path join $"($cache_key).nu")
        if ($cache_file | path exists) { source $cache_file }
    }
}
```

Wire it in:

```nu
# ~/.config/nushell/config.nu
$env.config.completions.external = {
    enable: true
    completer: {|spans| inshellah-complete $spans }
}
```

## How it works

When you type `docker compose up --<TAB>`:

1. Nushell calls the completer with `spans = ["docker", "compose", "up", "--"]`
2. The completer tries progressively deeper prefixes as cache keys
3. On cache miss, runs `inshellah help docker compose up`
4. Caches the result; all subsequent completions are instant

First tab-press latency is ~100-200ms. Depth is capped at 5 levels.

## Cache management

```sh
rm -rf ~/.cache/inshellah/          # Clear all
ls ~/.cache/inshellah/              # List cached
inshellah help docker run > ~/.cache/inshellah/docker-run.nu  # Regenerate one
```

## When to use this vs build-time generation

The NixOS module (`programs.inshellah.enable = true`) handles most commands
at build time. Runtime caching is useful for:

- Commands installed outside the system profile (cargo, pip, npm, go)
- Subcommand completions at arbitrary depth
- Systems without the NixOS module