@rust-js/build 0.0.1

package/README.md

@@ -0,0 +1,307 @@
+# Build hosts
+
+`build.js` prepares and invokes the native compiler. Vite delegates to it; other
+hosts can use it without importing the Vite plugin.
+
+Distributed tooling supports Node.js and Bun using standard Node.js APIs. Bun
+is used to develop, test, and create packages in this repository; users do not
+need it to run installed packages. Binding preparation and the native launcher
+use the host's current JavaScript runtime.
+
+```js
+import { createNativeBuilder } from "@rust-js/build/build";
+
+const builder = createNativeBuilder({
+  root: "/absolute/app",
+  rustJs: "/absolute/toolchain/rust-js",
+  resources: "/absolute/rust-js-resources",
+  cacheDir: "/absolute/app/.cache/rust-js",
+  bindings: [],
+  externs: { web: "/absolute/metadata/libwebapi.rmeta" },
+  rustcFlags: [],
+});
+await builder.compile({
+  crate: "/absolute/app/src/lib.rs",
+  output: "/absolute/app/generated/lib.js",
+  manifest: "/absolute/app/.cache/rust-js/manifest.json",
+});
+```
+
+`@rust-js/build` exposes package entry points: `/build` for native compiler
+preparation, `/manifest` for build-result validation, and `/publish` for WASI
+artifact publication. Vite and the playground declare this package dependency;
+neither imports tooling through a path outside its own package.
+
+`/patch`, and its command, `rust-js-patch [app-dir]`, tell an app's Cargo where
+the crates its npm packages have are: each package with `"rust-js": { "crate" }`,
+as `@rust-js/builtins` and `@rust-js/webapi` have, found as Node finds it, in
+npm's, bun's or pnpm's layout, is a `[patch.crates-io]` entry in the app's
+`.cargo/config.toml`, between `# rust-js: begin` and `# rust-js: end`. An app
+runs it as its `postinstall`, so Cargo and its editor have them once it's
+installed. A crate installed twice, which would be two of each of its types, is
+refused, with who asked for each.
+
+Both host packages are on npm, released with the compiler (ADR 0120). Local
+tarballs can be made with `bun pm pack` from `tooling/` and `vite-plugin/`.
+The package test installs these tarballs with Bun into an independent application
+and compiles through the plugin.
+Compiler discovery first uses the supplied `rustJs` path, then the application's
+`@rust-js/native` package, then the development checkout. Resource discovery uses the supplied `resources`
+path, then `@rust-js/resources` resolved from the application's dependencies,
+then the development checkout;
+compiler binaries and binding resources are not included in these host packages.
+
+Build and package a native compiler for the current macOS or Linux host:
+
+```sh
+cargo build --release --locked
+bun run pack:compiler target/release/rust-js /absolute/artifacts/native.tgz
+```
+
+The private `@rust-js/native` package contains the binary and a JavaScript launcher,
+with OS/architecture restrictions in its package manifest. Install the pinned
+Rust toolchain, its minimal profile and the `wasm32-unknown-unknown` target, on
+the destination machine first. The launcher
+asks that toolchain for its sysroot and sets the dynamic-library search path
+before forwarding arguments and exit status to the compiler. It does not install
+toolchains or modify global configuration. The adapter discovers this package
+automatically. To override it, set `rustJs` to an absolute compiler or launcher
+path, including its installed `.bin` link.
+The host hashes and watches both the launcher and its compiler binary.
+
+This is a local packaging path, tested on the development host. It still depends
+on Node.js or Bun, rustup, and compatible native system libraries. Clean-machine testing,
+Linux/macOS version qualification and signing remain open;
+the archive is not a standalone portable compiler distribution.
+
+Create a separate resource tarball from the repository root:
+
+```sh
+bun run pack:resources /absolute/artifacts/resources.tgz
+```
+
+This stages `@rust-js/resources` with the compiler's version, root toolchain pin,
+React/web binding sources and build scripts, and the locked Serde manifest and
+source. The resource package and metadata cache use the same input inventory.
+Install it as `@rust-js/resources`, or unpack it and set `resources` to the
+directory containing its `package.json` and `rust-toolchain.toml`.
+Build outputs go to the configured cache, outside the
+resource directory. The resource tarball contains source inputs, not prebuilt
+metadata, compiler binaries, or a Rust sysroot. Building still requires Node.js or Bun,
+Bash, and the pinned Rust toolchain; Cargo also needs its locked dependencies
+available locally or through its configured registry.
+
+To assemble all four packages together, use a new output directory:
+
+```sh
+bun run pack:distribution target/release/rust-js /absolute/artifacts
+cd /absolute/artifacts
+shasum -a 256 -c SHA256SUMS
+```
+
+On Linux, `sha256sum -c SHA256SUMS` also works. The command checks package versions
+against the compiler, stages every tarball, writes `distribution.json` with the
+compiler identity, host platform/architecture and archive hashes, then renames
+the completed directory into place. Existing destinations are rejected and a
+failed build removes its staging directory. `SHA256SUMS` covers all four archives
+and the distribution manifest. These hashes detect corruption; they do not
+authenticate the publisher. The command does not publish or install anything.
+
+For a local installation, add the four tarballs to the application's
+`package.json` using paths relative to that file, then install with the application's
+package manager. The local tarball setup below is tested with `bun install`;
+running the installed packages does not depend on that choice:
+
+```json
+{
+  "devDependencies": {
+    "vite": "8.3.0",
+    "@rust-js/vite-plugin": "./artifacts/vite-plugin.tgz",
+    "@rust-js/build": "./artifacts/build.tgz",
+    "@rust-js/native": "./artifacts/native.tgz",
+    "@rust-js/resources": "./artifacts/resources.tgz"
+  },
+  "overrides": {
+    "@rust-js/build": "./artifacts/build.tgz"
+  }
+}
+```
+
+The override routes the plugin's versioned dependency to the local tarball while
+the package is unpublished. Select `bindings: ["react", "serde"]`; neither a
+compiler path nor a resource path is needed for this installation:
+
+```js
+rustJs({ crates: ["src/App.rs"], bindings: ["react", "serde"] })
+```
+
+The isolated package test installs offline with lifecycle scripts disabled,
+repeats installation with a frozen lockfile, and exercises React/JSX and Serde
+using automatic resource discovery. It omits Vite's peer for its direct hook
+test; the separate Vite suite exercises the real bundler and Fast Refresh.
+The installed launcher, host, and binding preparation are exercised under both
+Node.js and Bun, with a failing stub for the other runtime on `PATH` so a hidden
+dependency fails the test. The CLI uses a Node.js shebang; Bun-only users can run
+`bun node_modules/.bin/rust-js`. The build adapter invokes it with its own runtime.
+Direct use of `react/build.sh` defaults to Node.js; set `RUST_JS_JS_RUNTIME` to a
+Bun executable to run it with Bun. Hosts supply this automatically.
+Clean-machine compiler installation, release authentication, platform qualification,
+and published package installation remain separate distribution work.
+
+For packaged resources, the adapter queries `rust-js --version-json` before
+preparing metadata. The response contains `version`, `toolchain`, and `abi`,
+matching the compiler identity in emitted manifests. The adapter requires the
+resource package's version and Rust pin to match, and accepts only ABI 1.
+Mismatch errors report both identities and leave existing output untouched.
+`rust-js --version` remains the human-readable form. Source-checkout resources
+without the `@rust-js/resources` package identity retain the development workflow.
+Matching version fields are a compatibility check, not proof of artifact
+provenance; release checksums and qualification are still needed.
+
+Use absolute compiler, resource, cache and extern paths. Crate and output paths
+may also be relative to `root`. `watchFiles` lists toolchain and binding inputs;
+add the validated manifest's `sources` for the application's watch set.
+
+`bindings` defaults to `["react"]`. This builds the web and React metadata for
+the application's installed React version. With no installed React, it uses the
+binding resource's default. The compiler bytes, binding source inputs, resource
+root, React version and compiler options identify the metadata cache directory.
+A build failure leaves no completion marker. Deleting the cache is safe.
+
+Use `bindings: ["react", "serde"]` for a React application that also uses
+`serde` derives and `serde_json`, or `["serde"]` for a non-React application.
+The adapter builds the locked Serde dependency set with the resource bundle's
+pinned toolchain and obtains artifact paths from Cargo's JSON output. Cargo
+checks freshness on every preparation; changes to the manifest, lockfile,
+binding source, compiler or options select a new cache directory. Paths with
+spaces are supported. Vite accepts the same `bindings` option:
+
+```js
+rustJs({ crates: ["src/App.rs"], bindings: ["react", "serde"] })
+```
+
+React and Serde are the built-in preparation recipes. Supply other matching metadata
+through `externs`; this does not make arbitrary dependency implementations
+available to the JavaScript backend. General Cargo dependency resolution and
+cross-crate JavaScript linking remain unsupported. The resource bundle currently
+uses the repository's binding build scripts and source layout; a standalone
+installable distribution is not yet provided.
+
+## Share model source with native Rust
+
+For now, compile shared source as a module in each target. For example, keep
+`shared/model.rs` beside `client/lib.rs` and `server/main.rs`, and include it
+from both entry points:
+
+```rust
+#[path = "../shared/model.rs"]
+mod model;
+```
+
+The shared module can contain supported Serde models and portable validation
+functions. Keep native I/O in the server entry point and browser APIs in the
+client. Configure the client builder with `bindings: ["serde"]` (plus `"react"`
+for React). The native server uses ordinary Serde dependencies; use matching
+versions and derive features when comparing JSON contracts.
+
+The compiler manifest lists the loaded shared file in `sources`. Watch that
+list and rebuild the client when shared source changes; rebuild the native
+server separately. Arbitrary Cargo dependencies, build scripts, features and
+procedural macros are not automatically prepared by this adapter. Its Serde
+recipe supplies the bundled dependency versions and derive support.
+
+[`test/shared-code.test.ts`](../test/shared-code.test.ts) creates an app outside
+the repository, compiles the same models and validation for both targets, and
+passes client-produced JSON through a native executable and back to the client.
+It checks malformed requests and rebuilds both targets after changing a shared
+validation rule. The test uses a subprocess for transport; HTTP, a browser UI,
+and a deployed full-stack pilot remain separate integration work.
+
+`manifest.js` validates the compiler's version-1 build result and remaps structured
+path fields. `publish.js` commits a completed WASI result to the host filesystem.
+Callers supply only a successful compiler result and serialize builds targeting
+the same outputs. Publication preserves unchanged files, checks stale-file
+ownership, and rolls back ordinary I/O errors. It does not guarantee crash-atomic
+multi-file replacement.
+
+## Build a Cargo workspace
+
+Cargo builds a workspace's libraries with rust-js as its workspace wrapper
+([ADR 0101](../docs/decisions/0101-cargo-workspace-wrapper.md)), each to JS of
+its own ([ADR 0100](../docs/decisions/0100-separate-crates.md)):
+
+```js
+import { checkCargo } from "@rust-js/build/cargo";
+
+const { js, crates } = await checkCargo({
+  manifestPath: "Cargo.toml", toolchain: "<pinned release>", compiler: "/path/to/rust-js",
+  packageName: "frontend", features: [],
+});
+```
+
+It runs `RUSTC_WORKSPACE_WRAPPER=<compiler> cargo check --target
+wasm32-unknown-unknown`. Each library of the workspace that `frontend` uses,
+and `frontend` itself, is JS in Cargo's target directory, beside the metadata
+of that build of it, importing the others; `js` is `frontend`'s, and `crates`
+each crate's JS and manifest. A feature set built before is the JS it was.
+Each file a crate's manifest lists is checked, of a build Cargo has as done
+too: one gone or edited is refused, and `cargo clean -p <package> --target
+wasm32-unknown-unknown` builds it again.
+Registry crates, build scripts and procedural macros are built by rustc, as
+Cargo asks; of registry crates, only serde's are known to rust-js at run time.
+`cargo build` is refused.
+
+A crate using React depends on the bindings in rust-js, and `checkCargo`'s
+`react` is the release it's checked for (ADR 0043), the latest otherwise:
+
+```toml
+[dependencies]
+react = { package = "rust-js-react", path = "/path/to/rust-js/react" }
+```
+
+In Vite, the plugin's `cargo` option builds the workspace with `checkCargo`, for
+the React the app has installed, and the app imports the package's JS as
+`rust-js:<package>`:
+
+```js
+// vite.config.js, in the workspace's web/
+plugins: [rustJs({ cargo: { package: "frontend", manifestPath: "../Cargo.toml" } }), react()]
+```
+
+```js
+import { App } from "rust-js:frontend";
+```
+
+An edit to any crate of the workspace is one `cargo check`, and the JS it
+changes is a Fast Refresh. Each module's JS is written beside its Rust, to be
+committed (ADR 0041): `frontend/src/api.rs` is `frontend/src/api.js`. Without
+rust-js, Vite builds from those. `cargo: { inSource: false }` leaves the JS in
+Cargo's target directory only. Cargo's target directory must be one Vite serves
+from: its workspace root, or another of `server.fs.allow`.
+
+## Experimental Cargo planning
+
+`@rust-js/build/cargo` exports `planCargoLibraries({ manifestPath, toolchain, target,
+packageName?, features?, noDefaultFeatures? })`. Supply an exact toolchain pin and
+an explicit target triple. `packageName` selects a member of a virtual workspace.
+
+The planner invokes Cargo metadata with `--frozen`: create and commit the lockfile
+first. It resolves offline without changing that lockfile, and returns local
+library packages in dependency order, preserving dependency aliases, source paths,
+editions and Cargo-resolved features. Development dependencies are excluded.
+Registry/git packages, build scripts, procedural macros and packages without an
+ordinary library target are rejected when reachable from the selected library.
+
+This is dependency discovery, not a Cargo compilation entry point. It does not
+produce rustc invocations, compile dependencies to JS, establish a cross-crate ABI
+or cache compilation artifacts. Metadata feature sets are Cargo resolution data,
+not a substitute for Cargo compiler-unit/build-script information. The native
+builder and Vite do not consume this experimental plan yet.
+
+The compiler also has an experimental scalar linkage proof, described in
+[ADR 0085](../docs/decisions/0085-scalar-library-linkage.md). A producer uses
+`rust-js shared.rs -o shared.js --library --manifest shared.json`; a consumer
+passes `--dependency shared.json` plus real rustc `--extern` metadata after `--`.
+This supports only the documented scalar free-function ABI. The caller must build
+matching metadata and JS and rebuild dependencies after source edits. The Cargo
+planner, native build adapter and Vite do not orchestrate these steps yet.

