init

doc/nixos.md

@@ -0,0 +1,140 @@
+# NixOS integration
+
+inshellah provides a NixOS module that automatically generates 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 generate $out/bin $out/share/man -o $out/share/nushell/vendor/autoload
+```
+
+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.)
+- 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.
+
+### Output
+
+Each command gets its own `.nu` file in the vendor autoload directory,
+module-wrapped:
+
+```nu
+module git-completions {
+export extern "git commit" [
+    --all(-a)         # Automatically stage modified and deleted files
+    --message(-m): string  # Use the given msg as the commit message
+    ...
+]
+}
+
+use git-completions *
+```
+
+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 generated .nu files
+  # Default matches nushell's vendor autoload convention
+  generatedCompletionsPath = "/share/nushell/vendor/autoload";
+};
+```
+
+## Troubleshooting
+
+**Completions not appearing**: Ensure nushell discovers the vendor
+autoload path. Check `$env.NU_VENDOR_AUTOLOAD_DIRS` or verify that
+`/run/current-system/sw/share` is in `$XDG_DATA_DIRS`.
+
+**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**: Generation failures are non-fatal (`|| true`).
+Check `journalctl` for the build log if completions are missing.