# nu-bang

Nushell bang-command bridge for Pi.

Runs Pi `!` and `!!` shell input through Nushell.
Adds Nushell completions for bang input.
Requires `nu` in `PATH`, or a configured Nushell executable.

## Install / load

Loaded through the root pi-ext package.
See [root README](../../README.md).

## Commands / tools / settings

- Commands:
  none
- Tools:
  none
- Hooks:
  `user_bash`, `session_start`, `session_shutdown`
- Settings:
  `nu-bang.command`

## Settings

`nu-bang.command` selects the Nushell executable for bang commands and bang completion.
Environment variable: `PI_NU_BANG_COMMAND`.
Default: `"nu"`, looked up in `PATH`.
Valid values: a non-empty string, either a bare command name or a path.
Precedence: `PI_NU_BANG_COMMAND`, trusted project `.pi/settings.json`, user `~/.pi/agent/settings.json`, default.
Project settings are ignored while the project is untrusted.
The value is resolved once at `session_start`.
An invalid value, such as a non-string or an empty or blank string, shows one warning and uses `nu`.
An invalid value never falls through to a lower-priority source.

```json
{ "nu-bang": { "command": "/usr/bin/nu" } }
```

## Behavior

- `user_bash` replaces Pi shell operations with Nushell execution for the
  Pi-provided command.
- Commands run as `<nu-bang.command> --no-history --error-style fancy --table-mode none -c
  <command>`.
- Execution receives Pi cwd, env, abort signal, and timeout.
- Working directory is checked before execution and completion.
- Abort and timeout terminate the spawned Nushell process.
- Output has terminal control sequences removed before it is returned.
- Long output is truncated with Pi's output truncation helper.
- Truncated full output is written to `pi-nu-bang-output-*.log` temp files with
  mode `0600`.
- `session_start` wraps the current autocomplete provider.
- Bang completion strips leading `!` or `!!` before asking Nushell for
  completions.
- Bang completion uses `<nu-bang.command> --no-history --error-style fancy -I <cwd>
  --ide-complete <offset> <temp>/command.nu`.
- Completion temp files live in `pi-nu-bang-*` temp dirs and are removed after
  use.
- Non-bang completion delegates to the existing provider.
- Bang completion failures fall back to the existing provider unless the request
  was aborted.
- Completion prefix detection handles pipes, spaces, cell paths, quoted paths,
  and escaped-space paths.
- Completion application replaces the current Nushell token and removes a stale
  closing quote when needed.
- Bang input always allows file-completion triggering; non-bang input delegates
  that decision.
- Completion JSON accepts Nushell's normal output and salvages malformed quoted
  list items.
- `session_shutdown` removes temporary completion dirs still tracked by the
  extension.

## Debugging

Opt-in metadata-only tracing follows [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `nu.execute.start`, `nu.execute.finish`, `nu.execute.error`.