package/build.js

@@ -0,0 +1,193 @@
+// Native build preparation. Hosts provide scheduling and consume manifests.
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cargoWorkspace, checkCargo } from "./cargo.js";
+import { resourceInputs } from "./resources.js";
+import { parseCompilerIdentity } from "./manifest.js";
+
+export const defaultResources = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const defaultCompiler = join(defaultResources, "target/debug/rust-js");
+
+export function findCompiler(root) {
+  const require = createRequire(join(root, "package.json"));
+  try { return join(dirname(require.resolve("@rust-js/native/package.json")), "bin/rust-js"); }
+  catch (error) {
+    if (error.code !== "MODULE_NOT_FOUND") throw error;
+    return defaultCompiler;
+  }
+}
+
+function installedResources(root) {
+  const require = createRequire(join(root, "package.json"));
+  try { return dirname(require.resolve("@rust-js/resources/package.json")); }
+  catch (error) {
+    if (error.code !== "MODULE_NOT_FOUND") throw error;
+    return defaultResources;
+  }
+}
+
+/** The React the project has installed, whose API the react crate is built
+ * with (ADR 0043): what a later React added doesn't compile. `null` without
+ * one, which gets the latest's. */
+function installedReact(root) {
+  try {
+    const require = createRequire(join(root, "package.json"));
+    return JSON.parse(readFileSync(require.resolve("react/package.json"), "utf8")).version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `@rust-js/runtime` as the project installed it, of `version`, the
+ * compiler's: the helpers the JS it writes imports are its release's (ADR
+ * 0103). Throws with what to install otherwise.
+ */
+function checkRuntime(root, version) {
+  // Where Node finds a package, from the app up: looked for each time, as
+  // it may be installed while a dev server runs.
+  let found;
+  for (let dir = resolve(root); !found; dir = dirname(dir)) {
+    const candidate = join(dir, "node_modules", "@rust-js", "runtime", "package.json");
+    if (existsSync(candidate)) found = candidate;
+    else if (dirname(dir) === dir) break;
+  }
+  if (!found) throw new Error(`the JS rust-js ${version} writes imports @rust-js/runtime ${version}: install it`);
+  const installed = JSON.parse(readFileSync(found, "utf8")).version;
+  if (installed !== version) throw new Error(`rust-js ${version} needs @rust-js/runtime ${version}, not the installed ${installed}`);
+}
+
+/** `command`'s stdout; what it says on stderr as it succeeds, its warnings,
+ * go to `warn`, if given. */
+function run(command, args, cwd, env = {}, warn) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env: { ...process.env, RUST_JS_JS_RUNTIME: process.execPath, ...env }, stdio: ["ignore", "pipe", "pipe"] });
+    let output = "";
+    let errors = "";
+    child.stdout.setEncoding("utf8").on("data", chunk => { output += chunk; });
+    child.stderr.setEncoding("utf8").on("data", chunk => { errors += chunk; });
+    child.on("error", reject);
+    child.on("close", code => {
+      if (code !== 0) return reject(new Error(errors || `${command} exited with ${code}`));
+      if (warn && errors) warn(errors);
+      resolve(output);
+    });
+  });
+}
+
+export function createNativeBuilder({ root, rustJs = findCompiler(root), resources = installedResources(root), cacheDir = join(root, "node_modules/.cache/rust-js"), rustcFlags = [], bindings = ["react"], externs = {} }) {
+  const repo = resources;
+  const compilerPath = existsSync(rustJs) ? realpathSync(rustJs) : rustJs;
+  const compilerInputs = [...new Set([rustJs, compilerPath])];
+  const nativePackage = join(dirname(compilerPath), "../package.json");
+  const packaged = existsSync(nativePackage) && JSON.parse(readFileSync(nativePackage, "utf8")).name === "@rust-js/native";
+  if (packaged) {
+    compilerInputs.push(nativePackage, join(dirname(compilerPath), "compiler"));
+  }
+  const compilerCommand = packaged ? process.execPath : rustJs;
+  const compilerArgs = packaged ? [compilerPath] : [];
+  const metadataInputs = resourceInputs(bindings).map(p => join(repo, p));
+  const pinned = () => readFileSync(join(repo, "rust-toolchain.toml"), "utf8").match(/^channel\s*=\s*"([^"]+)"/m)?.[1];
+  // What the compiler says it is, once: `--version-json`.
+  let identity;
+  const compilerIdentity = async () => (identity ??= parseCompilerIdentity(await run(compilerCommand, [...compilerArgs, "--version-json"], root)));
+
+  // Each recipe uses the pinned resources and a content-keyed cache directory.
+  async function prepare() {
+    if (!existsSync(rustJs)) throw new Error(`no rust-js at ${rustJs}: configure rustJs with an installed compiler or build it with cargo build`);
+    checkRuntime(root, (await compilerIdentity()).version);
+    const react = bindings.includes("react") ? installedReact(root) : null;
+    if (!bindings.length) return { flags: [], react };
+    const packagePath = join(repo, "package.json");
+    if (existsSync(packagePath)) {
+      const resourcePackage = JSON.parse(await readFile(packagePath, "utf8"));
+      if (resourcePackage.name === "@rust-js/resources") {
+        const identity = await compilerIdentity();
+        const pin = (await readFile(join(repo, "rust-toolchain.toml"), "utf8")).match(/^channel\s*=\s*"([^"]+)"/m)?.[1];
+        if (resourcePackage.version !== identity.version || pin !== identity.toolchain) {
+          throw new Error(`Incompatible rust-js resources: compiler ${identity.version} (${identity.toolchain}), resources ${resourcePackage.version} (${pin ?? "missing Rust pin"}). Install matching compiler and resources.`);
+        }
+      }
+    }
+    const hash = createHash("sha256").update(JSON.stringify({ resources: resolve(resources), react, bindings, rustcFlags }));
+    for (const path of compilerInputs) hash.update(await readFile(path));
+    for (const path of metadataInputs) hash.update(await readFile(path));
+    const key = hash.digest("hex");
+    const flags = [];
+    if (bindings.includes("react")) {
+      const metadata = join(cacheDir, "react", react ?? "latest", key);
+      const stamp = join(metadata, "complete");
+      if (!existsSync(stamp) || ["libreact.rmeta", "libwebapi.rmeta", "libjs.rmeta"].some(file => !existsSync(join(metadata, file)))) {
+        await mkdir(metadata, { recursive: true });
+        // The binding crates are this compiler's to compile (ADR 0112).
+        await run(join(repo, "react/build.sh"), ["-o", join(metadata, "libreact.rmeta"), ...(react ? ["--react", react] : [])], repo, { RUST_JS_COMPILER: compilerPath });
+        await writeFile(stamp, key);
+      }
+      // React's crates, each a program's to name (ADR 0102): `use js::spawn`.
+      for (const name of ["react", "webapi", "js"]) flags.push("--extern", `${name}=${join(metadata, `lib${name}.rmeta`)}`);
+      flags.push("-L", metadata);
+    }
+    if (bindings.includes("serde")) {
+      const toolchain = readFileSync(join(repo, "rust-toolchain.toml"), "utf8").match(/^channel\s*=\s*"([^"]+)"/m)?.[1];
+      if (!toolchain) throw new Error("Binding resources must declare a pinned Rust toolchain");
+      // Cargo's structured output handles hashed filenames and paths with spaces.
+      // Run Cargo even on reuse: it checks that every dependency is still fresh.
+      // For rust-js's target (ADR 0090); serde_derive, a procedural macro, runs on the host.
+      const output = await run("cargo", [`+${toolchain}`, "build", "--locked", "--message-format=json",
+        "--target", "wasm32-unknown-unknown",
+        "--manifest-path", join(repo, "serde/Cargo.toml"), "--target-dir", join(cacheDir, "serde", key)], repo);
+      const artifacts = output.split("\n").filter(Boolean).map(line => JSON.parse(line))
+        .filter(message => message.reason === "compiler-artifact");
+      // Where the target's libraries are, and where the host's macro is.
+      const directories = new Set(artifacts
+        .filter(message => message.target.kind.some(kind => kind === "lib" || kind === "rlib" || kind === "proc-macro"))
+        .flatMap(message => message.filenames.map(file => dirname(file))));
+      for (const name of ["serde", "serde_json"]) {
+        const artifact = artifacts.find(message => message.target.name === name && message.target.kind.includes("lib"));
+        const file = artifact?.filenames.find(file => file.endsWith(".rmeta"))
+          ?? artifact?.filenames.find(file => file.endsWith(".rlib"));
+        if (!file || !existsSync(file)) throw new Error(`Cargo produced no ${name} metadata`);
+        flags.push("--extern", `${name}=${file}`);
+      }
+      // Sorted: Cargo reports what it builds as each finishes, and one build's
+      // flags must be the next's.
+      for (const directory of [...directories].sort()) flags.push("-L", `dependency=${directory}`);
+    }
+    return { flags, react };
+  }
+
+  return {
+    /** A Cargo workspace's check (ADR 0101), with the pinned toolchain, this
+     * compiler, and the React the project has installed. */
+    async checkCargo(options) {
+      checkRuntime(root, (await compilerIdentity()).version);
+      return checkCargo({ ...options, toolchain: pinned(), compiler: rustJs, react: installedReact(root) ?? undefined });
+    },
+    /** The workspace of a Cargo manifest, and its target directory. */
+    cargoWorkspace(options) {
+      return cargoWorkspace({ ...options, toolchain: pinned() });
+    },
+    watchFiles: [...metadataInputs, ...(bindings.length ? [join(repo, "package.json")] : []), ...compilerInputs, ...Object.values(externs)],
+    prepare,
+    /** `save` runs the crate's checks a save runs, not those only for a
+     * build (ADR 0117); `warn` is given what rust-js warns of as it succeeds. */
+    async compile({ crate, output, manifest, save = false, warn = undefined }) {
+      const { flags, react } = await prepare();
+      try {
+        await run(compilerCommand, [...compilerArgs, crate, "-o", output, "--manifest", manifest, "--hooks", save ? "save" : "build",
+          "--", ...flags,
+          ...Object.entries(externs).flatMap(([name, file]) => ["--extern", `${name}=${file}`, "-L", dirname(file)]), ...rustcFlags], root, {}, warn);
+      } catch (error) {
+        if (react && error.message.includes("configured out")) {
+          error.message += `\nnote: this project has React ${react}; an item gated \`react = "X.Y"\` needs React X.Y or later\n`;
+        }
+        throw error;
+      }
+    },
+  };
+}

