init

doc/runtime-completions.md

@@ -0,0 +1,105 @@
+# runtime completion resolution
+
+the `complete` command has built-in on-the-fly resolution: when a command
+is not found in the index, it falls back to running `--help`, caches the
+result, and returns completions immediately. this means commands installed
+outside the system profile (via cargo, pip, npm, go, etc.) get completions
+on first tab-press with no manual setup.
+
+## how it works
+
+when you type `docker compose up --<TAB>`:
+
+1. nushell calls `inshellah complete docker compose up --`
+2. inshellah looks up the index for the longest matching prefix
+3. if found, it fuzzy-matches flags and subcommands against the partial input
+4. if not found, it locates the binary in `$PATH`, runs `--help`,
+   recursively resolves subcommands, caches the results in the user
+   directory (`$XDG_CACHE_HOME/inshellah`), and returns completions.
+   if `--help` produces rendered manpage output, the raw manpage source
+   is located and parsed instead for richer results
+
+all subsequent completions for that command are instant (served from cache).
+
+## setup
+
+the completer works with no extra configuration beyond the basic setup:
+
+```nu
+# ~/.config/nushell/config.nu
+$env.config.completions.external = {
+    enable: true
+    completer: {|spans|
+        inshellah complete ...$spans
+        | from json
+    }
+}
+```
+
+with the nixos module, the installed wrapper has the system paths
+hardcoded — no extra flags needed. the same snippet works:
+
+```nu
+$env.config.completions.external = {
+    enable: true
+    completer: {|spans|
+        inshellah complete ...$spans
+        | from json
+    }
+}
+```
+
+to manually specify system dirs, use colon-separated `--dir`:
+
+```nu
+$env.config.completions.external = {
+    enable: true
+    completer: {|spans|
+        inshellah complete ...$spans --dir $"($env.XDG_CACHE_HOME)/inshellah:/run/current-system/sw/share/inshellah"
+        | from json
+    }
+}
+```
+
+system directories (paths after the first in `--dir`) enable
+manpage-based fallback: when a command's `--help` delegates to `man`,
+the completer looks for the raw manpage in the sibling `share/man`
+directory (e.g. `share/inshellah` → `share/man`). if no system dirs
+are given, it falls back to `man -w` to locate the manpage.
+
+or use the `snippet` option provided by the flake module (see
+[nixos.md](nixos.md)).
+
+## cache management
+
+the user cache lives at `$XDG_CACHE_HOME/inshellah` (typically
+`~/.cache/inshellah`).
+
+```sh
+# list cached commands
+inshellah dump
+
+# view cached data for a command
+inshellah query docker
+
+# clear cache
+rm -rf ~/.cache/inshellah/
+
+# re-index from a prefix
+inshellah index /usr --dir ~/.cache/inshellah
+```
+
+## when to use this vs build-time indexing
+
+the nixos module (`programs.inshellah.enable = true`) handles system
+packages at build time. runtime resolution covers:
+
+- commands installed outside the system profile (cargo, pip, npm, go)
+- subcommand completions at arbitrary depth
+- systems without the nixos module
+
+for upfront indexing on non-nixos systems:
+
+```sh
+inshellah index /usr /usr/local
+```