@lariocpt/crust-mongo 0.0.0-stage → 0.3.5

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,123 @@
+---
+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
+```
+
+- `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.
+- 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.
+
+## 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
+
+```crust
+load 30s 100/s | parallel 50 | GET :3000/health | stats | 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).
+
+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.

package/skills/crust-logs/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: crust-logs
+description: Search a live log stream with crust's `logs` session — it holds a tail/procs/shell source open, keeps a ring buffer, and re-runs every typed pipeline fragment over the buffered past and then the live stream; `json on` parses NDJSON at query time, `search` counts the buffer instantly, `buffer N` resizes without restarting. Use when tailing dev services or containers, when a grep workflow keeps losing history, or when you want to widen a filter over logs you already saw.
+---
+
+# crust logs
+
+## What it is
+
+`logs <source>` keeps the source open and a ring buffer (default 10,000 items)
+behind it, so one query can look at the PAST you already streamed and stay
+attached to the live firehose. Every line you type at `logs>` is an ordinary
+crust pipeline fragment — the whole shell grammar is the query language.
+
+```crust
+logs tail -n 0 -F app.log
+logs procs({web: "bun run dev", api: "bun api.ts"})
+logs docker logs -f my-container
+logs --buffer 50000 tail -F big.log
+```
+
+Boot prints what it holds: `logs: tail -n 0 -F app.log — buffering last 10000
+items (`help` for commands, `exit` to leave)`.
+
+## A fragment runs TWICE
+
+Once over the buffer snapshot, then over the live stream until Ctrl-C, past a
+`-- live --` marker. So side effects fire twice: append with `>>`, never `>`,
+and a `POST` fragment re-sends buffered matches.
+
+- **Ctrl-C once** ends the live view *gracefully* — the stream finishes, so
+  terminal stages flush (a query ending in `stats` prints its summary right
+  then; `wc -l` prints its count). **Ctrl-C twice** hard-cancels a stuck query.
+  The session survives both.
+- A query that fails on the retro pass prints its error and re-prompts. Errors
+  never kill the session or the held source.
+
+## Session commands
+
+| command | what it does |
+| --- | --- |
+| `search <text>` | fixed substring over the BUFFER only — matches highlighted, and a count that always prints, zero included (`search: 5 matching item(s) of 36 buffered`). No live view, no Ctrl-C. For regex/case-folding/live, run a `grep` query |
+| `json on` / `json off` | parse string items at QUERY time (see below) |
+| `buffer` / `buffer N` | report usage (`buffer: 57/10000 items (pushed 57, evicted 0)`) or resize live, newest kept — widen a too-small window without losing the held source |
+| `clear` | empty the buffer (`buffer cleared`) |
+| `help` | the command list, including the double-run note |
+| `exit` / Ctrl-D | tear the source down and leave (procs get SIGTERM→SIGKILL) |
+
+Query errors print and re-prompt; up-arrow recalls earlier queries.
+
+## json on — and the silent zero it prevents
+
+With `json off` (the default) items are the raw strings. A lambda that reads
+fields therefore matches NOTHING, quietly: 50 buffered NDJSON lines, and
+`filter (e => e.level >= 30) | wc -l` reported `0`. `json on` fixes that at
+query time: a string item parsing to a JSON **object or array** reaches your
+lambdas parsed; plain text, strings that parse to primitives (`"42"` stays a
+string), and non-string items flow through unchanged and are counted out loud.
+The ring stores raw items, so `json off` is a lossless revert.
+
+When the buffer looks like NDJSON the session prints, once, on your first
+*pipeline fragment* (not on `help` or `search`):
+
+```
+hint: buffer looks like NDJSON — `json on` parses object lines at query time (`json off` reverts)
+```
+
+It never auto-enables — changing the item type under a lambda you already typed
+would be a false picture.
+
+## Item types by source
+
+- `tail`/shell sources: plain **strings**.
+- `procs({...})`: `{proc, stream, line}` **objects** — the session tells you so
+  at boot (`logs: items are {proc, stream, line} objects — try (l => l.line) or
+  filter (l => l.proc === "web")`). `(l => l.line)` extracts text,
+  `filter (l => l.proc === "web")` selects one process, and `search` still works
+  (it matches each item's rendered form).
+- Pretty-printing is just another stage: `grep api_request | pino-pretty
+  --colorize --singleLine` (`--colorize` forces ANSI through the pipe; local
+  `node_modules/.bin` is on PATH). Normalize `procs` objects first.
+
+## Traps
+
+- `logs` is interactive-only. No tty → exit 2 and a pointer:
+  `logs: interactive session needs a tty — for piped data use `cmd | crust -c 'stdin | …'``.
+  For piped data there is no session — build the pipeline directly.
+- The `logs` line owns its line: `logs tail -F app.log | grep ERROR` refuses
+  (`logs is a crust builtin — it runs in-process, so sh cannot run it`) rather
+  than letting sh report `command not found`. Type the filter at `logs>`.
+- A gate query (`count 1`, `expect 200`) runs against the BUFFER first — a
+  retro failure prints before a single live item arrives. That is the honest
+  order, but it means `logs`+gate reflects history, not just what follows.
+- `search` is buffer-only and fixed-substring: it never sees live items and
+  never interprets regex.
+- Ctrl-C at an idle `logs>` prompt is nothing: it prints `^C` and re-prompts,
+  the source keeps running. `exit` (or Ctrl-D) is the teardown — verified with a
+  `procs` source, including after a Ctrl-C: the group gets SIGTERM→SIGKILL and
+  no `sleep` survives the session.

package/skills/crust-mcp/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: crust-mcp
+description: Drive crust directly from an MCP-capable agent (OpenCode, Claude Code, Codex, Cursor) instead of a shell — `crust mcp` exposes every capability as a first-class tool: run_line, check_line, test_fixture/test_pipes, gen_fixtures, load_run, verify_web_links, plus lifecycle mock servers, supervised procs, and buffered log sessions that stay open across calls. Use when configuring crust as an MCP server, choosing which crust_* tool fits a task, or reasoning about what persists between tool calls and what does not.
+---
+
+# crust over MCP
+
+`crust mcp` speaks JSON-RPC 2.0 over stdio — one message per line. It is a
+whole-process MODE, not a REPL builtin: the MCP host owns stdin and stdout.
+
+## Install & configure
+
+`crust` must be on PATH (either channel works — same binary):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/lariocpt/crust/main/install.sh | bash
+# or: npm i -g @lariocpt/crust
+```
+
+Then register it with the agent host — e.g. OpenCode / Claude Code style:
+
+```json
+{ "mcpServers": { "crust": { "command": "crust", "args": ["mcp"] } } }
+```
+
+VS Code uses a DIFFERENT schema in `.vscode/mcp.json` (workspace) or the
+user-level MCP settings — the `mcpServers` shape above silently fails there
+("command is required" or the server just never appears):
+
+```json
+{
+  "servers": {
+    "crust": { "type": "stdio", "command": "/home/user/.local/bin/crust", "args": ["mcp"] }
+  }
+}
+```
+
+Two traps, both verified: (1) `"command"` must be the ABSOLUTE path — a
+GUI-launched VS Code does not inherit the shell's PATH, so bare `"crust"`
+dies `spawn crust ENOENT` if the launcher lives outside the default
+lookup dirs; (2) VS Code's MCP support ships inside the Chat/Copilot Chat
+extension — Code - OSS / VSCodium has no MCP host without an extension
+(Cline, Roo Code or Continue each carry their own MCP settings).
+
+Grammar lands automatically: the one-shot tools pass line/fixture text to a
+fresh crust child untouched, so anything the lexer accepts (`--redirect`,
+new builtins) is an MCP tool call the moment the installed binary has it —
+no MCP-side change per feature.
+
+Verify by hand — the transport is just lines on stdin:
+
+```bash
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' | crust mcp
+```
+
+## Two execution planes — what persists
+
+| Plane | Tools | State |
+| --- | --- | --- |
+| **One-shot** | `crust_run_line`, `crust_check_line`, `crust_test_fixture`, `crust_test_pipes`, `crust_gen_fixtures`, `crust_verify_web_links`, `crust_load_run` | a fresh crust CHILD per call — `cwd`/`env` apply per call and NEVER carry over; pass them explicitly |
+| **Lifecycle** | `crust_mock_server_start/stop/list/violations`, `crust_procs_start/stop`, `crust_logs_open/query/close` | held IN the server across calls; every held job dies when the server exits |
+
+`crust_run_line` runs ordinary crust grammar — one line, `|`-stages, lambdas:
+
+```crust
+range(1,5) | (n => n * n) | stats
+```
+
+## Honest failure — never a false pass over MCP
+
+A nonzero child exit, a killed timeout, a failed `assert`, a mock validation
+error is an **`isError` result** carrying the verbatim exit code and output.
+Zero matches is answered with an explicit "zero items", never silence. Trust
+`isError`; the text is evidence, not a verdict.
+
+## Picking the right tool
+
+- Validate generated crust first — `crust_check_line` parses without running
+  (files and ports don't need to exist).
+- `crust_procs_start` supervises dev services (env/after/ready/restart per
+  proc). Its stream is queried through `crust_logs_query` — items are
+  `{proc, stream, line}` objects. Gate readiness in a follow-up:
+
+```crust
+wait :3000/health
+```
+
+- `crust_logs_open` holds a tail/shell/`procs({…})` source with a ring buffer;
+  `crust_logs_query` runs a pipeline fragment over the buffered past, then
+  live for `live_ms` — `json: true` parses NDJSON items before the fragment:
+
+```crust
+filter (l => l.proc === "api") | (l => l.line) | grep -i timeout
+```
+
+- `crust_mock_server_start` defaults `port: 0` (OS-assigned) — always take
+  the returned `url`. `proxy: "<upstream>"` turns it into a conformance audit;
+  read findings with `crust_mock_server_violations`.
+- `crust_load_run` composes the documented pipeline (`load … | parallel … |
+  … | stats | assert`); an `assert` failure is `isError` — a run that
+  measured nothing is refused (`empty`), never a green gate.
+
+## Limits, stated
+
+- One tool call runs at a time (the interrupt bus is process-global).
+- Output is tail-capped per stream and truncation is always announced.
+- `crust_procs_stop` reports "teardown still in flight past 10s" honestly
+  when a child ignores SIGTERM — crust kills it on server exit.