init

doc/nushell-integration.md

@@ -0,0 +1,121 @@
+# Using inshellah completions in nushell
+
+inshellah generates nushell completions from three sources (in priority order):
+1. **Native generators** — programs that can emit nushell completions directly
+2. **Manpages** — groff/troff manpage parsing
+3. **`--help` output** — parsing help text as a fallback
+
+Each command gets a module-wrapped `.nu` file suitable for nushell's autoload.
+
+## Quick start
+
+Generate completions for a single command:
+
+```sh
+# From a manpage
+inshellah manpage /usr/share/man/man1/git.1.gz > git.nu
+
+# From --help output (recursively resolves subcommands)
+inshellah help rg > rg.nu
+
+# Without recursive resolution (for on-demand / runtime caching)
+inshellah help --iterative rg > rg.nu
+
+# Pipe --help text directly
+curl --help | inshellah parse-help curl > curl.nu
+```
+
+## Full system generation
+
+The `generate` command runs all three strategies across an entire system:
+
+```sh
+mkdir -p ~/completions
+inshellah generate /usr/bin /usr/share/man -o ~/completions
+```
+
+This produces one `.nu` file per command in the output directory. Each file
+is module-wrapped:
+
+```nu
+module git-completions {
+export extern "git" [
+    --all(-a)
+    --verbose(-v)
+    ...
+]
+}
+
+use git-completions *
+```
+
+Programs that provide their own nushell completion generators (e.g.
+`niri completions nushell`) are detected automatically and their native
+output is used instead of parsing.
+
+## NixOS module
+
+Enable automatic completion generation at system build time:
+
+```nix
+{
+  imports = [ ./path/to/inshellah/nix/module.nix ];
+  programs.inshellah.enable = true;
+}
+```
+
+This runs `inshellah generate` during the system profile build,
+producing per-command `.nu` files in nushell's vendor autoload path.
+Completions are available immediately with no manual configuration.
+
+The module uses a three-phase pipeline:
+1. Scans executables in `$out/bin` for native nushell completion support
+2. Parses manpages from `$out/share/man` (man1 and man8 sections)
+3. Falls back to `--help` parsing for unmanpaged executables
+
+All phases run with ELF binary scanning to skip executables that don't
+contain help flags, parallel execution scaled to available cores, and
+200ms timeouts.
+
+## Loading completions manually
+
+### Option A: Autoload directory (recommended)
+
+Nushell automatically sources `.nu` files from vendor autoload paths
+(discovered via `$XDG_DATA_DIRS`) and `~/.config/nushell/autoload/`.
+
+```sh
+mkdir -p ~/.config/nushell/autoload
+inshellah generate /usr/bin /usr/share/man -o ~/.config/nushell/autoload
+```
+
+### Option B: Batch to stdout
+
+For simpler setups, the `manpage-dir` command writes all completions to
+stdout (without module wrapping):
+
+```sh
+inshellah manpage-dir /usr/share/man > ~/.config/nushell/autoload/completions.nu
+```
+
+## What gets generated
+
+Each command produces a nushell `extern` block with flags, parameter
+types, and descriptions extracted from the source:
+
+```nu
+export extern "rg" [
+    --regexp(-e): string            # A pattern to search for
+    --file(-f): path                # Search for patterns from the given file
+    --count(-c)                     # Only show the count of matching lines
+    --color: string                 # Controls when to use color
+    --max-depth: int                # Limit the depth of directory traversal
+]
+```
+
+Subcommand manpages (e.g. `git-commit.1`) are detected via SYNOPSIS
+parsing and generate the correct nushell name (`git commit` not
+`git-commit`).
+
+Nushell built-in commands (ls, cd, mv, etc.) are excluded since nushell
+provides its own completions for these.