@lariocpt/crust-mongo 0.0.0-stage → 0.3.5

package/lib/skills-prompt.mjs

@@ -0,0 +1,134 @@
+// The "install the agent skills?" question, asked once, right after the binary
+// lands in the cache.
+//
+// WHY HERE. The skills are the difference between an agent that guesses at
+// crust's grammar and one that gets it right on the first try, and a user who
+// installs the package is exactly the moment that decision is live. Asking once,
+// at install, beats documenting the verb in a README nobody re-reads.
+//
+// WHAT IT MUST NEVER DO. Break `npm install`. Every failure mode — no TTY, no
+// binary, spawn refused, user typed noise — resolves to "declined", and the
+// caller keeps exit 0. A postinstall that exits non-zero aborts the whole
+// install, and "I did not want to answer a question" is not a reason to refuse
+// to install a package.
+//
+// The gating is a separate pure function because it is the part with real blast
+// radius: prompt in CI and the build hangs on a question nobody is there to
+// answer; skip the cwd check and the skills land inside node_modules/crust.
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+// Where the skills live. `.agents/skills` is the canonical, cross-client path;
+// `.claude/skills` is where Claude Code looks, and crust keeps a per-skill link
+// there. Both are checked for "already installed" so someone upgrading from a
+// crust that wrote only the Claude path is not asked to start over.
+const SKILLS_SUBDIR = ".agents/skills";
+const OTHER_SKILL_SUBDIRS = [".claude/skills"];
+
+/**
+ * Decide whether to ask, and where "this project" is.
+ *
+ * `INIT_CWD` is the directory `npm`/`bun`/`pnpm` were actually run from; the
+ * process cwd during a lifecycle script is the package directory
+ * (node_modules/crust), which is NOT where a project-scoped skill belongs.
+ */
+export function shouldAsk({
+  env = {},
+  stdinTty = false,
+  stdoutTty = false,
+  dir = env.INIT_CWD,
+} = {}) {
+  if (!stdinTty || !stdoutTty) return { ask: false, reason: "not an interactive terminal" };
+  // A CI runner has no human to answer, and `CI` is set by every mainstream one.
+  if (env.CI) return { ask: false, reason: "CI" };
+  if (env.CRUST_NO_SKILLS) return { ask: false, reason: "CRUST_NO_SKILLS is set" };
+  // A global install has no project to write into; suggest the global verb instead.
+  if (env.npm_config_global === "true" || env.npm_config_global === "1") {
+    return { ask: false, reason: "global install" };
+  }
+  // Nested install (crust pulled in as somebody's dependency): the skills are for
+  // the developer's own agent, not for the package that happens to depend on us.
+  if (!dir || dir.split(path.sep).includes("node_modules")) {
+    return { ask: false, reason: "not run from a project directory" };
+  }
+  if (!existsSync(dir)) return { ask: false, reason: "project directory is gone" };
+  const installedHere = [SKILLS_SUBDIR, ...OTHER_SKILL_SUBDIRS].some((sub) =>
+    hasCrustSkills(path.join(dir, sub)),
+  );
+  if (installedHere) {
+    return { ask: false, reason: "skills already installed" };
+  }
+  return { ask: true, dir };
+}
+
+/** Any `crust-*` skill already on disk counts as "this user has done this". */
+function hasCrustSkills(skillsDir) {
+  let names;
+  try {
+    names = readdirSync(skillsDir);
+  } catch {
+    return false;
+  }
+  return names.some((n) => n.startsWith("crust-"));
+}
+
+/**
+ * Ask, and on yes hand the terminal to `crust skills install` so the picker —
+ * not this script — decides which skills land where.
+ *
+ * stdio is inherited precisely so the picker can take raw mode over the same
+ * terminal. Reading the answer here and then re-reading keystrokes there would
+ * otherwise fight over stdin.
+ */
+export async function askSkills({ bin, env = {}, log = () => {}, cwd = env.INIT_CWD }) {
+  // No binary, no question: the picker lives inside it, and asking something we
+  // cannot act on turns a helpful prompt into a broken one.
+  if (!bin || !existsSync(bin)) return { asked: false, reason: "binary not available yet" };
+  const gate = shouldAsk({
+    env,
+    stdinTty: process.stdin.isTTY === true,
+    stdoutTty: process.stdout.isTTY === true,
+    dir: cwd,
+  });
+  if (!gate.ask) return { asked: false, reason: gate.reason };
+
+  log("");
+  log("crust ships agent skills — the SKILL.md guides Codex, Cursor, Claude Code");
+  log("and OpenCode read to drive crust correctly.");
+  log(`Install them into ${gate.dir}/.agents/skills? [y/N] `);
+
+  const answer = await readAnswer();
+  if (!/^y(es)?$/i.test(answer.trim())) {
+    log("skipped — `crust skills install` does it later (add --global for ~/.agents).");
+    log("to stop being asked: CRUST_NO_SKILLS=1");
+    return { asked: true, installed: false };
+  }
+  const code = await new Promise((resolve) => {
+    const child = spawn(bin, ["skills", "install"], { cwd: gate.dir, stdio: "inherit" });
+    child.on("error", () => resolve(-1));
+    child.on("close", (c) => resolve(c ?? -1));
+  });
+  return { asked: true, installed: code === 0, code };
+}
+
+/** One line from stdin. Resolves empty on EOF so a half-open pipe cannot hang. */
+function readAnswer() {
+  return new Promise((resolve) => {
+    let buf = "";
+    const done = (value) => {
+      process.stdin.off("data", onData);
+      process.stdin.off("end", onEnd);
+      resolve(value);
+    };
+    const onData = (chunk) => {
+      buf += chunk.toString("utf8");
+      const nl = buf.indexOf("\n");
+      if (nl !== -1) done(buf.slice(0, nl));
+    };
+    const onEnd = () => done(buf);
+    process.stdin.on("data", onData);
+    process.stdin.once("end", onEnd);
+    process.stdin.resume();
+  });
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@lariocpt/crust-mongo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.5",
+  "description": "crust with the MongoDB driver bundled — the mongo variant of the crust binary launcher",
+  "type": "module",
+  "license": "MIT",
+  "author": "Lario Borges",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lariocpt/crust.git"
+  },
+  "homepage": "https://lariocpt.github.io/crust-website/",
+  "bugs": "https://github.com/lariocpt/crust/issues",
+  "keywords": [
+    "bun",
+    "devops",
+    "pipeline",
+    "load-testing",
+    "mock-server",
+    "openapi",
+    "testing",
+    "fixtures",
+    "test-generation",
+    "cli",
+    "mongo",
+    "mongodb"
+  ],
+  "bin": {
+    "crust": "./bin/crust"
+  },
+  "crust": {
+    "source": "github",
+    "repo": "lariocpt/crust",
+    "variant": "mongo"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,36 @@
+// crust — npm postinstall.
+//
+// A fast path, not the mechanism. npm 12 blocks install scripts by default, so bin/crust
+// fetches the binary lazily on first use and this script only front-loads that work for
+// environments where scripts still run. All the logic lives in lib/install.mjs so the two
+// entry points cannot drift apart.
+//
+// It must never fail the install. A postinstall that exits non-zero aborts the whole
+// `npm install`, and "you are not on the LAN right now" is not a reason to refuse to install
+// a package whose launcher can recover later.
+import { ensureBinary, installHint } from "../lib/install.mjs";
+import { askSkills } from "../lib/skills-prompt.mjs";
+
+const say = (m) => console.log(`[crust] ${m}`);
+const warn = (m) => console.warn(`[crust] ${m}`);
+
+let manifest = null;
+try {
+  manifest = await ensureBinary({ log: say, warn });
+} catch (e) {
+  warn(e.message);
+  warn("it will be fetched on first run instead.");
+  for (const l of installHint()) warn(l);
+}
+
+// The one question this installer asks. Its own gate keeps it silent on CI, on a
+// non-tty, on a global install, and once the skills are already in place — and a
+// throw here must not take the install down with it, so it is caught rather than
+// trusted.
+try {
+  await askSkills({ bin: manifest?.bin, env: process.env, log: say });
+} catch (e) {
+  warn(`skills prompt skipped: ${e.message}`);
+}
+
+process.exit(0);

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

@@ -0,0 +1,154 @@
+---
+name: crust-api-testing
+description: Test HTTP APIs with crust — .pipes suites (one fixture pipeline per line, request chaining via capture, inline SQL verification), .crust.ts fixtures with setup/matchers, and gen-fixtures which derives negative-case matrices and CRUD flow suites from an OpenAPI spec. Use for API integration tests, contract tests from a spec, auth/authz negative cases, or DB-verified endpoint tests.
+---
+
+# crust API testing
+
+Three layers, one binary. Pick the lightest that fits:
+
+| Layer | File | Best for |
+|---|---|---|
+| `test-pipes` | `.pipes` — one pipeline per line | readable CRUD suites, chaining, SQL cross-checks |
+| `test-fixture` | `.crust.ts` — TS fixture modules | complex setup, matcher functions, stress (`-n`) |
+| `gen-fixtures` | generated from `openapi.json` | negative matrices + CRUD flows for every documented op |
+
+## .pipes suites (test-pipes)
+
+One shorthand pipeline per line; `#` comments; lines run sequentially per
+file. `capture` chains requests; `sql` verifies the database inline:
+
+```crust
+{"name": "Court", "floors": 3} | POST $BASE/api/buildings -H "authorization: Bearer $TOKEN" | assert (r => r.status === 201) | (r => r.json()) | capture BID (b => b.building.id)
+GET $BASE/api/buildings/$BID -H "authorization: Bearer $TOKEN" | expect 200
+sql "SELECT count(*)::int AS c FROM buildings WHERE name = 'Court'" | assert (r => r.c === 1)
+DELETE $BASE/api/buildings/$BID -H "authorization: Bearer $TOKEN" | expect 204
+GET $BASE/api/buildings/$BID -H "authorization: Bearer $TOKEN" | expect 404
+```
+
+Run: `test-pipes 'tests/**/*.pipes' [-b] [-t ms] [-s mod.ts] [-o report.xml]`.
+PASS/FAIL report lines are prefixed `file:LINE` with real file line numbers.
+`-o`'s extension picks the format: `.xml` is JUnit (testcase per line),
+`.json` the raw report — both CI-ingestable. Any other extension (or none)
+writes the same text report stdout shows; the file never changes the exit code.
+
+- **Setup module**: `-s mod.ts`, else sibling `<name>.setup.ts`; its
+  default export is awaited before the file and seeds `process.env`
+  ($BASE/$TOKEN). `sql` needs `$DATABASE_URL`.
+- **SQL row types**: rows arrive as the driver returns them — uuid and enum
+  columns as strings, but `count(*)` and `numeric` may arrive as
+  strings/bigints. Cast in SQL when comparing numbers
+  (`count(*)::int AS c`), and compare ids as strings.
+- **Hermetic per file**: `process.env` is snapshotted/restored around each
+  file — captures and setup vars never leak across files.
+- Status-check placement: `expect N` when the check ends the line;
+  `assert (r => r.status === N)` when more stages follow (expect only
+  throws at drain).
+- Redirect control: `--redirect error|manual|follow` on any http line —
+  `error` refuses a 3xx (a moved endpoint cannot pass by landing elsewhere;
+  the line fails with `redirect refused (--redirect error)`), `manual`
+  yields the 3xx so `GET … --redirect manual | expect 301` asserts a
+  redirect exists, `follow` is the default. This is the pipe-side twin of a
+  fixture's `input.redirect` — when a pipe cannot express a case, the
+  fixture can, and it has always had this control. In per-item/load position
+  a refusal is a `{status: 0, redirectRefused: true}` RECORD and the line
+  exits 0 — gate with `expect 200` or `stats | assert (s =>
+  s.redirectRefused === 0)`; exit 0 alone is never request success in load
+  mode.
+- Exit codes: 0 all pass · 1 any fail · 2 no files/bad args.
+
+## .crust.ts fixtures (test-fixture)
+
+One fixture = one request. `setup()` returns a ctx; `input` fields that are
+1-arg functions receive it; `output` fields that are 1+-arg functions are
+matchers `(actual, ctx)` — async matchers awaited:
+
+```ts
+export default {
+  name: "creates a user",
+  setup: async () => ({ token: await login() }),
+  input: {
+    url: "http://localhost:3000/api/users",
+    method: "POST",
+    headers: (ctx) => ({ authorization: `Bearer ${ctx.token}` }),
+    body: { name: "x" },
+  },
+  output: {
+    status: 201,
+    data: async (d, ctx) => (await db.userById(d.id)) !== null,
+  },
+};
+```
+
+Run: `test-fixture 'tests/*.crust.ts' -j8 [-n N] [-t ms] [-b] [-o report.xml]`.
+`-o`'s extension picks the format — `.xml` is JUnit for CI: testcase per
+run (stress iterations individually), percentiles in `<system-out>`; `.json` is
+the raw report, `.md` markdown, anything else the text report.
+
+`input.redirect: "error" | "manual" | "follow"` reaches fetch like any other
+`RequestInit` field — the fixture-side twin of the http stage's `--redirect`
+flag. `"error"` fails the fixture with the field named when the upstream
+answers 3xx (a moved endpoint cannot pass by landing elsewhere); `"manual"`
+records the 3xx so `output: { status: 301 }` asserts a redirect exists. Any
+other value is a loud fixture error, not a fetch mystery.
+
+`output.schema`: give it an inline JSON Schema and the response body must
+conform — violations fail with per-field pointer paths. Inline means
+$ref-free: a `$ref` anywhere in the schema is a loud error (the runner has
+no spec to resolve it against — it would otherwise pass silently).
+Unknown schema keywords pass (never-invent-a-violation). gen-fixtures emits
+this automatically when the spec documents a response schema for a case's
+expected status.
+Fixtures may run CONCURRENTLY under -j/--threads — share state only via a
+module-scope promise-cached factory. Fixture files may import ONLY relative
+modules and Bun builtins (the binary can't resolve npm at runtime) —
+`Bun.SQL`, `Bun.file`, `Bun.jwt`.
+
+## gen-fixtures — spec-driven cases
+
+```
+gen-fixtures ./openapi.json [--no-flows]   # --out/--setup default to tests/gen
+```
+
+Emits (deterministic, byte-stable — check the output in, regenerate, review
+the `git diff`):
+
+- **Negative matrix** per op (`<tag>.gen.crust.ts`): 401 no-creds, 403
+  authenticated-outsider (scope-gated paths), 404 unknown-id, and a 400
+  matrix per body field — missing required, wrong type, bad enum, too
+  short/long (minLength/maxLength), below/above numeric bounds, pattern
+  violations, unexpected extra property. Nullable `anyOf` fields unwrapped.
+- **CRUD flows** (`flows/flows.gen.pipes` + sibling setup, run by
+  test-pipes with zero extra flags): create → read (body round-trips the
+  captured id) → update → delete → read-after-delete-404, chained with
+  `capture`, auth via `$GEN_AUTH_HEADER`. SQL assertions are NOT derivable
+  from a spec — add those by hand in your own .pipes.
+
+Setup-module contract (imported lazily): `shared()` promise-cached context,
+`headersFor(ctx, "none"|"member"|"outsider")`, `resolvePath(ctx, template)`,
+`scopeParam`, `scopeRoots?`, `JSON_HEADERS`, and optional
+`flowOverrides: { "<template>": { body?: {...}, skip?: true } }` for creates
+whose values a spec can't express (business date rules → `body` merge;
+required foreign keys → `skip`).
+
+The `--out` dir is DELETED and recreated every run — never hand-edit
+generated files.
+
+What crust cannot attribute it does not emit. The pattern sampler returns a
+knowingly-wrong placeholder for a pattern it cannot read — a lookahead, Python
+`\A`/`\Z` anchors, a JavaScript regex literal written into `pattern` (groups
+it reads: `(?:…)`, `(a|b)`, `(…){n}`, so an AWS id like
+`^(subnet-[0-9a-f]{8}|subnet-[0-9a-f]{17})$` yields `subnet-00000000`); in a
+base body a placeholder makes a case about `name` invalid in `subnetId`, so its
+400 names the wrong field. Those cases — and a CRUD flow
+whose create body cannot be filled — are dropped and NAMED on stdout
+(`gen-fixtures: 2 case(s) skipped for POST /things …`, `skipping flow for
+/things …`). A silently smaller suite would look like coverage.
+
+## Workflow for a new API
+
+1. `gen-fixtures` against the spec → run matrix + flows → fix what fails.
+2. Hand-write `.pipes` for business flows the spec can't express (SQL
+   checks, multi-resource invariants).
+3. Reach for `.crust.ts` only when a case needs real code (crypto, files,
+   custom matchers).

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 `>`.