repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(nushell): tighten shell guidance

7b1b34be87ab8fbc972bb16e267da84556e49241

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (3)

pi/agent/skills/nushell/SKILL.md

Modified
2 2 name: nushell
3 -description: "Use when writing, debugging, or modernizing Nu code/config, editing .nu files, or translating shell commands to Nushell. Not generic Bash or terminal work."
3 +description: "Use when writing, debugging, or modernizing Nu code/config, or translating shell commands to Nushell."
4 4 license: MIT
7 7 # Nushell
9 -Target installed Nu, not remembered syntax.
10 -Keep language guidance here; use `mise` for Mise integration
11 -and `linux-userland` for Linux HOME/XDG boundaries.
9 +Target installed Nu, not memory. Keep Nu guidance here; follow project instructions for Mise and OS boundaries.
13 -## Discover
11 +## Source of truth
15 -Use `nu --no-config-file -c '<probe>'` for isolated language checks.
16 -This skips startup config, not inherited env or side effects in the probe.
17 -Never dump `$env`, source secret files,
18 -or run real login startup merely to check syntax.
13 +- Probe isolated: `nu --no-config-file -c '<probe>'`.
14 +- Ask installed Nu: `help <command>`, `help --find <term>`, `scope commands`.
15 +- For migrations, follow [Modernize](references/modernize.md): local help → release notes → isolated probes.
16 +- Use the [Nu book](https://www.nushell.sh/book/), especially [Coming from Bash](https://www.nushell.sh/book/coming_from_bash.html), and [release notes](https://www.nushell.sh/blog/).
20 -```nushell
21 -version | select version experimental_options
22 -help commands | where name == "path type" | get input_output
23 -help --find semver | select name usage
24 -help <command>
25 -```
27 -For deprecated syntax, inspect command metadata when available:
29 -```nushell
30 -scope commands | where name == "str upcase" | get deprecation_info
31 -```
33 -For migrations, follow [Modernize](references/modernize.md):
34 -local help, intervening release notes, then isolated behavior checks.
35 -Do not copy website examples without checking the installed CLI.
18 +Never dump `$env`, source secrets, or run real login startup merely to check syntax.
37 20 ## Code
39 22 - Pipelines carry typed values; external programs exchange byte streams.
40 -- Use `$env.NAME` for environment variables and `$row.field?` for optional fields.
41 - `null` has type `nothing`; guard before passing optional paths to filesystem commands.
42 -- `which` returns records, possibly none;
43 - check emptiness before extracting `get 0.path`.
44 -- Use `^cmd` to bypass internal commands; pass argument lists as `^cmd ...$args`.
45 -- Use `and`/`or` for booleans, not `&&`/`||`.
46 - `;` sequences expressions, not conditional success;
47 - external failures can stop execution.
48 -- Use `save` for pipeline values, `o+e> file` for external output to a file,
49 - and `o+e>| filter` for combined output into a pipeline.
50 - Do not put a filename after `o+e>|`.
23 +- Guard optional values before filesystem commands.
24 +- `which` may return nothing: check before `get 0.path`.
25 +- Use `^cmd ...$args` for external commands.
26 +- Use [Bash → Nu](https://www.nushell.sh/book/coming_from_bash.html), not Bash intuition:
52 -## External failures
28 + | Bash | Nu |
29 + | --- | --- |
30 + | `cmd1 && cmd2` | `cmd1; cmd2` |
31 + | `> file` | `o> file` or `| save file` |
32 + | `> /dev/null` | `| ignore` |
33 + | `> /dev/null 2>&1` | `o+e>| ignore` |
34 + | `$(cmd)` | `(cmd)`; inside strings `$"(cmd)"` |
54 -Capture output and status together instead of assuming
55 -`$env.LAST_EXIT_CODE` behaves like Bash `$?` in every context:
36 + `$"some text(s)"` runs `s`; escape literal parentheses (`\(`, `\)`) or use a plain string.
37 +- Use `save` for pipeline values; `o+e> file` for external output to a file; `o+e>| filter` for combined output.
57 -```nushell
58 -let result = (^tool ...$args | complete)
59 -if $result.exit_code != 0 {
60 - error make {msg: $"tool exited ($result.exit_code)"}
62 -let data = try { $result.stdout | from json --strict } catch {
63 - error make {msg: "tool returned invalid JSON"}
65 -```
39 +Optional CLI:
67 -Use `from json --strict` when the external contract requires JSON;
68 -the default parser accepts non-JSON input too.
69 -Distinguish process failure, malformed data, and valid empty results.
70 -Do not replace failures with `null`, `[]`, or success
71 -unless the caller explicitly permits that fallback.
72 -Do not expose raw stderr or output that may contain secrets.
41 +- Detect the feature first; resolve the executable at invocation time.
42 +- Check lookup before extracting its path; reuse that resolution for the operation.
43 +- Prompt/status with no executable → explicit degraded output, no spawn.
44 +- Explicit user action with no executable → actionable error, never fake success.
45 +- Test present/absent states with identical triggering metadata; hide only the target executable where possible.
74 -## Config and scripts
47 +## Details
76 -1. Identify the actual shell and launch mode:
77 - command string, script, interactive, or login.
78 - Use `$nu | columns`, then inspect only needed config paths,
79 - including `loginshell-path`, `vendor-autoload-dirs`, and `user-autoload-dirs`.
80 -2. Trace loaded files and their generators before editing activation warnings.
81 - Fix the owner or confirmed duplicate; do not patch generated output blindly.
82 -3. `source`, `use`, `run`, and `nu script.nu` are not interchangeable.
83 - Check local help for scope, pipeline input, `main` arguments,
84 - and top-level execution before switching invocation.
85 -4. Treat `$ans` as REPL state, not a script result store.
86 - Check local help before using version-specific argument annotations such as `external_arg`.
87 -5. Preserve typed signatures and error paths;
88 - reproduce type failures before blaming a release
89 - or disabling experimental checks.
49 +- [External process handling](references/external-processes.md)
50 +- [Configuration and scripts](references/configuration.md)
91 52 ## Verify
93 -Read the target and its imports first; diagnostics may expose source literals.
94 -For reviewed, non-secret code, run the helper from this skill directory:
54 +Read the target and imports first. For reviewed, non-secret code:
96 56 ```sh
97 57 node scripts/check.mjs /absolute/path/to/file.nu
58 +npm test
100 -It runs `nu --no-config-file --ide-check 100`, reports Nu version and diagnostics,
101 -and fails on Error severity even when Nu exits zero.
102 -It does not run the script body; parsing can read imports and evaluate constants,
103 -so this is not a sandbox.
104 -Missing Nu, process failure, stderr, or malformed diagnostics fail closed.
105 -Warnings are reported when emitted, but a pass does not prove absence
106 -of deprecations; Nu 0.115.1 IDE mode omits some.
108 -Then exercise positive and negative behavior with reviewed code
109 -in isolated temporary fixtures.
110 -Check exit codes, data shape, empty/missing inputs, and intended startup mode separately.
111 -Never execute a mutating script just to validate it.
113 -Helper regression tests: `npm test` in this skill directory;
114 -requires Node and Nu on PATH.
61 +The helper checks Nu version and IDE diagnostics; it does not run the script and a pass does not prove runtime correctness or absence of deprecations. Exercise positive/negative behavior in isolated temporary fixtures: present/absent tools, exit codes, data shape, empty/missing input, and startup mode. Never execute a mutating script merely to validate it.

pi/agent/skills/nushell/references/configuration.md

Added
new file mode 100644
1 +# Configuration and scripts
3 +1. Identify shell and launch mode. Inspect only needed `$nu` paths, including `loginshell-path`, `vendor-autoload-dirs`, and `user-autoload-dirs`.
4 +2. Trace loaded files and generators before editing startup warnings; fix the owner, not generated output.
5 +3. Check `help source`, `help use`, and `help run` before changing invocation. They are not interchangeable with `nu script.nu`.
6 +4. Treat `$ans` as REPL state, not a script result store. Preserve typed signatures and error paths.

pi/agent/skills/nushell/references/external-processes.md

Added
new file mode 100644
1 +# External processes
3 +Capture output and status together:
5 +```nu
6 +let result = (^tool ...$args | complete)
7 +if $result.exit_code != 0 {
8 + error make {msg: $"tool exited ($result.exit_code)"}
9 +}
10 +let data = try { $result.stdout | from json --strict } catch {
11 + error make {msg: "tool returned invalid JSON"}
13 +```
15 +Distinguish process failure, malformed data, valid empty results, and permitted fallback. Never expose raw output that may contain secrets.
17 +See [Nu's exit-code and redirection guidance](https://www.nushell.sh/book/stdout_stderr_exit_codes.html).