package/cargo.js

@@ -0,0 +1,249 @@
+// Cargo's builds of rust-js crates (ADR 0101), and the experimental
+// local-library planning before them (ADR 0085). Cargo owns resolution; this
+// adapter does not infer dependencies from source files or run build scripts.
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+
+import { fingerprint } from "./publish.js";
+
+const execute = promisify(execFile);
+
+/** Cargo's rustc, for every crate it compiles: rust-js's `--rustc`, rustc
+ * with rust-js's tool known (ADR 0112). The binding crates need it, which
+ * the workspace's wrapper runs for only when they're its members, and a
+ * plain rustc doesn't know the tool. The same pinned rustc, for the rest. */
+function rustcShim(compiler) {
+  const dir = join(tmpdir(), "rust-js", createHash("sha256").update(compiler).digest("hex").slice(0, 16));
+  const shim = join(dir, "rustc");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(shim, `#!/bin/sh\nexec ${JSON.stringify(compiler)} --rustc "$@"\n`, { mode: 0o755 });
+  return shim;
+}
+
+/** One exact toolchain: a release, `1.98.1`, or a dated nightly (ADR 0109). */
+const exactToolchain = toolchain => /^(\d+\.\d+\.\d+|nightly-\d{4}-\d{2}-\d{2})$/.test(toolchain ?? "");
+
+/** @param {{ manifestPath: string, toolchain: string, target: string, packageName?: string, features?: string[], noDefaultFeatures?: boolean }} options */
+export async function planCargoLibraries({ manifestPath, toolchain, target, packageName, features = [], noDefaultFeatures = false }) {
+  if (!exactToolchain(toolchain)) throw new Error("Cargo planning requires an exact toolchain pin");
+  if (typeof target !== "string" || !target) throw new Error("Cargo planning requires an explicit target triple");
+  const manifest = resolve(manifestPath);
+  const args = [`+${toolchain}`, "metadata", "--format-version=1", "--frozen", "--manifest-path", manifest, "--filter-platform", target];
+  if (features.length) args.push("--features", features.join(","));
+  if (noDefaultFeatures) args.push("--no-default-features");
+  const { stdout } = await execute("cargo", args, { cwd: dirname(manifest), maxBuffer: 64 * 1024 * 1024 });
+  const metadata = JSON.parse(stdout);
+  const packages = new Map(metadata.packages.map(pkg => [pkg.id, pkg]));
+  const nodes = new Map(metadata.resolve.nodes.map(node => [node.id, node]));
+  const selected = packageName
+    ? metadata.workspace_members.filter(id => packages.get(id).name === packageName)
+    : metadata.resolve.root ? [metadata.resolve.root] : [];
+  if (selected.length !== 1) throw new Error("Select one Cargo workspace library with packageName");
+  const ordered = [];
+  const visited = new Set();
+  const visiting = new Set();
+  const pending = [{ id: selected[0] }];
+  while (pending.length) {
+    const { id, library: completed } = pending.pop();
+    if (completed) {
+      visiting.delete(id);
+      visited.add(id);
+      ordered.push(completed);
+      continue;
+    }
+    if (visited.has(id)) continue;
+    if (visiting.has(id)) throw new Error(`Cyclic Cargo library dependency: ${id}`);
+    const pkg = packages.get(id), node = nodes.get(id);
+    if (!pkg || !node) throw new Error(`Cargo metadata is missing package ${id}`);
+    if (pkg.source !== null) throw new Error(`Cargo JS planning currently supports only local path libraries: ${pkg.name}`);
+    if (pkg.targets.some(t => t.kind.includes("custom-build"))) throw new Error(`Cargo JS planning does not support build scripts: ${pkg.name}`);
+    if (pkg.targets.some(t => t.kind.includes("proc-macro"))) throw new Error(`Cargo JS planning does not support procedural macros: ${pkg.name}`);
+    const libraries = pkg.targets.filter(t => t.kind.includes("lib"));
+    if (libraries.length !== 1) throw new Error(`Cargo JS planning requires one ordinary library target: ${pkg.name}`);
+    const library = libraries[0];
+    const dependencies = node.deps.filter(dep => dep.dep_kinds.some(kind => kind.kind === null))
+      .map(dep => ({ name: dep.name, packageId: dep.pkg })).sort((a, b) => a.name.localeCompare(b.name));
+    visiting.add(id);
+    pending.push({ id, library: {
+      id, name: pkg.name, crateName: library.name, edition: library.edition,
+      manifestPath: pkg.manifest_path, sourcePath: library.src_path,
+      features: [...node.features].sort(), dependencies,
+    } });
+    for (const dependency of [...dependencies].reverse()) pending.push({ id: dependency.packageId });
+  }
+  return { root: selected[0], toolchain, target, workspaceRoot: metadata.workspace_root, libraries: ordered };
+}
+
+/**
+ * `cargo check` of a workspace for rust-js's target, with rust-js as Cargo's
+ * workspace wrapper (ADR 0101), and where each crate rust-js compiled has its
+ * JS: beside the metadata Cargo keeps for that build of it, so a feature set
+ * built before is the JS it was. Cargo reports each crate it built or found
+ * fresh; the `.rust-js` beside its metadata says where its manifest is. `js` is
+ * the selected package's, or the manifest's own package's. `react` is the
+ * React release the react crate is checked for (ADR 0043), or its latest.
+ * With `inSource`, each module's JS is written beside its Rust too, as a
+ * project commits it (`writeInSource`), and `js` and `crates` are those.
+ * `files` is every module's JS, where it's served from.
+ * @param {{ manifestPath: string, toolchain: string, compiler: string, packageName?: string, features?: string[], noDefaultFeatures?: boolean, offline?: boolean, react?: string, inSource?: boolean }} options
+ * @returns {Promise<{ js: string, crates: Map<string, { js: string, manifest: string }>, files: string[] }>}
+ */
+export async function checkCargo({ manifestPath, toolchain, compiler, packageName, features = [], noDefaultFeatures = false, offline = false, react, inSource = false }) {
+  if (!exactToolchain(toolchain)) throw new Error("Cargo builds require an exact toolchain pin");
+  const manifest = resolve(manifestPath);
+  const args = [`+${toolchain}`, "check", "--message-format=json", "--target", "wasm32-unknown-unknown", "--manifest-path", manifest];
+  if (packageName) args.push("-p", packageName);
+  if (features.length) args.push("--features", features.join(","));
+  if (noDefaultFeatures) args.push("--no-default-features");
+  if (offline) args.push("--offline");
+  const env = { ...process.env, RUSTC_WORKSPACE_WRAPPER: resolve(compiler), RUSTC: rustcShim(resolve(compiler)) };
+  if (react) env.RUST_JS_REACT = react;
+  else delete env.RUST_JS_REACT;
+  const { stdout } = await execute("cargo", args, { cwd: dirname(manifest), env, maxBuffer: 64 * 1024 * 1024 }).catch((error) => {
+    const messages = String(error.stdout ?? "").split("\n").filter(Boolean).map(line => JSON.parse(line));
+    const rendered = messages.filter(m => m.reason === "compiler-message").map(m => m.message.rendered).join("");
+    throw new Error(`cargo check failed:\n${rendered}${error.stderr ?? ""}`);
+  });
+  const crates = new Map();
+  let js;
+  for (const line of stdout.split("\n").filter(Boolean)) {
+    const message = JSON.parse(line);
+    if (message.reason !== "compiler-artifact") continue;
+    const metadata = message.filenames.find(file => file.endsWith(".rmeta"));
+    const marker = metadata?.replace(/\.rmeta$/, ".rust-js");
+    if (!marker || !existsSync(marker)) continue;
+    // Its own manifest, then those of the libraries it was compiled with.
+    const library = readFileSync(marker, "utf8").split("\n")[0];
+    const built = existsSync(library) ? JSON.parse(readFileSync(library, "utf8")) : { artifacts: [{ file: library }] };
+    // What it published, as it published it, for a build Cargo has as done
+    // too: Cargo checks its own outputs, not rust-js's.
+    const changed = built.artifacts.find(({ file, hash }) => !existsSync(file) || fingerprint(readFileSync(file)) !== hash);
+    if (changed) {
+      const name = packageNameOf(message.package_id);
+      throw new Error(`${changed.file} isn't what rust-js wrote for Cargo's build of ${name}, which has it as done: `
+        + `\`cargo clean -p ${name} --target wasm32-unknown-unknown\` to build it again`);
+    }
+    // The crate root's module: `lib.jsx` when it has JSX (ADR 0075).
+    const entry = { js: built.modules.find(module => module.module.length === 0).file, manifest: library };
+    crates.set(message.target.name, entry);
+    if (packageName ? packageNameOf(message.package_id) === packageName : message.manifest_path === manifest) js = entry.js;
+  }
+  if (!js) throw new Error(`rust-js compiled no library of ${packageName ?? manifest}`);
+  const manifests = [...crates.values()].map(({ manifest }) => JSON.parse(readFileSync(manifest, "utf8")));
+  if (!inSource) return { js, crates, files: manifests.flatMap(({ modules }) => modules.map((module) => module.file)) };
+  const moved = writeInSource(manifests);
+  for (const entry of crates.values()) entry.js = moved.get(entry.js);
+  return { js: moved.get(js), crates, files: [...moved.values()] };
+}
+
+/** What rust-js writes first in a module's JS, and nowhere else. */
+const GENERATED = "// Generated by rust-js from ";
+
+/**
+ * Each module's JS, and its map, beside its Rust, as ReScript writes it in
+ * source and a project commits it (ADR 0041): `src/api.rs`'s is
+ * `src/api.js`, or `.jsx`. A module that isn't a file of its own, an
+ * inline `mod inner { .. }`, is where its file would be: `src/inner.js`
+ * of `src/lib.rs`'s, `src/api/inner.js` of `src/api.rs`'s, and it's an
+ * error if that's another module's, before anything's written. An import of another crate's module is of its
+ * copy, where it is; any other stays as written. A file is written only if
+ * it changed, and a module's JS rust-js wrote before, a `.js` or `.jsx`
+ * beside a crate's Rust that's no module's now, goes. Where each JS went.
+ * @param {{ library: { name: string }, modules: { file: string, map?: string, source: string, module: string[] }[] }[]} manifests
+ * @returns {Map<string, string>}
+ */
+export function writeInSource(manifests) {
+  const moved = new Map();
+  // `mod root { .. }` of a `[lib] path = "src/root.rs"` is where the root
+  // is, and two crates' inline `mod helper` of `sources/alpha.rs` and
+  // `sources/beta.rs` are in one place: none is written over another, as
+  // rust-js's own output refuses `mod lib` of `lib.rs`.
+  const byDestination = new Map();
+  const named = ({ crate, module }, other) => {
+    const own = module.length === 0 ? "the crate root" : `module \`${module.join("::")}\``;
+    if (crate === other.crate) return own;
+    return `crate \`${crate}\`'s ${module.length === 0 ? "root" : own}`;
+  };
+  for (const { library, modules } of manifests) {
+    const crateRoot = modules.find((m) => m.module.length === 0).source;
+    for (const { file, source, module } of modules) {
+      const extension = file.endsWith(".jsx") ? ".jsx" : ".js";
+      // The module whose file `source` is, by where it is: `src/api.rs`
+      // and `src/api/mod.rs` are `api`'s.
+      const own = source === crateRoot ? [] : relative(dirname(crateRoot), source).replace(/\.rs$/, "").split(sep);
+      if (own.at(-1) === "mod") own.pop();
+      const written = own.length === module.length && own.every((name, i) => name === module[i]);
+      moved.set(file, written ? source.replace(/\.rs$/, extension) : join(dirname(crateRoot), ...module) + extension);
+    }
+    for (const { file, module } of [...modules].sort((a, b) => a.module.length - b.module.length)) {
+      const to = moved.get(file);
+      const here = { crate: library.name, module };
+      const other = byDestination.get(to);
+      if (other) throw new Error(`rust-js can't write the JS in source: ${named(other, here)} and ${named(here, other)} would both be ${to}; rename the module`);
+      byDestination.set(to, here);
+    }
+  }
+  const write = (path, text) => {
+    if (existsSync(path) && readFileSync(path, "utf8") === text) return;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+  };
+  for (const { modules } of manifests) {
+    for (const { file, map } of modules) {
+      const to = moved.get(file);
+      const text = readFileSync(file, "utf8").replace(/((?:from|import)\s*\(?\s*)"(\.{1,2}\/[^"]+)"/g, (whole, lead, spec) => {
+        const target = moved.get(resolve(dirname(file), spec));
+        if (!target) return whole;
+        const path = relative(dirname(to), target);
+        return `${lead}"${path.startsWith(".") ? path : `./${path}`}"`;
+      });
+      write(to, text);
+      if (map && existsSync(map)) {
+        const json = JSON.parse(readFileSync(map, "utf8"));
+        json.sources = (json.sources ?? []).map((path) => relative(dirname(to), resolve(dirname(map), path)));
+        write(`${to}.map`, JSON.stringify(json));
+      }
+    }
+  }
+  // What rust-js wrote before beside a crate's Rust, and isn't a module's now.
+  const written = new Set(moved.values());
+  for (const { modules } of manifests) {
+    const root = dirname(modules.find((module) => module.module.length === 0).source);
+    for (const name of readdirSync(root, { recursive: true }).map(String)) {
+      const path = join(root, name);
+      if (!/\.jsx?$/.test(path) || written.has(path)) continue;
+      if (!readFileSync(path, "utf8").startsWith(GENERATED)) continue;
+      rmSync(path);
+      rmSync(`${path}.map`, { force: true });
+    }
+  }
+  return moved;
+}
+
+/**
+ * The workspace a Cargo manifest is of, a member's or the root's, and where
+ * Cargo builds it: what Cargo reads, and what it writes (ADR 0101), and where each of its
+ * packages is.
+ * @param {{ manifestPath: string, toolchain: string, offline?: boolean }} options
+ * @returns {Promise<{ root: string, target: string, packages: Map<string, string> }>}
+ */
+export async function cargoWorkspace({ manifestPath, toolchain, offline = false }) {
+  const manifest = resolve(manifestPath);
+  const args = [`+${toolchain}`, "metadata", "--no-deps", "--format-version=1", "--manifest-path", manifest, ...(offline ? ["--offline"] : [])];
+  const { stdout } = await execute("cargo", args, { cwd: dirname(manifest), maxBuffer: 64 * 1024 * 1024 }).catch((error) => {
+    throw new Error(`cargo metadata failed:\n${error.stderr ?? error.message}`);
+  });
+  const metadata = JSON.parse(stdout);
+  const packages = new Map(metadata.packages.map((pkg) => [pkg.name, dirname(pkg.manifest_path)]));
+  return { root: metadata.workspace_root, target: metadata.target_directory, packages };
+}
+
+/** The package's name in a Cargo package ID: `path+file:///dir#name@1.0`, or `path+file:///dir/name#1.0`. */
+function packageNameOf(id) {
+  const [url, fragment = ""] = id.split("#");
+  return fragment.includes("@") ? fragment.slice(0, fragment.lastIndexOf("@")) : url.slice(url.lastIndexOf("/") + 1);
+}

