init

.envrc

@@ -0,0 +1 @@
+use flake

.gitignore

@@ -0,0 +1,3 @@
+/target
+/_build
+/.direnv

README.md

@@ -0,0 +1,12 @@
+# inshellah
+
+nushell completions engine. indexes completions from manpages, native
+generators, and `--help` output, then serves them to nushell's external
+completer.
+
+see `doc/` for details:
+
+- [building and installing](doc/building.md) — compilation, arch/debian/fedora, opam, nix
+- [nushell integration](doc/nushell-integration.md) — setup, usage, examples
+- [nixos module](doc/nixos.md) — automatic build-time indexing
+- [runtime completions](doc/runtime-completions.md) — on-the-fly caching via the completer

bin/dune

@@ -0,0 +1,4 @@
+(executable
+ (public_name inshellah)
+ (name main)
+ (libraries inshellah))

doc/building.md

@@ -0,0 +1,163 @@
+# building and installing
+
+## dependencies
+
+inshellah is written in OCaml and uses dune as its build system.
+
+build dependencies:
+- **OCaml** >= 5.0
+- **dune** >= 3.20
+- **angstrom** — parser combinator library
+- **angstrom-unix** — unix extensions for angstrom
+- **camlzip** — gzip decompression for reading compressed manpages
+- **str** — regular expressions (ships with OCaml)
+- **unix** — process/file operations (ships with OCaml)
+
+runtime dependencies:
+- **man** (optional) — used as a fallback to locate manpages during
+  on-the-fly completion resolution. not needed if `--system-dir` is
+  provided (manpages are found via sibling `share/man`).
+
+## building with nix (recommended)
+
+if you have nix installed:
+
+```sh
+nix build
+```
+
+the binary is at `./result/bin/inshellah`.
+
+for development with a shell containing all dependencies:
+
+```sh
+nix develop
+dune build
+dune test
+```
+
+## building from source with opam
+
+install dependencies via opam:
+
+```sh
+opam install dune angstrom angstrom-unix camlzip
+```
+
+build and test:
+
+```sh
+dune build
+dune test
+```
+
+install into the opam switch:
+
+```sh
+dune install
+```
+
+## building from source without opam
+
+if your distribution packages the OCaml libraries directly, install
+them through your package manager, then build with dune:
+
+```sh
+dune build
+```
+
+the binary is at `_build/default/bin/main.exe`. copy it to your
+`$PATH`:
+
+```sh
+install -Dm755 _build/default/bin/main.exe /usr/local/bin/inshellah
+```
+
+## arch linux
+
+install OCaml and dune from the official repos, and the remaining
+libraries from the AUR or via opam:
+
+```sh
+# system packages
+sudo pacman -S ocaml dune
+
+# ocaml libraries (via opam)
+opam init    # if not already initialized
+eval $(opam env)
+opam install angstrom angstrom-unix camlzip
+
+# build
+dune build
+dune test
+
+# install
+sudo install -Dm755 _build/default/bin/main.exe /usr/local/bin/inshellah
+```
+
+## debian / ubuntu
+
+```sh
+sudo apt install ocaml opam
+opam init
+eval $(opam env)
+opam install dune angstrom angstrom-unix camlzip
+
+dune build
+sudo install -Dm755 _build/default/bin/main.exe /usr/local/bin/inshellah
+```
+
+## fedora
+
+```sh
+sudo dnf install ocaml opam
+opam init
+eval $(opam env)
+opam install dune angstrom angstrom-unix camlzip
+
+dune build
+sudo install -Dm755 _build/default/bin/main.exe /usr/local/bin/inshellah
+```
+
+## post-install setup
+
+after installing the binary, index completions from your system
+prefix(es):
+
+```sh
+# typical linux system
+inshellah index /usr /usr/local
+
+# check what was indexed
+inshellah dump
+```
+
+then wire up the nushell completer:
+
+```nu
+# ~/.config/nushell/config.nu
+$env.config.completions.external = {
+    enable: true
+    completer: {|spans|
+        inshellah complete ...$spans
+        | from json
+    }
+}
+```
+
+see [nushell-integration.md](nushell-integration.md) for full details
+on the completer, and [runtime-completions.md](runtime-completions.md)
+for on-the-fly resolution of commands not covered by the index.
+
+## re-indexing after package changes
+
+the index is a static cache — it doesn't update automatically when you
+install or remove packages. re-run `inshellah index` after significant
+package changes:
+
+```sh
+inshellah index /usr /usr/local
+```
+
+on nixos, the system index regenerates on every `nixos-rebuild`
+automatically. see [nixos.md](nixos.md) for details.

doc/nixos.md

