playground: ship uutils diffutils (diff, cmp)

sylvestre · sylvestre · commit 20a37bced4dd · 2026-06-20T16:04:26.000+02:00
Add uutils/diffutils to the playground alongside grep and find. The
diffutils binary is a multicall that provides diff and cmp, dispatched on
argv[0], so each command is invoked directly by name. Unlike grep/find it
has only pure-Rust dependencies (regex, not onig), so its WASM build needs
no WASI SDK.

Generalize the standalone-module registry from command-&gt;url to
module-&gt;{url, commands} so one module can back several commands: diff and
cmp share a single diffutils.wasm, load once on demand, and get one 'Load'
button. Add a couple of near-identical shopping-*.txt sample files so diff
and cmp have a small, readable change to show, plus a diff example, help
entry, version footer, and tests (diff/cmp exact-match; diff -u checked on
its hunk body, since its header carries an environment-dependent mtime).
diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml
@@ -50,6 +50,13 @@ jobs:
         path: './grep'
         fetch-depth: 0
 
+    - name: Checkout Diffutils Repository
+      uses: actions/checkout@v6
+      with:
+        repository: uutils/diffutils
+        path: './diffutils'
+        fetch-depth: 0
+
     - name: Install `rust` toolchain
       uses: dtolnay/rust-toolchain@stable
       with:
@@ -279,6 +286,46 @@ jobs:
           echo "find WASM build: ${find_short} (${find_date})"
         fi
 
+    - name: Build diffutils WASM binary
+      run: |
+        # uutils diffutils ships a single multicall binary that provides `diff`
+        # and `cmp` (dispatched on argv[0]). Unlike grep/find it has only
+        # pure-Rust dependencies (regex, not onig), so no WASI SDK is needed.
+        cd diffutils
+        cargo build --release --target wasm32-wasip1 --bin diffutils
+        if [ -f target/wasm32-wasip1/release/diffutils.wasm ]; then
+          mkdir -p ../uutils.github.io/static/wasm
+          cp target/wasm32-wasip1/release/diffutils.wasm ../uutils.github.io/static/wasm/diffutils.wasm
+          # Optimize WASM size if wasm-opt is available
+          if command -v wasm-opt &> /dev/null; then
+            wasm-opt -Oz ../uutils.github.io/static/wasm/diffutils.wasm -o ../uutils.github.io/static/wasm/diffutils.wasm
+          fi
+          echo "diffutils WASM binary size: $(du -h ../uutils.github.io/static/wasm/diffutils.wasm | cut -f1)"
+          # Advertise diff and cmp in the playground's command list. They ship as
+          # their own WASM module, so they aren't picked up by the coreutils
+          # feat_wasm scan above; append them to the generated list here.
+          commands_js=../uutils.github.io/static/wasm/commands.js
+          if [ -f "$commands_js" ]; then
+            existing=$(sed -n 's/^const WASM_COMMANDS = \[\(.*\)\];$/\1/p' "$commands_js")
+            echo "const WASM_COMMANDS = [${existing}, \"diff\", \"cmp\"];" > "$commands_js"
+          else
+            echo 'const WASM_COMMANDS = ["diff", "cmp"];' > "$commands_js"
+          fi
+          # Record the diffutils commit used to build its WASM module so the
+          # playground can show it alongside the coreutils build.
+          diff_hash=$(git rev-parse HEAD)
+          diff_short=$(git rev-parse --short HEAD)
+          diff_date=$(git show -s --format=%cI HEAD)
+          {
+            echo "const UUTILS_DIFFUTILS_VERSION = {"
+            echo "  commit: \"${diff_hash}\","
+            echo "  short: \"${diff_short}\","
+            echo "  date: \"${diff_date}\""
+            echo "};"
+          } >> ../uutils.github.io/static/wasm/version.js
+          echo "diffutils WASM build: ${diff_short} (${diff_date})"
+        fi
+
     - name: Run Zola
       uses: shalzz/zola-deploy-action@v0.22.1
       env:
diff --git a/content/playground.md b/content/playground.md
@@ -28,44 +28,45 @@ template = "page.html"
 <script defer>
   document.addEventListener("DOMContentLoaded", function() {
     initPlayground("wasm-playground");
-    // Build a "Load" button per optional standalone program (grep, find).
-    // These ship as their own WASM modules and load on demand to keep the
-    // initial page download light; running the command auto-loads it too.
+    // Build a "Load" button per optional standalone module (grep, find,
+    // diffutils). These ship as their own WASM modules and load on demand to
+    // keep the initial page download light; running a command auto-loads its
+    // module too (e.g. diff/cmp both come from the diffutils module).
     var loaderBar = document.getElementById("playground-loaders");
     if (loaderBar && Array.isArray(window.uutilsPrograms)) {
-      window.uutilsPrograms.forEach(function(cmd) {
+      window.uutilsPrograms.forEach(function(prog) {
         var btn = document.createElement("button");
         btn.className = "playground-loader";
         var markLoaded = function() {
           btn.disabled = true;
           btn.classList.add("loaded");
-          btn.textContent = "✓ " + cmd + " loaded";
+          btn.textContent = "✓ " + prog + " loaded";
         };
         var setIdleLabel = function(size) {
-          btn.textContent = "Load " + cmd + (size ? " (" + (size / 1024 / 1024).toFixed(1) + " MB)" : "");
+          btn.textContent = "Load " + prog + (size ? " (" + (size / 1024 / 1024).toFixed(1) + " MB)" : "");
         };
         setIdleLabel(0);
-        window.programSize(cmd).then(function(size) {
+        window.programSize(prog).then(function(size) {
           if (!btn.classList.contains("loaded") && !btn.disabled) setIdleLabel(size);
         });
         btn.addEventListener("click", function() {
           if (btn.disabled) return;
           btn.disabled = true;
-          btn.textContent = "Loading " + cmd + "…";
-          window.loadProgram(cmd).then(function(mod) {
+          btn.textContent = "Loading " + prog + "…";
+          window.loadProgram(prog).then(function(mod) {
             if (mod) {
               markLoaded();
             } else {
               btn.disabled = false;
-              btn.textContent = cmd + " unavailable";
+              btn.textContent = prog + " unavailable";
             }
           });
         });
-        // Keep the button in sync if the program is loaded by running it.
+        // Keep the button in sync if the module is loaded by running a command.
         document.addEventListener("uutils:program-loaded", function(e) {
-          if (e.detail && e.detail.cmd === cmd) markLoaded();
+          if (e.detail && e.detail.module === prog) markLoaded();
         });
-        if (window.isProgramLoaded(cmd)) markLoaded();
+        if (window.isProgramLoaded(prog)) markLoaded();
         loaderBar.appendChild(btn);
       });
     }
@@ -112,6 +113,12 @@ template = "page.html"
         parts.push('findutils <a href="' + findUrl + '"><code>' +
           UUTILS_FINDUTILS_VERSION.short + '</code></a> (' + findDate + ')');
       }
+      if (typeof UUTILS_DIFFUTILS_VERSION !== "undefined") {
+        var diffDate = UUTILS_DIFFUTILS_VERSION.date.split("T")[0];
+        var diffUrl = "https://github.com/uutils/diffutils/commit/" + UUTILS_DIFFUTILS_VERSION.commit;
+        parts.push('diffutils <a href="' + diffUrl + '"><code>' +
+          UUTILS_DIFFUTILS_VERSION.short + '</code></a> (' + diffDate + ')');
+      }
       if (typeof SITE_VERSION !== "undefined") {
         var siteDate = SITE_VERSION.date.split("T")[0];
         var siteUrl = "https://github.com/uutils/uutils.github.io/commit/" + SITE_VERSION.commit;
@@ -147,6 +154,7 @@ Click an example to run it in the terminal:
   <button class="playground-example">printf '🍒 cherry\n🍎 apple\n🍌 banana\n' | sort -k2</button>
   <button class="playground-example">printf '🍎 apple\n🍌 banana\n🍒 cherry\n🥝 kiwi\n' | grep 🍌</button>
   <button class="playground-example">find . -name '*.md'</button>
+  <button class="playground-example">diff -u shopping-old.txt shopping-new.txt</button>
   <button class="playground-example">sort -n < numbers.txt | head -3</button>
   <button class="playground-example">date</button>
   <button class="playground-example">uname -a</button>
diff --git a/static/js/wasm-terminal.js b/static/js/wasm-terminal.js
@@ -16,12 +16,21 @@ if (typeof SharedArrayBuffer === "undefined") {
 const WASM_URL = "/wasm/uutils.wasm";
 // Some utilities ship as their own standalone WASM modules rather than as part
 // of the coreutils multicall binary (grep lives in uutils/grep, find in
-// uutils/findutils). They are loaded lazily alongside the multicall module and
-// each is optional — see loadStandaloneWasm.
-const STANDALONE_WASM_URLS = {
-  grep: "/wasm/grep.wasm",
-  find: "/wasm/find.wasm",
+// uutils/findutils, diff and cmp in uutils/diffutils). Each module is loaded on
+// demand and is optional — see loadStandalone. A single module can provide
+// several commands (diffutils → diff, cmp), which the diffutils binary
+// dispatches on argv[0], so each command is invoked directly by its own name.
+const STANDALONE_MODULES = {
+  grep: { url: "/wasm/grep.wasm", commands: ["grep"] },
+  find: { url: "/wasm/find.wasm", commands: ["find"] },
+  diffutils: { url: "/wasm/diffutils.wasm", commands: ["diff", "cmp"] },
 };
+// Map each command to the module that provides it (e.g. diff -> "diffutils").
+const STANDALONE_COMMAND_MODULE = Object.fromEntries(
+  Object.entries(STANDALONE_MODULES).flatMap(
+    ([mod, def]) => def.commands.map(cmd => [cmd, mod])
+  )
+);
 const XTERM_CSS = "https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/css/xterm.min.css";
 const XTERM_CSS_INTEGRITY = "sha384-tStR1zLfWgsiXCF3IgfB3lBa8KmBe/lG287CL9WCeKgQYcp1bjb4/+mwN6oti4Co";
 const XTERM_JS = "https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/lib/xterm.min.js";
@@ -44,6 +53,9 @@ const SAMPLE_FILES = {
   "🍌.md": "# Banana\n",
   "🍒.md": "# Cherry\n",
   "🥝.md": "# Kiwi\n",
+  // Two near-identical lists so `diff`/`cmp` have a small, readable change to show.
+  "shopping-old.txt": "milk\neggs\nbread\nbutter\napples\n",
+  "shopping-new.txt": "milk\neggs\nyogurt\nbread\nhoney\napples\n",
 };
 
 // Commands available in the feat_wasm build.
@@ -61,7 +73,7 @@ const FALLBACK_COMMANDS = [
   "sha1sum", "sha224sum", "sha256sum", "sha384sum", "sha512sum",
   "shred", "shuf", "sleep", "sum", "tee", "true", "truncate",
   "uname", "unexpand", "uniq", "unlink", "vdir", "wc",
-  "grep", "find",
+  "grep", "find", "diff", "cmp",
 ];
 const AVAILABLE_COMMANDS =
   (typeof WASM_COMMANDS !== "undefined" && Array.isArray(WASM_COMMANDS) && WASM_COMMANDS.length > 0)
@@ -77,10 +89,10 @@ const LOCALE_SHORTCUTS = {
 };
 
 let wasmModule = null;
-// Compiled standalone modules, keyed by command name (e.g. "grep", "find").
+// Compiled standalone modules, keyed by module name (e.g. "grep", "diffutils").
 // A key is present only once its module has loaded successfully.
 const standaloneModules = {};
-// In-flight loads, keyed by command name, so a button click and a command that
+// In-flight loads, keyed by module name, so a button click and a command that
 // both trigger a load (or two rapid clicks) share one fetch instead of racing.
 const standaloneLoading = {};
 let wasiShim = null;
@@ -180,43 +192,46 @@ async function loadWasm() {
  * without a CI build) — in which case the command reports it's unavailable
  * rather than breaking the terminal.
  *
- * When `announce` is set and a terminal exists, a "loading <cmd>… done" notice
- * is printed live; the button UI instead reacts to the `uutils:program-loaded`
- * event dispatched on success.
+ * When `announce` is set and a terminal exists, a "loading <module>… done"
+ * notice is printed live; the button UI instead reacts to the
+ * `uutils:program-loaded` event dispatched on success.
+ *
+ * Keyed by module name (e.g. "diffutils"), so commands that share a module
+ * (diff, cmp) trigger a single fetch.
  */
-function loadStandalone(cmd, { announce = false } = {}) {
-  if (standaloneModules[cmd]) return Promise.resolve(standaloneModules[cmd]);
-  if (standaloneLoading[cmd]) return standaloneLoading[cmd];
-  const url = STANDALONE_WASM_URLS[cmd];
+function loadStandalone(mod, { announce = false } = {}) {
+  if (standaloneModules[mod]) return Promise.resolve(standaloneModules[mod]);
+  if (standaloneLoading[mod]) return standaloneLoading[mod];
+  const url = STANDALONE_MODULES[mod] && STANDALONE_MODULES[mod].url;
   if (!url) return Promise.resolve(null);
   const notify = announce && terminal;
-  if (notify) terminal.write(`loading ${cmd}… `);
-  standaloneLoading[cmd] = (async () => {
+  if (notify) terminal.write(`loading ${mod}… `);
+  standaloneLoading[mod] = (async () => {
     try {
       const { module, size } = await compileWasmModule(url);
-      standaloneModules[cmd] = module;
+      standaloneModules[mod] = module;
       wasmSize += size;
       if (notify) terminal.write(`done (${(size / 1024 / 1024).toFixed(1)} MB)\r\n`);
       if (typeof document !== "undefined") {
-        document.dispatchEvent(new CustomEvent("uutils:program-loaded", { detail: { cmd, size } }));
+        document.dispatchEvent(new CustomEvent("uutils:program-loaded", { detail: { module: mod, size } }));
       }
       return module;
     } catch (e) {
-      console.warn(`${cmd} WASM unavailable:`, e.message);
+      console.warn(`${mod} WASM unavailable:`, e.message);
       if (notify) terminal.write("unavailable\r\n");
       return null;
     } finally {
-      delete standaloneLoading[cmd];
+      delete standaloneLoading[mod];
     }
   })();
-  return standaloneLoading[cmd];
+  return standaloneLoading[mod];
 }
 
 async function initWasm() {
   if (wasmReady) return;
   try {
     // Only the coreutils multicall binary loads eagerly; the standalone
-    // modules (grep, find) are fetched on demand — see loadStandalone.
+    // modules (grep, find, diffutils) are fetched on demand — see loadStandalone.
     await Promise.all([loadWasiShim(), loadWasm()]);
     wasmReady = true;
   } catch (e) {
@@ -534,6 +549,7 @@ async function executeCommandLine(line) {
       "  seq 1 10 | factor\n" +
       "  grep -i alice names.txt\n" +
       "  find . -name '*.md'\n" +
+      "  diff -u shopping-old.txt shopping-new.txt\n" +
       "  basename /usr/local/bin/rustc\n" +
       "  date\n" +
       "  uname -a\n"
@@ -607,12 +623,14 @@ async function executeCommandLine(line) {
       return `uutils: command not found: ${cmd}\nType 'help' for available commands.\n`;
     }
 
-    // Some utilities (grep, find) are separate WASM modules rather than part
-    // of the coreutils multicall binary, and are loaded on demand. Fetch the
-    // module the first time the command is used (no-op once cached).
-    const isStandalone = cmd in STANDALONE_WASM_URLS;
-    if (isStandalone && !standaloneModules[cmd]) {
-      const mod = await loadStandalone(cmd, { announce: true });
+    // Some utilities (grep, find, diff, cmp) are separate WASM modules rather
+    // than part of the coreutils multicall binary, and are loaded on demand.
+    // Fetch the module the first time one of its commands is used (no-op once
+    // cached; diff and cmp share the single diffutils module).
+    const moduleName = STANDALONE_COMMAND_MODULE[cmd];
+    const isStandalone = !!moduleName;
+    if (isStandalone && !standaloneModules[moduleName]) {
+      const mod = await loadStandalone(moduleName, { announce: true });
       if (!mod) return `${cmd} is not available in this build.\n`;
     }
 
@@ -651,7 +669,7 @@ async function executeCommandLine(line) {
           : [resolvedArgs[0], "--color=never", ...resolvedArgs.slice(1)];
       }
       const wasmArgs = isStandalone ? dispatchArgs : ["coreutils", ...resolvedArgs];
-      const result = await runCommand(wasmArgs, stdinData, isStandalone ? standaloneModules[cmd] : wasmModule);
+      const result = await runCommand(wasmArgs, stdinData, isStandalone ? standaloneModules[moduleName] : wasmModule);
       if (result.stderr) {
         return result.stderr + result.stdout;
       }
@@ -914,7 +932,7 @@ async function initPlayground(containerId) {
     terminal.writeln("");
     terminal.writeln("Type \x1b[1;32mhelp\x1b[0m for available commands.");
     terminal.writeln("Sample data files: names.txt, numbers.txt, fruits.txt, csv.txt, words.txt");
-    terminal.writeln("\x1b[2mgrep and find load on demand — just run them, or use the buttons below.\x1b[0m");
+    terminal.writeln("\x1b[2mgrep, find and diff/cmp load on demand — just run them, or use the buttons below.\x1b[0m");
   } catch (e) {
     terminal.writeln(" \x1b[1;31mfailed\x1b[0m");
     terminal.writeln("Failed to load WASM binary. Commands are not available.");
@@ -962,15 +980,16 @@ window.uutilsExecute = executeCommandLine;
 window.runInTerminal = runInTerminal;
 window.setLocale = setLocale;
 
-// On-demand loading of the optional standalone programs (grep, find), used by
-// the "Load" buttons on the playground page.
-window.uutilsPrograms = Object.keys(STANDALONE_WASM_URLS);
-window.loadProgram = (cmd) => loadStandalone(cmd);
-window.isProgramLoaded = (cmd) => !!standaloneModules[cmd];
-// Best-effort byte size of a program's module, for the button label (0 if the
-// server doesn't report Content-Length or the binary is missing).
-window.programSize = async (cmd) => {
-  const url = STANDALONE_WASM_URLS[cmd];
+// On-demand loading of the optional standalone modules (grep, find, diffutils),
+// used by the "Load" buttons on the playground page. Keyed by module name; one
+// module may back several commands (diffutils → diff, cmp).
+window.uutilsPrograms = Object.keys(STANDALONE_MODULES);
+window.loadProgram = (mod) => loadStandalone(mod);
+window.isProgramLoaded = (mod) => !!standaloneModules[mod];
+// Best-effort byte size of a module, for the button label (0 if the server
+// doesn't report Content-Length or the binary is missing).
+window.programSize = async (mod) => {
+  const url = STANDALONE_MODULES[mod] && STANDALONE_MODULES[mod].url;
   if (!url) return 0;
   try {
     const r = await fetch(url, { method: "HEAD" });
@@ -997,6 +1016,7 @@ window._uutilsTestInternals = {
   get wasmReady() { return wasmReady; },
   get grepReady() { return !!standaloneModules.grep; },
   get findReady() { return !!standaloneModules.find; },
+  get diffutilsReady() { return !!standaloneModules.diffutils; },
   initWasm,
   loadStandalone,
   LOCALE_SHORTCUTS,
diff --git a/static/js/wasm-terminal.test.html b/static/js/wasm-terminal.test.html
@@ -498,7 +498,7 @@ <h1>wasm-terminal unit tests</h1>
       // Exercises directory traversal plus a pipe into a coreutils utility.
       await assertAsync("find piped into sort",
         executeCommandLine("find . -type f -name '*.txt' | sort"),
-        "./csv.txt\n./fruits.txt\n./names.txt\n./numbers.txt\n./words.txt\n");
+        "./csv.txt\n./fruits.txt\n./names.txt\n./numbers.txt\n./shopping-new.txt\n./shopping-old.txt\n./words.txt\n");
 
       // find matches (and returns) emoji / multibyte filenames.
       await assertAsync("find emoji-named files",
@@ -508,6 +508,47 @@ <h1>wasm-terminal unit tests</h1>
       section("find WASM module (SKIPPED - find.wasm not loaded)");
     }
 
+    // ===== diff / cmp (diffutils standalone WASM module) =====
+    // diff and cmp share one module (diffutils). Pre-load it via the on-demand
+    // loader (also covers that diff and cmp resolve to the same module). Skips
+    // gracefully if diffutils.wasm is absent.
+    await T.loadStandalone("diffutils");
+    if (T.diffutilsReady) {
+      section("diffutils WASM module (diff, cmp)");
+
+      assert("diff in AVAILABLE_COMMANDS",
+        AVAILABLE_COMMANDS.includes("diff"), true);
+      assert("cmp in AVAILABLE_COMMANDS",
+        AVAILABLE_COMMANDS.includes("cmp"), true);
+
+      // Normal diff of the two near-identical shopping lists. Exact match is
+      // safe here (unlike `diff -u`, whose header carries a file mtime).
+      await assertAsync("diff (normal) shows the changed lines",
+        executeCommandLine("diff shopping-old.txt shopping-new.txt"),
+        "2a3,3\n> yogurt\n4c5\n< butter\n---\n> honey\n");
+
+      // Unified diff: assert on the stable hunk body (its --- / +++ header
+      // lines include a timestamp that varies by environment).
+      const uni = await executeCommandLine("diff -u shopping-old.txt shopping-new.txt");
+      assert("diff -u has the hunk header", uni.includes("@@ -1,5 +1,6 @@"), true);
+      assert("diff -u adds yogurt", uni.includes("\n+yogurt\n"), true);
+      assert("diff -u removes butter", uni.includes("\n-butter\n"), true);
+      assert("diff -u adds honey", uni.includes("\n+honey\n"), true);
+
+      // Identical files: no output, success.
+      await assertAsync("diff of identical files is empty",
+        executeCommandLine("diff names.txt names.txt"),
+        "");
+
+      // cmp reports the first differing byte/line. (browser_wasi_shim runs in
+      // the C locale, so cmp says "byte" rather than "char".)
+      await assertAsync("cmp reports first difference",
+        executeCommandLine("cmp shopping-old.txt shopping-new.txt"),
+        "shopping-old.txt shopping-new.txt differ: byte 11, line 3\n");
+    } else {
+      section("diffutils WASM module (SKIPPED - diffutils.wasm not loaded)");
+    }
+
   } else {
     section("l10n WASM integration (SKIPPED - WASM not loaded)");
   }
