@lariocpt/crust-mongo 0.0.0-stage → 0.3.6

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.6",
+  "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,299 @@
+---
+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, gen-fixtures which derives negative-case matrices and CRUD flow suites from an OpenAPI spec, and the evidence-tier taxonomy (snapshot vs DB-verified vs demo). Use for API integration tests, contract tests from a spec, auth/authz negative cases, or DB-verified endpoint tests.
+---
+
+# crust API testing
+
+## The shared principle: the lightest CORRECT layer
+
+Choose the lightest native layer that preserves correctness, observability,
+and safety — not merely the shortest syntax.
+
+- Use `.pipes` for straightforward requests, assertions, and supported request chaining.
+- Use `.crust.ts` when setup, custom matchers, or required safety controls cannot be expressed in pipes.
+- Use `gen-fixtures` for supported contract-derived cases, followed by review.
+- Use native load pipelines for paced traffic, measurements, and explicit success gates.
+- Do not force a case into pipes when doing so removes a required guarantee.
+- Consult repository-specific execution and credential policies before running examples.
+
+Three layers, one binary:
+
+| 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.
+- Result shapes per execution context (`Response` vs timed `{status, ms, url}`
+  records, body draining, `.json()` availability): canonical table at
+  https://lariocpt.github.io/crust-website/docs/http-result-shapes/.
+- 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`.
+
+## What evidence does your test produce?
+
+**Tier 1 — snapshot / contract verification.** Response vs a declared case +
+supplied snapshot; setup prepares REQUEST CONTEXT (url, headers, expected),
+not state. Never call it "seeded"/"integration" when nothing is seeded or
+verified at the data layer — it proves contract shape + declared oracle.
+
+**Tier 2 — DB-verified flow.** seed → verify the seed → call the API → query
+the DB → compare against the LIVE query result. Native shape:
+
+```crust
+{"email": "u-$RUN_ID@t.dev"} | POST $BASE/api/users -H "authorization: Bearer $TOKEN" | assert (r => r.status === 201) | (r => r.json()) | capture UID (u => u.id)
+sql "SELECT email FROM users WHERE id = '$UID'" | assert (r => r.email === "u-$RUN_ID@t.dev")
+```
+
+Carries: run-owned data (`$RUN_ID` unique per run, set by setup — never
+shared mutable state); explicit identity matching (query the id you
+captured, never an unrelated record); failure-path cleanup defined BEFORE
+writes — a later line is happy-path only; guaranteed teardown is `crust.onExit`.
+
+**Tier 3 — demo / quickstart.** Disposable local resource, ordinary CRUD —
+the built-in mock server is the native fit — isolates "how little glue does
+crust need" from app safeguards (graph resolution, provisioning denial,
+identity-sensitive stores) — separate approved fixture, never folded in.
+
+Cross-cutting: label the tier so a green run cannot imply DB-level proof it
+never produced; approval/redirect/transport safeguards stay regardless of
+tier; setup attestations (flags asserting IAM/graph/provisioning policy) are
+DECLARATIONS, not backend verification.
+
+## 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`).
+When the contract disagrees with the 400 convention (422 backends, 404/403
+concealment), the optional `expectations` block configures correct statuses —
+a documented status always wins over a configured one;
+`docs/USAGE.md §gen-fixtures` has the schema and precedence.
+
+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.
+
+Every generation's LAST write is `<out>/gen-manifest.json`: each case with
+its expectation's provenance (`contract:<spec pointer>` when the spec
+documents the status), each skip, each unsupported op — review it BEFORE
+running. Deterministic (same spec + version → byte-identical); it records
+generation, never execution.
+https://lariocpt.github.io/crust-website/docs/recipes/gen-fixtures/
+
+## Generated cases are candidates, not certified coverage
+
+A generator can derive request mutations from a schema. It cannot universally
+infer backend-specific status codes, error envelopes, authorization
+concealment policies, business preconditions, or cleanup behavior.
+
+For negative tests:
+
+- Begin with an otherwise valid request.
+- Mutate one intended condition.
+- Ensure authentication and resource preconditions allow the request to
+  reach the intended validation layer (a request that dies at auth never
+  proves the validation code).
+- Assert the documented status.
+- Where the contract provides structured error evidence, verify the relevant
+  field, location, or error code.
+- Avoid exact human-readable message matching unless wording is contractual.
+
+A generic error status is insufficient evidence when the request could have
+failed for an unrelated reason. And the generated **400 validation matrix is
+a generator assumption, not a universal API convention** — some contracts
+specify `422` (or another status) for validation failures; when the contract
+disagrees, say so in review and adjust expectations to the CONTRACT, never
+the other way around. Document unsupported assumptions and skipped cases
+rather than silently reducing coverage or normalizing the contract to fit
+generation.
+
+## Contract review before generation
+
+Review the contract BEFORE generating and record the review beside the
+generated output. Record fields (one per line):
+
+```
+API/service:
+Contract path:
+Contract revision:
+Backend revision, if available:
+Crust version:
+Reviewer:
+Review date:
+Generated output directory:
+Intended execution scope:
+Unresolved discrepancies:
+```
+
+Highest-risk checks (full checklist:
+https://lariocpt.github.io/crust-website/docs/contract-review/):
+
+- Expected statuses come from the reviewed contract — validation cases do
+  NOT default to 400 (a 422 contract must generate 422 expectations).
+- Authorization cases account for intentional 404 concealment; unknown-id
+  cases use syntactically valid identifiers.
+- One intended condition per negative case; unrelated fields stay valid so
+  the request reaches the intended validation layer.
+- Dedicated `--out` dir; regeneration cannot touch manual fixtures; never
+  hand-edit generated files.
+- Classify every failure (backend · contract · generator · environment ·
+  incorrect test) BEFORE changing any expectation.
+- Execution is approved separately — target, identity, resource scope,
+  writes, cleanup. This review grants no permission beyond the recorded
+  execution scope.
+
+## Workflow for a new API
+
+1. Identify the authoritative contract and record its version or revision.
+2. Review generation assumptions against that contract: validation status
+   codes; authentication and authorization behavior; error envelopes;
+   resource identifiers; response schemas; CRUD lifecycle support.
+3. Generate into a dedicated output directory (`--out`, default `tests/gen`).
+   Generation DELETES and recreates that directory; never target manually
+   authored sources.
+4. Review generated cases, expected responses, setup requirements, and
+   skipped cases (they are NAMED on stdout) before execution.
+5. Obtain the required target, identity, resource, write, cleanup, and load
+   approvals from repository policy — the skill never grants any of them.
+6. Execute only the approved scope.
+7. Classify failures before changing expectations or implementation:
+   backend defect · contract defect · unsupported generator assumption ·
+   environment/setup failure · incorrect test.
+8. Add manually authored native fixtures or pipelines for unsupported cases.
+   Do not hand-edit generated files (the next regeneration erases the edit).
+9. Record remaining coverage gaps explicitly.
+
+> Never change an expected result solely because the backend returned
+> something different. A passing test must reflect a reviewed contract.
+
+## Version and evidence
+
+Behavior described here was verified against **crust v0.3.5** (source-read
+and run through the compiled binary where it matters: `--redirect` record
+shapes, `output.schema` $ref refusal, gen-fixtures skip reporting). New in
+**v0.3.6**: the `gen-manifest.json` review artifact, the setup-module
+`expectations` block, and the evidence-tier taxonomy. Newer
+crust versions may extend behavior; re-verify before documenting it. Keep
+approved targets, credentials, transport exceptions, resource ownership, and
+execution restrictions in repository policy, not in this skill.