package/manifest.js

@@ -0,0 +1,79 @@
+// The compiler's versioned build result. Shared by native and WASI hosts.
+function validCompiler(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && typeof value.version === "string" && value.version.length > 0
+    && typeof value.toolchain === "string" && value.toolchain.length > 0
+    && value.abi === 1;
+}
+
+export function parseCompilerIdentity(text) {
+  const value = JSON.parse(text);
+  if (!validCompiler(value)) throw new Error("Unsupported rust-js compiler identity or ABI; expected ABI 1");
+  return value;
+}
+
+export function parseManifest(text) {
+  let result;
+  try { result = JSON.parse(text); }
+  catch (error) { throw new Error(`Invalid rust-js manifest JSON: ${error.message}`); }
+  const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+  const strings = value => Array.isArray(value) && value.every(item => typeof item === "string");
+  const path = value => typeof value === "string" && (/^\//.test(value) || /^[A-Za-z]:[\\/]/.test(value));
+  const paths = value => strings(value) && value.every(path);
+  const fingerprint = value => object(value) && path(value.file)
+    && typeof value.hash === "string" && /^[0-9a-f]{16}$/.test(value.hash);
+  if (!object(result) || result.version !== 1) {
+    throw new Error(`Unsupported rust-js manifest version ${result?.version}; expected 1`);
+  }
+  if (result.compiler !== undefined && !validCompiler(result.compiler)) {
+    throw new Error("Unsupported rust-js compiler identity or ABI; expected ABI 1");
+  }
+  if (result.library !== undefined) {
+    const library = result.library;
+    // ADR 0100: each item another crate can reach, by rustc's key for it.
+    if (!object(library) || library.version !== 2 || typeof library.name !== "string" || !library.name
+        || typeof library.crate_hash !== "string" || !library.crate_hash
+        || !Array.isArray(library.inputs) || !library.inputs.every(fingerprint)
+        || !strings(library.impls) || !strings(library.libraries)
+        || !Array.isArray(library.items) || !library.items.every(item => object(item)
+          && typeof item.key === "string" && typeof item.rust_path === "string" && strings(item.module)
+          && typeof item.export === "string" && (item.member === null || typeof item.member === "string")
+          && Array.isArray(item.drops) && item.drops.every(Number.isInteger))) {
+      throw new Error("Invalid rust-js library contract; expected library ABI 2");
+    }
+  }
+  if (!path(result.input) || !path(result.output) || !paths(result.sources)
+      || !Array.isArray(result.modules) || !result.modules.every(module => object(module)
+        && strings(module.module) && path(module.file) && path(module.map)
+        && (module.source === null || path(module.source)) && paths(module.imports))
+      || !Array.isArray(result.artifacts) || !result.artifacts.every(artifact => object(artifact)
+        && path(artifact.file) && typeof artifact.hash === "string" && /^[0-9a-f]{16}$/.test(artifact.hash))) {
+    throw new Error("Invalid rust-js manifest: expected absolute paths, modules and fingerprinted artifacts");
+  }
+  const artifacts = new Set(result.artifacts.map(artifact => artifact.file));
+  const modules = new Set(result.modules.map(module => module.file));
+  if (artifacts.size !== result.artifacts.length
+      || modules.size !== result.modules.length
+      || result.modules.some(module => !artifacts.has(module.file) || !artifacts.has(module.map)
+        || module.imports.some(file => !modules.has(file)))) {
+    throw new Error("Invalid rust-js manifest: inconsistent module artifacts or imports");
+  }
+  return result;
+}
+
+// Remap only paths. Names, fingerprints and future unrelated fields stay intact.
+export function mapManifestPaths(manifest, map) {
+  return {
+    ...manifest,
+    input: map(manifest.input), output: map(manifest.output),
+    sources: manifest.sources.map(map),
+    modules: manifest.modules.map(module => ({
+      ...module, file: map(module.file), map: map(module.map),
+      source: module.source === null ? null : map(module.source), imports: module.imports.map(map),
+    })),
+    artifacts: manifest.artifacts.map(artifact => ({ ...artifact, file: map(artifact.file) })),
+    ...(manifest.library === undefined ? {} : { library: {
+      ...manifest.library, inputs: manifest.library.inputs.map(input => ({ ...input, file: map(input.file) })),
+    } }),
+  };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@rust-js/build",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Build preparation, manifests, and publication for rust-js hosts.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rust-js-lang/rust-js.git",
+    "directory": "tooling"
+  },
+  "bin": {
+    "rust-js-patch": "./patch.js"
+  },
+  "exports": {
+    "./build": "./build.js",
+    "./manifest": "./manifest.js",
+    "./publish": "./publish.js",
+    "./cargo": "./cargo.js",
+    "./patch": "./patch.js"
+  },
+  "files": [
+    "build.js",
+    "resources.js",
+    "manifest.js",
+    "publish.js",
+    "README.md",
+    "cargo.js",
+    "patch.js"
+  ]
+}