@@ -0,0 +1,196 @@
+# nixos integration
+
+inshellah provides a nixos module that automatically indexes nushell
+completions for all installed packages at system build time.
+
+## enabling
+
+```nix
+# in your flake.nix outputs:
+{
+  nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
+    modules = [
+      inshellah.nixosModules.default
+      {
+        programs.inshellah.enable = true;
+      }
+    ];
+  };
+}
+```
+
+or if importing the module directly:
+
+```nix
+# configuration.nix
+{ pkgs, ... }: {
+  imports = [ ./path/to/inshellah/nix/module.nix ];
+  programs.inshellah = {
+    enable = true;
+    package = pkgs.inshellah;  # or your local build
+  };
+}
+```
+
+## what happens at build time
+
+the module hooks into `environment.extraSetup`, which runs during the
+system profile build (the `buildEnv` that creates `/run/current-system/sw`).
+at that point, all system packages are merged, so `$out/bin` contains every
+executable and `$out/share/man` contains every manpage.
+
+inshellah runs a single command:
+
+```
+inshellah index "$out" --dir $out/share/inshellah
+```
+
+this executes a three-phase pipeline:
+
+### phase 1: native completion detection (parallel)
+
+for each executable, inshellah scans the elf binary for the string
+`completion`. if found, it probes common patterns like
+`CMD completions nushell` to see if the program can generate its own
+nushell completions. native output is used verbatim — these are always
+higher quality than parsed completions.
+
+programs like `niri`, and any clap/cobra tool with nushell support,
+are handled this way.
+
+### phase 2: manpage parsing (sequential)
+
+for commands not covered by phase 1, inshellah parses manpages from
+man1 (user commands) and man8 (sysadmin commands). it handles:
+
+- gnu `.TP` style (coreutils, help2man)
+- `.IP` style (curl, hand-written)
+- `.PP`+`.RS`/`.RE` style (git, docbook)
+- nix3 bullet+hyperlink style (`nix run`, `nix build`, etc.)
+- mdoc (bsd) format
+- deroff fallback for unusual formats
+
+synopsis sections are parsed to detect subcommands: `git-commit.1`
+generates `export extern "git commit"`, not `export extern "git-commit"`.
+
+### phase 3: --help fallback (parallel)
+
+remaining executables without manpages get `--help` (or `-h`) called
+with a 200ms timeout. elf binaries are pre-scanned for the `-h` string
+to skip those that don't support help flags. shell scripts are run
+directly (they're fast). execution is parallelized to available cores.
+
+when `--help` produces rendered manpage output instead of plain help
+text (e.g. `git stash --help` delegates to `man`), the raw manpage
+source is located and parsed with the groff parser for richer results.
+
+### output
+
+each command gets its own file in `/share/inshellah` under the system
+profile. native generators produce `.nu` files; parsed results produce
+`.json` files. the `complete` command reads both formats.
+
+nushell built-in commands (ls, cd, cp, mv, etc.) are excluded since
+nushell provides its own completions.
+
+### performance
+
+on a typical nixos system (~950 executables, ~1600 manpages):
+- total time: ~4-10 seconds
+- native gzip decompression (camlzip, no process spawning)
+- parallel --help with core-scaled forking
+- elf string scanning to skip ~15% of binaries
+
+## module options
+
+```nix
+programs.inshellah = {
+  enable = true;
+
+  # the inshellah package (set automatically by the flake module)
+  package = pkgs.inshellah;
+
+  # where to place indexed completion files under the system profile
+  # default: "/share/inshellah"
+  completionsPath = "/share/inshellah";
+
+  # commands to skip entirely during indexing
+  ignoreCommands = [ "problematic-tool" ];
+
+  # commands to skip manpage parsing for (uses --help instead)
+  helpOnlyCommands = [ "nix" ];
+};
+```
+
+## using the completer
+
+the flake module sets a read-only `snippet` option containing the nushell
+config needed to wire up the completer. you can access it via
+`config.programs.inshellah.snippet` and paste it into your nushell config,
+or source it from a file generated by your nixos config.
+
+the snippet sets up the external completer pointing at the system index
+at `/run/current-system/sw/share/inshellah`:
+
+```nu
+let inshellah_complete = {|spans|
+    inshellah complete ...$spans --system-dir /run/current-system/sw/share/inshellah | from json
+}
+$env.config.completions.external = {
+    enable: true
+    max_results: 100
+    completer: $inshellah_complete
+}
+```
+
+## home manager and other user-level package managers
+
+the nixos module only indexes packages installed at the system level
+(those that end up in `/run/current-system/sw`). if you use home-manager,
+nix-env, or another user-level package manager, those binaries and
+manpages live elsewhere — typically under `/etc/profiles/per-user/<name>`
+or `~/.nix-profile`.
+
+to get completions for user-installed packages, run `inshellah index`
+against those prefixes separately:
+
+```sh
+# home-manager / per-user profile
+inshellah index /etc/profiles/per-user/$USER
+
+# classic nix-env profile
+inshellah index ~/.nix-profile
+```
+
+this indexes into the default user cache (`$XDG_CACHE_HOME/inshellah`),
+which the completer searches automatically. you can re-run this after
+installing new packages, or add it to a home-manager activation script.
+
+if you want to automate this in home-manager:
+
+```nix
+# home.nix
+home.activation.inshellah-index = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
+  ${pkgs.inshellah}/bin/inshellah index /etc/profiles/per-user/$USER 2>/dev/null || true
+'';
+```
+
+the completer will then search both the system index (`--system-dir`)
+and the user cache, so completions from both sources are available.
+
+## troubleshooting
+
+**completions not appearing**: ensure the completer is configured in
+your nushell config (see above). check that the system index exists:
+`ls /run/current-system/sw/share/inshellah/`.
+
+**missing completions for a specific command**: check if it's a nushell
+built-in (`help commands | where name == "thecommand"`). built-ins are
+excluded because nushell serves its own completions for them.
+
+**stale completions after update**: completions regenerate on every
+`nixos-rebuild`. if a command changed its flags, rebuild to pick up
+the changes.
+
+**build-time errors**: indexing failures are non-fatal (`|| true`).
+check `journalctl` for the build log if completions are missing.

doc/nushell-integration.md

@@ -0,0 +1,191 @@
+# using inshellah completions in nushell
+
+inshellah indexes completions from three sources (in priority order):
+1. **native generators** — programs that can emit nushell completions directly
+2. **manpages** — groff/troff/mdoc manpage parsing
+3. **`--help` output** — parsing help text as a fallback
+
+indexed data is stored as `.json` and `.nu` files in a directory that the
+`complete` command reads from at tab-completion time.
+
+## quick start
+
+index completions from a system prefix:
+
+```sh
+# index from a prefix containing bin/ and share/man/
+inshellah index /usr
+
+# index from multiple prefixes
+inshellah index /usr /usr/local
+
+# store in a custom directory
+inshellah index /usr --dir ~/my-completions
+```
+
+parse a single manpage:
+
+```sh
+inshellah manpage /usr/share/man/man1/git.1.gz
+```
+
+batch-process all manpages under a directory (man1 and man8):
+
+```sh
+inshellah manpage-dir /usr/share/man
+```
+
+## commands
+
+```
+inshellah index PREFIX... [--dir PATH] [--ignore FILE] [--help-only FILE]
+    index completions into a directory of json/nu files.
+    PREFIX is a directory containing bin/ and share/man/.
+    default dir: $XDG_CACHE_HOME/inshellah
+    --ignore FILE     skip listed commands entirely
+    --help-only FILE  skip manpages for listed commands, use --help instead
+
+inshellah complete CMD [ARGS...] [--dir PATH] [--system-dir PATH]
+    nushell custom completer. outputs json completion candidates.
+    falls back to --help resolution if command is not indexed.
+    manpages are found via sibling share/man of --system-dir paths.
+
+inshellah query CMD [--dir PATH] [--system-dir PATH]
+    print stored completion data for CMD.
+
+inshellah dump [--dir PATH] [--system-dir PATH]
+    list indexed commands.
+
+inshellah manpage FILE
+    parse a manpage and emit nushell extern block.
+
+inshellah manpage-dir DIR
+    batch-process manpages under DIR (man1 and man8 sections).
+```
+
+## the index pipeline
+
+the `index` command runs a three-phase pipeline over all executables
+in each `PREFIX/bin`:
+
+### phase 1: native completion detection (parallel)
+
+for each executable, inshellah scans the elf binary for the string
+`completion`. if found, it probes common patterns like
+`CMD completions nushell` to see if the program can generate its own
+nushell completions. native output is used verbatim — these are always
+higher quality than parsed completions.
+
+programs like `niri`, and any clap/cobra tool with nushell support,
+are handled this way.
+
+### phase 2: manpage parsing (sequential)
+
+for commands not covered by phase 1, inshellah parses manpages from
+man1 (user commands) and man8 (sysadmin commands). it handles:
+
+- gnu `.TP` style (coreutils, help2man)
+- `.IP` style (curl, hand-written)
+- `.PP`+`.RS`/`.RE` style (git, docbook)
+- nix3 bullet+hyperlink style (`nix run`, `nix build`, etc.)
+- mdoc (bsd) format
+- deroff fallback for unusual formats
+
+synopsis sections are parsed to detect subcommands: `git-commit.1`
+generates `export extern "git commit"`, not `export extern "git-commit"`.
+
+### phase 3: --help fallback (parallel)
+
+remaining executables without manpages get `--help` (or `-h`) called
+with a 200ms timeout. elf binaries are pre-scanned for the `-h` string
+to skip those that don't support help flags. shell scripts are run
+directly (they're fast). execution is parallelized to available cores.
+
+subcommands are recursively resolved — if `--help` output lists
+subcommands, inshellah runs `CMD SUBCMD --help` for each.
+
+when a `--help` invocation produces rendered manpage output (some
+commands like `git stash` delegate `--help` to `man`), inshellah
+detects this and locates the raw manpage source to parse with the
+groff parser instead. this yields richer results (subcommands,
+structured flag sections) than parsing the rendered text.
+
+### output
+
+each command gets its own file in the index directory. native generators
+produce `.nu` files; parsed results produce `.json` files. the `complete`
+command reads both formats.
+
+nushell built-in commands (ls, cd, cp, mv, etc.) are excluded since
+nushell provides its own completions.
+
+### performance
+
+on a typical nixos system (~950 executables, ~1600 manpages):
+- total time: ~4-10 seconds
+- native gzip decompression (camlzip, no process spawning)
+- parallel --help with core-scaled forking
+- elf string scanning to skip ~15% of binaries
+
+## the completer
+
+the `complete` command is designed to be wired into nushell as an
+external completer. it reads from the index directory (`--dir`) and
+optional system directories (`--system-dir`), performs fuzzy matching,
+and outputs json completion candidates.
+
+if a command is not indexed, `complete` falls back to on-the-fly
+`--help` resolution — it runs the command's help, caches the result
+in the user directory, and returns completions immediately.
+
+### setting up the completer
+
+```nu
+# ~/.config/nushell/config.nu
+$env.config.completions.external = {
+    enable: true
+    completer: {|spans|
+        inshellah complete ...$spans
+        | from json
+    }
+}
+```
+
+with the nixos module, use the provided `snippet` option value (see
+[nixos.md](nixos.md)) which points at the system index automatically.
+
+## nixos module
+
+enable automatic completion indexing at system build time:
+
+```nix
+{
+  imports = [ ./path/to/inshellah/nix/module.nix ];
+  programs.inshellah.enable = true;
+}
+```
+
+this runs `inshellah index` during the system profile build. see
+[nixos.md](nixos.md) for full details.
+
+## what gets generated
+
+the `manpage` and `manpage-dir` commands emit nushell `extern` blocks
+with flags, parameter types, and descriptions:
+
+```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.

doc/runtime-completions.md

@@ -0,0 +1,92 @@
+# 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, add `--system-dir` to also search the system index:
+
+```nu
+$env.config.completions.external = {
+    enable: true
+    completer: {|spans|
+        inshellah complete ...$spans --system-dir /run/current-system/sw/share/inshellah
+        | from json
+    }
+}
+```
+
+`--system-dir` also enables 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-dir` is 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
+```

dune-project

@@ -0,0 +1,28 @@
+(lang dune 3.20)
+
+(name inshellah)
+
+(generate_opam_files true)
+
+(source
+ (github username/reponame))
+
+(authors "atagen <boss@atagen.co>")
+
+(maintainers "atagen <boss@atagen.co>")
+
+(license GPL-3.0-or-later)
+
+(package
+ (name inshellah)
+ (synopsis "Nushell completions generator")
+ (description
+  "Inshellah parses manpages and --help switches to generate completions for nushell.")
+ (depends
+  ocaml
+  dune
+  angstrom
+  angstrom-unix
+  camlzip)
+ (tags
+  (shell completions nushell parser angstrom)))

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1773385838,
+        "narHash": "sha256-ylF2AGl08seexxlLvMqj3jd+yZq56W9zicwe51mp0Pw=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "fef542e7a88eec2b698389e6279464fd479926b6",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,71 @@
+{
+  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
+
+  outputs =
+    { self, nixpkgs }:
+    let
+      forAllSystems =
+        f:
+        nixpkgs.lib.genAttrs [ "x86_64-linux" "aarch64-linux" ] (
+          system: f (import nixpkgs { inherit system; })
+        );
+    in
+    {
+      devShells = forAllSystems (pkgs: {
+        default = pkgs.mkShell {
+          packages = with pkgs.ocamlPackages; [
+            dune_3
+            ocaml
+            angstrom
+            angstrom-unix
+            camlzip
+            ppx_inline_test
+            ocaml-lsp
+            ocamlformat
+            ocamlformat-rpc-lib
+            utop
+          ];
+        };
+      });
+
+      packages = forAllSystems (pkgs: {
+        default = pkgs.ocamlPackages.buildDunePackage {
+          pname = "inshellah";
+          version = "0.1";
+          src = ./.;
+          nativeBuildInputs = [ pkgs.git ];
+          buildInputs = with pkgs.ocamlPackages; [
+            dune_3
+            ocaml
+            angstrom
+            angstrom-unix
+            camlzip
+          ];
+
+          meta.mainProgram = "inshellah";
+        };
+      });
+
+      nixosModules.default =
+        {
+          pkgs,
+          lib,
+          config,
+          ...
+        }:
+        {
+          imports = [ ./nix/module.nix ];
+          programs.inshellah.package = self.packages.${pkgs.stdenv.hostPlatform.system}.default;
+          programs.inshellah.snippet = ''
+            let inshellah_complete = {|spans|
+              ${lib.getExe config.programs.inshellah.package} complete ...$spans --system-dir /run/current-system/sw/${config.programs.inshellah.completionsPath} | from json
+            }
+            $env.config.completions.external = {
+              enable: true
+              max_results: 100
+              completer: $inshellah_complete
+            }
+          '';
+        };
+    };
+}

inshellah.opam

@@ -0,0 +1,35 @@
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "Nushell completions generator"
+description:
+  "Inshellah parses manpages and --help switches to generate completions for nushell."
+maintainer: ["atagen <boss@atagen.co>"]
+authors: ["atagen <boss@atagen.co>"]
+license: "GPL-3.0-or-later"
+tags: ["shell" "completions" "nushell" "parser" "angstrom"]
+homepage: "https://github.com/username/reponame"
+bug-reports: "https://github.com/username/reponame/issues"
+depends: [
+  "ocaml"
+  "dune" {>= "3.20"}
+  "angstrom"
+  "angstrom-unix"
+  "camlzip"
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/username/reponame.git"
+x-maintenance-intent: ["(latest)"]

lib/dune

@@ -0,0 +1,3 @@
+(library
+ (name inshellah)
+ (libraries angstrom angstrom-unix camlzip str unix))

lib/nushell.ml

@@ -0,0 +1,253 @@
+(* nushell.ml — generate nushell extern definitions from parsed help data.
+ *
+ * this module is the code generation backend. it takes a help_result (from
+ * the parser or manpage modules) and produces nushell source code that
+ * defines `extern` declarations — nushell's mechanism for teaching the shell
+ * about external commands' flags and subcommands so it can offer completions.
+ *
+ * it also maintains a list of nushell's built-in commands to avoid generating
+ * extern definitions that would shadow them.
+ *
+ * key responsibilities:
+ *   - deduplicating flag entries (same flag from multiple help sources)
+ *   - mapping parameter names to nushell types (path, int, string)
+ *   - formatting flags in nushell syntax: --flag(-f): type  # description
+ *   - handling positional arguments with nushell's ordering constraints
+ *   - escaping special characters for nushell string literals
+ *)
+
+open Parser
+
+module SSet = Set.Make(String)
+module SMap = Map.Make(String)
+module CSet = Set.Make(Char)
+
+(* nushell built-in commands and keywords — we must never generate `extern`
+ * definitions for these because it would shadow nushell's own implementations.
+ * this list is maintained manually and should be updated with new nushell releases. *)
+let nushell_builtins = [
+  "alias"; "all"; "ansi"; "any"; "append"; "ast"; "attr";
+  "bits"; "break"; "bytes";
+  "cal"; "cd"; "char"; "chunk-by"; "chunks"; "clear"; "collect";
+  "columns"; "commandline"; "compact"; "complete"; "config"; "const";
+  "continue"; "cp";
+  "date"; "debug"; "decode"; "def"; "default"; "describe"; "detect";
+  "do"; "drop"; "du";
+  "each"; "echo"; "encode"; "enumerate"; "error"; "every"; "exec";
+  "exit"; "explain"; "explore"; "export"; "export-env"; "extern";
+  "fill"; "filter"; "find"; "first"; "flatten"; "for"; "format"; "from";
+  "generate"; "get"; "glob"; "grid"; "group-by";
+  "hash"; "headers"; "help"; "hide"; "hide-env"; "histogram";
+  "history"; "http";
+  "if"; "ignore"; "input"; "insert"; "inspect"; "interleave"; "into";
+  "is-admin"; "is-empty"; "is-not-empty"; "is-terminal"; "items";
+  "job"; "join";
+  "keybindings"; "kill";
+  "last"; "length"; "let"; "let-env"; "lines"; "load-env"; "loop"; "ls";
+  "match"; "math"; "merge"; "metadata"; "mkdir"; "mktemp"; "module";
+  "move"; "mut"; "mv";
+  "nu-check"; "nu-highlight";
+  "open"; "overlay";
+  "panic"; "par-each"; "parse"; "path"; "plugin"; "port"; "prepend"; "print"; "ps";
+  "query";
+  "random"; "reduce"; "reject"; "rename"; "return"; "reverse"; "rm";
+  "roll"; "rotate"; "run-external";
+  "save"; "schema"; "scope"; "select"; "seq"; "shuffle"; "skip"; "sleep";
+  "slice"; "sort"; "sort-by"; "source"; "source-env"; "split"; "start";
+  "stor"; "str"; "sys";
+  "table"; "take"; "tee"; "term"; "timeit"; "to"; "touch"; "transpose";
+  "try"; "tutor";
+  "ulimit"; "umask"; "uname"; "uniq"; "uniq-by"; "unlet"; "update";
+  "upsert"; "url"; "use";
+  "values"; "version"; "view";
+  "watch"; "where"; "which"; "while"; "whoami"; "window"; "with-env"; "wrap";
+  "zip";
+]
+
+(* lazily constructed set for fast membership checks against builtins *)
+let builtin_set = lazy (SSet.of_list nushell_builtins)
+
+(* returns true if the given command name collides with a nushell built-in *)
+let is_nushell_builtin cmd =
+  SSet.mem cmd (Lazy.force builtin_set)
+
+(* deduplicate flag entries that refer to the same flag.
+ * when the same flag appears multiple times (e.g. from overlapping manpage
+ * sections or repeated help text), we keep the "best" version using a score:
+ *   - both short+long form present: +10 (most informative)
+ *   - has a parameter: +5
+ *   - description length bonus: up to +5
+ *
+ * after deduplication by long name, we also remove standalone short flags
+ * whose letter is already covered by a Both(short, long) entry. this prevents
+ * emitting both "-v" and "--verbose(-v)" which nushell would reject as a
+ * duplicate. the filtering preserves original ordering from the help text. *)
+let dedup_entries entries =
+  (* produce a canonical key for each entry based on its switch form *)
+  let key_of entry =
+    match entry.switch with
+    | Short c -> Printf.sprintf "-%c" c
+    | Long l | Both (_, l) -> Printf.sprintf "--%s" l
+  in
+  (* compute a quality score for ranking duplicate entries *)
+  let score entry =
+    let switch_bonus = match entry.switch with Both _ -> 10 | _ -> 0 in
+    let param_bonus = match entry.param with Some _ -> 5 | None -> 0 in
+    let desc_bonus = min 5 (String.length entry.desc / 10) in
+    switch_bonus + param_bonus + desc_bonus
+  in
+  (* fold over entries, keeping only the highest-scored entry per key *)
+  let best = List.fold_left (fun acc entry ->
+    let key = key_of entry in
+    match SMap.find_opt key acc with
+    | Some prev when score prev >= score entry -> acc
+    | _ -> SMap.add key entry acc
+  ) SMap.empty entries in
+  (* collect all short-flag characters that are already part of a Both entry,
+   * so we can suppress standalone Short entries for the same character *)
+  let covered = SMap.fold (fun _ entry acc ->
+    match entry.switch with
+    | Both (c, _) -> CSet.add c acc
+    | _ -> acc
+  ) best CSet.empty in
+  (* emit entries in original order, skipping duplicates and covered shorts *)
+  List.fold_left (fun (seen, acc) entry ->
+    let key = key_of entry in
+    if SSet.mem key seen then (seen, acc)
+    else match entry.switch with
+    | Short c when CSet.mem c covered -> (seen, acc)
+    | _ -> (SSet.add key seen, SMap.find key best :: acc)
+  ) (SSet.empty, []) entries |> snd |> List.rev
+
+(* map parameter names to nushell types.
+ * nushell's `extern` declarations use typed parameters, so we infer the type
+ * from the parameter name. file/path-related names become "path" (enables
+ * path completion), numeric names become "int", everything else is "string". *)
+let nushell_type_of_param = function
+  | "FILE" | "file" | "PATH" | "path" | "DIR" | "dir" | "DIRECTORY"
+  | "FILENAME" | "PATTERNFILE" -> "path"
+  | "NUM" | "N" | "COUNT" | "NUMBER" | "int" | "INT" | "COLS" | "WIDTH"
+  | "LINES" | "DEPTH" | "depth" -> "int"
+  | _ -> "string"
+
+(* escape a string for use inside nushell double-quoted string literals.
+ * only double quotes and backslashes need escaping in nushell's syntax. *)
+let escape_nu s =
+  if not (String.contains s '"') && not (String.contains s '\\') then s
+  else begin
+    let buf = Buffer.create (String.length s + 4) in
+    String.iter (fun c -> match c with
+      | '"' -> Buffer.add_string buf "\\\""
+      | '\\' -> Buffer.add_string buf "\\\\"
+      | _ -> Buffer.add_char buf c
+    ) s;
+    Buffer.contents buf
+  end
+
+(* format a single flag entry as a nushell `extern` parameter line.
+ * output examples:
+ *   "    --verbose(-v)                       # increase verbosity"
+ *   "    --output(-o): path                  # write output to file"
+ *   "    -n: int                             # number of results"
+ *
+ * the description is right-padded to column 40 with a "# " comment prefix.
+ * nushell's syntax for combined short+long is "--long(-s)". *)
+let format_flag entry =
+  let name = match entry.switch with
+    | Both (short_char, l) -> Printf.sprintf "--%s(-%c)" l short_char
+    | Long l -> Printf.sprintf "--%s" l
+    | Short short_char -> Printf.sprintf "-%c" short_char
+  in
+  let typed = match entry.param with
+    | Some (Mandatory p) | Some (Optional p) -> ": " ^ nushell_type_of_param p
+    | None -> ""
+  in
+  let flag = "    " ^ name ^ typed in
+  if String.length entry.desc = 0 then flag
+  else
+    let pad_len = max 1 (40 - String.length flag) in
+    flag ^ String.make pad_len ' ' ^ "# " ^ entry.desc
+
+(* format a positional argument as a nushell `extern` parameter line.
+ * nushell syntax: "...name: type" for variadic, "name?: type" for optional.
+ * hyphens in names are converted to underscores since nushell identifiers
+ * cannot contain hyphens. *)
+let format_positional positional =
+  let name = String.map (function '-' -> '_' | c -> c) positional.pos_name in
+  let prefix = if positional.variadic then "..." else "" in
+  let suffix = if positional.optional && not positional.variadic then "?" else "" in
+  let typ = nushell_type_of_param (String.uppercase_ascii positional.pos_name) in
+  Printf.sprintf "    %s%s%s: %s" prefix name suffix typ
+
+(* enforce nushell's positional argument ordering rules:
+ *   1. no required positional may follow an optional one
+ *   2. at most one variadic ("rest") parameter is allowed
+ *
+ * if a required positional appears after an optional one, it is silently
+ * promoted to optional. duplicate variadic params are dropped.
+ * uses a fold to track the state across the list in one pass. *)
+let fixup_positionals positionals =
+  List.fold_left (fun (seen_optional, seen_variadic, acc) positional ->
+    if positional.variadic then
+      (* only allow the first variadic parameter *)
+      if seen_variadic then (seen_optional, seen_variadic, acc)
+      else (true, true, positional :: acc)
+    else if seen_optional then
+      (* once we've seen an optional, all subsequent must be optional too *)
+      (true, seen_variadic, { positional with optional = true } :: acc)
+    else
+      (positional.optional, seen_variadic, positional :: acc)
+  ) (false, false, []) positionals
+  |> fun (_, _, acc) -> List.rev acc
+
+(* generate the full nushell `extern` block for a command.
+ * produces output like:
+ *   export extern "git add" [
+ *     ...pathspec?: path
+ *     --verbose(-v)              # be verbose
+ *     --dry-run(-n)              # dry run
+ *   ]
+ *
+ * subcommands that weren't resolved into their own full definitions get
+ * stub `extern` blocks with just a comment containing their description:
+ *   export extern "git stash" [  # stash changes
+ *   ]
+ *)
+let extern_of cmd_name result =
+  let entries = dedup_entries result.entries in
+  let escaped_name = escape_nu cmd_name in
+  let positionals = fixup_positionals result.positionals in
+  (* format all positional and flag lines, each terminated with a newline *)
+  let pos_lines = List.map (fun positional -> format_positional positional ^ "\n") positionals in
+  let flags = List.map (fun entry -> format_flag entry ^ "\n") entries in
+  let main = Printf.sprintf "export extern \"%s\" [\n%s%s]\n" escaped_name (String.concat "" pos_lines) (String.concat "" flags) in
+  (* generate stub extern blocks for unresolved subcommands *)
+  let subs = List.map (fun (subcommand : subcommand) ->
+    Printf.sprintf "\nexport extern \"%s %s\" [  # %s\n]\n"
+      escaped_name (escape_nu subcommand.name) (escape_nu subcommand.desc)
+  ) result.subcommands in
+  String.concat "" (main :: subs)
+
+(* public alias for extern_of — this is the main entry point for callers *)
+let generate_extern = extern_of
+
+(* derive a nushell `module` name from a command name.
+ * replaces non-alphanumeric characters with hyphens and appends "-completions".
+ * e.g. "git" becomes "git-completions", "docker-compose" stays "docker-compose-completions" *)
+let module_name_of cmd_name =
+  let s = String.map (function
+    | ('a'..'z' | 'A'..'Z' | '0'..'9' | '-' | '_') as c -> c | _ -> '-') cmd_name in
+  s ^ "-completions"
+
+(* generate a complete nushell `module` wrapping the `extern`.
+ * output: "module git-completions { ... }\n\nuse git-completions *\n"
+ * the `use` at the end makes the `extern` immediately available in scope. *)
+let generate_module cmd_name result =
+  let mod_name = module_name_of cmd_name in
+  Printf.sprintf "module %s {\n%s}\n\nuse %s *\n" mod_name (extern_of cmd_name result) mod_name
+
+(* convenience wrapper: generate an `extern` from just a list of entries
+ * (no subcommands, positionals, or description). used when we only have
+ * flag data and nothing else. *)
+let generate_extern_from_entries cmd_name entries =
+  generate_extern cmd_name { entries; subcommands = []; positionals = []; description = "" }

lib/parser.ml

@@ -0,0 +1,814 @@
+(* parser.ml — parse --help output into structured flag/subcommand/positional data.
+ *
+ * this module is the core of inshellah's help-text understanding. it takes the
+ * raw text that a cli tool prints when you run `cmd --help` and extracts:
+ *   - flag entries (short/long switches with optional parameters and descriptions)
+ *   - subcommand listings (name + description pairs)
+ *   - positional arguments (from usage lines)
+ *
+ * the parser is built on Angstrom (a monadic parser combinator library) for the
+ * structured flag/subcommand extraction, with hand-rolled imperative parsers for
+ * usage-line positional extraction (where the format is too varied for clean
+ * combinator composition).
+ *
+ * key design decisions:
+ *   - the Angstrom parser runs in prefix-consume mode — it doesn't need to parse
+ *     the entire input, just extract what it can recognize. unrecognized lines are
+ *     skipped via skip_non_option_line.
+ *   - multi-line descriptions are handled via indentation-based continuation:
+ *     lines indented 8+ spaces that don't start with '-' are folded into the
+ *     previous entry's description.
+ *   - subcommand detection uses a heuristic: lines with a name followed by 2+
+ *     spaces then a description, where the name is at least 2 chars. section
+ *     headers (like "arguments:") toggle whether name-description pairs are
+ *     treated as subcommands or positionals.
+ *   - positional extraction has two paths: usage-line parsing (the common case)
+ *     and CLI11's explicit "positionals:" section format.
+ *)
+
+open Angstrom
+
+(* strip ansi escape sequences and osc hyperlinks from --help output.
+ * many modern cli tools emit colored/styled output even when piped,
+ * so we need to clean this before parsing. handles:
+ *   - csi sequences (esc [ ... final_byte) — colors, cursor movement, etc.
+ *   - osc sequences (esc ] ... bel/st) — hyperlinks, window titles, etc.
+ *   - other two-byte esc+char sequences *)
+let strip_ansi s =
+  let buf = Buffer.create (String.length s) in
+  let len = String.length s in
+  let pos = ref 0 in
+  while !pos < len do
+    if !pos + 1 < len && Char.code s.[!pos] = 0x1b then begin
+      let next = s.[!pos + 1] in
+      if next = '[' then begin
+        (* csi sequence: esc [ ... final_byte *)
+        pos := !pos + 2;
+        while !pos < len && not (s.[!pos] >= '@' && s.[!pos] <= '~') do incr pos done;
+        if !pos < len then incr pos
+      end else if next = ']' then begin
+        (* osc sequence: esc ] ... (terminated by bel or esc \) *)
+        pos := !pos + 2;
+        let terminated = ref false in
+        while !pos < len && not !terminated do
+          if s.[!pos] = '\x07' then
+            (incr pos; terminated := true)
+          else if !pos + 1 < len && Char.code s.[!pos] = 0x1b && s.[!pos + 1] = '\\' then
+            (pos := !pos + 2; terminated := true)
+          else
+            incr pos
+        done
+      end else begin
+        (* other esc sequence, skip esc + one char *)
+        pos := !pos + 2
+      end
+    end else begin
+      Buffer.add_char buf s.[!pos];
+      incr pos
+    end
+  done;
+  Buffer.contents buf
+
+(* --- character class predicates ---
+ * used throughout the Angstrom parsers to classify characters.
+ * separated out for readability and reuse. *)
+
+let is_whitespace = function ' ' | '\t' -> true | _ -> false
+
+let is_alphanumeric = function
+  | 'A' .. 'Z' | 'a' .. 'z' | '0' .. '9' -> true
+  | _ -> false
+
+(* characters allowed inside parameter names like FILE, output-dir, etc. *)
+let is_param_char = function
+  | 'A' .. 'Z' | 'a' .. 'z' | '0' .. '9' | '_' | '-' -> true
+  | _ -> false
+
+(* used to detect ALL_CAPS parameter names like FILE, TIME_STYLE *)
+let is_upper_or_underscore = function
+  | 'A' .. 'Z' | '_' -> true
+  | _ -> false
+
+(* characters allowed in long flag names (--foo-bar, --enable-feature2) *)
+let is_long_char = function
+  | 'A' .. 'Z' | 'a' .. 'z' | '0' .. '9' | '-' -> true
+  | _ -> false
+
+(* --- core types ---
+ * these types represent the structured output of parsing a help text.
+ * they are shared across the entire codebase (nushell codegen, store, manpage parser).
+ *
+ * switch: a flag can be short-only (-v), long-only (--verbose), or both (-v, --verbose).
+ *   the both variant keeps the pair together so nushell can emit "--verbose(-v)".
+ *
+ * param: flags can take mandatory (--output FILE) or optional (--color[=WHEN]) values.
+ *
+ * entry: one complete flag definition — its switch form, optional parameter, and
+ *   the description text (potentially multi-line, already joined).
+ *
+ * help_result: the complete parsed output for a single command. *)
+type switch = Short of char | Long of string | Both of char * string
+type param = Mandatory of string | Optional of string
+type entry = { switch : switch; param : param option; desc : string }
+type subcommand = { name : string; desc : string }
+type positional = { pos_name : string; optional : bool; variadic : bool }
+type help_result = { entries : entry list; subcommands : subcommand list; positionals : positional list; description : string }
+
+(* --- low-level Angstrom combinators ---
+ * building blocks for all the parsers below. *)
+
+(* consume horizontal whitespace (spaces and tabs) without crossing lines *)
+let inline_ws = skip_while (function ' ' | '\t' -> true | _ -> false)
+(* end of line — matches either a newline or end of input.
+ * this is the permissive version used in most places. *)
+let eol = end_of_line <|> end_of_input
+(* strict end of line — must consume an actual newline character.
+ * used in skip_non_option_line so we don't accidentally match eof
+ * and consume it when we shouldn't. *)
+let eol_strict = end_of_line
+
+(* --- switch and parameter parsers ---
+ * parse the flag name portion of an option line, e.g. "-v", "--verbose" *)
+
+let short_switch = char '-' *> satisfy is_alphanumeric
+let long_switch = string "--" *> take_while1 is_long_char
+let comma = char ',' *> inline_ws
+
+(* parameter parsers — handle the various syntaxes tools use to indicate
+ * that a flag takes a value. the formats are surprisingly diverse:
+ *   --output=FILE        (eq_man_param — mandatory, common in gnu tools)
+ *   --color[=WHEN]       (eq_opt_param — optional with = syntax)
+ *   --depth DEPTH        (space_upper_param — space-separated ALL_CAPS)
+ *   --file <path>        (space_angle_param — angle brackets)
+ *   --file [<path>]      (space_opt_angle_param — optional angle brackets)
+ *   --format string      (space_type_param — go/cobra lowercase type word)
+ *)
+let eq_opt_param =
+  string "[=" *> take_while1 is_param_char <* char ']' >>| fun a -> Optional a
+
+let eq_man_param =
+  char '=' *> take_while1 is_param_char >>| fun a -> Mandatory a
+
+(* space-separated ALL_CAPS param: e.g. " FILE", " TIME_STYLE".
+ * peek ahead and check the first char is uppercase, then validate
+ * the entire word is ALL_CAPS. prevents false positives where a
+ * description word like "Do" or "Set" immediately follows the flag name.
+ * digits are allowed (e.g. "SHA256") but lowercase chars disqualify. *)
+let space_upper_param =
+  char ' ' *> peek_char_fail >>= fun c ->
+  if is_upper_or_underscore c then
+    take_while1 is_param_char >>= fun name ->
+    if String.length name >= 1 && String.for_all (fun c -> is_upper_or_underscore c || c >= '0' && c <= '9') name then
+      return (Mandatory name)
+    else
+      fail "not an all-caps param"
+  else
+    fail "not an uppercase param"
+
+(* angle-bracket param: e.g. "<file>", "<notation>" *)
+let angle_param =
+  char '<' *> take_while1 (fun c -> c <> '>') <* char '>' >>| fun name ->
+  Mandatory name
+
+(* space + angle bracket param *)
+let space_angle_param =
+  char ' ' *> angle_param
+
+(* optional angle bracket param: [<file>] *)
+let opt_angle_param =
+  char '[' *> char '<' *> take_while1 (fun c -> c <> '>') <* char '>' <* char ']'
+  >>| fun name -> Optional name
+
+let space_opt_angle_param =
+  char ' ' *> opt_angle_param
+
+(* go/cobra style: space + lowercase type word like "string", "list", "int".
+ * capped at 10 chars to avoid consuming description words.
+ * go's flag libraries commonly emit "--timeout duration" or "--name string"
+ * where the type name is a short lowercase word. longer words are almost
+ * certainly the start of a description, not a type annotation. *)
+let space_type_param =
+  char ' ' *> peek_char_fail >>= fun c ->
+  if c >= 'a' && c <= 'z' then
+    take_while1 (fun c -> c >= 'a' && c <= 'z') >>= fun name ->
+    if String.length name <= 10 then
+      return (Mandatory name)
+    else
+      fail "too long for type param"
+  else
+    fail "not a lowercase type param"
+
+(* try each parameter format in order of specificity. the ordering matters:
+ * eq_opt_param must come before eq_man_param because "[=WHEN]" would otherwise
+ * partially match as "=WHEN" then fail on the trailing "]". similarly,
+ * space_opt_angle_param before space_angle_param to catch "[<file>]" before "<file>". *)
+let param_parser =
+  option None
+    (choice
+       [ eq_opt_param; eq_man_param;
+         space_opt_angle_param; space_angle_param;
+         space_upper_param; space_type_param ]
+     >>| fun a -> Some a)
+
+(* switch parser — handles the various ways help text presents flag names.
+ * formats handled (in order of attempt):
+ *   -a, --all       (short + comma + long — gnu style)
+ *   -a --all        (short + space + long — some tools omit the comma)
+ *   --all / -a      (long + slash + short — rare but seen in some tools)
+ *   -a              (short only)
+ *   --all           (long only)
+ *
+ * the ordering is critical because Angstrom's choice commits to
+ * the first parser that makes progress. short_switch consumes "-a", so the
+ * combined parsers must be tried before the short-only parser. *)
+let switch_parser =
+  choice
+    [
+      (short_switch >>= fun s ->
+       comma *> long_switch >>| fun l -> Both (s, l));
+      (short_switch >>= fun s ->
+       char ' ' *> long_switch >>| fun l -> Both (s, l));
+      (long_switch >>= fun l ->
+       inline_ws *> char '/' *> inline_ws *>
+       short_switch >>| fun s -> Both (s, l));
+      (short_switch >>| fun s -> Short s);
+      (long_switch >>| fun l -> Long l);
+    ]
+
+(* --- description parsing with multi-line continuation ---
+ * descriptions in help text often wrap across multiple lines. the convention
+ * is that continuation lines are deeply indented (8+ spaces) and don't start
+ * with '-' (which would indicate a new flag entry). we peek ahead to check
+ * indentation without consuming, then decide whether to fold the line in. *)
+
+(* take the rest of the line as text (does not consume the newline itself) *)
+let rest_of_line = take_till (fun c -> c = '\n' || c = '\r')
+
+(* check if a line is a continuation line: deeply indented, doesn't start with '-'.
+ * tabs count as 8 spaces to match typical terminal rendering.
+ * the 8-space threshold was chosen empirically — most help formatters indent
+ * descriptions at least this much, while flag lines are indented 2-4 spaces. *)
+let continuation_line =
+  peek_string 1 >>= fun _ ->
+  (* must start with significant whitespace (8+ spaces or tab) *)
+  let count_indent s =
+    let indent = ref 0 in
+    let pos = ref 0 in
+    while !pos < String.length s do
+      (match s.[!pos] with
+       | ' ' -> incr indent
+       | '\t' -> indent := !indent + 8
+       | _ -> pos := String.length s);
+      incr pos
+    done;
+    !indent
+  in
+  available >>= fun avail ->
+  if avail = 0 then fail "eof"
+  else
+    (* peek ahead to see indentation level *)
+    peek_string (min avail 80) >>= fun preview ->
+    let indent = count_indent preview in
+    let trimmed = String.trim preview in
+    let starts_with_dash =
+      String.length trimmed > 0 && trimmed.[0] = '-'
+    in
+    if indent >= 8 && not starts_with_dash then
+      (* this is a continuation line — consume whitespace + text *)
+      inline_ws *> rest_of_line <* eol
+    else
+      fail "not a continuation line"
+
+(* parse description text: first line (after switch+param) plus any continuation lines.
+ * blank continuation lines are filtered out, and all lines are trimmed and joined
+ * with spaces into a single string. *)
+let description =
+  inline_ws *> rest_of_line <* eol >>= fun first_line ->
+  many continuation_line >>| fun cont_lines ->
+  let all = first_line :: cont_lines in
+  let all = List.filter (fun s -> String.length (String.trim s) > 0) all in
+  String.concat " " (List.map String.trim all)
+
+(* description that appears on a separate line below the flag.
+ * this handles the clap (rust) "long" help format where flags and descriptions
+ * are on separate lines:
+ *   --verbose
+ *           increase verbosity
+ * here there's no inline description — just deeply-indented continuation lines. *)
+let description_below =
+  many1 continuation_line >>| fun lines ->
+  let lines = List.filter (fun s -> String.length (String.trim s) > 0) lines in
+  String.concat " " (List.map String.trim lines)
+
+(* --- line classification for skipping ---
+ * the parser needs to skip lines it doesn't understand (section headers,
+ * blank lines, description paragraphs not attached to a flag, etc.)
+ * without consuming lines that are flag entries. *)
+
+(* peek ahead to check if the current line looks like a flag entry.
+ * an option line starts with whitespace then '-'. *)
+let at_option_line =
+  peek_string 1 >>= fun _ ->
+  available >>= fun avail ->
+  if avail = 0 then fail "eof"
+  else
+    peek_string (min avail 40) >>= fun preview ->
+    let s = String.trim preview in
+    if String.length s > 0 && s.[0] = '-' then return ()
+    else fail "not an option line"
+
+(* skip a non-option line (section header, blank, description-only, etc.).
+ * uses eol_strict (not eol) so it won't match at eof — this prevents the
+ * parser from infinitely skipping at the end of input. if the line looks
+ * like an option line (at_option_line succeeds), we deliberately fail so
+ * that the entry parser gets a chance at it instead. *)
+let skip_non_option_line =
+  (at_option_line *> fail "this is an option line")
+  <|> (rest_of_line *> eol_strict *> return ())
+
+(* --- entry parsing --- *)
+
+(* parse a single flag entry: leading whitespace, then switch+param, then description.
+ * the description can appear on the same line (inline) or on the next line (below).
+ * if there's no description at all, we accept an empty string.
+ * the (eol *> description_below) branch handles the clap long-help format. *)
+let entry =
+  inline_ws *>
+  lift2 (fun (sw, param) desc -> { switch = sw; param; desc })
+    (lift2 (fun a b -> (a, b)) switch_parser param_parser)
+    (description <|> (eol *> (description_below <|> return "")))
+
+(* --- subcommand parsing ---
+ * subcommand lines in help text follow the pattern:
+ *   "  name   description"
+ * where the name and description are separated by 2+ spaces.
+ * some tools also include argument placeholders between name and description:
+ *   "  start UNIT...   start one or more units"
+ *   "  list [PATTERN]  list matching units"
+ *)
+
+let is_subcommand_char = function
+  | 'a' .. 'z' | 'A' .. 'Z' | '0' .. '9' | '-' | '_' -> true
+  | _ -> false
+
+(* skip argument placeholders like UNIT..., [PATTERN...|PID...], <file>
+ * that appear between the subcommand name and the description.
+ * only consumes single-space gaps — the two-space gap before the
+ * description is left for the main parser to use as the delimiter.
+ *
+ * this is a recursive (fix-point) parser that peeks ahead to distinguish
+ * single-space argument gaps from the double-space description separator.
+ * it accepts tokens that start with [, <, or are ALL_CAPS (with dots/pipes/
+ * commas for variadic syntax). *)
+let skip_arg_placeholders =
+  fix (fun self ->
+    (* peek ahead: single space followed by arg-like token *)
+    available >>= fun avail ->
+    if avail < 2 then return ()
+    else
+    peek_string (min avail 2) >>= fun peek_two ->
+    if String.length peek_two >= 2 && peek_two.[0] = ' ' && peek_two.[1] <> ' ' then
+      (* single space — could be an arg placeholder *)
+      let next = peek_two.[1] in
+      if next = '[' || next = '<'
+         || (next >= 'A' && next <= 'Z') then
+        (* peek the full token to check if it's ALL_CAPS/brackets *)
+        peek_string (min avail 80) >>= fun preview ->
+        (* extract the token after the single space *)
+        let tok_start = 1 in
+        let token_end = ref tok_start in
+        while !token_end < String.length preview
+              && preview.[!token_end] <> ' '
+              && preview.[!token_end] <> '\n'
+              && preview.[!token_end] <> '\r' do
+          incr token_end
+        done;
+        let tok = String.sub preview tok_start (!token_end - tok_start) in
+        (* accept as placeholder if it starts with [ or < or is ALL_CAPS
+           (possibly with dots, pipes, dashes) *)
+        let is_placeholder =
+          tok.[0] = '[' || tok.[0] = '<'
+          || String.for_all (fun c ->
+               (c >= 'A' && c <= 'Z') || c = '_' || c = '-'
+               || c = '.' || c = '|' || c = ',' || (c >= '0' && c <= '9')
+             ) tok
+        in
+        if is_placeholder then
+          advance (1 + String.length tok) *> self
+        else return ()
+      else return ()
+    else return ())
+
+(* parse a subcommand entry line.
+ * requires: name >= 2 chars, followed by 2+ spaces, then description.
+ * the name is lowercased for consistent lookup.
+ *
+ * if the description starts with "- " (a dash-space prefix), it's stripped.
+ * some tools format their subcommand lists as:
+ *   "  add   - add a new item"
+ * where the "- " is decorative, not part of the description. *)
+let subcommand_entry =
+  inline_ws *>
+  take_while1 is_subcommand_char >>= fun name ->
+  if String.length name < 2 then fail "subcommand name too short"
+  else
+  skip_arg_placeholders *>
+  char ' ' *> char ' ' *> inline_ws *>
+  rest_of_line <* eol >>| fun desc ->
+  { name = String.lowercase_ascii name;
+    desc = let trimmed = String.trim desc in
+      if String.length trimmed >= 2 && trimmed.[0] = '-' && trimmed.[1] = ' ' then
+        String.trim (String.sub trimmed 2 (String.length trimmed - 2))
+      else trimmed }
+
+(* --- section header detection ---
+ * section headers are critical for disambiguating subcommands from positional
+ * arguments. lines like "commands:" introduce subcommand sections, while
+ * "arguments:" or "positionals:" introduce argument sections where the same
+ * name+description format should not be treated as subcommands. *)
+
+(* detect section names that introduce positional argument listings.
+ * the check is case-insensitive and strips trailing colons. *)
+let is_arg_section s =
+  let lc = String.lowercase_ascii (String.trim s) in
+  let base = if String.ends_with ~suffix:":" lc
+    then String.sub lc 0 (String.length lc - 1) |> String.trim
+    else lc in
+  base = "arguments" || base = "args" || base = "positionals"
+  || base = "positional arguments"
+
+(* a section header: left-aligned (or lightly indented, <= 4 spaces) text
+ * ending with ':', not starting with '-'. must be consumed before
+ * subcommand_entry in the choice combinator, otherwise "commands:" would
+ * be parsed as a subcommand named "commands" with description ":".
+ *
+ * returns a bool indicating whether this is an argument section (true)
+ * or some other section (false). this drives the subcommand filtering logic
+ * in help_parser — entries under argument sections are excluded from the
+ * subcommand list. *)
+let section_header =
+  available >>= fun avail ->
+  if avail = 0 then fail "eof"
+  else
+    peek_string (min avail 80) >>= fun preview ->
+    (* extract just the first line from the preview *)
+    let first_line = match String.index_opt preview '\n' with
+      | Some pos -> String.sub preview 0 pos
+      | None -> preview in
+    let trimmed = String.trim first_line in
+    let len = String.length trimmed in
+    let indent = let pos = ref 0 in
+      while !pos < String.length first_line && (first_line.[!pos] = ' ' || first_line.[!pos] = '\t') do incr pos done;
+      !pos in
+    if len >= 2 && trimmed.[len - 1] = ':' && trimmed.[0] <> '-' && indent <= 4 then
+      rest_of_line <* eol_strict >>| fun line -> is_arg_section line
+    else fail "not a section header"
+
+(* --- top-level parser ---
+ * the main help parser: walks through all lines, trying each line as one of:
+ *   1. a flag entry (starts with whitespace + '-')
+ *   2. a section header (left-aligned text ending with ':')
+ *   3. a subcommand line (name + 2+ spaces + description)
+ *   4. anything else — skip
+ *
+ * the choice ordering matters: entries are tried first (highest priority),
+ * then section headers (must beat subcommand_entry to avoid misparse),
+ * then subcommands, then skip as fallback.
+ *
+ * after collecting all items, two post-processing steps happen:
+ *   - subcommands under argument sections are excluded (tracked via
+ *     a running in_arg_sec boolean toggled by section headers)
+ *   - duplicate subcommand names are deduplicated, keeping the entry
+ *     with the longer description (heuristic: more info = better)
+ *
+ * positionals are not extracted here — they come from the usage line
+ * parser (extract_usage_positionals) or CLI11's explicit section parser
+ * (extract_cli11_positionals), applied later in parse_help. *)
+let help_parser =
+  let open Angstrom in
+  fix (fun _self ->
+    let try_entry =
+      entry >>| fun e -> `Entry e
+    in
+    let try_section =
+      section_header >>| fun is_arg -> `Section is_arg
+    in
+    let try_subcommand =
+      subcommand_entry >>| fun sc -> `Subcommand sc
+    in
+    let try_skip =
+      skip_non_option_line >>| fun () -> `Skip
+    in
+    many (choice [ try_entry; try_section; try_subcommand; try_skip ]) >>| fun items ->
+    let entries = List.filter_map (function `Entry e -> Some e | _ -> None) items in
+    let subcommands =
+      List.fold_left (fun (in_arg_sec, acc) item ->
+        match item with
+        | `Section is_arg -> (is_arg, acc)
+        | `Subcommand sc when not in_arg_sec -> (in_arg_sec, sc :: acc)
+        | _ -> (in_arg_sec, acc)
+      ) (false, []) items
+      |> snd |> List.rev
+      |> List.fold_left (fun acc sc ->
+           match List.assoc_opt sc.name acc with
+           | Some prev when String.length prev.desc >= String.length sc.desc -> acc
+           | _ -> (sc.name, sc) :: List.remove_assoc sc.name acc
+         ) []
+      |> List.rev_map snd
+    in
+    { entries; subcommands; positionals = []; description = "" })
+
+(* --- usage line parsing ---
+ * usage lines look like: "usage: git add [OPTIONS] [--] [<pathspec>...]"
+ * to extract positional arguments, we first need to skip past the command
+ * name prefix ("git add") to reach the argument portion.
+ *
+ * skip_command_prefix walks word-by-word, treating each space-separated
+ * token as part of the command name as long as it:
+ *   - is made of "word chars" (alphanumeric, hyphen, underscore, slash, dot)
+ *   - contains at least one lowercase letter (to distinguish from ALL_CAPS
+ *     positional names like FILE)
+ *   - doesn't start with [, <, (, {, or - (which indicate arguments, not
+ *     command name components)
+ *
+ * this is an imperative index-walking parser rather than using Angstrom,
+ * because usage lines are a single string (not line-oriented) and the format
+ * is too varied for clean combinator composition. *)
+let skip_command_prefix s =
+  let len = String.length s in
+  let pos = ref 0 in
+  let skip_ws () = while !pos < len && (s.[!pos] = ' ' || s.[!pos] = '\t') do incr pos done in
+  let is_word_char = function
+    | 'a'..'z' | 'A'..'Z' | '0'..'9' | '-' | '_' | '/' | '.' -> true
+    | _ -> false
+  in
+  let rec loop () =
+    skip_ws ();
+    if !pos >= len then ()
+    else if s.[!pos] = '[' || s.[!pos] = '<' || s.[!pos] = '(' || s.[!pos] = '{' || s.[!pos] = '-' then ()
+    else if is_word_char s.[!pos] then begin
+      let start = !pos in
+      while !pos < len && is_word_char s.[!pos] do incr pos done;
+      let word = String.sub s start (!pos - start) in
+      let has_lower = ref false in
+      String.iter (fun c -> if c >= 'a' && c <= 'z' then has_lower := true) word;
+      if not !has_lower then
+        pos := start
+      else
+        loop ()
+    end
+  in
+  loop ();
+  !pos
+
+(* parse the argument portion of a usage line into positional definitions.
+ * handles these syntactic forms:
+ *   <file>          - mandatory positional
+ *   [file]          - optional positional
+ *   FILE            - mandatory positional (ALL_CAPS convention)
+ *   <file>...       - variadic (also handles utf-8 ellipsis)
+ *   [file...]       - optional variadic
+ *   curly-brace alternatives - skipped, not a positional
+ *   -flag           - flags (skipped)
+ *
+ * certain ALL_CAPS names are skipped because they're not real positionals —
+ * "OPTIONS", "FLAGS", etc. are section labels that sometimes appear in usage
+ * lines for readability.
+ *
+ * deduplication at the end ensures we don't emit the same positional twice
+ * (can happen when usage lines are reformatted or repeated). *)
+let parse_usage_args s =
+  let len = String.length s in
+  let pos = ref 0 in
+  let positionals = ref [] in
+  let skip_ws () =
+    while !pos < len && (s.[!pos] = ' ' || s.[!pos] = '\t') do incr pos done in
+  let is_pos_char c =
+    (c >= 'A' && c <= 'Z') || c = '_' || c = '-' || (c >= '0' && c <= '9') in
+  (* detect trailing dots or utf-8 ellipsis indicating variadic args *)
+  let read_dots () =
+    skip_ws ();
+    if !pos + 2 < len && s.[!pos] = '.' && s.[!pos+1] = '.' && s.[!pos+2] = '.' then
+      (pos := !pos + 3; true)
+    else if !pos + 2 < len && s.[!pos] = '\xe2' && s.[!pos+1] = '\x80' && s.[!pos+2] = '\xa6' then
+      (pos := !pos + 3; true)  (* utf-8 ellipsis *)
+    else false
+  in
+  (* names that are section labels, not actual positional arguments *)
+  let is_skip name =
+    let u = String.uppercase_ascii name in
+    u = "OPTIONS" || u = "OPTION" || u = "FLAGS" || u = "FLAG"
+  in
+  (* validate that a name contains only alphanumeric, underscore, hyphen chars *)
+  let is_clean_name name =
+    String.length name >= 2
+    && String.for_all (fun c ->
+         (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z')
+         || (c >= '0' && c <= '9') || c = '_' || c = '-') name
+  in
+  let is_letter c = (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') in
+  (* skip {A|c|d|...} alternative blocks — not positional arguments *)
+  let skip_braces () =
+    if !pos < len && s.[!pos] = '{' then begin
+      let depth = ref 1 in
+      incr pos;
+      while !pos < len && !depth > 0 do
+        if s.[!pos] = '{' then incr depth
+        else if s.[!pos] = '}' then decr depth;
+        incr pos
+      done;
+      ignore (read_dots ());
+      true
+    end else false
+  in
+  while !pos < len do
+    skip_ws ();
+    if !pos >= len then ()
+    else if skip_braces () then ()
+    else match s.[!pos] with
+    | '[' ->
+      (* optional positional: [name] or [<name>] or [name...] *)
+      incr pos;
+      let start = !pos in
+      let depth = ref 1 in
+      while !pos < len && !depth > 0 do
+        if s.[!pos] = '[' then incr depth
+        else if s.[!pos] = ']' then decr depth;
+        incr pos
+      done;
+      let bracket_end = !pos - 1 in
+      let inner = String.sub s start (max 0 (bracket_end - start)) |> String.trim in
+      let inner, has_inner_dots =
+        if String.ends_with ~suffix:"..." inner then
+          (String.sub inner 0 (String.length inner - 3) |> String.trim, true)
+        else (inner, false)
+      in
+      let variadic = has_inner_dots || read_dots () in
+      if String.length inner > 0
+         && inner.[0] <> '-'
+         && (is_letter inner.[0] || inner.[0] = '<') then begin
+        let name =
+          if inner.[0] = '<' then
+            let e = try String.index inner '>' with Not_found -> String.length inner in
+            String.sub inner 1 (e - 1)
+          else inner
+        in
+        if is_clean_name name && not (is_skip name) then
+          positionals := { pos_name = String.lowercase_ascii name;
+                       optional = true; variadic } :: !positionals
+      end
+    | '<' ->
+      (* mandatory positional in angle brackets: <name> *)
+      incr pos;
+      let start = !pos in
+      while !pos < len && s.[!pos] <> '>' do incr pos done;
+      let name = String.sub s start (!pos - start) in
+      if !pos < len then incr pos;
+      let variadic = read_dots () in
+      if is_clean_name name && not (is_skip name) then
+        positionals := { pos_name = String.lowercase_ascii name;
+                     optional = false; variadic } :: !positionals
+    | '-' ->
+      (* flag — skip entirely, not a positional *)
+      while !pos < len && s.[!pos] <> ' ' && s.[!pos] <> '\t' && s.[!pos] <> ']' do incr pos done
+    | c when c >= 'A' && c <= 'Z' ->
+      (* ALL_CAPS positional name *)
+      let start = !pos in
+      while !pos < len && is_pos_char s.[!pos] do incr pos done;
+      let name = String.sub s start (!pos - start) in
+      let variadic = read_dots () in
+      if String.length name >= 2
+         && String.for_all (fun c ->
+              (c >= 'A' && c <= 'Z') || c = '_' || c = '-' || (c >= '0' && c <= '9')
+            ) name
+         && not (is_skip name) then
+        positionals := { pos_name = String.lowercase_ascii name;
+                     optional = false; variadic } :: !positionals
+    | _ ->
+      incr pos
+  done;
+  (* deduplicate positionals by name, keeping the first occurrence *)
+  List.rev !positionals
+  |> List.fold_left (fun (seen, acc) p ->
+       if List.mem p.pos_name seen then (seen, acc)
+       else (p.pos_name :: seen, p :: acc)
+     ) ([], [])
+  |> snd |> List.rev
+
+(* find the "usage:" line in the help text and extract positionals from it.
+ * searches line-by-line for a line starting with "usage:" (case-insensitive).
+ * handles both inline usage ("usage: cmd [OPTIONS] FILE") and the clap style
+ * where the actual usage is on the next line:
+ *   USAGE:
+ *     cmd [OPTIONS] FILE
+ *
+ * also handles the bare "usage" header (no colon) followed by a next line. *)
+let extract_usage_positionals text =
+  let lines = String.split_on_char '\n' text in
+  let lines_arr = Array.of_list lines in
+  let len = Array.length lines_arr in
+  (* search through lines for the first usage header and return the usage content *)
+  let find_usage_line () =
+    let check_line idx =
+      let trimmed = String.trim lines_arr.(idx) in
+      let trimmed_len = String.length trimmed in
+      let lc = String.lowercase_ascii trimmed in
+      if trimmed_len >= 6 && String.sub lc 0 6 = "usage:" then begin
+        let after = String.sub trimmed 6 (trimmed_len - 6) |> String.trim in
+        if String.length after > 0 then Some after
+        else if idx + 1 < len then
+          (* clap style: USAGE:\n  cmd [OPTIONS] PATTERN *)
+          let next = String.trim lines_arr.(idx + 1) in
+          if String.length next > 0 then Some next else None
+        else None
+      end else if lc = "usage" then begin
+        if idx + 1 < len then
+          let next = String.trim lines_arr.(idx + 1) in
+          if String.length next > 0 then Some next else None
+        else None
+      end else None
+    in
+    (* use List.find_map over the index range to find the first matching line *)
+    List.find_map check_line (List.init len Fun.id)
+  in
+  match find_usage_line () with
+  | None -> []
+  | Some usage ->
+    let cmd_end = skip_command_prefix usage in
+    let args = String.sub usage cmd_end (String.length usage - cmd_end) in
+    parse_usage_args args
+
+(* extract positionals from CLI11's explicit "POSITIONALS:" section.
+ * CLI11 (a c++ arg parsing library) emits a dedicated section:
+ *   Positionals:
+ *     name TEXT           description here
+ *     count INT           another description
+ *
+ * this is preferred over usage-line extraction when present because it
+ * provides more accurate type information. the parser looks for the
+ * section header, then reads indented lines until a blank or unindented
+ * line signals the end. type words (TEXT, INT, FLOAT, etc.) between the
+ * name and description are skipped. *)
+let extract_cli11_positionals text =
+  let lines = String.split_on_char '\n' text in
+  (* parse a single indented positional line into a positional record *)
+  let parse_one s =
+    let len = String.length s in
+    let pos = ref 0 in
+    let is_name_char c =
+      (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')
+      || (c >= '0' && c <= '9') || c = '_' || c = '-' in
+    while !pos < len && is_name_char s.[!pos] do incr pos done;
+    if !pos < 2 then None
+    else
+      let name = String.sub s 0 !pos in
+      while !pos < len && (s.[!pos] = ' ' || s.[!pos] = '\t') do incr pos done;
+      (* skip type word: TEXT, INT, FLOAT, ENUM, BOOLEAN, etc. *)
+      while !pos < len && s.[!pos] >= 'A' && s.[!pos] <= 'Z' do incr pos done;
+      while !pos < len && (s.[!pos] = ' ' || s.[!pos] = '\t') do incr pos done;
+      let variadic = !pos + 2 < len && s.[!pos] = '.' && s.[!pos+1] = '.' && s.[!pos+2] = '.' in
+      Some { pos_name = String.lowercase_ascii name; optional = false; variadic }
+  in
+  (* parse consecutive indented lines under the section header *)
+  let rec parse_lines lines acc =
+    match lines with
+    | [] -> List.rev acc
+    | line :: rest ->
+      let len = String.length line in
+      if len = 0 || (line.[0] <> ' ' && line.[0] <> '\t') then
+        List.rev acc
+      else
+        let trimmed = String.trim line in
+        if String.length trimmed = 0 then List.rev acc
+        else match parse_one trimmed with
+          | Some p -> parse_lines rest (p :: acc)
+          | None -> parse_lines rest acc
+  in
+  (* scan lines for the positionals section header, then parse the body *)
+  let rec find_section = function
+    | [] -> []
+    | line :: rest ->
+      let trimmed = String.trim line in
+      if trimmed = "POSITIONALS:" || trimmed = "Positionals:" then
+        parse_lines rest []
+      else
+        find_section rest
+  in
+  find_section lines
+
+(* top-level entry point: parse a --help text string into a help_result.
+ * steps:
+ *   1. strip ansi escapes (colors, hyperlinks, etc.)
+ *   2. run the Angstrom help_parser for flags and subcommands
+ *   3. extract positionals via CLI11 format (preferred) or usage line (fallback)
+ *   4. merge positionals into the result
+ * uses Angstrom's prefix-consume mode — we don't need to parse every byte. *)
+let parse_help txt =
+  let clean = strip_ansi txt in
+  match Angstrom.parse_string ~consume:Consume.Prefix help_parser clean with
+  | Ok result ->
+    let cli11 = extract_cli11_positionals clean in
+    let usage = extract_usage_positionals clean in
+    let positionals = if cli11 <> [] then cli11 else usage in
+    Ok { result with positionals }
+  | Error msg -> Error msg

lib/store.ml

@@ -0,0 +1,498 @@
+(* store.ml — filesystem-backed cache of parsed completion data.
+ *
+ * this module handles persistence of completion data to disk. each command's
+ * help_result is serialized to JSON and stored as a file in a cache directory
+ * (default: $XDG_CACHE_HOME/inshellah). commands with native nushell completions
+ * are stored as .nu files instead.
+ *
+ * the store also provides lookup, listing, and subcommand discovery by
+ * scanning filenames in the cache directory.
+ *
+ * file naming convention:
+ *   - spaces in command names become underscores (e.g. "git add" -> "git_add.json")
+ *   - subcommands of a parent share the prefix (e.g. "git_add.json", "git_commit.json")
+ *   - .json files contain serialized help_result
+ *   - .nu files contain native nushell extern source code
+ *
+ * the module includes a minimal hand-rolled JSON parser/serializer because
+ * we only need to handle our own output format (no need for a full JSON library).
+ *)
+
+open Parser
+
+(* get the default store path: $XDG_CACHE_HOME/inshellah, falling back to
+ * ~/.cache/inshellah if XDG_CACHE_HOME is not set. *)
+let default_store_path () =
+  let cache = try Sys.getenv "XDG_CACHE_HOME"
+    with Not_found -> Filename.concat (Sys.getenv "HOME") ".cache" in
+  Filename.concat cache "inshellah"
+
+(* recursively create directories along a path (equivalent to mkdir -p).
+ * splits the path into components and folds over them, accumulating
+ * the current directory prefix and creating each level if missing. *)
+let ensure_dir dir =
+  let sep = Filename.dir_sep in
+  let parts = String.split_on_char sep.[0] dir in
+  (* determine the starting prefix: absolute paths begin with "/" *)
+  let start = if String.length dir > 0 && dir.[0] = sep.[0] then sep else "" in
+  let _final =
+    List.fold_left (fun current part ->
+      if part = "" then current
+      else begin
+        let next = if current = sep then sep ^ part
+                   else if current = "" then part
+                   else current ^ sep ^ part in
+        (if not (Sys.file_exists next) then Unix.mkdir next 0o755);
+        next
+      end
+    ) start parts
+  in
+  ()
+
+(* convert command name to safe filename: spaces become underscores,
+ * non-alphanumeric chars become hyphens.
+ * e.g. "git add" -> "git_add", "docker-compose" -> "docker-compose" *)
+let filename_of_command cmd =
+  String.map (function
+    | ' ' -> '_'
+    | ('a'..'z' | 'A'..'Z' | '0'..'9' | '-' | '_' | '.') as char_val -> char_val
+    | _ -> '-') cmd
+
+(* inverse of filename_of_command: underscores back to spaces.
+ * note: this is lossy — original underscores in command names
+ * (e.g. "my_tool") would be converted to spaces. in practice this
+ * doesn't matter because tools with underscores in names are rare,
+ * and subcommands use space-separated naming. *)
+let command_of_filename base_name =
+  String.map (function '_' -> ' ' | char_val -> char_val) base_name
+
+(* --- JSON serialization of help_result ---
+ * hand-rolled JSON emitters. we don't use a JSON library because:
+ *   1. the schema is fixed and simple — we only serialize our own types
+ *   2. avoiding dependencies keeps the binary small
+ *   3. printf-style emission is fast and straightforward for our types *)
+
+(* escape a string for JSON: quotes, backslashes, and control characters.
+ * control chars below 0x20 are emitted as \uXXXX unicode escapes. *)
+let escape_json contents =
+  let buf = Buffer.create (String.length contents + 4) in
+  String.iter (fun char_val -> match char_val with
+    | '"' -> Buffer.add_string buf "\\\""
+    | '\\' -> Buffer.add_string buf "\\\\"
+    | '\n' -> Buffer.add_string buf "\\n"
+    | '\t' -> Buffer.add_string buf "\\t"
+    | '\r' -> Buffer.add_string buf "\\r"
+    | c when Char.code c < 0x20 ->
+      Buffer.add_string buf (Printf.sprintf "\\u%04x" (Char.code c))
+    | c -> Buffer.add_char buf c
+  ) contents;
+  Buffer.contents buf
+
+(* wrap a string in quotes after escaping for JSON *)
+let json_string text = Printf.sprintf "\"%s\"" (escape_json text)
+
+(* the literal null value for JSON output *)
+let json_null = "null"
+
+(* serialize a switch (short flag, long flag, or both) to JSON *)
+let json_switch_of = function
+  | Short char_val ->
+    Printf.sprintf "{\"type\":\"short\",\"char\":%s}" (json_string (String.make 1 char_val))
+  | Long name ->
+    Printf.sprintf "{\"type\":\"long\",\"name\":%s}" (json_string name)
+  | Both (char_val, name) ->
+    Printf.sprintf "{\"type\":\"both\",\"char\":%s,\"name\":%s}"
+      (json_string (String.make 1 char_val)) (json_string name)
+
+(* serialize a parameter spec (mandatory, optional, or absent) to JSON *)
+let json_param_of = function
+  | None -> json_null
+  | Some (Mandatory name) ->
+    Printf.sprintf "{\"kind\":\"mandatory\",\"name\":%s}" (json_string name)
+  | Some (Optional name) ->
+    Printf.sprintf "{\"kind\":\"optional\",\"name\":%s}" (json_string name)
+
+(* serialize a single flag entry (switch + param + description) to JSON *)
+let json_entry_of entry =
+  Printf.sprintf "{\"switch\":%s,\"param\":%s,\"desc\":%s}"
+    (json_switch_of entry.switch) (json_param_of entry.param) (json_string entry.desc)
+
+(* serialize a subcommand (name + description) to JSON *)
+let json_subcommand_of sc =
+  Printf.sprintf "{\"name\":%s,\"desc\":%s}" (json_string sc.name) (json_string sc.desc)
+
+(* serialize a positional argument to JSON *)
+let json_positional_of p =
+  Printf.sprintf "{\"name\":%s,\"optional\":%b,\"variadic\":%b}"
+    (json_string p.pos_name) p.optional p.variadic
+
+(* serialize a list of items to a JSON array using the given formatter *)
+let json_list formatter items =
+  "[" ^ String.concat "," (List.map formatter items) ^ "]"
+
+(* serialize an entire help_result to a JSON object string *)
+let json_of_help_result ?(source="help") result =
+  Printf.sprintf "{\"source\":%s,\"description\":%s,\"entries\":%s,\"subcommands\":%s,\"positionals\":%s}"
+    (json_string source)
+    (json_string result.description)
+    (json_list json_entry_of result.entries)
+    (json_list json_subcommand_of result.subcommands)
+    (json_list json_positional_of result.positionals)
+
+(* --- JSON deserialization ---
+ * minimal hand-rolled recursive-descent JSON parser. only handles the subset
+ * we emit: strings, booleans, nulls, arrays, and objects. no number parsing
+ * (we don't emit numbers). this is intentionally minimal — we only read back
+ * our own serialized format, so robustness against arbitrary JSON is not needed.
+ *
+ * note: the \u escape handler does basic UTF-8 encoding for code points
+ * up to 0xFFFF but doesn't handle surrogate pairs. this is fine for our use
+ * case since we only escape control characters below 0x20. *)
+
+type json =
+  | Jnull
+  | Jbool of bool
+  | Jstring of string
+  | Jarray of json list
+  | Jobject of (string * json) list
+
+(* JSON accessor helpers — return sensible defaults for missing/wrong types *)
+let json_get key = function
+  | Jobject pairs -> (try List.assoc key pairs with Not_found -> Jnull)
+  | _ -> Jnull
+
+(* extract a string from a JSON value, defaulting to empty string *)
+let json_to_string = function Jstring text -> text | _ -> ""
+
+(* extract a boolean from a JSON value, defaulting to false *)
+let json_to_bool = function Jbool value -> value | _ -> false
+
+(* extract a list from a JSON array value, defaulting to empty list *)
+let json_to_list = function Jarray items -> items | _ -> []
+
+exception Json_error of string
+
+(* imperative recursive-descent JSON parser.
+ * uses a mutable position ref to walk through the string.
+ * note: boolean/null parsing just advances a fixed number of chars
+ * without validating the actual characters — safe because we only read
+ * our own output, but would be incorrect for arbitrary JSON. *)
+let parse_json contents =
+  let len = String.length contents in
+  let pos = ref 0 in
+  (* peek at the current character without consuming it *)
+  let peek () = if !pos < len then contents.[!pos] else '\x00' in
+  (* advance the position by one character *)
+  let advance () = incr pos in
+  (* skip over any whitespace characters at current position *)
+  let skip_ws () =
+    while !pos < len && (contents.[!pos] = ' ' || contents.[!pos] = '\t'
+                         || contents.[!pos] = '\n' || contents.[!pos] = '\r') do
+      advance ()
+    done in
+  (* skip whitespace then consume the expected character, or raise *)
+  let expect char_val =
+    skip_ws ();
+    if peek () <> char_val then
+      raise (Json_error (Printf.sprintf "expected '%c' at %d" char_val !pos));
+    advance () in
+  (* mutually recursive parsers for each JSON value type *)
+  let rec parse_value () =
+    skip_ws ();
+    match peek () with
+    | '"' -> Jstring (parse_string ())
+    | '{' -> parse_object ()
+    | '[' -> parse_array ()
+    | 'n' -> advance (); advance (); advance (); advance (); Jnull
+    | 't' -> advance (); advance (); advance (); advance (); Jbool true
+    | 'f' ->
+      advance (); advance (); advance (); advance (); advance (); Jbool false
+    | char_val ->
+      raise (Json_error (Printf.sprintf "unexpected '%c' at %d" char_val !pos))
+  (* parse a quoted string value, handling escape sequences *)
+  and parse_string () =
+    expect '"';
+    let buf = Buffer.create 32 in
+    while peek () <> '"' do
+      if peek () = '\\' then begin
+        advance ();
+        (match peek () with
+         | '"' -> Buffer.add_char buf '"'
+         | '\\' -> Buffer.add_char buf '\\'
+         | 'n' -> Buffer.add_char buf '\n'
+         | 't' -> Buffer.add_char buf '\t'
+         | 'r' -> Buffer.add_char buf '\r'
+         | 'u' ->
+           (* handle \uXXXX unicode escapes with basic UTF-8 encoding *)
+           advance ();
+           let hex = String.sub contents !pos 4 in
+           pos := !pos + 3;
+           let code = int_of_string ("0x" ^ hex) in
+           if code < 128 then Buffer.add_char buf (Char.chr code)
+           else begin
+             if code < 0x800 then begin
+               Buffer.add_char buf (Char.chr (0xc0 lor (code lsr 6)));
+               Buffer.add_char buf (Char.chr (0x80 lor (code land 0x3f)))
+             end else begin
+               Buffer.add_char buf (Char.chr (0xe0 lor (code lsr 12)));
+               Buffer.add_char buf (Char.chr (0x80 lor ((code lsr 6) land 0x3f)));
+               Buffer.add_char buf (Char.chr (0x80 lor (code land 0x3f)))
+             end
+           end
+         | char_val -> Buffer.add_char buf char_val);
+        advance ()
+      end else begin
+        Buffer.add_char buf (peek ());
+        advance ()
+      end
+    done;
+    advance (); (* consume closing quote *)
+    Buffer.contents buf
+  (* parse a JSON object: { "key": value, ... } *)
+  and parse_object () =
+    expect '{';
+    skip_ws ();
+    if peek () = '}' then (advance (); Jobject [])
+    else begin
+      let pairs = ref [] in
+      let more = ref true in
+      while !more do
+        skip_ws ();
+        let key = parse_string () in
+        expect ':';
+        let value = parse_value () in
+        pairs := (key, value) :: !pairs;
+        skip_ws ();
+        if peek () = ',' then advance ()
+        else more := false
+      done;
+      expect '}';
+      Jobject (List.rev !pairs)
+    end
+  (* parse a JSON array: [ value, value, ... ] *)
+  and parse_array () =
+    expect '[';
+    skip_ws ();
+    if peek () = ']' then (advance (); Jarray [])
+    else begin
+      let items = ref [] in
+      let more = ref true in
+      while !more do
+        let value = parse_value () in
+        items := value :: !items;
+        skip_ws ();
+        if peek () = ',' then advance ()
+        else more := false
+      done;
+      expect ']';
+      Jarray (List.rev !items)
+    end
+  in
+  parse_value ()
+
+(* --- JSON to OCaml type converters ---
+ * these reconstruct our parser types from their JSON representations.
+ * they mirror the json_*_of serializers above. *)
+
+(* reconstruct a switch value from its JSON representation *)
+let switch_of_json json_node =
+  match json_to_string (json_get "type" json_node) with
+  | "short" ->
+    let char_str = json_to_string (json_get "char" json_node) in
+    Short (if String.length char_str > 0 then char_str.[0] else '?')
+  | "long" -> Long (json_to_string (json_get "name" json_node))
+  | "both" ->
+    let char_str = json_to_string (json_get "char" json_node) in
+    Both ((if String.length char_str > 0 then char_str.[0] else '?'),
+          json_to_string (json_get "name" json_node))
+  | _ -> Long "?"
+
+(* reconstruct a parameter spec from its JSON representation *)
+let param_of_json = function
+  | Jnull -> None
+  | json_node ->
+    let name = json_to_string (json_get "name" json_node) in
+    (match json_to_string (json_get "kind" json_node) with
+     | "mandatory" -> Some (Mandatory name)
+     | "optional" -> Some (Optional name)
+     | _ -> None)
+
+(* reconstruct a flag entry from its JSON representation *)
+let entry_of_json json_node =
+  { switch = switch_of_json (json_get "switch" json_node);
+    param = param_of_json (json_get "param" json_node);
+    desc = json_to_string (json_get "desc" json_node) }
+
+(* reconstruct a subcommand from its JSON representation *)
+let subcommand_of_json json_node =
+  { name = json_to_string (json_get "name" json_node);
+    desc = json_to_string (json_get "desc" json_node) }
+
+(* reconstruct a positional argument from its JSON representation *)
+let positional_of_json json_node =
+  { pos_name = json_to_string (json_get "name" json_node);
+    optional = json_to_bool (json_get "optional" json_node);
+    variadic = json_to_bool (json_get "variadic" json_node) }
+
+(* reconstruct a full help_result from its JSON representation *)
+let help_result_of_json json_node =
+  { entries = List.map entry_of_json (json_to_list (json_get "entries" json_node));
+    subcommands = List.map subcommand_of_json (json_to_list (json_get "subcommands" json_node));
+    positionals = List.map positional_of_json (json_to_list (json_get "positionals" json_node));
+    description = json_to_string (json_get "description" json_node) }
+
+(* --- filesystem operations --- *)
+
+(* write a string to a file, overwriting any existing content *)
+let write_file path contents =
+  let oc = open_out path in
+  output_string oc contents;
+  close_out oc
+
+(* read an entire file into a string, returning None on any error *)
+let read_file path =
+  try
+    let ic = open_in path in
+    let size = in_channel_length ic in
+    let contents = Bytes.create size in
+    really_input ic contents 0 size;
+    close_in ic;
+    Some (Bytes.to_string contents)
+  with _ -> None
+
+(* write a parsed help_result to the store as JSON *)
+let write_result ~dir ?(source="help") command result =
+  let path = Filename.concat dir (filename_of_command command ^ ".json") in
+  write_file path (json_of_help_result ~source result)
+
+(* write native nushell completion source to the store as a .nu file *)
+let write_native ~dir command data =
+  let path = Filename.concat dir (filename_of_command command ^ ".nu") in
+  write_file path data
+
+(* check whether a path exists and is a directory *)
+let is_dir path = Sys.file_exists path && Sys.is_directory path
+
+(* look for a command's data file across multiple store directories.
+ * checks JSON first, then .nu. returns the first match found.
+ * directories are searched in order (user dir before system dirs). *)
+let find_file dirs command =
+  let base_name = filename_of_command command in
+  List.find_map (fun directory ->
+    let json_path = Filename.concat directory (base_name ^ ".json") in
+    if Sys.file_exists json_path then Some json_path
+    else
+      let nu_path = Filename.concat directory (base_name ^ ".nu") in
+      if Sys.file_exists nu_path then Some nu_path
+      else None
+  ) dirs
+
+(* look up a command and deserialize its help_result from JSON.
+ * only searches for .json files (not .nu, since those can't be deserialized
+ * back into help_result). returns None if not found or parse fails. *)
+let lookup dirs command =
+  let base_name = filename_of_command command in
+  List.find_map (fun directory ->
+    let path = Filename.concat directory (base_name ^ ".json") in
+    match read_file path with
+    | Some data ->
+      (try Some (help_result_of_json (parse_json data))
+       with _ -> None)
+    | None -> None
+  ) dirs
+
+(* look up a command's raw data (JSON or .nu source) without parsing.
+ * used by the "query" command to dump stored data as-is. *)
+let lookup_raw dirs command =
+  let base_name = filename_of_command command in
+  List.find_map (fun directory ->
+    let json_path = Filename.concat directory (base_name ^ ".json") in
+    match read_file json_path with
+    | Some _ as result -> result
+    | None ->
+      let nu_path = Filename.concat directory (base_name ^ ".nu") in
+      read_file nu_path
+  ) dirs
+
+(* strip known extensions (.json or .nu) from a filename, returning None
+ * if the filename has neither extension *)
+let chop_extension filename =
+  if Filename.check_suffix filename ".json" then Some (Filename.chop_suffix filename ".json")
+  else if Filename.check_suffix filename ".nu" then Some (Filename.chop_suffix filename ".nu")
+  else None
+
+(* discover subcommands of a command by scanning filenames in the store.
+ * looks for files whose names start with the command's filename + "_"
+ * (e.g. for "git", finds "git_add.json", "git_commit.json", etc.)
+ *
+ * only returns immediate subcommands (no nested underscores beyond the prefix).
+ * tries to extract description from the JSON "description" field if available.
+ *
+ * note: this filesystem-based discovery is used as a fallback when the
+ * command's own help_result doesn't list subcommands. it enables completion
+ * for subcommands that were indexed from separate manpages or help runs. *)
+let subcommands_of dirs command =
+  let prefix = filename_of_command command ^ "_" in
+  let prefix_len = String.length prefix in
+  let module SMap = Map.Make(String) in
+  let subs = List.fold_left (fun subs directory ->
+    if is_dir directory then
+      Array.fold_left (fun subs filename ->
+        if not (String.starts_with ~prefix filename) then subs
+        else
+          let is_json = Filename.check_suffix filename ".json" in
+          match chop_extension filename with
+          | None -> subs
+          | Some base_name ->
+            let rest = String.sub base_name prefix_len (String.length base_name - prefix_len) in
+            (* skip nested subcommands and empty names *)
+            if String.contains rest '_' || String.length rest = 0 then subs
+            else if SMap.mem rest subs then subs
+            else
+              (* try to read the description from the JSON file *)
+              let desc = if is_json then
+                match read_file (Filename.concat directory filename) with
+                | Some data ->
+                  (try json_to_string (json_get "description" (parse_json data))
+                   with _ -> "")
+                | None -> ""
+              else "" in
+              SMap.add rest { name = rest; desc } subs
+      ) subs (Sys.readdir directory)
+    else subs
+  ) SMap.empty dirs in
+  SMap.fold (fun _ sc acc -> sc :: acc) subs [] |> List.rev
+
+(* list all indexed commands across all store directories.
+ * returns a sorted, deduplicated list of command names. *)
+let all_commands dirs =
+  let module SSet = Set.Make(String) in
+  List.fold_left (fun cmds directory ->
+    if is_dir directory then
+      Array.fold_left (fun cmds filename ->
+        match chop_extension filename with
+        | Some base_name -> SSet.add (command_of_filename base_name) cmds
+        | None -> cmds
+      ) cmds (Sys.readdir directory)
+    else cmds
+  ) SSet.empty dirs
+  |> SSet.elements
+
+(* determine how a command was indexed: "help", "manpage", "native", etc.
+ * for JSON files, reads the "source" field. for .nu files, returns "native".
+ * used by the "dump" command to show provenance. *)
+let file_type_of dirs command =
+  let base_name = filename_of_command command in
+  List.find_map (fun directory ->
+    let json_path = Filename.concat directory (base_name ^ ".json") in
+    if Sys.file_exists json_path then
+      (match read_file json_path with
+       | Some data ->
+         (try Some (json_to_string (json_get "source" (parse_json data)))
+          with _ -> Some "json")
+       | None -> Some "json")
+    else
+      let nu_path = Filename.concat directory (base_name ^ ".nu") in
+      if Sys.file_exists nu_path then Some "native"
+      else None
+  ) dirs

nix/module.nix

@@ -0,0 +1,109 @@
+# NixOS module: automatic nushell completion indexing
+#
+# Indexes completions using three strategies in priority order:
+#   1. Native completion generators (e.g. CMD completions nushell)
+#   2. Manpage parsing
+#   3. --help output parsing
+#
+# Produces a directory of .json/.nu files at build time.
+# The `complete` command reads from this directory as a system overlay.
+#
+# Usage:
+#   { pkgs, ... }: {
+#     imports = [ ./path/to/inshellah/nix/module.nix ];
+#     programs.inshellah.enable = true;
+#   }
+
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+
+let
+  cfg = config.programs.inshellah;
+in
+{
+  options.programs.inshellah = {
+    enable = lib.mkEnableOption "nushell completion indexing via inshellah";
+
+    package = lib.mkOption {
+      type = lib.types.package;
+      description = "package to use for indexing completions";
+    };
+
+    completionsPath = lib.mkOption {
+      type = lib.types.str;
+      default = "/share/inshellah";
+      description = ''
+        subdirectory within the system profile where completion files
+        are placed. used as --system-dir for the completer.
+      '';
+    };
+
+    ignoreCommands = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      default = [ ];
+      example = [ "problematic-tool" ];
+      description = ''
+        list of command names to skip during completion indexing
+      '';
+    };
+
+    helpOnlyCommands = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      default = [ ];
+      example = [ "nix" ];
+      description = ''
+        list of command names to skip manpage parsing for,
+        using --help scraping instead
+      '';
+    };
+
+    snippet = lib.mkOption {
+      type = lib.types.str;
+      readOnly = true;
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    environment.systemPackages = [ config.programs.inshellah.package ];
+    environment.pathsToLink = [ "/share/nushell/autoload" ];
+    environment.extraSetup =
+      let
+        inshellah = "${cfg.package}/bin/inshellah";
+        destDir = "$out${cfg.completionsPath}";
+        ignoreFile = pkgs.writeText "inshellah-ignore" (lib.concatStringsSep "\n" cfg.ignoreCommands);
+        ignoreFlag = lib.optionalString (cfg.ignoreCommands != [ ]) " --ignore ${ignoreFile}";
+        helpOnlyFile = pkgs.writeText "inshellah-help-only" (
+          lib.concatStringsSep "\n" cfg.helpOnlyCommands
+        );
+        helpOnlyFlag = lib.optionalString (cfg.helpOnlyCommands != [ ]) " --help-only ${helpOnlyFile}";
+      in
+      ''
+        mkdir -p ${destDir}
+
+        if [ -d "$out/bin" ] && [ -d "$out/share/man" ]; then
+          ${inshellah} index "$out" --dir ${destDir}${ignoreFlag}${helpOnlyFlag} \
+            2>/dev/null || true
+        fi
+
+        find ${destDir} -maxdepth 1 -empty -delete
+
+        # nushell hardcodes sudo and doas to bypass the external completer,
+        # returning command-name completion instead of calling inshellah.
+        # these @complete external stubs override that so inshellah handles
+        # their flags and elevation stripping. placed in the nushell autoload
+        # dir so they are sourced automatically at shell startup.
+        mkdir -p $out/share/nushell/vendor/autoload
+        cat > $out/share/nushell/vendor/autoload/inshellah-elevation.nu << 'NUSHELL'
+        @complete external
+        extern "sudo" []
+
+        @complete external
+        extern "doas" []
+        NUSHELL
+      '';
+  };
+}

test/dune

@@ -0,0 +1,3 @@
+(test
+ (name test_inshellah)
+ (libraries inshellah str))

test/test_inshellah.ml

@@ -0,0 +1,492 @@
+open Inshellah.Parser
+open Inshellah.Manpage
+open Inshellah.Nushell
+
+let failures = ref 0
+let passes = ref 0
+
+let check name condition =
+  if condition then begin
+    incr passes;
+    Printf.printf "  PASS: %s\n" name
+  end else begin
+    incr failures;
+    Printf.printf "  FAIL: %s\n" name
+  end
+
+let parse txt =
+  match parse_help txt with
+  | Ok r -> r
+  | Error msg -> failwith (Printf.sprintf "parse_help failed: %s" msg)
+
+(* --- Help parser tests --- *)
+
+let test_gnu_basic () =
+  Printf.printf "\n== GNU basic flags ==\n";
+  let r = parse "  -a, --all                  do not ignore entries starting with .\n" in
+  check "one entry" (List.length r.entries = 1);
+  let e = List.hd r.entries in
+  check "both switch" (e.switch = Both ('a', "all"));
+  check "no param" (e.param = None);
+  check "desc" (String.length e.desc > 0)
+
+let test_gnu_eq_param () =
+  Printf.printf "\n== GNU = param ==\n";
+  let r = parse "      --block-size=SIZE      scale sizes by SIZE\n" in
+  check "one entry" (List.length r.entries = 1);
+  let e = List.hd r.entries in
+  check "long switch" (e.switch = Long "block-size");
+  check "mandatory param" (e.param = Some (Mandatory "SIZE"))
+
+let test_gnu_opt_param () =
+  Printf.printf "\n== GNU optional param ==\n";
+  let r = parse "      --color[=WHEN]         color the output WHEN\n" in
+  check "one entry" (List.length r.entries = 1);
+  let e = List.hd r.entries in
+  check "long switch" (e.switch = Long "color");
+  check "optional param" (e.param = Some (Optional "WHEN"))
+
+let test_underscore_param () =
+  Printf.printf "\n== Underscore in param (TIME_STYLE) ==\n";
+  let r = parse "      --time-style=TIME_STYLE  time/date format\n" in
+  check "one entry" (List.length r.entries = 1);
+  let e = List.hd r.entries in
+  check "param with underscore" (e.param = Some (Mandatory "TIME_STYLE"))
+
+let test_short_only () =
+  Printf.printf "\n== Short-only flag ==\n";
+  let r = parse "  -v                       verbose output\n" in
+  check "one entry" (List.length r.entries = 1);
+  check "short switch" ((List.hd r.entries).switch = Short 'v')
+
+let test_long_only () =
+  Printf.printf "\n== Long-only flag ==\n";
+  let r = parse "      --help                 display help\n" in
+  check "one entry" (List.length r.entries = 1);
+  check "long switch" ((List.hd r.entries).switch = Long "help")
+
+let test_multiline_desc () =
+  Printf.printf "\n== Multi-line description ==\n";
+  let r = parse {|      --block-size=SIZE      with -l, scale sizes by SIZE when printing them;
+                               e.g., '--block-size=M'; see SIZE format below
+|} in
+  check "one entry" (List.length r.entries = 1);
+  let e = List.hd r.entries in
+  check "desc includes continuation" (String.length e.desc > 50)
+
+let test_multiple_entries () =
+  Printf.printf "\n== Multiple entries ==\n";
+  let r = parse {|  -a, --all                  do not ignore entries starting with .
+  -A, --almost-all           do not list implied . and ..
+      --author               with -l, print the author of each file
+|} in
+  check "three entries" (List.length r.entries = 3)
+
+let test_clap_short_sections () =
+  Printf.printf "\n== Clap short with section headers ==\n";
+  let r = parse {|INPUT OPTIONS:
+  -e, --regexp=PATTERN       A pattern to search for.
+  -f, --file=PATTERNFILE     Search for patterns from the given file.
+SEARCH OPTIONS:
+  -s, --case-sensitive       Search case sensitively.
+|} in
+  check "three entries" (List.length r.entries = 3);
+  let e = List.hd r.entries in
+  check "first is regexp" (e.switch = Both ('e', "regexp"));
+  check "first has param" (e.param = Some (Mandatory "PATTERN"))
+
+let test_clap_long_style () =
+  Printf.printf "\n== Clap long style (desc below flag) ==\n";
+  let r = parse {|  -H, --hidden
+          Include hidden directories and files.
+
+      --no-ignore
+          Do not respect ignore files.
+|} in
+  check "two entries" (List.length r.entries = 2);
+  let e = List.hd r.entries in
+  check "hidden switch" (e.switch = Both ('H', "hidden"));
+  check "desc below" (String.length e.desc > 0)
+
+let test_clap_long_angle_param () =
+  Printf.printf "\n== Clap long angle bracket param ==\n";
+  let r = parse {|      --nonprintable-notation <notation>
+          Set notation for non-printable characters.
+|} in
+  check "one entry" (List.length r.entries = 1);
+  let e = List.hd r.entries in
+  check "long switch" (e.switch = Long "nonprintable-notation");
+  check "angle param" (e.param = Some (Mandatory "notation"))
+
+let test_space_upper_param () =
+  Printf.printf "\n== Space-separated ALL_CAPS param ==\n";
+  let r = parse "  -f, --foo FOO  foo help\n" in
+  check "one entry" (List.length r.entries = 1);
+  let e = List.hd r.entries in
+  check "switch" (e.switch = Both ('f', "foo"));
+  check "space param" (e.param = Some (Mandatory "FOO"))
+
+let test_go_cobra_flags () =
+  Printf.printf "\n== Go/Cobra flags ==\n";
+  let r = parse {|Flags:
+  -D, --debug              Enable debug mode
+  -H, --host string        Daemon socket to connect to
+  -v, --version            Print version information
+|} in
+  check "three flag entries" (List.length r.entries = 3);
+  (* Check the host flag has a type param *)
+  let host = List.nth r.entries 1 in
+  check "host switch" (host.switch = Both ('H', "host"));
+  check "host type param" (host.param = Some (Mandatory "string"))
+
+let test_go_cobra_subcommands () =
+  Printf.printf "\n== Go/Cobra subcommands ==\n";
+  let r = parse {|Common Commands:
+  run         Create and run a new container from an image
+  exec        Execute a command in a running container
+  build       Build an image from a Dockerfile
+|} in
+  check "has subcommands" (List.length r.subcommands > 0)
+
+let test_busybox_tab () =
+  Printf.printf "\n== Busybox tab-indented ==\n";
+  let r = parse "\t-1\tOne column output\n\t-a\tInclude names starting with .\n" in
+  check "two entries" (List.length r.entries = 2);
+  check "first is -1" ((List.hd r.entries).switch = Short '1')
+
+let test_no_debug_prints () =
+  Printf.printf "\n== No debug side effects ==\n";
+  (* The old parser had print_endline at module load time.
+     If we got here without "opt param is running" on stdout, we're good. *)
+  check "no debug prints" true
+
+(* --- Manpage parser tests --- *)
+
+let test_manpage_tp_style () =
+  Printf.printf "\n== Manpage .TP style ==\n";
+  let groff = {|.SH OPTIONS
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+do not ignore entries starting with .
+.TP
+\fB\-A\fR, \fB\-\-almost\-all\fR
+do not list implied . and ..
+.TP
+\fB\-\-block\-size\fR=\fISIZE\fR
+with \fB\-l\fR, scale sizes by SIZE
+.SH AUTHOR
+Written by someone.
+|} in
+  let result = parse_manpage_string groff in
+  check "three entries" (List.length result.entries = 3);
+  if List.length result.entries >= 1 then begin
+    let e = List.hd result.entries in
+    check "first is -a/--all" (e.switch = Both ('a', "all"));
+    check "first desc" (String.length e.desc > 0)
+  end;
+  if List.length result.entries >= 3 then begin
+    let e = List.nth result.entries 2 in
+    check "block-size switch" (e.switch = Long "block-size");
+    check "block-size param" (e.param = Some (Mandatory "SIZE"))
+  end
+
+let test_manpage_ip_style () =
+  Printf.printf "\n== Manpage .IP style ==\n";
+  let groff = {|.SH OPTIONS
+.IP "\fB\-k\fR, \fB\-\-insecure\fR"
+Allow insecure connections.
+.IP "\fB\-o\fR, \fB\-\-output\fR \fIfile\fR"
+Write output to file.
+.SH SEE ALSO
+|} in
+  let result = parse_manpage_string groff in
+  check "two entries" (List.length result.entries = 2);
+  if List.length result.entries >= 1 then begin
+    let e = List.hd result.entries in
+    check "first is -k/--insecure" (e.switch = Both ('k', "insecure"))
+  end
+
+let test_manpage_groff_stripping () =
+  Printf.printf "\n== Groff escape stripping ==\n";
+  let s = strip_groff_escapes {|\fB\-\-color\fR[=\fIWHEN\fR]|} in
+  check "font escapes removed" (not (String.contains s 'f' && String.contains s 'B'));
+  check "dashes converted" (String.contains s '-');
+  let s2 = strip_groff_escapes {|\(aqhello\(aq|} in
+  check "aq -> quote" (String.contains s2 '\'')
+
+let test_manpage_empty_options () =
+  Printf.printf "\n== Manpage with no OPTIONS section ==\n";
+  let groff = {|.SH NAME
+foo \- does stuff
+.SH DESCRIPTION
+Does stuff.
+|} in
+  let result = parse_manpage_string groff in
+  check "no entries" (List.length result.entries = 0)
+
+let test_slash_switch_separator () =
+  Printf.printf "\n== Slash switch separator (--long / -s) ==\n";
+  let r = parse "  --verbose / -v             Increase verbosity\n" in
+  check "one entry" (List.length r.entries = 1);
+  let e = List.hd r.entries in
+  check "both switch" (e.switch = Both ('v', "verbose"));
+  check "no param" (e.param = None);
+  check "desc" (e.desc = "Increase verbosity")
+
+let test_manpage_nix3_style () =
+  Printf.printf "\n== Manpage nix3 style ==\n";
+  let groff = {|.SH Options
+.SS Logging-related options
+.IP "\(bu" 3
+.UR #opt-verbose
+\f(CR--verbose\fR
+.UE
+/ \f(CR-v\fR
+.IP
+Increase the logging verbosity level.
+.IP "\(bu" 3
+.UR #opt-quiet
+\f(CR--quiet\fR
+.UE
+.IP
+Decrease the logging verbosity level.
+.SH SEE ALSO
+|} in
+  let result = parse_manpage_string groff in
+  check "two entries" (List.length result.entries = 2);
+  if List.length result.entries >= 1 then begin
+    let e = List.hd result.entries in
+    check "verbose is Both" (e.switch = Both ('v', "verbose"));
+    check "verbose desc" (String.length e.desc > 0)
+  end;
+  if List.length result.entries >= 2 then begin
+    let e = List.nth result.entries 1 in
+    check "quiet is Long" (e.switch = Long "quiet");
+    check "quiet desc" (String.length e.desc > 0)
+  end
+
+let test_manpage_nix3_with_params () =
+  Printf.printf "\n== Manpage nix3 with params ==\n";
+  let groff = {|.SH Options
+.IP "\(bu" 3
+.UR #opt-arg
+\f(CR--arg\fR
+.UE
+\fIname\fR \fIexpr\fR
+.IP
+Pass the value as the argument name to Nix functions.
+.IP "\(bu" 3
+.UR #opt-include
+\f(CR--include\fR
+.UE
+/ \f(CR-I\fR \fIpath\fR
+.IP
+Add path to search path entries.
+.IP
+This option may be given multiple times.
+.SH SEE ALSO
+|} in
+  let result = parse_manpage_string groff in
+  check "two entries" (List.length result.entries = 2);
+  if List.length result.entries >= 1 then begin
+    let e = List.hd result.entries in
+    check "arg is Long" (e.switch = Long "arg");
+    check "arg has param" (e.param <> None)
+  end;
+  if List.length result.entries >= 2 then begin
+    let e = List.nth result.entries 1 in
+    check "include is Both" (e.switch = Both ('I', "include"));
+    check "include has path param" (e.param = Some (Mandatory "path"))
+  end
+
+let test_synopsis_subcommand () =
+  Printf.printf "\n== SYNOPSIS subcommand detection ==\n";
+  let groff = {|.SH "SYNOPSIS"
+.sp
+.nf
+\fBgit\fR \fBcommit\fR [\fB\-a\fR | \fB\-\-interactive\fR]
+.fi
+.SH "DESCRIPTION"
+|} in
+  let cmd = extract_synopsis_command groff in
+  check "detected git commit" (cmd = Some "git commit")
+
+let test_synopsis_standalone () =
+  Printf.printf "\n== SYNOPSIS standalone command ==\n";
+  let groff = {|.SH Synopsis
+.LP
+\f(CRnix-build\fR [\fIpaths\fR]
+.SH Description
+|} in
+  let cmd = extract_synopsis_command groff in
+  check "detected nix-build" (cmd = Some "nix-build")
+
+let test_synopsis_nix3 () =
+  Printf.printf "\n== SYNOPSIS nix3 subcommand ==\n";
+  let groff = {|.SH Synopsis
+.LP
+\f(CRnix run\fR [\fIoption\fR] \fIinstallable\fR
+.SH Description
+|} in
+  let cmd = extract_synopsis_command groff in
+  check "detected nix run" (cmd = Some "nix run")
+
+(* --- Nushell generation tests --- *)
+
+let contains s sub =
+  try
+    let _ = Str.search_forward (Str.regexp_string sub) s 0 in true
+  with Not_found -> false
+
+let test_nushell_basic () =
+  Printf.printf "\n== Nushell basic extern ==\n";
+  let r = parse "  -a, --all                  do not ignore entries starting with .\n" in
+  let nu = generate_extern "ls" r in
+  check "has extern" (contains nu "export extern \"ls\"");
+  check "has --all(-a)" (contains nu "--all(-a)");
+  check "has comment" (contains nu "# do not ignore")
+
+let test_nushell_param_types () =
+  Printf.printf "\n== Nushell param type mapping ==\n";
+  let r = parse {|  -w, --width=COLS           set output width
+      --block-size=SIZE      scale sizes
+  -o, --output FILE          output file
+|} in
+  let nu = generate_extern "ls" r in
+  check "COLS -> int" (contains nu "--width(-w): int");
+  check "SIZE -> string" (contains nu "--block-size: string");
+  check "FILE -> path" (contains nu "--output(-o): path")
+
+let test_nushell_subcommands () =
+  Printf.printf "\n== Nushell subcommands ==\n";
+  let r = parse {|Common Commands:
+  run         Create and run a new container
+  exec        Execute a command
+
+Flags:
+  -D, --debug              Enable debug mode
+|} in
+  let nu = generate_extern "docker" r in
+  check "has main extern" (contains nu "export extern \"docker\"");
+  check "has --debug" (contains nu "--debug(-D)");
+  check "has run subcommand" (contains nu "export extern \"docker run\"");
+  check "has exec subcommand" (contains nu "export extern \"docker exec\"")
+
+let test_nushell_from_manpage () =
+  Printf.printf "\n== Nushell from manpage ==\n";
+  let groff = {|.SH OPTIONS
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+do not ignore entries starting with .
+.TP
+\fB\-\-block\-size\fR=\fISIZE\fR
+scale sizes by SIZE
+.SH AUTHOR
+|} in
+  let result = parse_manpage_string groff in
+  let nu = generate_extern "ls" result in
+  check "has extern" (contains nu "export extern \"ls\"");
+  check "has --all(-a)" (contains nu "--all(-a)");
+  check "has --block-size" (contains nu "--block-size: string")
+
+let test_nushell_module () =
+  Printf.printf "\n== Nushell module wrapper ==\n";
+  let r = parse "  -v, --verbose              verbose output\n" in
+  let nu = generate_module "myapp" r in
+  check "has module" (contains nu "module myapp-completions");
+  check "has extern inside" (contains nu "export extern \"myapp\"");
+  check "has flag" (contains nu "--verbose(-v)")
+
+let test_dedup_entries () =
+  Printf.printf "\n== Deduplication ==\n";
+  let r = parse {|  -v, --verbose              verbose output
+  --verbose                  verbose mode
+  -v                         be verbose
+|} in
+  let nu = generate_extern "test" r in
+  (* Count occurrences of --verbose *)
+  let count =
+    let re = Str.regexp_string "--verbose" in
+    let n = ref 0 in
+    let i = ref 0 in
+    (try while true do
+       let _ = Str.search_forward re nu !i in
+       incr n; i := Str.match_end ()
+     done with Not_found -> ());
+    !n
+  in
+  check "verbose appears once" (count = 1);
+  check "best version kept (Both)" (contains nu "--verbose(-v)")
+
+let test_dedup_manpage () =
+  Printf.printf "\n== Dedup from manpage ==\n";
+  let groff = {|.SH OPTIONS
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Be verbose.
+.SH DESCRIPTION
+Use \fB\-v\fR for verbose output.
+Use \fB\-\-verbose\fR to see more.
+|} in
+  let result = parse_manpage_string groff in
+  let nu = generate_extern "test" result in
+  check "has --verbose(-v)" (contains nu "--verbose(-v)");
+  (* Should not have standalone -v or duplicate --verbose *)
+  let lines = String.split_on_char '\n' nu in
+  let verbose_lines = List.filter (fun l -> contains l "verbose") lines in
+  check "only one verbose line" (List.length verbose_lines = 1)
+
+let test_font_boundary_spacing () =
+  Printf.printf "\n== Font boundary spacing ==\n";
+  (* \fB--max-results\fR\fIcount\fR should become "--max-results count" *)
+  let s = strip_groff_escapes {|\fB\-\-max\-results\fR\fIcount\fR|} in
+  check "has space before param" (contains s "--max-results count");
+  (* \fB--color\fR[=\fIWHEN\fR] should NOT insert space before = *)
+  let s2 = strip_groff_escapes {|\fB\-\-color\fR[=\fIWHEN\fR]|} in
+  check "no space before =" (contains s2 "--color[=WHEN]")
+
+let () =
+  Printf.printf "Running help parser tests...\n";
+  test_gnu_basic ();
+  test_gnu_eq_param ();
+  test_gnu_opt_param ();
+  test_underscore_param ();
+  test_short_only ();
+  test_long_only ();
+  test_multiline_desc ();
+  test_multiple_entries ();
+  test_clap_short_sections ();
+  test_clap_long_style ();
+  test_clap_long_angle_param ();
+  test_space_upper_param ();
+  test_go_cobra_flags ();
+  test_go_cobra_subcommands ();
+  test_busybox_tab ();
+  test_no_debug_prints ();
+
+  Printf.printf "\nRunning manpage parser tests...\n";
+  test_manpage_tp_style ();
+  test_manpage_ip_style ();
+  test_manpage_groff_stripping ();
+  test_manpage_empty_options ();
+  test_slash_switch_separator ();
+  test_manpage_nix3_style ();
+  test_manpage_nix3_with_params ();
+  test_synopsis_subcommand ();
+  test_synopsis_standalone ();
+  test_synopsis_nix3 ();
+
+  Printf.printf "\nRunning nushell generation tests...\n";
+  test_nushell_basic ();
+  test_nushell_param_types ();
+  test_nushell_subcommands ();
+  test_nushell_from_manpage ();
+  test_nushell_module ();
+
+  Printf.printf "\nRunning dedup and font tests...\n";
+  test_dedup_entries ();
+  test_dedup_manpage ();
+  test_font_boundary_spacing ();
+
+  Printf.printf "\n=== Results: %d passed, %d failed ===\n" !passes !failures;
+  if !failures > 0 then exit 1