@blamejs/core 0.7.18 → 0.7.19

package/lib/bundler.js

@@ -1,441 +1,441 @@
-"use strict";
-/**
- * bundler — content-hashed asset pipeline + manifest, with optional
- * operator-supplied ESM engine for module-graph bundling, tree-shaking,
- * minification, and source maps.
- *
- * What this primitive does:
- *   - Reads each named entry from disk (or runs it through an
- *     operator-supplied engine first for module-graph builds)
- *   - Computes a content hash (SHA3-512, first 16 hex chars)
- *   - Writes the entry to outdir/<name>.<hash>.<ext> for cache-busting
- *   - Emits manifest.json mapping logical name → hashed filename
- *   - Optionally watches entries and rebuilds on change
- *
- * Engine surface (new in v0.6.44):
- *
- *   var bundler = b.bundler.create({
- *     entries: { app: "./src/app.js" },
- *     outdir:  "./public/dist",
- *     engine:  engineInstance,        // optional — defaults to passthrough
- *   });
- *
- * `engineInstance` implements:
- *
- *   {
- *     name:       string,                          // logged on build
- *     transform:  async (entryPath, contentBuf) => {
- *       content:   Buffer | string,                 // post-transform output
- *       sourceMap: string | Buffer | null,          // optional .map sibling
- *       imports?:  [string],                        // optional — for graph-aware watch
- *     },
- *   }
- *
- * The default engine is `b.bundler.engine.passthrough` — reads the file
- * verbatim, no transform. This is what every existing `b.bundler.create`
- * call gets without setting `engine`.
- *
- * For ESM module-graph bundling + tree-shake + minify + sourcemaps,
- * operators supply esbuild themselves (devDependency or operator-side
- * vendored) and adapt it via:
- *
- *   var esbuild = require("esbuild");
- *   var bundler = b.bundler.create({
- *     entries: { app: "./src/app.js" },
- *     outdir:  "./public/dist",
- *     engine:  b.bundler.engine.fromEsbuild(esbuild, {
- *       bundle:    true,
- *       format:    "esm",
- *       target:    ["chrome120", "firefox120", "safari17"],
- *       minify:    true,
- *       sourcemap: true,
- *     }),
- *   });
- *
- * The framework intentionally does NOT vendor `esbuild-wasm` itself
- * (the wasm blob is ~10 MB — bigger than every other vendored dep
- * combined; it would 3-5x the @blamejs/core npm tarball for a build-
- * time tool most operators only need at deploy time anyway). Treating
- * esbuild as an operator-supplied driver follows the same pattern as
- * `b.externalDb` and `b.mtlsCa.create({ engine })`: the framework owns
- * the integration seam, the operator brings the heavy machinery.
- *
- * Out of scope (true even with the engine surface):
- *   - A bespoke bundler bundled INSIDE the framework. The engine
- *     surface IS the answer; operators wanting esbuild / rollup /
- *     swc / vite wire them through it.
- *
- * Operator with no engine + multi-file ESM source: pre-concat manually
- * and point bundler at the result.
- *
- * Manifest format (manifest.json under outdir):
- *   { "app": "app.4a8c2f1d9e3b7062.js", "styles": "styles.b29f1e7c.css" }
- *
- * Integrates with lib/static.js: serve `outdir` as a static directory;
- * lib/static.js's hashed-path detection sets long-cache headers on
- * files that look hashed, and integrity() reads the manifest to
- * generate Subresource Integrity attributes.
- */
-
-var path = require("path");
-var fs = require("fs");
-var crypto = require("./crypto");
-var atomicFile = require("./atomic-file");
-var logModule = require("./log");
-var nb = require("./numeric-bounds");
-var safeJson = require("./safe-json");
-var validateOpts = require("./validate-opts");
-var { defineClass } = require("./framework-error");
-
-var BundlerError = defineClass("BundlerError", { alwaysPermanent: true });
-var bootLog = logModule.boot("bundler");
-
-// Default content-hash length: 16 hex chars (8 bytes of SHA3-512). Long
-// enough that collision probability is negligible for asset cache busting,
-// short enough to keep generated filenames readable.
-var DEFAULT_HASH_LEN = 0x10;
-var MIN_HASH_LEN     = 0x4;
-var MAX_HASH_LEN     = 0x40;
-var DEFAULT_GRACE_MS = 100;
-
-function _hashContent(buf, hexLen) {
-  // SHA3-512 → take the first hexLen hex chars. Same family as the
-  // framework's other content fingerprints (no SHA-256 for new code).
-  return crypto.sha3Hash(buf).slice(0, hexLen);
-}
-
-function _hashedName(baseName, hash, ext) {
-  return baseName + "." + hash + ext;
-}
-
-// outDir mode is 0o755 (world-readable) because the bundler emits
-// assets a public HTTP server reads. Other framework dirs default to
-// 0o700 via atomicFile.ensureDir.
-function _ensureOutDir(p) {
-  try { atomicFile.ensureDir(p, 0o755); }
-  catch (e) {
-    if (e && e.code !== "EEXIST") {
-      throw new BundlerError("bundler/mkdir-failed",
-        "could not create outdir '" + p + "': " + ((e && e.message) || String(e)));
-    }
-  }
-}
-
-function _validateEntries(entries) {
-  if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
-    throw new BundlerError("bundler/no-entries",
-      "bundler.create requires opts.entries (a { name: path } map)");
-  }
-  var names = Object.keys(entries);
-  if (names.length === 0) {
-    throw new BundlerError("bundler/no-entries",
-      "bundler.create: opts.entries map must have at least one entry");
-  }
-  // Reject names with path separators or '..' so operator-supplied
-  // logical names can't escape the outdir on write.
-  for (var i = 0; i < names.length; i++) {
-    var n = names[i];
-    if (typeof n !== "string" || n.length === 0 ||
-        /[\\/]/.test(n) || n === ".." || n === ".") {
-      throw new BundlerError("bundler/bad-entry-name",
-        "entry name '" + n + "' must be a non-empty string without path separators");
-    }
-    var p = entries[n];
-    if (typeof p !== "string" || p.length === 0) {
-      throw new BundlerError("bundler/bad-entry-path",
-        "entry '" + n + "' must map to a non-empty source path");
-    }
-  }
-}
-
-// ---- Engine surface ----
-//
-// Engines transform an entry's content before the cache-busting / hash
-// step. The default `passthrough` engine reads the file verbatim — same
-// behavior every pre-v0.6.44 caller got. Operators wanting ESM
-// module-graph bundling supply esbuild (or any compatible tool) and
-// adapt it via `engine.fromEsbuild(esbuild, opts)`.
-var engine = {
-  passthrough: {
-    name: "passthrough",
-    transform: async function (_entryPath, contentBuf) {
-      return { content: contentBuf, sourceMap: null };
-    },
-  },
-
-  fromEsbuild: function (esbuild, esbuildOpts) {
-    if (!esbuild || typeof esbuild.build !== "function") {
-      throw new BundlerError("bundler/bad-engine",
-        "engine.fromEsbuild: pass the esbuild module (require('esbuild')); " +
-        "got " + typeof esbuild);
-    }
-    var baseOpts = Object.assign({
-      bundle:     true,
-      write:      false,
-      format:     "esm",
-      platform:   "browser",
-      logLevel:   "silent",
-    }, esbuildOpts || {});
-    return {
-      name: "esbuild",
-      transform: async function (entryPath, _contentBuf) {
-        var rv = await esbuild.build(Object.assign({}, baseOpts, {
-          entryPoints: [entryPath],
-        }));
-        // esbuild { write: false } returns { outputFiles: [{ path, contents }, ...] }.
-        // For a single entry without sourcemaps we get one file; with
-        // sourcemap we get the .js + .js.map. Match by extension.
-        var outFiles = (rv && rv.outputFiles) || [];
-        var jsLike = null;
-        var map    = null;
-        for (var i = 0; i < outFiles.length; i++) {
-          var f = outFiles[i];
-          if (/\.map$/.test(f.path)) map = f.text;
-          else jsLike = f;
-        }
-        if (!jsLike) {
-          throw new BundlerError("bundler/engine-empty",
-            "esbuild engine returned no output for " + entryPath);
-        }
-        return {
-          content:   Buffer.from(jsLike.contents),
-          sourceMap: map,
-        };
-      },
-    };
-  },
-};
-
-function _validateEngine(eng) {
-  if (eng == null) return engine.passthrough;
-  if (typeof eng !== "object") {
-    throw new BundlerError("bundler/bad-engine",
-      "opts.engine must be an object with { name, transform }, got " + typeof eng);
-  }
-  if (typeof eng.transform !== "function") {
-    throw new BundlerError("bundler/bad-engine",
-      "opts.engine.transform must be a function (entryPath, contentBuf) → " +
-      "{ content, sourceMap? }");
-  }
-  if (typeof eng.name !== "string" || eng.name.length === 0) {
-    throw new BundlerError("bundler/bad-engine",
-      "opts.engine.name must be a non-empty string");
-  }
-  return eng;
-}
-
-function create(opts) {
-  opts = opts || {};
-  validateOpts(opts, [
-    "entries", "outdir", "cwd", "engine",
-    "manifest", "hash", "hashLen", "graceMs", "log",
-    "_watch", "_setTimeout", "_clearTimeout",
-  ], "b.bundler");
-  _validateEntries(opts.entries);
-  validateOpts.requireNonEmptyString(opts.outdir, "bundler.create: opts.outdir", BundlerError, "bundler/no-outdir");
-  var engineImpl = _validateEngine(opts.engine);
-
-  var entries     = Object.assign({}, opts.entries);
-  var cwd         = opts.cwd || process.cwd();
-  var outdir      = path.isAbsolute(opts.outdir) ? opts.outdir : path.resolve(cwd, opts.outdir);
-  var manifestName = (opts.manifest === false || opts.manifest === null)
-    ? null
-    : (typeof opts.manifest === "string" && opts.manifest.length > 0
-        ? opts.manifest
-        : "manifest.json");
-  var hashOn   = opts.hash !== false;
-  var hashLen  = DEFAULT_HASH_LEN;
-  if (opts.hashLen !== undefined) {
-    if (!nb.isPositiveFiniteInt(opts.hashLen) ||
-        opts.hashLen < MIN_HASH_LEN || opts.hashLen > MAX_HASH_LEN) {
-      throw new BundlerError("bundler/bad-hash-len",
-        "bundler.create: opts.hashLen must be a positive finite integer " +
-        "between " + MIN_HASH_LEN + " and " + MAX_HASH_LEN +
-        "; got " + nb.shape(opts.hashLen));
-    }
-    hashLen = opts.hashLen;
-  }
-  var log      = opts.log || null;
-
-  // Test seam: tests pass a fake watcher so we don't actually fs.watch
-  var watchFn = opts._watch || function (dirOrFile, wopts, listener) {
-    return fs.watch(dirOrFile, wopts, listener);
-  };
-  var setTimeoutFn  = opts._setTimeout  || setTimeout;
-  var clearTimeoutFn = opts._clearTimeout || clearTimeout;
-  nb.requireNonNegativeFiniteIntIfPresent(opts.graceMs,
-    "bundler.create: opts.graceMs", BundlerError, "bundler/bad-grace-ms");
-  var graceMs = opts.graceMs !== undefined ? opts.graceMs : DEFAULT_GRACE_MS;
-
-  var watchers      = [];
-  var debounceTimer = null;
-  var watching      = false;
-
-  function _resolveEntry(p) {
-    return path.isAbsolute(p) ? p : path.resolve(cwd, p);
-  }
-
-  var _logVia = logModule.makeViaOrFallback(log, bootLog);
-
-  async function build() {
-    var t0 = Date.now();
-    _ensureOutDir(outdir);
-
-    var outputs = [];
-    var manifest = {};
-    var names = Object.keys(entries);
-
-    for (var i = 0; i < names.length; i++) {
-      var name = names[i];
-      var entryPath = _resolveEntry(entries[name]);
-      var ext = path.extname(entryPath);
-      var raw;
-      try { raw = fs.readFileSync(entryPath); }
-      catch (e) {
-        throw new BundlerError("bundler/read-failed",
-          "could not read entry '" + name + "' at " + entryPath +
-          ": " + ((e && e.message) || String(e)));
-      }
-      var transformed;
-      try { transformed = await engineImpl.transform(entryPath, raw); }
-      catch (e) {
-        throw new BundlerError("bundler/engine-failed",
-          "engine '" + engineImpl.name + "' failed on entry '" + name +
-          "': " + ((e && e.message) || String(e)));
-      }
-      var content = transformed && transformed.content != null ? transformed.content : raw;
-      if (typeof content === "string") content = Buffer.from(content, "utf8");
-      else if (!Buffer.isBuffer(content)) {
-        throw new BundlerError("bundler/engine-bad-output",
-          "engine '" + engineImpl.name + "' returned non-Buffer / non-string content for '" +
-          name + "'");
-      }
-      var sourceMap = transformed && transformed.sourceMap;
-      var hash = hashOn ? _hashContent(content, hashLen) : null;
-      var outName = hashOn ? _hashedName(name, hash, ext) : (name + ext);
-      var outPath = path.join(outdir, outName);
-      // atomic-file write so a concurrent reader (the http server
-      // serving outdir) never sees a partial file
-      atomicFile.writeSync(outPath, content, { mode: 0o644 });
-      // Sibling .map when the engine produced one. Source maps go
-      // unhashed (browsers fetch <hashed.js>.map) — write them
-      // alongside as <hashedOutName>.map.
-      var sourceMapPath = null;
-      if (sourceMap) {
-        sourceMapPath = outPath + ".map";
-        var mapBuf = Buffer.isBuffer(sourceMap) ? sourceMap : Buffer.from(String(sourceMap), "utf8");
-        atomicFile.writeSync(sourceMapPath, mapBuf, { mode: 0o644 });
-      }
-      outputs.push({
-        name:          name,
-        entry:         entryPath,
-        path:          outPath,
-        hash:          hash,
-        bytes:         content.length,
-        ext:           ext,
-        sourceMapPath: sourceMapPath,
-      });
-      manifest[name] = outName;
-    }
-
-    var manifestPath = null;
-    if (manifestName) {
-      manifestPath = path.join(outdir, manifestName);
-      atomicFile.writeSync(
-        manifestPath,
-        safeJson.stringify(manifest, null, 2) + "\n",
-        { mode: 0o644 }
-      );
-    }
-
-    var result = {
-      outputs:      outputs,
-      manifestPath: manifestPath,
-      manifest:     manifest,
-      durationMs:   Date.now() - t0,
-    };
-    _logVia("info", "build complete",
-      { entries: outputs.length, durationMs: result.durationMs });
-    return result;
-  }
-
-  function _scheduleRebuild(reason, callback) {
-    if (debounceTimer) {
-      try { clearTimeoutFn(debounceTimer); } catch (_e) { /* timer already cleared */ }
-    }
-    debounceTimer = setTimeoutFn(function () {
-      debounceTimer = null;
-      _logVia("info", "rebuilding", { reason: reason });
-      build().then(
-        function (r) { if (callback) try { callback(null, r); } catch (_e) { /* operator callback threw — logged elsewhere if material */ } },
-        function (e) {
-          _logVia("error", "rebuild failed", { error: (e && e.message) || String(e) });
-          if (callback) try { callback(e, null); } catch (_e) { /* operator callback threw — already logged */ }
-        }
-      );
-    }, graceMs);
-    if (debounceTimer && typeof debounceTimer.unref === "function") debounceTimer.unref();
-  }
-
-  function watch(callback) {
-    if (watching) return;
-    watching = true;
-    var names = Object.keys(entries);
-    for (var i = 0; i < names.length; i++) {
-      (function (name) {
-        var entryPath = _resolveEntry(entries[name]);
-        // Watch the entry's directory (single-file watches are flaky
-        // across editors that write-then-rename). Filter events to the
-        // entry's basename only.
-        var dir = path.dirname(entryPath);
-        var base = path.basename(entryPath);
-        var w;
-        try {
-          w = watchFn(dir, { persistent: false }, function (eventType, filename) {
-            if (filename && String(filename) === base) {
-              _scheduleRebuild(name, callback);
-            }
-          });
-        } catch (e) {
-          _logVia("warn", "could not watch " + dir,
-            { error: (e && e.message) || String(e) });
-          return;
-        }
-        if (w && typeof w.on === "function") {
-          w.on("error", function (err) {
-            _logVia("warn", "watcher error",
-              { dir: dir, error: (err && err.message) || String(err) });
-          });
-        }
-        watchers.push(w);
-      })(names[i]);
-    }
-  }
-
-  async function close() {
-    watching = false;
-    if (debounceTimer) {
-      try { clearTimeoutFn(debounceTimer); } catch (_e) { /* timer already cleared */ }
-      debounceTimer = null;
-    }
-    for (var i = 0; i < watchers.length; i++) {
-      try { if (watchers[i] && typeof watchers[i].close === "function") watchers[i].close(); }
-      catch (_e) { /* close best-effort */ }
-    }
-    watchers = [];
-  }
-
-  return {
-    build:    build,
-    watch:    watch,
-    close:    close,
-    entries:  entries,
-    outdir:   outdir,
-  };
-}
-
-module.exports = {
-  create:        create,
-  engine:        engine,
-  BundlerError:  BundlerError,
-};
+"use strict";
+/**
+ * bundler — content-hashed asset pipeline + manifest, with optional
+ * operator-supplied ESM engine for module-graph bundling, tree-shaking,
+ * minification, and source maps.
+ *
+ * What this primitive does:
+ *   - Reads each named entry from disk (or runs it through an
+ *     operator-supplied engine first for module-graph builds)
+ *   - Computes a content hash (SHA3-512, first 16 hex chars)
+ *   - Writes the entry to outdir/<name>.<hash>.<ext> for cache-busting
+ *   - Emits manifest.json mapping logical name → hashed filename
+ *   - Optionally watches entries and rebuilds on change
+ *
+ * Engine surface (new in v0.6.44):
+ *
+ *   var bundler = b.bundler.create({
+ *     entries: { app: "./src/app.js" },
+ *     outdir:  "./public/dist",
+ *     engine:  engineInstance,        // optional — defaults to passthrough
+ *   });
+ *
+ * `engineInstance` implements:
+ *
+ *   {
+ *     name:       string,                          // logged on build
+ *     transform:  async (entryPath, contentBuf) => {
+ *       content:   Buffer | string,                 // post-transform output
+ *       sourceMap: string | Buffer | null,          // optional .map sibling
+ *       imports?:  [string],                        // optional — for graph-aware watch
+ *     },
+ *   }
+ *
+ * The default engine is `b.bundler.engine.passthrough` — reads the file
+ * verbatim, no transform. This is what every existing `b.bundler.create`
+ * call gets without setting `engine`.
+ *
+ * For ESM module-graph bundling + tree-shake + minify + sourcemaps,
+ * operators supply esbuild themselves (devDependency or operator-side
+ * vendored) and adapt it via:
+ *
+ *   var esbuild = require("esbuild");
+ *   var bundler = b.bundler.create({
+ *     entries: { app: "./src/app.js" },
+ *     outdir:  "./public/dist",
+ *     engine:  b.bundler.engine.fromEsbuild(esbuild, {
+ *       bundle:    true,
+ *       format:    "esm",
+ *       target:    ["chrome120", "firefox120", "safari17"],
+ *       minify:    true,
+ *       sourcemap: true,
+ *     }),
+ *   });
+ *
+ * The framework intentionally does NOT vendor `esbuild-wasm` itself
+ * (the wasm blob is ~10 MB — bigger than every other vendored dep
+ * combined; it would 3-5x the @blamejs/core npm tarball for a build-
+ * time tool most operators only need at deploy time anyway). Treating
+ * esbuild as an operator-supplied driver follows the same pattern as
+ * `b.externalDb` and `b.mtlsCa.create({ engine })`: the framework owns
+ * the integration seam, the operator brings the heavy machinery.
+ *
+ * Out of scope (true even with the engine surface):
+ *   - A bespoke bundler bundled INSIDE the framework. The engine
+ *     surface IS the answer; operators wanting esbuild / rollup /
+ *     swc / vite wire them through it.
+ *
+ * Operator with no engine + multi-file ESM source: pre-concat manually
+ * and point bundler at the result.
+ *
+ * Manifest format (manifest.json under outdir):
+ *   { "app": "app.4a8c2f1d9e3b7062.js", "styles": "styles.b29f1e7c.css" }
+ *
+ * Integrates with lib/static.js: serve `outdir` as a static directory;
+ * lib/static.js's hashed-path detection sets long-cache headers on
+ * files that look hashed, and integrity() reads the manifest to
+ * generate Subresource Integrity attributes.
+ */
+
+var path = require("path");
+var fs = require("fs");
+var crypto = require("./crypto");
+var atomicFile = require("./atomic-file");
+var logModule = require("./log");
+var nb = require("./numeric-bounds");
+var safeJson = require("./safe-json");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var BundlerError = defineClass("BundlerError", { alwaysPermanent: true });
+var bootLog = logModule.boot("bundler");
+
+// Default content-hash length: 16 hex chars (8 bytes of SHA3-512). Long
+// enough that collision probability is negligible for asset cache busting,
+// short enough to keep generated filenames readable.
+var DEFAULT_HASH_LEN = 0x10;
+var MIN_HASH_LEN     = 0x4;
+var MAX_HASH_LEN     = 0x40;
+var DEFAULT_GRACE_MS = 100;
+
+function _hashContent(buf, hexLen) {
+  // SHA3-512 → take the first hexLen hex chars. Same family as the
+  // framework's other content fingerprints (no SHA-256 for new code).
+  return crypto.sha3Hash(buf).slice(0, hexLen);
+}
+
+function _hashedName(baseName, hash, ext) {
+  return baseName + "." + hash + ext;
+}
+
+// outDir mode is 0o755 (world-readable) because the bundler emits
+// assets a public HTTP server reads. Other framework dirs default to
+// 0o700 via atomicFile.ensureDir.
+function _ensureOutDir(p) {
+  try { atomicFile.ensureDir(p, 0o755); }
+  catch (e) {
+    if (e && e.code !== "EEXIST") {
+      throw new BundlerError("bundler/mkdir-failed",
+        "could not create outdir '" + p + "': " + ((e && e.message) || String(e)));
+    }
+  }
+}
+
+function _validateEntries(entries) {
+  if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+    throw new BundlerError("bundler/no-entries",
+      "bundler.create requires opts.entries (a { name: path } map)");
+  }
+  var names = Object.keys(entries);
+  if (names.length === 0) {
+    throw new BundlerError("bundler/no-entries",
+      "bundler.create: opts.entries map must have at least one entry");
+  }
+  // Reject names with path separators or '..' so operator-supplied
+  // logical names can't escape the outdir on write.
+  for (var i = 0; i < names.length; i++) {
+    var n = names[i];
+    if (typeof n !== "string" || n.length === 0 ||
+        /[\\/]/.test(n) || n === ".." || n === ".") {
+      throw new BundlerError("bundler/bad-entry-name",
+        "entry name '" + n + "' must be a non-empty string without path separators");
+    }
+    var p = entries[n];
+    if (typeof p !== "string" || p.length === 0) {
+      throw new BundlerError("bundler/bad-entry-path",
+        "entry '" + n + "' must map to a non-empty source path");
+    }
+  }
+}
+
+// ---- Engine surface ----
+//
+// Engines transform an entry's content before the cache-busting / hash
+// step. The default `passthrough` engine reads the file verbatim — same
+// behavior every pre-v0.6.44 caller got. Operators wanting ESM
+// module-graph bundling supply esbuild (or any compatible tool) and
+// adapt it via `engine.fromEsbuild(esbuild, opts)`.
+var engine = {
+  passthrough: {
+    name: "passthrough",
+    transform: async function (_entryPath, contentBuf) {
+      return { content: contentBuf, sourceMap: null };
+    },
+  },
+
+  fromEsbuild: function (esbuild, esbuildOpts) {
+    if (!esbuild || typeof esbuild.build !== "function") {
+      throw new BundlerError("bundler/bad-engine",
+        "engine.fromEsbuild: pass the esbuild module (require('esbuild')); " +
+        "got " + typeof esbuild);
+    }
+    var baseOpts = Object.assign({
+      bundle:     true,
+      write:      false,
+      format:     "esm",
+      platform:   "browser",
+      logLevel:   "silent",
+    }, esbuildOpts || {});
+    return {
+      name: "esbuild",
+      transform: async function (entryPath, _contentBuf) {
+        var rv = await esbuild.build(Object.assign({}, baseOpts, {
+          entryPoints: [entryPath],
+        }));
+        // esbuild { write: false } returns { outputFiles: [{ path, contents }, ...] }.
+        // For a single entry without sourcemaps we get one file; with
+        // sourcemap we get the .js + .js.map. Match by extension.
+        var outFiles = (rv && rv.outputFiles) || [];
+        var jsLike = null;
+        var map    = null;
+        for (var i = 0; i < outFiles.length; i++) {
+          var f = outFiles[i];
+          if (/\.map$/.test(f.path)) map = f.text;
+          else jsLike = f;
+        }
+        if (!jsLike) {
+          throw new BundlerError("bundler/engine-empty",
+            "esbuild engine returned no output for " + entryPath);
+        }
+        return {
+          content:   Buffer.from(jsLike.contents),
+          sourceMap: map,
+        };
+      },
+    };
+  },
+};
+
+function _validateEngine(eng) {
+  if (eng == null) return engine.passthrough;
+  if (typeof eng !== "object") {
+    throw new BundlerError("bundler/bad-engine",
+      "opts.engine must be an object with { name, transform }, got " + typeof eng);
+  }
+  if (typeof eng.transform !== "function") {
+    throw new BundlerError("bundler/bad-engine",
+      "opts.engine.transform must be a function (entryPath, contentBuf) → " +
+      "{ content, sourceMap? }");
+  }
+  if (typeof eng.name !== "string" || eng.name.length === 0) {
+    throw new BundlerError("bundler/bad-engine",
+      "opts.engine.name must be a non-empty string");
+  }
+  return eng;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "entries", "outdir", "cwd", "engine",
+    "manifest", "hash", "hashLen", "graceMs", "log",
+    "_watch", "_setTimeout", "_clearTimeout",
+  ], "b.bundler");
+  _validateEntries(opts.entries);
+  validateOpts.requireNonEmptyString(opts.outdir, "bundler.create: opts.outdir", BundlerError, "bundler/no-outdir");
+  var engineImpl = _validateEngine(opts.engine);
+
+  var entries     = Object.assign({}, opts.entries);
+  var cwd         = opts.cwd || process.cwd();
+  var outdir      = path.isAbsolute(opts.outdir) ? opts.outdir : path.resolve(cwd, opts.outdir);
+  var manifestName = (opts.manifest === false || opts.manifest === null)
+    ? null
+    : (typeof opts.manifest === "string" && opts.manifest.length > 0
+        ? opts.manifest
+        : "manifest.json");
+  var hashOn   = opts.hash !== false;
+  var hashLen  = DEFAULT_HASH_LEN;
+  if (opts.hashLen !== undefined) {
+    if (!nb.isPositiveFiniteInt(opts.hashLen) ||
+        opts.hashLen < MIN_HASH_LEN || opts.hashLen > MAX_HASH_LEN) {
+      throw new BundlerError("bundler/bad-hash-len",
+        "bundler.create: opts.hashLen must be a positive finite integer " +
+        "between " + MIN_HASH_LEN + " and " + MAX_HASH_LEN +
+        "; got " + nb.shape(opts.hashLen));
+    }
+    hashLen = opts.hashLen;
+  }
+  var log      = opts.log || null;
+
+  // Test seam: tests pass a fake watcher so we don't actually fs.watch
+  var watchFn = opts._watch || function (dirOrFile, wopts, listener) {
+    return fs.watch(dirOrFile, wopts, listener);
+  };
+  var setTimeoutFn  = opts._setTimeout  || setTimeout;
+  var clearTimeoutFn = opts._clearTimeout || clearTimeout;
+  nb.requireNonNegativeFiniteIntIfPresent(opts.graceMs,
+    "bundler.create: opts.graceMs", BundlerError, "bundler/bad-grace-ms");
+  var graceMs = opts.graceMs !== undefined ? opts.graceMs : DEFAULT_GRACE_MS;
+
+  var watchers      = [];
+  var debounceTimer = null;
+  var watching      = false;
+
+  function _resolveEntry(p) {
+    return path.isAbsolute(p) ? p : path.resolve(cwd, p);
+  }
+
+  var _logVia = logModule.makeViaOrFallback(log, bootLog);
+
+  async function build() {
+    var t0 = Date.now();
+    _ensureOutDir(outdir);
+
+    var outputs = [];
+    var manifest = {};
+    var names = Object.keys(entries);
+
+    for (var i = 0; i < names.length; i++) {
+      var name = names[i];
+      var entryPath = _resolveEntry(entries[name]);
+      var ext = path.extname(entryPath);
+      var raw;
+      try { raw = fs.readFileSync(entryPath); }
+      catch (e) {
+        throw new BundlerError("bundler/read-failed",
+          "could not read entry '" + name + "' at " + entryPath +
+          ": " + ((e && e.message) || String(e)));
+      }
+      var transformed;
+      try { transformed = await engineImpl.transform(entryPath, raw); }
+      catch (e) {
+        throw new BundlerError("bundler/engine-failed",
+          "engine '" + engineImpl.name + "' failed on entry '" + name +
+          "': " + ((e && e.message) || String(e)));
+      }
+      var content = transformed && transformed.content != null ? transformed.content : raw;
+      if (typeof content === "string") content = Buffer.from(content, "utf8");
+      else if (!Buffer.isBuffer(content)) {
+        throw new BundlerError("bundler/engine-bad-output",
+          "engine '" + engineImpl.name + "' returned non-Buffer / non-string content for '" +
+          name + "'");
+      }
+      var sourceMap = transformed && transformed.sourceMap;
+      var hash = hashOn ? _hashContent(content, hashLen) : null;
+      var outName = hashOn ? _hashedName(name, hash, ext) : (name + ext);
+      var outPath = path.join(outdir, outName);
+      // atomic-file write so a concurrent reader (the http server
+      // serving outdir) never sees a partial file
+      atomicFile.writeSync(outPath, content, { mode: 0o644 });
+      // Sibling .map when the engine produced one. Source maps go
+      // unhashed (browsers fetch <hashed.js>.map) — write them
+      // alongside as <hashedOutName>.map.
+      var sourceMapPath = null;
+      if (sourceMap) {
+        sourceMapPath = outPath + ".map";
+        var mapBuf = Buffer.isBuffer(sourceMap) ? sourceMap : Buffer.from(String(sourceMap), "utf8");
+        atomicFile.writeSync(sourceMapPath, mapBuf, { mode: 0o644 });
+      }
+      outputs.push({
+        name:          name,
+        entry:         entryPath,
+        path:          outPath,
+        hash:          hash,
+        bytes:         content.length,
+        ext:           ext,
+        sourceMapPath: sourceMapPath,
+      });
+      manifest[name] = outName;
+    }
+
+    var manifestPath = null;
+    if (manifestName) {
+      manifestPath = path.join(outdir, manifestName);
+      atomicFile.writeSync(
+        manifestPath,
+        safeJson.stringify(manifest, null, 2) + "\n",
+        { mode: 0o644 }
+      );
+    }
+
+    var result = {
+      outputs:      outputs,
+      manifestPath: manifestPath,
+      manifest:     manifest,
+      durationMs:   Date.now() - t0,
+    };
+    _logVia("info", "build complete",
+      { entries: outputs.length, durationMs: result.durationMs });
+    return result;
+  }
+
+  function _scheduleRebuild(reason, callback) {
+    if (debounceTimer) {
+      try { clearTimeoutFn(debounceTimer); } catch (_e) { /* timer already cleared */ }
+    }
+    debounceTimer = setTimeoutFn(function () {
+      debounceTimer = null;
+      _logVia("info", "rebuilding", { reason: reason });
+      build().then(
+        function (r) { if (callback) try { callback(null, r); } catch (_e) { /* operator callback threw — logged elsewhere if material */ } },
+        function (e) {
+          _logVia("error", "rebuild failed", { error: (e && e.message) || String(e) });
+          if (callback) try { callback(e, null); } catch (_e) { /* operator callback threw — already logged */ }
+        }
+      );
+    }, graceMs);
+    if (debounceTimer && typeof debounceTimer.unref === "function") debounceTimer.unref();
+  }
+
+  function watch(callback) {
+    if (watching) return;
+    watching = true;
+    var names = Object.keys(entries);
+    for (var i = 0; i < names.length; i++) {
+      (function (name) {
+        var entryPath = _resolveEntry(entries[name]);
+        // Watch the entry's directory (single-file watches are flaky
+        // across editors that write-then-rename). Filter events to the
+        // entry's basename only.
+        var dir = path.dirname(entryPath);
+        var base = path.basename(entryPath);
+        var w;
+        try {
+          w = watchFn(dir, { persistent: false }, function (eventType, filename) {
+            if (filename && String(filename) === base) {
+              _scheduleRebuild(name, callback);
+            }
+          });
+        } catch (e) {
+          _logVia("warn", "could not watch " + dir,
+            { error: (e && e.message) || String(e) });
+          return;
+        }
+        if (w && typeof w.on === "function") {
+          w.on("error", function (err) {
+            _logVia("warn", "watcher error",
+              { dir: dir, error: (err && err.message) || String(err) });
+          });
+        }
+        watchers.push(w);
+      })(names[i]);
+    }
+  }
+
+  async function close() {
+    watching = false;
+    if (debounceTimer) {
+      try { clearTimeoutFn(debounceTimer); } catch (_e) { /* timer already cleared */ }
+      debounceTimer = null;
+    }
+    for (var i = 0; i < watchers.length; i++) {
+      try { if (watchers[i] && typeof watchers[i].close === "function") watchers[i].close(); }
+      catch (_e) { /* close best-effort */ }
+    }
+    watchers = [];
+  }
+
+  return {
+    build:    build,
+    watch:    watch,
+    close:    close,
+    entries:  entries,
+    outdir:   outdir,
+  };
+}
+
+module.exports = {
+  create:        create,
+  engine:        engine,
+  BundlerError:  BundlerError,
+};