@lariocpt/crust-mongo 0.0.0-stage → 0.3.6

package/skills/crust-builtins/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: crust-builtins
+description: crust has two separate namespaces — tool builtins (`mock-server`, `test-fixture`, `test-pipes`, `gen-fixtures`, `verify-web-links`, `logs`, `dotenv`, `skills`) that need a line of their own, and registered functions (`base64`, `salt`, `jwt`, `bundle`, `sql`, `wait`) that are space-separated stages usable as a source or mid-pipeline. Explains what the upstream item means to each one, why `bundle(5)` is a shell syntax error, and how to reach crypto/FS from a lambda. Use when a crust stage exits 2 with `syntax error near unexpected token`, when a mid-pipeline function eats the wrong argument, or when a lambda says `salt is not defined`.
+---
+
+# crust's two namespaces
+
+| | What it is | Where it runs | Parens? |
+| --- | --- | --- | --- |
+| **Tool builtin** | `mock-server`, `test-fixture`, `test-pipes`, `gen-fixtures`, `verify-web-links`, `logs`, `dotenv`, `skills` | dispatched **before** pipeline parsing, in-process, own line | subcommand style: `logs tail -F app.log` |
+| **Registered function** | `base64`, `salt`, `jwt`, `bundle`, `sql`, `wait` + anything you add with `crust.fn` | an ordinary pipeline stage, or a source when nothing is upstream | **space-separated**: `salt 16`, not `salt(16)` |
+
+`cd`, `export`, `alias`, `source`, `exit`, `history`, `help` and the job verbs
+`jobs`, `fg`, `bg` are builtins too — the ones sh has its own version of, which
+is why a redirect on *those* is left to sh. `procs`, `range`, `load`, `read`, `tail` and friends are **sources**,
+not builtins.
+
+`source` is the only session builtin with its own argument grammar:
+`source <file> [args…]` — a `.ts`/`.js` file is imported; a `.sh`/`.bash`/`.zsh`
+file (or one whose first line is a `#!` shebang naming a shell) runs **once in
+a child shell** — its exported `KEY=value` delta comes back into the session,
+its exit code is the line's, its side effects are real, but unsets don't
+propagate and its cwd never comes back; anything else runs line-by-line in this
+session (aliases, `export`s and `capture`s persist). An unmarked file that
+looks like multi-line shell, or that doesn't parse as crust, is refused,
+never half-run. In the line-by-line form the args are the *sourced file's*
+positional arguments (`$1`, `$2`, … — `$0` is its own path), and the caller's
+positionals are restored when the file ends; the shell form's child never sees
+them — its `$1…` are its own shell's, not the file's:
+
+```crust
+# demo.sh does `export DEMO=one` and changes cwd; only the export survives
+source ./demo.sh
+export   # → … DEMO=one … — the env delta came back, the cwd did not
+# line-by-line only: the args are the file's $1… ($0 its path)
+source ./more.crust one two
+```
+
+## Job control is a third shape
+
+`jobs`, `fg`, `bg` are ordinary builtins. `wait %1` and `kill %1` are **not** —
+registering either name wholesale would take a word sh (or crust) already owns,
+so only the `%job` operand form is intercepted and every other line keeps its
+owner:
+
+```crust
+wait :3000/health --timeout 5s   # the registered `wait` function — readiness
+kill -9 4242                     # sh's: a PID is not a job spec
+wait %1                          # the job wait
+kill %1                          # the job signal — reports the SEND, not the death
+```
+
+A trailing `&` on a shell line is crust's too (its own process group, stdin
+`/dev/null`, outlives the session), and `jobs`/`fg`/`bg`/`wait %N` are how it
+comes back. `Ctrl-Z` suspends a crust pipeline, builtin or `fg`/`wait` with
+SIGSTOP; it cannot stop a foreground inherit-stdio child, because the runtime
+ignores SIGTSTP and children inherit that ignore.
+
+The single most common mistake is writing the JS form:
+
+```
+bundle(5)   →  sh: -c: line 1: syntax error near unexpected token `('   (exit 2)
+```
+
+Parens are crust syntax only for **lexer sources** (`range(0,9)`,
+`read("…")`) — everything else in a stage is a shell word list.
+
+A stage that *starts* with `{` or `[` is a JSON literal when it parses, or when
+tight text still looks like someone typing one — a quote, colon, comma or a `$`
+inside the brackets (`{"n":$N}`, `[1,$N]`). The shell's own bracket shapes are
+always spaced, so `[ … ]` and `{ …; }` are shell stages, in any position — and a
+mid-pipeline one works too, which it used not to:
+
+```crust
+{ echo a; echo b; } | cat
+[ -f package.json ] && echo there
+```
+
+## What the item means, per function
+
+A registered function is called `fn(item, ...lineArgs)` mid-pipeline. So the
+first slot is **your data**, and each function decides what to do with it:
+
+| Function | As a source | Mid-pipeline |
+| --- | --- | --- |
+| `base64 [-d\|decode] [-f\|--file <path>] [-o\|--out <path>]` | encodes the literal argument, or a file's bytes with `--file` | encodes (or decodes) **each item**; the item is data, never an option |
+| `salt [bytes] [hex\|base64\|base64url]` | one salt, size = the argument | **one salt per item**; the size is the argument *trailing* the item |
+| `jwt sign\|verify\|decode --secret <s>` | payload/token = the argument | the item **is** the payload (sign) or token (verify/decode) |
+| `sql "<query>" [params…]` | streams rows | the query stays the one you wrote; the item **binds as the first parameter** when the line declares none |
+| `mongo "<expr>"` | streams documents — an expression on `db` (`db.users.find({}).limit(10)`), cursor drained per item | the item binds as `item` in the expression — `… \| mongo "db.users.insertMany(item)"`; needs the mongo-bundled binary (`@lariocpt/crust-mongo`) |
+| `wait <target> [--timeout <dur>]` | waits for the argument | the item is the target |
+| `bundle <entry> [--outfile…]` | bundles the argument | a string item **is an entrypoint** |
+
+```crust
+base64 hello
+echo aGk= | base64 -d
+salt 32 base64
+lines users.csv | salt 16
+jwt sign '{"sub":"42"}' --secret k
+sql "select id, email from users limit 5" | (r => r.email)
+range(2,2) | (n => "beta") | sql "SELECT name FROM t WHERE name = ?" | assert (r => r.name === "beta")
+mongo "db.users.find({active: true}).limit(10)"
+read docs.json | (s => JSON.parse(s)) | mongo "db.users.insertMany(item)"
+wait :3001/health --timeout 30s
+bundle src/index.ts --outfile dist/app.js --minify
+```
+
+Options come from the line, never from the item: `printf '%s' -d | base64` is
+`LWQ=`, the two characters encoded, not a mode flip. A dash that is not one of
+that function's options is refused rather than encoded (`base64 --desc hello`
+used to print `LS1kZXNj` and exit 0), and decoding refuses a character outside
+the alphabet — Node's decoder skips unknown characters, which printed three
+replacement characters at exit 0 for `not base64!!!`.
+
+Each of the six also answers `-h`/`--help` with its own usage screen and exit
+**0** — at parse time, **before any stage runs**, so `… | sql --help` prints
+usage without making the request (the `touch` upstream of it never happens).
+The scan stops at `--`, so `base64 -- --help` encodes the flag, and a value
+that arrives through the pipe is data, never an option
+(`printf '%s' --help | base64` encodes it). A `crust.fn` override of the name
+keeps its own argument handling — `--help` is just another argument to it.
+
+```crust
+base64 --help
+```
+
+`wait` failing to become ready exits **1** — measured for every target form
+(`:PORT`, `:PORT/path`, `port:PORT`) and for a `--timeout` that expires. crust
+has no exit **124**: that number is `timeout(1)` killing crust from outside, so
+wrapping a probe in `timeout` steals the code you were gating on.
+
+## A lambda cannot call them
+
+Registered functions live in crust's function table, not in the JS scope a
+lambda compiles into:
+
+```
+range(2,2) | (x => salt(4))   →  crust: salt is not defined   (exit 1)
+```
+
+That is not a dead end: a lambda body has Bun's own globals, and `await` works
+in it, so reach the underlying capability directly.
+
+```crust
+range(0,9) | (_ => crypto.getRandomValues(new Uint8Array(8)).toHex())
+range(0,0) | (_ => JSON.parse(await Bun.file("package.json").text()).name)
+```
+
+Prefer the registered function when it fits (`salt 16` per item is shorter than
+the `crypto` line); drop to a lambda when you need something crust doesn't ship.
+
+## Session environment
+
+A line of pure assignments *is* the session environment — it runs the same code
+`export` runs, so the two spellings cannot disagree:
+
+```crust
+FOO=bar
+PATH=$PATH:/tmp/bin
+CFLAGS+=$EXTRA_FLAGS
+TOKEN='$literal'
+```
+
+`FOO=bar` used to be `sh -c 'FOO=bar'` — exit **0**, value gone, and the next
+line expanded `$FOO` to nothing. Quoting is sh's: `'…'` protects `$`, `"…"`
+expands it, and a backslash protects exactly one character, so `FOO=C:\temp`
+survives.
+
+Two shapes are deliberately **not** session state:
+
+- `FOO=bar cmd args` is sh's *transient* prefix — the variable lives for that
+  one command — so the line goes to sh untouched and later lines see nothing.
+- `FOO=$(cmd)` is refused rather than run: its value would have to cross back
+  out of a child process. The honest route is a pipeline — `git rev-parse HEAD`
+  piped into a `capture` stage of that name. Quoting doesn't change that, and
+  neither does a pipe inside the substitution (`FOO=$(date | head -1)` is
+  refused too, not quietly dropped); a `$()` in a *shell* stage stays
+  sh's, so `echo "$(date)"` still prints the date — but a `$()` in a
+  *crust* stage is refused before anything runs, and the named route is
+  capture: `date +%s | capture TS`, then `GET :3000/?t=$TS`.
+
+## These are not shell commands
+
+`base64`, `sort`, `head`, `wc` and friends exist as **real binaries** too. crust
+runs its own when the name is registered (`base64 hello` encodes the *text*, not
+a file), and sh's when it is not (`… | sort` is `/usr/bin/sort`). Neither one
+takes a redirect: crust refuses it and tells you what to write instead — with
+two different messages, because a function and a tool fail differently.
+
+`base64` is the shadow that bites: `/usr/bin/base64 in.ts` encodes the FILE,
+crust's encodes the five characters of the path (`aW4udHM=`) and now says so on
+stderr. A file's bytes are `base64 --file logo.png` — crust's only binary-safe
+route, because a pipeline decodes UTF-8 on the way (`read logo.png | base64`
+gives `77+9…` for a PNG whose real answer is `iVBORw0…`) — and `--out <path>` is
+how the answer reaches a file, since a function stage cannot be redirected.
+
+A **registered function** with a redirect is refused as a stage, and pointed at
+a shell tail:
+
+```
+sql "select 1" > one.txt
+  → crust: `> one.txt`: crust has no redirect except on a shell stage, whose
+    text goes to sh as-is — a sql stage would read it as data. to save a
+    pipeline, end the line with a shell stage instead: | cat > one.txt
+```
+
+The refusal also catches a stage the redirect **hides**. Stage patterns match the
+whole text, so `range(1,3) > f` stopped matching as a `range` and fell through to
+`sh -c`, where sh's own syntax error answered at exit 2 (and `parallel 5 > f`
+ran GNU parallel and exited 0 with an empty file). crust strips the tail, sees
+the stage, and refuses. Affected: `range`, `capture`, `parallel`, `expect`,
+`stats`, `stdin`, and `load` — where the tail used to break load's parser first
+and the complaint was about the rate plan. `grep` is the exception: its redirect
+is the shell's and works, so `read **/*.log | grep ERROR > errors.txt` is a
+supported way to save a filtered log.
+
+```crust
+base64 hello | cat > out.b64
+base64 --file logo.png --out logo.b64
+base64 --file logo.b64 -d --out logo-copy.png
+```
+
+A **tool builtin** is refused as a program, and the message prints the exact
+whole-invocation redirect that works:
+
+```
+verify-web-links --base-url https://example.com --json > report.json
+  → crust: verify-web-links is a crust builtin, it runs in-process and cannot
+    redirect. Redirect the whole invocation instead:
+    crust -c 'verify-web-links --base-url https://example.com --json' > report.json
+```
+
+```bash
+crust -c 'verify-web-links --base-url https://example.com --json' > report.json
+```
+
+Tools that produce a file themselves have a flag for it (`-o` / `--outfile` /
+`--report`); check that before reaching for `>`.

package/skills/crust-cli/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: crust-cli
+description: How to invoke crust and read its answer — the run modes (`-c`, script file, piped stdin, REPL, tool subcommands like `crust skills install`), what each exit code actually means (0/1/2/127/130, and why there is no 124), `--check` as a linter including what it cannot catch, `--env-file` vs `dotenv` vs `export`, the REPL's verified keybindings and Ctrl-C semantics, and where crust's globals (`GET`, `range`, `parallel`, `crust.fn`) do and do not exist. Use when a crust run's exit code is confusing, when a CI step passes on a failing line, when `--check` says ok but the line dies, when `GET is not defined` appears in a `.ts` file, or when driving the REPL from a script.
+---
+
+# Running crust, and reading what it says back
+
+## Run modes
+
+| Invocation | What happens |
+| --- | --- |
+| `crust` (stdin is a TTY) | Interactive REPL. |
+| `crust` (stdin is piped) | Reads **lines of crust** from stdin to EOF and runs them like a script (fail-fast, same exit codes). stdin is the *command* source in this mode, so a shell stage inside those lines sees EOF. Want data on stdin? Use `-c`. |
+| `crust run.crust [args…]` | Script mode: blank lines and `#` comments are skipped (so a `#!/usr/bin/env crust` shebang works), lines run in order, and it **fails fast** — the first failing line stops the file and becomes the process exit code. A line ending in `\` continues on the next. The extension doesn't matter. Extra arguments are the script's **positional arguments** — `$0` is the path, `$1`…`$9` the rest, `$#` the count, `$@`/`$*` all of them joined — expanding wherever an env var does (URLs, JSON literals, `-H` strings, fn args, `stats --out`), and empty, never literal, outside script mode. A leading `--` after the path is a separator, not an argument. An unreadable path is 127. |
+| `crust -c '<line>'` | One line. A shell stage inherits the process stdin, so `docker logs app \| crust -c 'grep ERROR'` really does grep the logs. To feed a **crust** pipeline, name the source: `docker logs -f app \| crust -c 'stdin \| grep ERROR'`. To run several lines, put a **newline inside the one argument** — they then behave like a script (fail-fast) — or continue one line with a trailing `\`. Two lines as two arguments is refused. Quote the whole pipeline: `-c range(1,2) extra` splits into three argv words and is refused. |
+| `crust <tool> [args…]` | A **tool builtin as a subcommand**: `crust skills install`, `crust mock-server openapi.yaml -p4000`, `crust test-fixture 'fixtures/*.crust.ts' -j8`. Same flags as the REPL line, and `crust <tool> --help` prints them. The names that work are the ones needing no live session: `skills`, `test-fixture`, `test-pipes`, `gen-fixtures`, `mock-server`, `verify-web-links`. The **session** builtins (`cd`, `export`, `alias`, `unalias`, `source`, `dotenv`, `exit`, `help`, `history`) are refused rather than silently doing nothing — a one-shot process has no session to change. `logs` is refused too, for a different reason: its argument is the rest of the line **verbatim** (a `procs({...})` literal), which argv cannot carry. Each refusal exits 2 and names the builtin, instead of the `cannot read cd` a fallthrough to script mode produced. A file that exists wins when it is the only argument, so `crust skills` runs `./skills`; any extra argument selects the tool. |
+| `crust --check '<line>'` | Parse without running. See below. |
+| `crust --env-file <path> …` | Loads `.env` before *any* run mode and before `init.ts`. The "loaded" note goes to stderr so a `-c` pipeline's stdout stays clean. A missing file exits **2, loudly** — this flag exists to replace shell shims that failed silently. Does not combine with `--check`. |
+| `crust -h` / `-V` | Usage / version, exit 0. |
+
+## Exit codes (measured against the binary, not guessed)
+
+| Code | Meaning | Examples |
+| --- | --- | --- |
+| 0 | Success. | `range(1,2)` |
+| 1 | **crust** failed. Every error crust itself raises. | `assert` mismatch, a lambda that throws, `expect 200` vs a 500, `wait: <target> not ready after Ns`, a `GET` that can't connect, `read` on a missing file, a refused empty stage (`echo a \|\| echo b`), a builtin name that reached sh. |
+| 2 | Invocation or syntax error — nothing ran. | `crust --nonsense`, `--check` with no line, `--env-file` on a missing file, `-c` given two lines, `mock-server --bogus` (prints the valid flags), sh's own parse errors on a pure-shell line (`bundle(5)`) — and the same parse error on any shell stage of a **mixed** line (named; before this a bad stage N surfaced only when its child exited, after stages 1..N-1 had run). |
+| the stage's own | A shell stage's exit code, propagated. | `range(1,3) \| sh -c "exit 9"` → 9 |
+| 127 | Command not found (shell stage), or an unreadable script file. | `nosuchbinary-xyz` |
+| 130 / 143 | crust killed by SIGINT / SIGTERM. | Ctrl-C during a long `-c` run |
+
+**A builtin name is not a missing binary.** `crust verify-web-links` with no
+arguments exits **2** with the tool's own usage, and `crust skills install
+--bogus` exits **2** naming the valid flags. 127 means a *script path* could not
+be read, or sh could not find a command — if a builtin name produces 127, the
+binary really is an older one that treated every positional as a path.
+
+**There is no crust exit 124.** `wait` timing out is exit **1** with
+`crust: wait: <target> not ready after Ns`. If a probe reports 124, then
+`timeout(1)` — your harness — killed crust. Give `wait`/`load`/`procs` probes a
+generous outer timeout, and when testing cancellation signal the real bun PID.
+
+A **bare `wait :3000` probes `/`**, and readiness means a **2xx** — a mock server
+or an API with no root route 404s forever, so the line fails after the full
+timeout on a server that is perfectly up. Use a real health path (`wait
+:3000/health`) or `wait port:3000` for a TCP connect; crust says so in the
+failure message now, because "not ready" alone reads like a slow boot.
+
+### The last command wins (the one CI trap here)
+
+A line made **entirely of shell stages** is handed to sh as one `sh -c` string,
+so its code is the **last** command's — no `pipefail`:
+
+```bash
+ls /nope | wc -l      # 0 — wc succeeded
+ls /nope              # 2
+```
+
+The moment a line contains a crust stage, crust owns the exit code and a
+failing shell stage propagates. So a gate must **end on a crust stage**:
+
+```crust
+# a run.crust: blanks and `#` are skipped, lines run in order, first failure stops the file
+wait :3000/health
+range(1,99) | parallel 10 | GET http://localhost:3000/items | expect 200 | stats
+GET http://localhost:3000/items | assert (x => x.length > 0)
+# a trailing `\` continues the line — in a script, in piped stdin, in a
+# multi-line -c, or at the REPL (where an unbalanced quote or ( continues too)
+load 10s 100/s | parallel 20 | GET http://localhost:3000/items \
+  | expect 200 | stats
+```
+
+Or ask sh to gate, explicitly:
+
+```bash
+sh -c 'set -o pipefail; ls /nope | wc -l'   # 2 — would be 0 without pipefail
+```
+
+## `--check`: the linter, and its edges
+
+`crust --check '<line>'` exits **0** if every line parses, **1** with the error
+otherwise (`ok: N line(s) parse`). It splits on newlines and skips blank and
+`#` lines, so a whole fenced block goes in as one argument. It checks three
+things: crust's own grammar, a builtin-head line against **that CLI's flag
+spec**, and every shell stage through `sh -n` (noexec — `cat > f` under `-n`
+does not create `f`).
+
+```bash
+crust --check 'read /nonexistent/*.json | POST :3000/x'   # ok — sources are lazy
+```
+
+```
+crust: shell stage does not parse (stage: head -(): sh: -c: line 1: syntax error near unexpected token `(`
+  in: range(1,3) | head -(
+```
+
+The runtime runs the same preflight before executing any stage of a **mixed**
+line, so a shell stage that does not parse exits 2 with this message and
+nothing has run (measured pre-fix: `touch f | base64 | head -(` exited 2 and
+`f` existed). A pure-shell line is one `sh -c`, which sh parses the whole line
+for before executing anything, so its own stderr stays the answer there — and
+127 (command not found) is a runtime error the preflight cannot see.
+
+What it does **not** check: anything needing I/O or a live process — a missing
+fixture path, an unreachable URL, a wrong `output` matcher key, a semantic
+refusal at runtime (`--env-file` + `--check` is refused for exactly this
+reason). "Checks clean" means *parses*, never *will pass*.
+
+## Environment
+
+| How | Scope | Reaches sh stages? |
+| --- | --- | --- |
+| `crust --env-file <path> …` | one process, before `init.ts` | yes |
+| `dotenv <path>` / `dotenv --append` / `dotenv status` / `dotenv clear` | the session | yes |
+| `export FOO=bar` | the session | yes |
+| a bare `FOO=bar` line | the session — the same code as `export`, including `+=` | yes |
+| `capture NAME` stage | writes `process.env.NAME` from the stream, for **later lines** | yes |
+
+## The REPL
+
+Verified in a real pty, not read off the source:
+
+- **Editing:** `Ctrl-A` / `Ctrl-E` home/end, arrow keys move (and `Home`/`End`/
+  `Delete`), `Ctrl-K` kill to end, `Ctrl-U` kill to start, `Ctrl-W` kill
+  previous word, `Ctrl-L` repaint (the buffer survives), `Backspace`, `Tab`
+  completes.
+- **Tab** completes a **path** mid-stage (`ls sr` + Tab → `ls src/`) and lists
+  names from `$PATH` at the start of a stage. It does **not** know crust's own
+  builtins or registered functions — `verify-web-` + Tab lists nothing useful.
+- **History:** up/down arrows. It is plain text at
+  `$XDG_DATA_HOME/crust/history` (default `~/.local/share/crust/history`), it
+  survives restarts, `history` prints it numbered, and re-running a recalled
+  line does not append a duplicate.
+- **`Ctrl-R`** searches that history as you type: a `(crust-search):` line opens
+  below the one you are editing, showing the newest entry containing your query;
+  another `Ctrl-R` steps further back, `Backspace` shortens the query. `Enter`
+  **accepts** — the match lands on the prompt line, editable, and the **next**
+  `Enter` runs it (so a search at a `…` continuation prompt cannot lose the
+  pending line). `Ctrl-G` / `Esc` / `Ctrl-C` cancel and restore the draft
+  byte-exact; `Ctrl-C` mid-search does **not** clear the line. No match paints
+  `-- no match --` and `Enter` inserts the query as text — it never runs
+  nothing, and it never rewrites the history file.
+- **`Ctrl-C`** at the prompt just clears the line. Mid-run it **cancels**:
+  children are killed, the line reports 130, and the prompt comes back so the
+  session continues. One item already produced by the source can still print
+  after the prompt redraws — cosmetic; the source is stopped.
+- **`Ctrl-D`** (or `exit`) leaves; the exit code is 0 unless `exit <code>`.
+- **`Ctrl-Z`** suspends what the line is waiting on — a crust pipeline, a
+  builtin, a `fg`/`wait` — as a job: SIGSTOP, `[2]+  Stopped    sleep 12`, prompt
+  back, `bg` resumes a suspended pipeline as one unit. During a **foreground
+  inherit-stdio child** it does nothing at all (see Job control below).
+
+## Job control
+
+`cmd &` is crust's own background job: its own process group (so a signal
+reaches a forking `sh`'s whole tree), stdin `/dev/null`, output still on the
+terminal, and it **outlives crust**. `%1` / `%` / `%+` name jobs; a bare number
+names a job to `fg`/`bg`/`jobs` and a **PID** to `kill`.
+
+| Line | What it does |
+| --- | --- |
+| `jobs`, `jobs -l` | the table; `-l` adds `(pid …)` and the code once there is one; an unknown option is refused, not ignored |
+| `fg [spec]` | resume (if stopped) and **wait**; the job's own code becomes the line's |
+| `bg [spec]` | resume a stopped job; an error if it was not stopped |
+| `wait %1` | the job wait — **bare `wait` is the readiness stage**, `wait :3000/health` |
+| `kill %1`, `kill -9 %1` | prints `Sent SIGTERM to job 1 (pid …)` — the send, not the death. `kill -9 4242` is sh's |
+
+Statuses are `Running`, `Stopped`, `Done`, `Exit N`, `Terminated` (128+signal),
+`Failed` (gone with no code — never a silent pass). Finished jobs stay listed for
+the session, which is how `wait %1` still reports the code of a job that ended
+minutes ago. `Ctrl-C` during `fg`/`wait` kills the job and returns 130.
+
+SIGSTOP, never SIGTSTP: Bun's runtime ignores SIGTSTP and a child it spawns
+inherits that ignore across `exec`, so **Ctrl-Z cannot stop a foreground
+inherit-stdio child** (`vim`, a bare `sleep 20`) — the `^Z` echoes and the child
+keeps running; Ctrl-C is the escape (child dies, line 130). Running jobs are left
+alone at exit because outliving the session is what `&` means; **stopped** ones are
+resumed with a notice, since SIGSTOP survives reparenting and no shell resumes a
+process it did not stop.
+Driving it non-interactively: crust checks for a TTY, so pipe bytes through
+`script` and pace them — `{ printf 'range(1,3)\n'; sleep 1; printf '\004'; } |
+script -qec 'crust' /dev/null`.
+
+## Where crust's globals exist
+
+`GET`, `range`, `parallel`, `load`, `procs`, `$`, `crust.*` and everything you
+define in `init.ts` are globals **wherever crust starts its runtime**: the REPL,
+`-c`, piped stdin, a script file, `~/.config/crust/init.ts`, and any `.ts`/`.js`
+file crust imports (`source hooks/warmup.ts` — inside it, `load` and `parallel`
+are just there). A file run by plain `bun script.ts` never starts crust, so
+those names are `undefined` there; import what you need from the modules
+(`../src/sinks` today) or run the file under crust instead.
+
+## Auto-discovered stages
+
+crust scans your **global bun install** at startup and turns opted-in packages
+into pipeline stages — no `init.ts` entry needed.
+
+- Reads `$CRUST_GLOBAL_PREFIX/package.json` (default `~/.bun/install/global`) and
+  inspects its dependencies. A package with a `bin` field and **no** `crust`
+  field is skipped, so it keeps working as a plain shell command; add
+  `"crust": { … }` and it becomes a stage *as well as* a command.
+- `package.json` → `"crust": { "stage": "default" }` (or a named export) picks
+  which export becomes the stage; otherwise the default export, or the sole
+  function export. The stage is called `fn(item, ...args)` like any registered
+  function, so it works as a source *and* mid-pipeline.
+- Scoped packages are exposed after the `/` (`@me/shout` → `shout`). A name
+  already registered (by `crust.fn` in `init.ts`) wins — discovery never
+  overwrites explicit config.
+- The scan is cached at `$CRUST_CACHE_DIR/globals.json` (default
+  `~/.cache/crust`) keyed on the prefix `package.json` mtime; delete that file
+  after changing the install by hand.
+- `CRUST_DEBUG=1` prints every decision: `skipping "x" — has bin field`,
+  `failed to inspect …`, `name collision on …`. That's where to look when a
+  package you expected just isn't a stage.

package/skills/crust-load-testing/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: crust-load-testing
+description: Load-test and soak-test HTTP services with crust — the load rate source, parallel workers, timed verbs, stats windows, CI threshold gates via assert, and baseline comparison with stats --out. Use for smoke-load, latency percentiles, rps checks, performance regression gates in CI, or "is this endpoint fast/degrading" questions.
+---
+
+# crust load testing
+
+One line gives you a paced load run with real percentiles and a CI-ready
+exit code. Tick pacing batches due slots per wakeup, so the generator
+sustains 5000+ ticks/s — your real ceiling is downstream (`parallel` pool ×
+service time). Single-process smoke-load and soak tooling, not a
+distributed rig.
+
+## The shapes
+
+```crust
+# fixed volume: N requests, K at a time
+range(0, 999) | parallel 50 | GET :3000/health | expect 200 | stats
+
+# paced: arrival RATE for a DURATION (load 30s 100/s), concurrency capped by parallel
+load 30s 100/s | parallel 50 | GET :3000/health | expect 200 | stats
+
+# ramp: comma-separated phases, one stats stream across all of them
+load 10s 50/s, 30s 200/s | parallel 100 | GET :3000/health | stats --every 5
+
+# POST load: ticks are {n, phase, scheduledAt, lagMs} — build bodies from them
+load 10s 20/s | (t => ({name: "user" + t.n})) | parallel 8 | POST :3000/users | expect 2xx | stats
+```
+
+> **Report availability:** `expect` throws at drain, so an `expect` placed
+> BEFORE `stats` that fails prevents the summary from ever being emitted
+> (the first two shapes above are illustrative of syntax, not of CI
+> reporting). When the summary/report must survive a status failure, put
+> `stats` (and `stats --out report.json`) before the gates and gate status
+> on the summary instead — see CI gates below.
+
+- `parallel` puts ANY http verb in load mode: output is `{status, ms, url}`
+  timing records, bodies drained, network errors become `status: 0` records
+  (they show in the histogram instead of killing the run). So a run whose
+  every request was refused prints `{"status":{"0":40}}` and still exits 0
+  unless a gate is present — `expect 200` over a dead port exits 1. `stats`
+  reports, it does not gate.
+- **Completion ≠ success — three separate outcomes:** the run *completed*
+  (exit 0, no fatal stage error), *request correctness passed* (explicit
+  gates accepted the outcomes), *performance passed* (latency/throughput
+  thresholds held). A gate that only checks latency can be satisfied by fast
+  error responses — a 500 in 2ms is under any p95 budget. Latency-only
+  examples are NOT the definition of a passing load test; gate status too.
+- The summary carries failure tallies `timedOut` and `redirectRefused`
+  (always present, 0 on a clean run): a `--timeout` budget hit or a
+  `--redirect error` refusal is a `{status: 0, timedOut/redirectRefused:
+  true}` RECORD, not a failure exit. Gate them — `expect 200` (status 0
+  fails it) or `stats | assert (s => s.redirectRefused === 0)`; exit 0
+  alone is never request success in load mode.
+- Rate (`load`) and concurrency (`parallel N`) are independent knobs.
+  Little's law sizes the pool: `N ≥ rate × p99-in-seconds`.
+- Durations `ms|s|m`; rates `N/s` or `N/m`, decimals allowed.
+
+Canonical, version-pinned result-shape table: https://lariocpt.github.io/crust-website/docs/http-result-shapes/.
+
+## Honesty guarantees (read before quoting numbers)
+
+- A gate that measured NOTHING fails: `stats` over an empty stream is tagged
+  `empty: true` and `assert` refuses it. `{count: 0, p95: 0}` used to satisfy
+  `s => s.p95 < 200`, so a run that issued zero requests reported success.
+- Percentiles are bucketed (0.1ms below 100ms, 1ms below 1s) and report the
+  bucket's upper bound — never faster than reality. `count` and `meanMs` are
+  exact. Memory is constant, so a multi-hour soak is safe.
+
+- `stats.rps` is MEASURED, never the target. If downstream saturates, stale
+  slots are skipped (never burst) and reported on stderr:
+  `load: target 3000 ticks — emitted 2868, dropped 132 … achieved 95.6/s`.
+  A drop report means the target rate was NOT sustained — raise `parallel N`
+  or lower the rate before quoting percentiles.
+- Percentiles come only from timed records; they include body download (a
+  route that drips its body over 100ms reports p50 102, not 0.4).
+- With `--every`, a slow request lands in the window it FINISHED in — and
+  because stats waits for a completion before it can flush, a window's
+  `wallMs` can exceed N (measured: `--every 2` → window 1 `wallMs: 3006`).
+- `--out` takes `.json` only — any other extension is a loud error, never a
+  text file written under a json-looking name.
+
+## CI gates — thresholds are assert composition
+
+The primary shape gates **status first, then performance**, with `stats`
+(and the report) upstream of every gate so the summary survives a failing
+gate. When failure artifacts must survive request-status failures, collect
+statistics and write the report BEFORE applying aggregate gates:
+
+```crust
+load 30s 100/s | parallel 50 | GET :3000/health | stats --out load/last.json | assert (s => Object.keys(s.status).every(k => k.startsWith("2"))) | assert (s => s.timedOut === 0) | assert (s => s.redirectRefused === 0) | assert (s => s.p95 < 200) | assert (s => s.rps > 80)
+```
+
+One assert per threshold: the failure names the predicate and prints the
+actual summary, and the line exits 1 (`crust -c` stops there). The gates
+above cover all four things a load gate must mean: every response was 2xx
+(a fast 500 is not a pass), no timeout or redirect-refusal records, the
+latency budget held, and the achieved rate held. An empty run is refused by
+`assert` itself (`empty: true`), so "measured nothing" never passes.
+`rps` is the ACHIEVED rate — if the target was not sustained, stderr already
+said so (`emitted … dropped … achieved …`); a drop report means the number
+below the rate gate is the honest one.
+
+Baseline gate — `--out` writes a versioned artifact
+(`{crustStats: 1, startedAt, urls, summary, windows?}`), an async assert
+reads it back:
+
+```crust
+load 10s 100/s | parallel 50 | GET :3000/health | stats --out load/last.json | assert (async s => { const b = await Bun.file("load/baseline.json").json(); return s.p95 < 2 * b.summary.p95 })
+```
+
+The artifact is written BEFORE the gate runs, so a failed gate still leaves
+the file for CI upload.
+
+Soak with fail-fast windows (`--every N` emits `{window: k, …}` deltas then
+`{final: true, …}`; a bare predicate gates every one of them):
+
+```crust
+load 60s 25/s | parallel 25 | GET :3000/health | stats --every 5 | assert (s => !s.window || s.p95 < 400)
+```
+
+Guard `!s.window ||` scopes a threshold to window objects, `!s.final ||` to
+the final summary — and a guard needs the object it guards. Without `--every`
+the plain summary carries neither key, so `!s.window` is true and `||`
+short-circuits: the threshold never runs. `stats | assert (s => !s.window ||
+s.p95 < 0.1)` exits 0 with p95 at 4.2. Drop the guard when you drop `--every`.
+
+## Warmup
+
+A separate line in the same script — its stats simply aren't gated:
+
+```crust
+range(0, 99) | parallel 10 | GET :3000/health | stats
+load 30s 100/s | parallel 50 | GET :3000/health | stats | assert (s => s.p95 < 200)
+```
+
+## TS API equivalent
+
+The same surface as globals inside `init.ts` (and crust-run config code) —
+`load`, `parallel`, `timedGet`, `timedHttpItem`, `statsStage`, `Pipeline`:
+
+```ts
+const out = await load([{ durMs: 10_000, rps: 100 }])
+  .pipe(parallel(50, timedGet("http://localhost:3000/health")))
+  .pipe(statsStage(undefined, "load/last.json"))
+  .collect();
+```
+
+`timedHttpItem(method, url, opts?)` is the any-verb per-item timer when you
+need POST bodies from upstream items.
+
+## Version and evidence
+
+Behavior here was verified against **crust v0.3.5** — summary schema
+(`{count, wallMs, rps, status, timedOut, redirectRefused, p50, p95, p99,
+meanMs}`, `empty: true` on a zero-request run) and the `--out`-before-gates
+write order are source-verified; throughput claims (5000+ ticks/s) are
+single-process measurements on the author's hardware — environment-dependent,
+not a promise. Pick the lightest correct layer for the job (see the
+crust-api-testing skill's shared principle), and keep approved targets and
+execution restrictions in repository policy, not in this skill.