fix: replace wasm-pack with pinned wasm-bindgen-cli in dev setup

The Lua WASM build requires -Zbuild-std which wasm-pack doesn't support,
so the build switched to cargo build + wasm-bindgen CLI directly. This
updates developer tooling to match:

- cargo dev-setup: installs wasm-bindgen-cli@0.2.108 instead of wasm-pack;
  version-checks the installed binary and reinstalls if it doesn't match
  the pinned version (wrong version = hard build error at schema mismatch)
- build-wasm.js: pre-flight check reads expected version from Cargo.lock
  and exits early with a clear actionable error if the CLI version differs
- CONTRIBUTING.md: document wasm-bindgen-cli requirement, version pinning
  note, and macOS Homebrew LLVM prerequisite for WASM builds

Author: gordonwoodhull

CONTRIBUTING.md

@@ -8,16 +8,33 @@
 
 The repo includes a `rust-toolchain.toml` that auto-installs the correct nightly toolchain, components (rustfmt, clippy), and the `wasm32-unknown-unknown` target on your first `cargo` invocation. No manual `rustup` steps needed.
 
-### Development tools (cargo-nextest, wasm-pack)
+### Development tools (cargo-nextest, wasm-bindgen-cli)
 
-This project uses [nextest](https://nexte.st/) instead of `cargo test`, and [wasm-pack](https://rustwasm.github.io/wasm-pack/) for building WASM modules. Install both with:
+This project uses [nextest](https://nexte.st/) instead of `cargo test`, and
+[wasm-bindgen-cli](https://rustwasm.github.io/wasm-bindgen/) for building WASM modules. Install both with:
 
 ```bash
 cargo dev-setup
 ```
 
 This detects already-installed tools and skips them. When [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) is available, it downloads pre-built binaries (seconds); otherwise it falls back to `cargo install --locked` (slower, compiles from source).
 
+> **Note:** `wasm-bindgen-cli` must exactly match the `wasm-bindgen` crate version pinned in
+> `crates/wasm-quarto-hub-client/Cargo.lock`. `cargo dev-setup` installs the correct pinned version
+> automatically. If you install it manually, use the version shown in that `Cargo.lock`
+> (currently `0.2.108`): `cargo install wasm-bindgen-cli --version 0.2.108`.
+> Running `npm run build:all` will tell you if there's a version mismatch.
+
+### macOS: Homebrew LLVM (for WASM builds)
+
+The WASM build compiles Lua C source for `wasm32-unknown-unknown`, which requires LLVM clang — Apple's built-in clang does not support that target.
+
+```bash
+brew install llvm
+```
+
+This only needs to be done once. The build scripts locate it automatically in the standard Homebrew paths (`/opt/homebrew/opt/llvm` on Apple Silicon, `/usr/local/opt/llvm` on Intel).
+
 ### Pandoc 3.6+ (optional)
 
 Four tests in the `pampa` crate compare output against Pandoc. These tests require Pandoc 3.6 or later and will fail when Pandoc is missing or too old. `cargo dev-setup` checks this and warns if needed.

crates/xtask/src/dev_setup.rs

@@ -14,28 +14,53 @@ struct Tool {
     /// Command and args to check if the tool is installed.
     check_cmd: &'static str,
     check_args: &'static [&'static str],
+    /// If set, the tool must report exactly this version string (matched as a
+    /// substring of its `--version` output).  A wrong version is treated the
+    /// same as "not installed" and the pinned version is (re-)installed.
+    required_version: Option<&'static str>,
 }
 
 const TOOLS: &[Tool] = &[
     Tool {
         package: "cargo-nextest",
         check_cmd: "cargo",
         check_args: &["nextest", "--version"],
+        required_version: None,
     },
+    // wasm-bindgen-cli must exactly match the wasm-bindgen crate version locked
+    // in crates/wasm-quarto-hub-client/Cargo.lock.  A version mismatch produces
+    // a hard build error ("schema version … must exactly match").
     Tool {
-        package: "wasm-pack",
-        check_cmd: "wasm-pack",
+        package: "wasm-bindgen-cli",
+        check_cmd: "wasm-bindgen",
         check_args: &["--version"],
+        required_version: Some("0.2.108"),
     },
 ];
 
 fn is_installed(tool: &Tool) -> bool {
-    Command::new(tool.check_cmd)
-        .args(tool.check_args)
-        .stdout(std::process::Stdio::null())
-        .stderr(std::process::Stdio::null())
-        .status()
-        .is_ok_and(|s| s.success())
+    let output = Command::new(tool.check_cmd).args(tool.check_args).output();
+
+    let Ok(output) = output else { return false };
+    if !output.status.success() {
+        return false;
+    }
+
+    if let Some(required) = tool.required_version {
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        let combined = format!("{stdout}{stderr}");
+        if !combined.contains(required) {
+            let found = combined.lines().next().unwrap_or("unknown").trim();
+            println!(
+                "  {} — wrong version installed ({found}), need {required}",
+                tool.package
+            );
+            return false;
+        }
+    }
+
+    true
 }
 
 fn has_binstall() -> bool {
@@ -47,28 +72,41 @@ fn has_binstall() -> bool {
         .is_ok_and(|s| s.success())
 }
 
-fn install(package: &str, use_binstall: bool) -> Result<()> {
+fn install(tool: &Tool, use_binstall: bool) -> Result<()> {
+    let package = tool.package;
+    // Build the versioned package spec, e.g. "wasm-bindgen-cli@0.2.108"
+    let versioned = tool
+        .required_version
+        .map(|v| format!("{package}@{v}"))
+        .unwrap_or_else(|| package.to_string());
+
     if use_binstall {
-        println!("  Installing {package} via cargo binstall...");
+        println!("  Installing {versioned} via cargo binstall...");
         let status = Command::new("cargo")
-            .args(["binstall", "--no-confirm", package])
+            .args(["binstall", "--no-confirm", &versioned])
             .status()
-            .with_context(|| format!("Failed to run cargo binstall {package}"))?;
+            .with_context(|| format!("Failed to run cargo binstall {versioned}"))?;
 
         if status.success() {
             return Ok(());
         }
         println!("  binstall failed, falling back to cargo install...");
     }
 
-    println!("  Installing {package} via cargo install...");
+    let mut args = vec!["install", "--locked"];
+    if let Some(v) = tool.required_version {
+        args.extend(["--version", v]);
+    }
+    args.push(package);
+
+    println!("  Installing {versioned} via cargo install...");
     let status = Command::new("cargo")
-        .args(["install", "--locked", package])
+        .args(&args)
         .status()
-        .with_context(|| format!("Failed to run cargo install {package}"))?;
+        .with_context(|| format!("Failed to run cargo install {versioned}"))?;
 
     if !status.success() {
-        bail!("Failed to install {package}");
+        bail!("Failed to install {versioned}");
     }
 
     Ok(())
@@ -90,7 +128,7 @@ pub fn run() -> Result<()> {
             println!("  {} — already installed", tool.package);
             already += 1;
         } else {
-            install(tool.package, use_binstall)?;
+            install(tool, use_binstall)?;
             installed += 1;
         }
     }

crates/xtask/src/main.rs

@@ -6,7 +6,7 @@
 //! ```
 //!
 //! Available commands:
-//! - `dev-setup`: Install required development tools (cargo-nextest, wasm-pack)
+//! - `dev-setup`: Install required development tools (cargo-nextest, wasm-bindgen-cli)
 //! - `lint`: Run custom lint checks on the codebase
 //! - `test`: Run workspace tests with platform-appropriate crate exclusions
 //! - `verify`: Run full project verification (build + tests for Rust and hub-client)
@@ -32,7 +32,7 @@ struct Cli {
 enum Command {
     /// Install required development tools.
     ///
-    /// Checks for cargo-nextest and wasm-pack, installing any that are missing.
+    /// Checks for cargo-nextest and wasm-bindgen-cli (pinned version), installing any that are missing.
     /// Uses cargo-binstall for faster binary installs when available,
     /// falling back to cargo install --locked otherwise.
     DevSetup {},

hub-client/scripts/build-wasm.js

@@ -12,8 +12,8 @@
  *   - Homebrew LLVM (macOS): `brew install llvm`
  */
 
-import { spawn } from 'child_process';
-import { existsSync, mkdirSync, rmSync } from 'fs';
+import { spawn, spawnSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { platform } from 'os';
@@ -57,7 +57,58 @@ function run(cmd, args, opts = {}) {
   });
 }
 
+/**
+ * Read the wasm-bindgen version locked in the wasm crate's Cargo.lock.
+ * Returns a string like "0.2.108", or null if it can't be determined.
+ */
+function lockedWasmBindgenVersion() {
+  try {
+    const lockPath = join(wasmCrate, 'Cargo.lock');
+    const text = readFileSync(lockPath, 'utf-8');
+    const match = text.match(/name = "wasm-bindgen"\nversion = "([^"]+)"/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify that the installed wasm-bindgen CLI matches the version locked in
+ * Cargo.lock.  The versions must match exactly — a mismatch causes a hard
+ * build error ("schema version … must exactly match").
+ */
+function checkWasmBindgenVersion() {
+  const expected = lockedWasmBindgenVersion();
+  if (!expected) {
+    console.warn('Warning: could not read wasm-bindgen version from Cargo.lock');
+    return;
+  }
+
+  const result = spawnSync('wasm-bindgen', ['--version'], { encoding: 'utf-8' });
+  if (result.error || result.status !== 0) {
+    console.error('Error: wasm-bindgen CLI not found.');
+    console.error(`Install the pinned version with:`);
+    console.error(`  cargo install -f wasm-bindgen-cli --version ${expected}`);
+    console.error('Or run: cargo dev-setup');
+    process.exit(1);
+  }
+
+  const installed = (result.stdout || result.stderr || '').trim();
+  if (!installed.includes(expected)) {
+    console.error(`Error: wasm-bindgen version mismatch.`);
+    console.error(`  installed: ${installed}`);
+    console.error(`  required:  wasm-bindgen ${expected}  (from Cargo.lock)`);
+    console.error('');
+    console.error('The CLI version must exactly match the wasm-bindgen crate version.');
+    console.error(`Fix with:`);
+    console.error(`  cargo install -f wasm-bindgen-cli --version ${expected}`);
+    console.error('Or run: cargo dev-setup');
+    process.exit(1);
+  }
+}
+
 async function buildWasm() {
+  checkWasmBindgenVersion();
   console.log('Building wasm-quarto-hub-client...\n');
 
   // Clean pkg/ directory