init

doc/runtime-completions.md

@@ -0,0 +1,101 @@
+# 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" "--iterative" ...($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 --iterative docker compose up`
+4. Caches the result; all subsequent completions are instant
+
+The `--iterative` flag tells inshellah to resolve only the immediate level
+without recursing into subcommands. This keeps each cache miss fast
+(~100-200ms) and lets the completer progressively resolve deeper levels
+on demand. Without `--iterative`, `inshellah help` recursively resolves
+all subcommands, which is better for upfront generation but too slow for
+interactive tab-completion.
+
+Depth is capped at 5 levels.
+
+## Cache management
+
+```sh
+rm -rf ~/.cache/inshellah/          # Clear all
+ls ~/.cache/inshellah/              # List cached
+inshellah help --iterative 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
+
+For one-off upfront generation (not runtime caching), use `inshellah help`
+without `--iterative` to recursively resolve all subcommands at once:
+
+```sh
+inshellah help docker > docker.nu  # Resolves all subcommands recursively
+```