@lariocpt/crust-mongo 0.0.0-stage → 0.3.5

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# crust
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Mock it, test it, load it, tail it: the whole test stack baked into one
+binary.** Spec-driven, generated, zero dependencies.
+
+Never reports a false pass — a run that measured nothing fails.
+
+An OpenAPI mock server, fixture suites generated from the spec, load gates CI
+can fail on, a process orchestrator, and a link checker — every tool composes
+on the same `|` stream, driven from an interactive REPL, a `crust -c`
+one-liner, a `.crust` script, or as a one-shot command from your shell
+(`crust mock-server openapi.yaml -p 4000`).
+
+```bash
+npm i -g @lariocpt/crust
+```
+
+**Documentation: https://lariocpt.github.io/crust-website/**
+
+Source and issues: https://github.com/lariocpt/crust
+
+## What it looks like
+
+Lines below are parsed against the live grammar on every build, so an example
+that stopped working fails CI rather than misleading you.
+
+**Fixture tests** — `.crust.ts` fixtures with `setup()` context and async
+matchers, JUnit for CI, and `-n/-j` to turn any fixture into a stress run:
+
+```crust
+test-fixture "tests/api/**/*.crust.ts" -j 8 -o reports/api.junit.xml
+test-fixture tests/api/checkout.crust.ts -n 500 -j 32 -o reports/stress.json
+```
+
+**Load testing with a gate CI can trust** — thresholds are `assert`
+composition, and a run that measured nothing is refused rather than passing:
+
+```crust
+load 30s 200/s | parallel 50 | GET :3000/health | expect 200 | stats | assert (s => s.p95 < 250)
+load 10s 50/s, 5m 200/s | parallel 200 | GET $BASE/api/search | stats --every 15 | assert (s => !s.window || s.p99 < 800)
+```
+
+**A persistent mock server from a Swagger/OpenAPI spec** — stateful CRUD
+persisted to sqlite so it survives a restart, seeded from a file, with
+spec-violating requests rejected as 422:
+
+```crust
+mock-server ./openapi.yaml -p 4010 --state ./.crust/mock.sqlite --seed seeds/dev.json --validate
+{"thing": {"name": "x"}} | POST :4010/api/things | expect 201 | (r => r.json()) | capture TID (t => t.thing.id)
+```
+
+Point it at a real API instead and it audits that API's spec conformance:
+
+```crust
+mock-server ./swagger.json -p 4747 --proxy http://localhost:3001 --report violations.ndjson
+```
+
+**SQL assertions, inline** — rows stream one item each, and an empty result
+fails instead of passing quietly. The bind placeholder is `?` for every
+dialect (crust rewrites it to `$n` for Postgres URLs):
+
+```crust
+sql "SELECT count(*)::int AS c FROM buildings WHERE name = 'Court'" | assert (r => r.c === 1)
+sql "SELECT status FROM orders WHERE id = ?" $OID | assert (r => r.status === "paid")
+```
+
+**Pretty logs from every service at once** — `procs` merges stdout and stderr
+into one stream of `{proc, stream, line}` items, so you filter them as objects
+and hand the text to `pino-pretty` (local `node_modules/.bin` is on PATH):
+
+```crust
+procs({api: "bun run dev", worker: "bun run worker", db: "docker compose logs -f postgres"}) | (l => l.line) | pino-pretty --colorize
+procs({api: "bun run dev", worker: "bun run worker"}) | filter (l => l.stream === "stdout") | (l => l.line) | pino-pretty --colorize --minimumLevel warn
+```
+
+**Interactive log querying** — `logs` holds one live stream and lets you iterate
+on filters against its buffered past and live future:
+
+```crust
+logs procs({api: "bun run dev", worker: "bun run worker"})
+logs docker logs -f my-app
+```
+
+At its prompt each line runs over the buffer, then live until Ctrl-C:
+
+```text
+logs> filter (l => l.proc === "api") | (l => l.line) | grep -i timeout
+logs> json on
+logs> filter (e => e.level >= 50) | stats --every 5
+logs> search "connection reset"
+```
+
+## Interactive shell
+
+The REPL continues a line — a trailing `\`, an unbalanced quote, or an unclosed
+`(` holds the line instead of erroring, so pasted multi-line JSON survives the
+Enter. `Ctrl-R` searches history; `&`, `jobs`, `fg`, `bg`, `wait %N`,
+`kill %N` and `Ctrl-Z` are job control. Scripts take positional arguments
+(`$0`, `$1…`, `$#`, `$@`), a bare `FOO=x` line persists for the session, and
+`source` runs `.ts` files, `.crust` scripts, and shell scripts alike.
+
+## MCP server
+
+`crust mcp` speaks the Model Context Protocol over stdio, so an MCP-capable
+agent (OpenCode, Claude Code, Codex, Cursor) drives crust directly — every
+capability is a first-class tool, not a shell to fumble through. One-shot tools
+(`crust_run_line`, `crust_test_fixture`, `crust_load_run`, …) run a fresh crust
+process per call; lifecycle tools keep a mock server, a supervised `procs`
+runner, or a buffered `logs` session open across calls and tear them down
+honestly on exit. A nonzero run is always an `isError` result with the verbatim
+output — never a false pass.
+
+```json
+{ "mcpServers": { "crust": { "command": "crust", "args": ["mcp"] } } }
+```
+
+The `crust-mcp` skill teaches an agent which `crust_*` tool fits which task.
+
+## Agent skills
+
+Crust ships the SKILL.md guides that teach a coding agent how to drive it —
+pipelines, fixture suites, load gates, the mock server, `procs`, the log
+sessions, the link checker, the MCP server — embedded in the binary, so they
+always match the version you run.
+They go into `.agents/skills/`, the cross-client directory Codex, Cursor and
+OpenCode read, plus a link per skill in `.claude/skills/` for Claude Code, the
+one mainstream host that doesn't read the standard path:
+
+```bash
+bunx crust skills install          # on a terminal: pick which ones
+bunx crust skills install --all    # everything, into ./.agents/skills
+bunx crust skills install --select crust-cli,crust-logs
+bunx crust skills install --global # into ~/.agents/skills
+```
+
+The menu lists each skill with its status in the target it would write to
+(`current`, `not installed`, `EDITED locally`) and `g` switches between the
+project and `~/.agents/skills`; declining exits `0`. A `.claude/skills/<name>`
+directory crust did not write is left alone and reported — `--force` consents
+to replacing it with a link.
+
+`npm install` asks once whether to install them. It never asks on CI, with
+piped output, for a global install, or once crust skills are already in the
+project under either path, and it can never fail the install. Answering no
+writes nothing; `CRUST_NO_SKILLS=1` stops the question permanently.
+
+## What this package installs
+
+This package is a ~4 KB launcher, not the binary. On first use it downloads the
+`bun build --compile` executable for your platform from the matching GitHub
+Release, verifies its published sha256 before the file is ever made executable,
+and caches it under `~/.cache/crust`. Every install route resolves that same
+artifact.
+
+What it installed is recorded in `install-manifest.json` next to `package.json`
+(plane, binary version, the package version that asked for it, the cached path
+and its sha256). Every run re-checks that the manifest was written for THIS
+package version on THIS plane: a version bump or a plane switch is a cache
+miss, so the launcher re-resolves, re-verifies the sha256 and rewrites the
+manifest — a stale install never shadows a new release, and no file has to be
+deleted by hand.
+
+Supported platforms: linux x64/arm64, macOS x64/arm64. On anything else, build
+from source — see the repository README.
+
+### Environment variables
+
+| Variable | Effect |
+|---|---|
+| `CRUST_SOURCE` | `github` (default for this package) or `apps` — which artifact plane to resolve from. |
+| `CRUST_GITHUB_REPO` | Override the `owner/repo` the release is fetched from. |
+| `CRUST_APPS_URL` | Base URL of a self-hosted artifact plane, used when `CRUST_SOURCE=apps`. |
+| `CRUST_NO_SKILLS` | Set to any value to stop the postinstall question about installing agent skills. `crust skills install` still works. |
+
+MIT © Lario Borges

package/bin/crust

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// crust — launcher shim.
+//
+// The real binary is a ~91 MB Bun-compiled ELF living in the user's cache. This shim finds
+// it, downloading it on first use if the postinstall never ran, and hands over the process.
+//
+// The lazy download is the load-bearing part: npm 12 blocks install scripts by DEFAULT, so
+// a package that only fetches in postinstall installs "successfully" and then cannot run.
+// Fetching here means `npm i -g crust` works under any script policy — the cost is that the
+// very first invocation pays the download.
+import { spawn } from "node:child_process";
+import { ensureBinary, readManifest, installHint, resolveSource, readPkg } from "../lib/install.mjs";
+
+const say = (m) => console.error(`[crust] ${m}`);
+
+function bail(lines, code = 127) {
+  for (const l of lines) console.error(`[crust] ${l}`);
+  process.exit(code);
+}
+
+// Pass the plane AND the package: readManifest's whole job is to reject a cached
+// binary that belongs to a DIFFERENT artifact plane or a DIFFERENT package version,
+// and with no arguments those guards are skipped — so CRUST_SOURCE was silently
+// ignored on every run after the first, and a version bump kept the old binary in
+// play until a human deleted the manifest by hand.
+const pkg = readPkg();
+let manifest = readManifest(pkg, resolveSource(pkg));
+
+if (!manifest) {
+  try {
+    // Progress goes to stderr, never stdout: crust is a shell and gets piped, so anything on
+    // stdout here would corrupt the first command someone runs through it.
+    manifest = await ensureBinary({ log: say, warn: say });
+  } catch (e) {
+    bail([`could not install the crust binary: ${e.message}`, ...installHint()]);
+  }
+}
+
+// Async spawn with inherited stdio rather than exec or spawnSync: crust is interactive, so it
+// needs the real tty — and the shim must be a transparent SIGNAL conduit. spawnSync was not:
+// a single-pid SIGTERM (Playwright stopping a webServer, systemd, a bare `kill`) hit only this
+// node process, libuv put the binary down without ceremony, and a crust `procs` supervisor
+// died WITHOUT running its group-kill teardown — orphaning every dev server it held. Forward
+// the termination signals and let the binary do its own graceful shutdown.
+const child = spawn(manifest.bin, process.argv.slice(2), { stdio: "inherit" });
+child.on("error", (e) => bail([`failed to launch ${manifest.bin}: ${e.message}`]));
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => {
+    try {
+      child.kill(sig);
+    } catch {
+      /* already gone */
+    }
+  });
+}
+child.on("exit", (code, signal) => {
+  // A plain exit-code passthrough loses signals, which makes `crust` dying to SIGINT look
+  // different from the binary dying to SIGINT. Re-raise instead.
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/lib/install.mjs

@@ -0,0 +1,330 @@
+// crust — resolve and install the prebuilt binary for this package.
+//
+// WHY THIS PACKAGE IS A LAUNCHER RATHER THAN THE BINARY
+// `bun build --compile` produces a ~91 MB self-contained executable. Shipping that inside the
+// npm tarball would put ~91 MB into the registry per published version and hard-lock the
+// package to one platform. Instead the binary is published ONCE per build to an artifact
+// plane, and every install route resolves that one artifact — same file, same sha256.
+//
+// TWO PLANES, ONE RESOLVER. The public release publishes binaries to GitHub Releases; the
+// LAN build publishes to apps.in.drlario.org. Which one this copy of the package uses is
+// stamped into package.json as `crust.source` at publish time ("github" or "apps") and can be
+// overridden with CRUST_SOURCE. The verify-then-rename download path below is shared, because
+// "did the bytes we ran match the bytes that were published" must not depend on the plane.
+//
+// WHY THIS IS A LIBRARY AND NOT JUST A POSTINSTALL
+// npm 12 blocks install scripts BY DEFAULT (`allowScripts`), so a postinstall-only design
+// silently ships a package that cannot run — verified on npm 12.0.2 with no local config.
+// So the binary is fetched lazily by bin/crust on first use, and the postinstall is only a
+// fast path for environments that still permit it. Either entry point calls ensureBinary().
+//
+// Node stdlib only, deliberately: this runs before the package's own dependencies are
+// guaranteed usable in every npm/pnpm/bun layout, so it must not have any.
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, chmodSync, writeFileSync, createReadStream, unlinkSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const MANIFEST_PATH = path.join(PKG_ROOT, "install-manifest.json");
+
+const APPS_URL = (process.env.CRUST_APPS_URL || "https://apps.in.drlario.org").replace(/\/+$/, "");
+const CACHE_ROOT = path.join(process.env.XDG_CACHE_HOME || path.join(homedir(), ".cache"), "crust");
+const DEFAULT_REPO = "lariocpt/crust";
+
+export function readPkg() {
+  return JSON.parse(readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+}
+
+// Env beats the stamp so someone on the LAN can point a public install at the internal plane
+// (and vice versa) without editing an installed package.
+export function resolveSource(pkg = readPkg()) {
+  const raw = (process.env.CRUST_SOURCE || pkg.crust?.source || "apps").toLowerCase();
+  if (raw !== "apps" && raw !== "github") {
+    throw new Error(`unknown CRUST_SOURCE '${raw}' — expected 'github' or 'apps'`);
+  }
+  return raw;
+}
+
+// `crust-linux-x64`, `crust-darwin-arm64`, … — the names the release workflow uploads.
+/**
+ * @param {string} [platform]
+ * @param {string} [arch]
+ * @param {string|null} [variant] e.g. "mongo" (from package.json crust.variant)
+ */
+export function assetName(platform = process.platform, arch = process.arch, variant = null) {
+  // The mongo variant ships as a separate asset (crust-linux-x64-mongo): same
+  // version, different binary. Clean builds have no variant and keep the
+  // original name forever.
+  return `crust-${platform}-${arch}${variant ? `-${variant}` : ""}`;
+}
+
+function ghRepo(pkg) {
+  if (process.env.CRUST_GITHUB_REPO) return process.env.CRUST_GITHUB_REPO;
+  if (pkg.crust?.repo) return pkg.crust.repo;
+  const m = /github\.com[/:]([^/]+\/[^/.]+)/.exec(pkg.repository?.url || "");
+  return m ? m[1] : DEFAULT_REPO;
+}
+
+// The two LAN planes version the same build differently, and that is deliberate — see the
+// header of publish/bin/apps-publish:
+//
+//   apps plane : <pkgversion>+<shortsha>      e.g. 0.1.0+78f2a43
+//   npm plane  : <pkgversion>-ci.<n>.<sha>    e.g. 0.1.0-ci.42.78f2a43
+//
+// semver ignores build metadata after `+` when ordering, so the registry cannot use the apps
+// form. The shared short sha is what ties one back to the other.
+function shaFromNpmVersion(v) {
+  const m = /-ci\.\d+\.([0-9a-f]{7,40})$/.exec(v);
+  return m ? m[1] : null;
+}
+
+function parseIndex(tsv) {
+  // Columns: kind name version file sha256 bytes path
+  return tsv
+    .split("\n")
+    .filter((l) => l && !l.startsWith("#"))
+    .map((l) => l.split("\t"))
+    .filter((c) => c.length >= 7 && c[0] === "tool" && c[1] === "crust")
+    .map(([kind, name, version, file, sha256, bytes, p]) => ({ kind, name, version, file, sha256, bytes, path: p }));
+}
+
+// Prefer the artifact this exact package was built alongside; fall back to whatever `latest`
+// points at. The fallback matters because apps-publish prunes old versions (KEEP_VERSIONS),
+// so an npm version can outlive its binary — a working newer crust with a warning beats a
+// hard failure.
+function pickRow(rows, wantSha) {
+  if (wantSha) {
+    const exact = rows.find((r) => r.version.endsWith(`+${wantSha}`) && !r.path.includes("/latest/"));
+    if (exact) return { row: exact, exact: true };
+  }
+  const latest = rows.find((r) => r.path.includes("/latest/"));
+  return latest ? { row: latest, exact: false } : null;
+}
+
+// SHA256SUMS is the plain `sha256sum` format: "<hex>  <filename>" per line.
+function parseSums(text) {
+  const out = new Map();
+  for (const line of text.split("\n")) {
+    const m = /^([0-9a-f]{64})\s+\*?(.+?)\s*$/.exec(line);
+    if (m) out.set(m[2], m[1]);
+  }
+  return out;
+}
+
+async function get(url) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) throw new Error(`GET ${url} -> ${res.status} ${res.statusText}`);
+  return res;
+}
+
+function sha256OfFile(p) {
+  return new Promise((resolve, reject) => {
+    const h = createHash("sha256");
+    createReadStream(p).on("data", (c) => h.update(c)).on("end", () => resolve(h.digest("hex"))).on("error", reject);
+  });
+}
+
+async function downloadVerified(url, dest, wantSha) {
+  const res = await get(url);
+  const tmp = `${dest}.part.${process.pid}`;
+  const hash = createHash("sha256");
+  // Stream rather than buffer: ~91 MB held in memory purely to hash it is waste on a machine
+  // that is probably doing something else.
+  await pipeline(
+    Readable.fromWeb(res.body),
+    async function* (src) { for await (const chunk of src) { hash.update(chunk); yield chunk; } },
+    createWriteStream(tmp, { mode: 0o755 }),
+  );
+  const got = hash.digest("hex");
+  if (got !== wantSha) {
+    unlinkSync(tmp);
+    throw new Error(`checksum mismatch for ${url}\n  expected ${wantSha}\n  got      ${got}`);
+  }
+  // Verify BEFORE the file reaches its final name, never after: a truncated or tampered
+  // download must not be executable on disk even briefly. The rename is atomic, and the
+  // pid-suffixed temp name keeps two concurrent installs from fighting over one .part file.
+  renameSync(tmp, dest);
+  chmodSync(dest, 0o755);
+  return dest;
+}
+
+// Both resolvers return the same shape: { version, url, sha256, bytes, from, note }.
+// `note` is a non-fatal warning for the caller to surface.
+async function resolveFromApps(pkg) {
+  const wantSha = shaFromNpmVersion(pkg.version);
+
+  const res = await get(`${APPS_URL}/index.tsv`);
+  const rows = parseIndex(await res.text());
+  if (!rows.length) throw new Error(`no 'crust' rows in ${APPS_URL}/index.tsv — has the crust binary job run yet?`);
+
+  const picked = pickRow(rows, wantSha);
+  if (!picked) throw new Error("index.tsv has crust rows but none resolvable");
+  const { row, exact } = picked;
+
+  return {
+    version: row.version,
+    url: `${APPS_URL}/${row.path}`,
+    sha256: row.sha256,
+    bytes: Number(row.bytes) || 0,
+    from: APPS_URL,
+    note: wantSha && !exact
+      ? `binary for ${pkg.version} (sha ${wantSha}) is no longer published — falling back to latest (${row.version})`
+      : null,
+  };
+}
+
+async function resolveFromGithub(pkg) {
+  const repo = ghRepo(pkg);
+  const tag = `v${pkg.version}`;
+  const base = `https://github.com/${repo}/releases/download/${tag}`;
+  const asset = assetName(process.platform, process.arch, pkg.crust?.variant || null);
+
+  // The checksums file is the source of truth for what this release actually contains, so an
+  // unsupported platform fails here with the real list rather than as a 404 on the binary.
+  const sums = parseSums(await (await get(`${base}/SHA256SUMS`)).text());
+  const sha256 = sums.get(asset);
+  if (!sha256) {
+    const have = [...sums.keys()].filter((k) => k.startsWith("crust-")).join(", ") || "(none)";
+    throw new Error(
+      `release ${tag} has no ${asset}\n  platforms in this release: ${have}\n` +
+      `  build from source instead: https://github.com/${repo}#build-from-source`,
+    );
+  }
+
+  return { version: pkg.version, url: `${base}/${asset}`, sha256, bytes: 0, from: `github.com/${repo}@${tag}`, note: null };
+}
+
+// The part of a version both planes share: the apps plane writes a build as
+// `<base>+<sha>`, the LAN npm plane as `<base>-ci.<n>.<sha>` — strip the suffix
+// and both collapse to the same core version.
+function coreVersion(v) {
+  return typeof v === "string" ? v.split(/[+-]/)[0] : null;
+}
+
+/**
+ * @typedef {object} Manifest
+ * @property {string} source the artifact plane ("apps" or "github")
+ * @property {string} version the binary's version as the plane publishes it
+ * @property {string} [packageVersion] the package version the manifest was written for
+ *   (absent on manifests written by older launcher releases)
+ * @property {string} bin absolute path of the verified binary in the cache
+ * @property {string} sha256 verified sha256 of the binary
+ * @property {string} from the plane the binary was resolved from
+ */
+
+/**
+ * @param {object} [pkg] the installed package's package.json (read from disk if omitted)
+ * @param {string|null} [source] the artifact plane this run resolved to
+ * @returns {Manifest|null} the manifest if it validates, otherwise a cache miss
+ */
+export function readManifest(pkg = readPkg(), source = null) {
+  if (!existsSync(MANIFEST_PATH)) return null;
+  try {
+    const m = JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+    if (!m || typeof m !== "object" || !m.bin || !existsSync(m.bin)) return null;
+    // A manifest written under a different plane describes a binary this run did not ask for
+    // (someone set CRUST_SOURCE between runs). Re-resolve rather than launch it.
+    if (source && m.source && m.source !== source) return null;
+    // Same for a different package version: after a bump (0.3.0 -> 0.3.1) the old manifest
+    // would keep shadowing the new release until a human deleted the file by hand. The
+    // package version the manifest was WRITTEN FOR is `packageVersion`; manifests written by
+    // older launcher releases predate that field, so fall back to the binary's own version
+    // at core granularity — one re-resolve upgrades them to the new shape and pins them.
+    if (typeof pkg?.version !== "string") return null;
+    if (typeof m.packageVersion === "string") {
+      if (m.packageVersion !== pkg.version) return null;
+    } else if (coreVersion(m.version) !== coreVersion(pkg.version)) {
+      return null;
+    }
+    return m;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve, download if needed, record what was verified, return the manifest.
+// `log` is a sink so the shim can stay quiet on the happy path while the postinstall talks.
+/**
+ * @param {object} [options]
+ * @param {(message: string) => void} [options.log]
+ * @param {(message: string) => void} [options.warn]
+ */
+export async function ensureBinary({ log = () => {}, warn = () => {} } = {}) {
+  const pkg = readPkg();
+  const source = resolveSource(pkg);
+
+  const cached = readManifest(pkg, source);
+  if (cached) return cached;
+
+  const r = source === "github" ? await resolveFromGithub(pkg) : await resolveFromApps(pkg);
+  if (r.note) warn(r.note);
+
+  // The cache key carries the platform because a home directory can be shared across machines
+  // of different architectures; two hosts must not race for one path holding one arch's ELF.
+  // The variant is in the key too: clean and mongo binaries share a version but are not
+  // interchangeable, and one ~/.cache must not let them overwrite each other.
+  const variant = pkg.crust?.variant ? `-${pkg.crust.variant}` : "";
+  const dir = path.join(CACHE_ROOT, `${r.version}-${process.platform}-${process.arch}${variant}`);
+  const bin = path.join(dir, "crust");
+  mkdirSync(dir, { recursive: true });
+
+  if (existsSync(bin) && (await sha256OfFile(bin)) === r.sha256) {
+    log(`already cached: ${r.version}`);
+  } else {
+    const size = r.bytes ? ` (${(r.bytes / 1048576).toFixed(0)} MB)` : "";
+    log(`downloading crust ${r.version}${size} from ${r.from}`);
+    await downloadVerified(r.url, bin, r.sha256);
+    log(`installed -> ${bin}`);
+  }
+
+  const manifest = {
+    source,
+    version: r.version,
+    packageVersion: pkg.version,
+    bin,
+    sha256: r.sha256,
+    from: r.from,
+  };
+  // Recorded rather than re-derived: after a `latest` fallback the resolved version is no
+  // longer derivable from this package's own version, and the shim must launch the binary
+  // that was actually verified — not whatever latest points at next week. `packageVersion`
+  // records the package version that ASKED FOR that binary: readManifest rejects a manifest
+  // written for a different one, so a version bump self-heals (re-resolve, re-verify,
+  // rewrite) while a pin written under X.Y.Z still stands on the next run under X.Y.Z.
+  try {
+    writeFileSync(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`);
+  } catch (e) {
+    // A global install under a root-owned prefix is read-only for a normal user. The cache
+    // write already succeeded, so this is recoverable — the next run just re-resolves.
+    warn(`could not write install-manifest.json (${e.message}); will re-resolve on each run`);
+  }
+  return manifest;
+}
+
+// What to tell a user whose download just failed — the recovery differs per plane, and a LAN
+// URL printed at someone on the public internet is worse than no hint at all.
+export function installHint() {
+  let pkg;
+  try {
+    pkg = readPkg();
+  } catch {
+    return [];
+  }
+  if (resolveSource(pkg) === "github") {
+    const repo = ghRepo(pkg);
+    return [
+      `Binaries for v${pkg.version} come from https://github.com/${repo}/releases.`,
+      "If that host is unreachable, install directly with:",
+      `  curl -fsSL https://raw.githubusercontent.com/${repo}/main/install.sh | bash`,
+    ];
+  }
+  return [
+    `The binary is hosted on the LAN at ${APPS_URL}, so this needs to run on that network.`,
+    "Override the host with CRUST_APPS_URL, or install directly with:",
+    `  curl -fsSL ${APPS_URL}/install.sh | bash -s -- crust`,
+  ];
+}