package/patch.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// The patch an app's Cargo needs to find the crates its npm packages have:
+// each package with `"rust-js": { "crate": ".." }`, found as Node finds a
+// package, from the app and from each such package, where its package
+// manager put it, all in one `node_modules`, npm's and bun's way, or in a
+// store, and linked, pnpm's. Cargo, and an editor's rust-analyzer, are told
+// where each is by `[patch.crates-io]`, in the app's `.cargo/config.toml`,
+// between rust-js's lines, which an install's `postinstall` writes again.
+//
+//   rust-js-patch [app-dir]
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const BEGIN = "# rust-js: begin";
+const END = "# rust-js: end";
+
+/**
+ * Write the patch of the app at `app`, and return the crates it names, each
+ * with where it is, from the app. Throws, writing nothing, if a crate is
+ * installed twice, which would be two of each of its types, or a package's
+ * crate is another version than it is.
+ * @param {string} app
+ * @returns {{ crate: string, path: string }[]}
+ */
+export function writePatch(app) {
+  const root = realpathSync(app);
+  const crates = installedCrates(root);
+  const lines = [...crates].sort(([x], [y]) => x.localeCompare(y)).map(([crate, path]) => `${crate} = { path = ${JSON.stringify(path)} }`);
+  const config = join(root, ".cargo", "config.toml");
+  const rest = existsSync(config) ? withoutBlock(readFileSync(config, "utf8")) : "";
+  if (/^\s*\[\s*patch\s*\.\s*("crates-io"|crates-io)\s*\]/m.test(rest)) {
+    throw new Error(`.cargo/config.toml has a [patch.crates-io] of its own, and TOML has one of a table, which rust-js writes: move its entries to Cargo.toml's [patch.crates-io], which Cargo takes with it`);
+  }
+  if (lines.length === 0) {
+    if (rest.trim()) writeFileSync(config, rest);
+    else rmSync(config, { force: true });
+    return [];
+  }
+  const block = [
+    BEGIN,
+    "# Where Cargo finds each crate an npm package has: written by rust-js from",
+    "# what's installed, as each install ends. Edits here are written over.",
+    "[patch.crates-io]",
+    ...lines,
+    END,
+    "",
+  ].join("\n");
+  mkdirSync(dirname(config), { recursive: true });
+  writeFileSync(config, rest.trim() ? `${rest.trimEnd()}\n\n${block}` : block);
+  return [...crates].map(([crate, path]) => ({ crate, path }));
+}
+
+/** `text` without rust-js's block, and the blank line rust-js put before it. */
+function withoutBlock(text) {
+  const start = text.indexOf(BEGIN);
+  if (start < 0) return text;
+  const end = text.indexOf(END, start);
+  const after = end < 0 ? text.length : text.indexOf("\n", end) < 0 ? text.length : text.indexOf("\n", end) + 1;
+  return text.slice(0, start).replace(/\n\n$/, "\n") + text.slice(after);
+}
+
+/**
+ * Each crate the app's packages have, by its name, and where it is, from
+ * the app: one, or an error naming each place and who asked for it.
+ * @param {string} root the app's directory, its real path
+ * @returns {Map<string, string>}
+ */
+function installedCrates(root) {
+  /** @type {Map<string, Map<string, { version: string, askers: Set<string> }>>} */
+  const found = new Map();
+  const seen = new Set();
+  /** @type {{ from: string, name: string, asker: string }[]} */
+  const queue = names(readJson(join(root, "package.json"))).map(name => ({ from: root, name, asker: "the app" }));
+  while (queue.length) {
+    const { from, name, asker } = /** @type {{ from: string, name: string, asker: string }} */ (queue.shift());
+    const dir = lookup(from, name);
+    if (!dir) continue;
+    const pkg = readJson(join(dir, "package.json"));
+    const crate = pkg["rust-js"]?.crate;
+    if (typeof crate !== "string") continue;
+    const at = found.get(crate) ?? new Map();
+    found.set(crate, at);
+    const place = at.get(dir) ?? { version: pkg.version, askers: new Set() };
+    place.askers.add(asker);
+    at.set(dir, place);
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    checkCrate(dir, pkg, crate);
+    for (const next of names(pkg, true)) queue.push({ from: dir, name: next, asker: pkg.name });
+  }
+  const crates = new Map();
+  for (const [crate, at] of found) {
+    const places = [...at].map(([dir, { version, askers }]) => `${version} at ${shown(root, dir)}, for ${[...askers].join(", ")}`);
+    if (at.size > 1) {
+      throw new Error(`${crate} is installed twice, which would be two of each of its types: ${places.join("; ")}. Install one version, which each package asks for`);
+    }
+    crates.set(crate, shown(root, [...at.keys()][0]));
+  }
+  return crates;
+}
+
+/** The packages `pkg` depends on: its own, and, for a package, its peers. */
+function names(pkg, peers = false) {
+  const fields = ["dependencies", "devDependencies", "optionalDependencies", ...(peers ? ["peerDependencies"] : [])];
+  return [...new Set(fields.flatMap(field => Object.keys(pkg[field] ?? {})))];
+}
+
+/** Where Node finds package `name` from `from`, as its real path. */
+function lookup(from, name) {
+  for (let dir = from; ; dir = dirname(dir)) {
+    if (basename(dir) !== "node_modules") {
+      const candidate = join(dir, "node_modules", name, "package.json");
+      if (existsSync(candidate)) return realpathSync(dirname(candidate));
+    }
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+/** A package's crate is the one it names, at the version it is. */
+function checkCrate(dir, pkg, crate) {
+  const manifest = join(dir, "Cargo.toml");
+  if (!existsSync(manifest)) throw new Error(`${pkg.name} names a crate, ${crate}, and has no Cargo.toml`);
+  const table = /^\[package\][^\S\n]*\n([\s\S]*?)(?=^\[|(?![\s\S]))/m.exec(readFileSync(manifest, "utf8"))?.[1] ?? "";
+  const field = key => new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, "m").exec(table)?.[1];
+  if (field("name") !== crate) throw new Error(`${pkg.name} names its crate ${crate}, and its Cargo.toml ${field("name")}`);
+  if (field("version") !== pkg.version) {
+    throw new Error(`${pkg.name} is ${pkg.version}, and its crate, ${crate}, ${field("version")}: they're to be one version`);
+  }
+}
+
+/** `dir`, as the app's config names it: from the app, with `/`. */
+function shown(root, dir) {
+  return relative(root, dir).split(sep).join("/");
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  const app = resolve(process.argv[2] ?? ".");
+  try {
+    const crates = writePatch(app);
+    if (crates.length) console.log(`rust-js: Cargo finds ${crates.map(c => c.crate).join(", ")} in node_modules`);
+  } catch (error) {
+    console.error(`rust-js: ${error instanceof Error ? error.message : error}`);
+    process.exitCode = 1;
+  }
+}

package/publish.js

@@ -0,0 +1,95 @@
+// Host publication for a successful WASI build. The manifest is committed last.
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+import { parseManifest } from "./manifest.js";
+
+export function fingerprint(bytes) {
+  let hash = 0xcbf29ce484222325n;
+  for (const byte of bytes) hash = BigInt.asUintN(64, (hash ^ BigInt(byte)) * 0x100000001b3n);
+  return hash.toString(16).padStart(16, "0");
+}
+
+// A path with its symlinks resolved, as the native compiler's `absolute`
+// resolves them, so aliases of one file are one path; one that doesn't
+// exist yet, through the part of it that does.
+function real(path) {
+  if (existsSync(path)) return realpathSync(path);
+  const parent = dirname(resolve(path));
+  return parent === resolve(path) ? parent : join(real(parent), basename(path));
+}
+
+// What an older build wrote that this one may remove, by the native
+// compiler's rules (src/output.rs): a generated file, in the output's
+// directory, that this build neither writes nor reads, still as it was
+// written. Anything else, a person's file or a source, is left alone.
+function staleArtifacts(previous, manifest, writes) {
+  const outputDir = real(dirname(manifest.output));
+  const kept = new Set([manifest.input, ...manifest.sources, ...writes.keys()].map(real));
+  return (previous?.artifacts ?? []).filter(({ file, hash }) => {
+    if (!existsSync(file)) return false;
+    const path = real(file);
+    return [".js", ".jsx", ".map"].includes(extname(path))
+      && path.startsWith(outputDir + sep)
+      && !kept.has(path)
+      && fingerprint(readFileSync(path)) === hash;
+  }).map(({ file }) => ({ file: real(file) }));
+}
+
+export function publishArtifacts(manifestPath, manifest, files) {
+  parseManifest(JSON.stringify(manifest));
+  for (const artifact of manifest.artifacts) {
+    const bytes = files.get(artifact.file);
+    if (!bytes || fingerprint(bytes) !== artifact.hash) throw new Error(`Missing or inconsistent artifact: ${artifact.file}`);
+  }
+  if (files.size !== manifest.artifacts.length) throw new Error("Unexpected artifacts outside manifest");
+  const previous = existsSync(manifestPath) ? parseManifest(readFileSync(manifestPath, "utf8")) : undefined;
+  if (previous && (previous.input !== manifest.input || previous.output !== manifest.output)) {
+    throw new Error("Manifest belongs to a different compilation");
+  }
+  const writes = new Map(files);
+  writes.set(manifestPath, Buffer.from(JSON.stringify(manifest, null, 2) + "\n"));
+  const stale = staleArtifacts(previous, manifest, writes);
+  const id = randomUUID();
+  const staged = [];
+  const changed = [];
+  try {
+    // Stage every byte before replacing any output. Unchanged files keep mtimes.
+    for (const [path, data] of writes) {
+      if (existsSync(path) && readFileSync(path).equals(Buffer.from(data))) continue;
+      mkdirSync(dirname(path), { recursive: true });
+      const stage = `${path}.${id}.stage`;
+      staged.push(stage);
+      writeFileSync(stage, data, { flag: "wx" });
+      changed.push({ path, stage, backup: `${path}.${id}.backup`, saved: false, installed: false });
+    }
+    // Stale files are backed up too, so an ordinary I/O failure can roll back.
+    const manifestWrite = changed.find(change => change.path === manifestPath);
+    const commit = [...changed.filter(change => change !== manifestWrite),
+      ...stale.map(({ file }) => ({ path: file, backup: `${file}.${id}.backup`, saved: false, installed: false })),
+      ...(manifestWrite ? [manifestWrite] : [])];
+    changed.splice(0, changed.length, ...commit);
+    for (const change of changed) {
+      if (existsSync(change.path)) {
+        renameSync(change.path, change.backup);
+        change.saved = true;
+      }
+      if (change.stage) {
+        renameSync(change.stage, change.path);
+        change.installed = true;
+      }
+    }
+  } catch (error) {
+    const recovery = [];
+    for (const change of [...changed].reverse()) {
+      try {
+        if (change.installed) rmSync(change.path);
+        if (change.saved) renameSync(change.backup, change.path);
+      } catch (failure) { recovery.push(`${change.path}: ${failure}; backup: ${change.backup}`); }
+    }
+    throw new Error(`${error}${recovery.length ? `\nRecovery failures:\n${recovery.join("\n")}` : ""}`);
+  } finally {
+    for (const stage of staged) rmSync(stage, { force: true });
+  }
+  for (const change of changed) if (change.saved) rmSync(change.backup);
+}

package/resources.js

@@ -0,0 +1,22 @@
+// Shared by cache invalidation and resource packaging: every prepared input
+// must travel with the bundle and participate in the metadata cache key.
+export const bindingInputs = {
+  react: [
+    "react/build.sh", "react/cfg.js", "react/versions.json",
+    "react/src/lib.rs", "react/src/event.rs", "react/src/dom.rs", "react/src/elements.rs",
+    "react/Cargo.toml", "react/build.rs",
+    "webapi/build.sh", "webapi/src/lib.rs", "webapi/Cargo.toml",
+    "builtins/build.sh", "builtins/src/lib.rs", "builtins/Cargo.toml",
+  ],
+  serde: ["serde/Cargo.toml", "serde/Cargo.lock", "serde/src/lib.rs"],
+};
+
+export function resourceInputs(bindings) {
+  return [...new Set([
+    ...(bindings.length ? ["rust-toolchain.toml"] : []),
+    ...bindings.flatMap(name => {
+      if (!Object.hasOwn(bindingInputs, name)) throw new Error(`Unsupported built-in binding: ${name}; supply explicit externs instead`);
+      return bindingInputs[name];
+    }),
+  ])];
+}