@exodus/stasis 1.0.0-alpha.3 → 1.0.0-beta.1

package/src/audit.js

@@ -1,43 +1,6 @@
-import { readFileSync } from 'node:fs'
-import { brotliDecompressSync } from 'node:zlib'
-
 import { advisories } from './apis/npm/index.js'
 import semver from './apis/npm/semver.cjs'
-import { Bundle } from './bundle.js'
-import { Lockfile } from './lockfile.js'
-
-function parseFile(file) {
-  let buf
-  try {
-    buf = readFileSync(file)
-  } catch (cause) {
-    if (cause.code === 'ENOENT') throw new Error(`File not found: ${file}`, { cause })
-    throw new Error(`Failed to read ${file}: ${cause.message}`, { cause })
-  }
-  // Lockfiles are JSON text starting with `{`; code/resource bundles are
-  // brotli-compressed JSON. Sniff to route to the right parser so its
-  // diagnostic surfaces on failure.
-  if (buf[0] === 0x7b /* '{' */) {
-    try {
-      return Lockfile.parse(buf.toString('utf8'))
-    } catch (cause) {
-      throw new Error(`Failed to parse stasis lockfile: ${file}`, { cause })
-    }
-  }
-  let text
-  try {
-    text = brotliDecompressSync(buf).toString('utf8')
-  } catch (cause) {
-    throw new Error(`Failed to read ${file} as a stasis bundle (not brotli)`, { cause })
-  }
-  // Code bundles carry `formats`/`imports`; resource bundles don't. Route on shape.
-  try {
-    const isCode = JSON.parse(text).formats !== undefined
-    return isCode ? Bundle.parseCode(text) : Bundle.parseResources(text)
-  } catch (cause) {
-    throw new Error(`Failed to parse stasis bundle: ${file}`, { cause })
-  }
-}
+import { parseFile } from './parse.js'
 
 // Only audit installed dependencies; workspace/first-party packages live under
 // non-`node_modules` keys in .modules (Lockfile/Bundle merge sources in) and

package/src/bundle-from-lockfile.js

@@ -0,0 +1,65 @@
+import { isUtf8 } from 'node:buffer'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { sha512integrity } from '@exodus/stasis-core/state-util'
+import { moduleFileKey } from '@exodus/stasis-core/util'
+
+// Reconstruct an in-memory Bundle from a lockfile by reading every file it attests
+// from disk and verifying each against the lockfile's SRI digest -- the exact inverse
+// of `extract`'s lockfileFromBundle. A changed or tampered file fails closed here (the
+// digest won't match), so building from a lockfile is as trustworthy as a
+// `stasis run --lock=frozen` replay: the build only ever sees bytes the lockfile
+// vouches for. `root` is the project root the lockfile's paths are relative to.
+//
+// Directory captures (`stasis run --fs` readdir listings, format 'directory') are
+// skipped: they key a listing at a directory's own path, not a file esbuild could load.
+export function bundleFromLockfile(lockfile, { root }) {
+  if (!lockfile.imports) throw new Error('stasis: lockfile has no recorded import graph')
+  const formats = lockfile.formats ?? new Map()
+  const modules = new Map()
+  for (const [dir, { name, version, ecosystem, files }] of lockfile.modules) {
+    const out = Object.create(null)
+    for (const [rel, integrity] of Object.entries(files)) {
+      const file = moduleFileKey(dir, rel)
+      const format = formats.get(file)
+      if (format === 'directory') continue
+      const abs = resolve(root, file)
+      let bytes
+      try {
+        bytes = readFileSync(abs)
+      } catch (cause) {
+        throw new Error(`stasis: file attested by the lockfile is missing on disk: ${file}`, { cause })
+      }
+      // The lockfile digests raw on-disk bytes; verify against them before trusting
+      // the file. (Code and 'resource' files hash identically whether viewed as a
+      // string or bytes, since Node hashes a string as its UTF-8 bytes.)
+      const actual = sha512integrity(bytes)
+      if (actual !== integrity) {
+        throw new Error(`stasis: ${file} does not match the lockfile (expected ${integrity}, got ${actual})`)
+      }
+      // Store content the way a Bundle does: 'resource:base64' as base64 text,
+      // everything else (code, 'resource') as a raw UTF-8 string. A non-base64 entry is
+      // digested AND served as UTF-8 text, so a non-UTF-8 byte would transcode lossily
+      // (U+FFFD), diverging the served content from the verified bytes -- mirror the
+      // capture side's isUtf8 guard and fail closed instead.
+      if (format === 'resource:base64') {
+        out[rel] = bytes.toString('base64')
+      } else {
+        if (!isUtf8(bytes)) throw new Error(`stasis: ${file} is recorded as '${format ?? 'code'}' but is not valid UTF-8`)
+        out[rel] = bytes.toString('utf8')
+      }
+    }
+    modules.set(dir, ecosystem === undefined
+      ? { name, version, files: out }
+      : { name, version, ecosystem, files: out })
+  }
+  return new Bundle({
+    config: lockfile.config,
+    entries: lockfile.entries,
+    modules,
+    imports: lockfile.imports,
+    formats,
+  })
+}

package/src/bundle.js

@@ -1,217 +1,4 @@
-import {
-  assert,
-  fileMapToObject,
-  fileSetToObject,
-  fromEntries,
-  objectToMaps,
-  sortPaths,
-  splitNodeModulesPath,
-} from './util.js'
-
-const VERSION = 1
-const LEGACY_VERSION = 0
-
-const normalize = ({ name, version, files }) =>
-  ({ name, version, files: fromEntries(Object.entries(files)) })
-
-const inferModuleDir = (path) =>
-  splitNodeModulesPath(path) ?? { dir: '.', rel: path, name: null }
-
-// Bundle handles the JSON shape of stasis.code.br / stasis.resources.br;
-// callers (State) are responsible for the brotli wrapper around the JSON
-// text. On-disk version:
-//   v0 — legacy flat layout: top-level `sources` (or `resources`) keyed by
-//        project-relative path. No entries/modules metadata.
-//   v1 — current layout, mirrors stasis.lock.json: per-package buckets under
-//        `sources` (workspace) and `modules` (node_modules) with name+version+files,
-//        plus `entries`. File payloads carry bytes (UTF-8 source strings or base64
-//        resource blobs) instead of SRI digests.
-// We load both v0 and v1; we always serialize v1. v0 is converted on load to
-// the same in-memory shape — paths are regrouped by package dir via
-// `inferModuleDir` (best-effort, last-wins). name/version stay null since v0
-// records neither, which State uses as a marker to skip metadata cross-checks.
-export class Bundle {
-  static VERSION = VERSION
-
-  // The on-disk version this instance represents. Defaults to VERSION; parse*
-  // sets it to whatever the file declared (LEGACY_VERSION for v0 input).
-  // Serialization always writes the current VERSION regardless — loading v0 and
-  // re-saving promotes the bundle to v1.
-  version = VERSION
-  config
-  entries
-  modules
-  formats
-  imports
-
-  constructor({ config = { scope: 'full' }, entries, modules, formats, imports, version = VERSION } = {}) {
-    assert([LEGACY_VERSION, VERSION].includes(version))
-    assert(['node_modules', 'full'].includes(config.scope))
-    this.version = version
-    this.config = config
-    this.entries = entries ?? new Set()
-    this.modules = modules ?? new Map()
-    this.formats = formats ?? new Map()
-    this.imports = imports ?? new Map()
-  }
-
-  // Flat project-relative view of file contents collected from this.modules.
-  // Values are UTF-8 source strings for code bundles, base64 for resource bundles.
-  get sources() {
-    const m = new Map()
-    for (const [dir, { files }] of this.modules) {
-      for (const [rel, content] of Object.entries(files)) {
-        m.set(dir === '.' ? rel : `${dir}/${rel}`, content)
-      }
-    }
-    return m
-  }
-
-  static parseCode(text) {
-    const json = JSON.parse(text)
-    assert(json.version === VERSION || json.version === LEGACY_VERSION)
-    assert(['node_modules', 'full'].includes(json.config?.scope))
-    assert(json.formats)
-    assert(json.imports)
-
-    const modules = new Map()
-    let entries = new Set()
-
-    if (json.version === VERSION) {
-      const full = json.config.scope === 'full'
-      if (json.modules !== undefined) {
-        assert(typeof json.modules === 'object' && json.modules !== null)
-        for (const [dir, info] of Object.entries(json.modules)) {
-          assert(dir.includes('node_modules'))
-          assert(!dir.startsWith('..'))
-          assert(info?.name && info.version && info.files)
-          modules.set(dir, normalize(info))
-        }
-      }
-      if (full) {
-        assert(Array.isArray(json.entries))
-        // Empty entries in v1 + full would let `state.assertEntry` skip its check
-        // (it short-circuits on entries.size === 0 for v0+no-lockfile compatibility).
-        // Forbid the shape at parse time so tampered bundles can't exploit that path.
-        assert(json.entries.length > 0, 'v1 bundle with scope=full must have at least one entry')
-        assert(json.sources && typeof json.sources === 'object')
-        entries = new Set(json.entries)
-        for (const [dir, info] of Object.entries(json.sources)) {
-          assert(!dir.includes('node_modules'))
-          assert(!dir.startsWith('..'))
-          assert(info?.name && info.version && info.files)
-          modules.set(dir, normalize(info))
-        }
-      } else {
-        assert(json.entries === undefined)
-        assert(json.sources === undefined)
-      }
-      for (const [, { files }] of modules) {
-        for (const rel of Object.keys(files)) assert(!rel.startsWith('..'))
-      }
-    } else {
-      // v0 legacy: flat sources at top level, regrouped by inferred module dir.
-      assert(json.sources)
-      for (const [path, content] of Object.entries(json.sources)) {
-        assert(!path.startsWith('..'))
-        const { dir, rel, name } = inferModuleDir(path)
-        assert(!dir.startsWith('..') && !rel.startsWith('..'))
-        if (!modules.has(dir)) modules.set(dir, { name, version: null, files: Object.create(null) })
-        modules.get(dir).files[rel] = content
-      }
-    }
-
-    return new Bundle({
-      version: json.version,
-      config: json.config,
-      entries,
-      modules,
-      formats: new Map(Object.entries(json.formats)),
-      imports: objectToMaps(json.imports),
-    })
-  }
-
-  static parseResources(text) {
-    const json = JSON.parse(text)
-    assert(json.version === VERSION || json.version === LEGACY_VERSION)
-
-    const modules = new Map()
-    let config = { scope: 'full' }
-
-    if (json.version === VERSION) {
-      assert(['node_modules', 'full'].includes(json.config?.scope))
-      config = json.config
-      const full = config.scope === 'full'
-      if (json.modules !== undefined) {
-        assert(typeof json.modules === 'object' && json.modules !== null)
-        for (const [dir, info] of Object.entries(json.modules)) {
-          assert(dir.includes('node_modules'))
-          assert(!dir.startsWith('..'))
-          assert(info?.name && info.version && info.files)
-          modules.set(dir, normalize(info))
-        }
-      }
-      if (full && json.sources !== undefined) {
-        assert(typeof json.sources === 'object' && json.sources !== null)
-        for (const [dir, info] of Object.entries(json.sources)) {
-          assert(!dir.includes('node_modules'))
-          assert(!dir.startsWith('..'))
-          assert(info?.name && info.version && info.files)
-          modules.set(dir, normalize(info))
-        }
-      } else if (!full) {
-        assert(json.sources === undefined)
-      }
-      for (const [, { files }] of modules) {
-        for (const rel of Object.keys(files)) assert(!rel.startsWith('..'))
-      }
-    } else {
-      // v0 legacy: flat resources at top level, regrouped by inferred module dir.
-      assert(json.resources)
-      for (const [path, content] of Object.entries(json.resources)) {
-        assert(!path.startsWith('..'))
-        const { dir, rel, name } = inferModuleDir(path)
-        assert(!dir.startsWith('..') && !rel.startsWith('..'))
-        if (!modules.has(dir)) modules.set(dir, { name, version: null, files: Object.create(null) })
-        modules.get(dir).files[rel] = content
-      }
-    }
-
-    return new Bundle({ version: json.version, config, modules })
-  }
-
-  #groupedFromModules() {
-    const moduleEntries = []
-    const sourceEntries = []
-    for (const [dir, { name, version, files }] of this.modules) {
-      if (Object.keys(files).length === 0) continue
-      const inNodeModules = dir.includes('node_modules')
-      if (inNodeModules) assert(name && version && files)
-      const sorted = fromEntries(Object.entries(files).toSorted((a, b) => sortPaths(a[0], b[0])))
-      const target = inNodeModules ? moduleEntries : sourceEntries
-      target.push([dir, { name, version, files: sorted }])
-    }
-    moduleEntries.sort((a, b) => sortPaths(a[0], b[0]))
-    sourceEntries.sort((a, b) => sortPaths(a[0], b[0]))
-    return { modules: fromEntries(moduleEntries), sources: fromEntries(sourceEntries) }
-  }
-
-  serializeCode() {
-    const entries = fileSetToObject(this.entries)
-    const { modules, sources } = this.#groupedFromModules()
-    const formats = fileMapToObject(this.formats)
-    const imports = fileMapToObject(this.imports)
-    const data = { version: VERSION, config: this.config }
-    if (this.config.scope === 'full') Object.assign(data, { entries, sources })
-    Object.assign(data, { modules, formats, imports })
-    return JSON.stringify(data, undefined, 2)
-  }
-
-  serializeResources() {
-    const { modules, sources } = this.#groupedFromModules()
-    const data = { version: VERSION, config: this.config }
-    if (this.config.scope === 'full') Object.assign(data, { sources })
-    Object.assign(data, { modules })
-    return JSON.stringify(data, undefined, 2)
-  }
-}
+// Public-export adapter: backs `@exodus/stasis/bundle`. The implementation lives in
+// @exodus/stasis-core; internal tooling and tests import `@exodus/stasis-core/bundle`
+// directly, so this file exists only to back the package's `exports` map.
+export * from '@exodus/stasis-core/bundle'

package/src/cmd/build.js

@@ -0,0 +1,321 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, extname, join, relative, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { State } from '@exodus/stasis-core/state'
+import { StasisEsbuild } from '@exodus/stasis-plugins/esbuild'
+import { bundleFromLockfile } from '../bundle-from-lockfile.js'
+import { parseFileWithKind } from '../parse.js'
+
+// Re-exported so `@exodus/stasis/cmd/build` keeps surfacing the lockfile->bundle
+// reconstruction alongside the command; the implementation lives in its own module.
+export { bundleFromLockfile }
+
+// JS/TS entry extensions esbuild can build. esbuild handles JSX/TSX natively (loader
+// 'jsx'/'tsx', derived from the extension by the load plugin), and stasis-core already
+// classifies .jsx/.tsx as code (CODE_EXTENSIONS), so a bundle/lockfile captured by the
+// esbuild/webpack plugins can carry them as entries.
+const JS_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts', '.jsx', '.tsx'])
+
+// Allowlist (NOT a blocklist) of per-file formats `stasis build` accepts in an artifact:
+// the JS/TS/JSON code formats esbuild builds, plus the non-code payload formats
+// (resource/directory) that are inert unless the SELECTED entry imports them. An allowlist
+// so a new language format added to `stasis bundle` later (e.g. a future `go`) is rejected
+// here by default, rather than slipping through to a cryptic esbuild failure in the build.
+const BUILDABLE_FORMATS = new Set([
+  'module', 'commonjs', 'json', 'module-typescript', 'commonjs-typescript',
+  'resource', 'resource:base64', 'directory',
+])
+
+// esbuild is an OPTIONAL peer dependency: `stasis build` is the only command that
+// needs a bundler, so we don't force every stasis install to pull one in. Resolve it
+// from the local install first (a peer dep hoisted into the project's node_modules, or
+// an npx-provided copy), then fall back to a global install, with an actionable error
+// if neither is present.
+async function importEsbuild() {
+  let mod
+  try {
+    mod = await import('esbuild')
+  } catch (cause) {
+    // Only a genuine "not installed" miss falls through to the global lookup; a
+    // different failure (a corrupt install, a syntax error in esbuild) is surfaced.
+    if (cause?.code !== 'ERR_MODULE_NOT_FOUND' && cause?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+      throw cause
+    }
+    const globalMain = resolveGlobalEsbuild()
+    if (!globalMain) {
+      throw new Error(
+        'stasis build requires esbuild, which could not be found.\n' +
+        'Install it as a dev dependency (npm i -D esbuild / pnpm add -D esbuild / yarn add -D esbuild) ' +
+        'or globally (npm i -g esbuild).',
+        { cause }
+      )
+    }
+    mod = await import(pathToFileURL(globalMain).href)
+  }
+  // esbuild ships a CJS module exposing named exports (build, context, ...); Node's
+  // interop surfaces them directly. A globally-imported CJS copy may instead land its
+  // exports on `default` -- accept both shapes.
+  return typeof mod.build === 'function' ? mod : mod.default
+}
+
+// Locate a globally-installed esbuild via the package managers' "global root" commands.
+// Returns the absolute path to esbuild's entry, or undefined when none is installed.
+function resolveGlobalEsbuild() {
+  const probes = [
+    ['npm', ['root', '-g']],
+    ['pnpm', ['root', '-g']],
+    ['yarn', ['global', 'dir']],
+  ]
+  for (const [cmd, args] of probes) {
+    let out
+    try {
+      out = spawnSync(cmd, args, { encoding: 'utf8' })
+    } catch {
+      continue // package manager not installed
+    }
+    if (!out || out.status !== 0 || !out.stdout) continue
+    const base = out.stdout.trim()
+    if (!base) continue
+    // `npm/pnpm root -g` print the global node_modules dir; `yarn global dir` prints a
+    // dir whose node_modules holds the packages. Try both shapes.
+    for (const nm of [base, join(base, 'node_modules')]) {
+      if (!existsSync(join(nm, 'esbuild', 'package.json'))) continue
+      try {
+        return createRequire(join(nm, 'noop.js')).resolve('esbuild')
+      } catch {
+        // keep probing
+      }
+    }
+  }
+  return undefined
+}
+
+// Validate that an artifact is something esbuild can build: full scope (node_modules
+// scope omits the entry and workspace code, so it can't be built on its own), at least
+// one entry, all entries JS/TS, and only buildable per-file formats (see BUILDABLE_FORMATS).
+function assertBuildable(artifact, label) {
+  if (artifact.config.scope !== 'full') {
+    throw new Error(
+      `stasis build requires a full-scope artifact; ${label} is scope='${artifact.config.scope}'. ` +
+      `node_modules-scope artifacts omit the entry and workspace code, so there is nothing to build.`
+    )
+  }
+  const entries = [...artifact.entries]
+  if (entries.length === 0) {
+    throw new Error(`stasis build: ${label} declares no entries to build`)
+  }
+  for (const entry of entries) {
+    if (!JS_EXTS.has(extname(entry))) {
+      throw new Error(`stasis build only builds JavaScript/TypeScript entries (esbuild); got non-JS entry '${entry}' in ${label}`)
+    }
+  }
+  // artifact.formats is a Map (Bundle) or may be null on a legacy lockfile (an absent map
+  // is fine -- nothing to check). Reject any format outside the allowlist: the non-JS
+  // LANGUAGE bundlers' formats (Solidity/PHP/Bash/Rust) and anything added later.
+  //
+  // NOTE: resource formats are IN the allowlist -- deliberately NOT rejected here. A resource
+  // is recorded as a FILE but never as an import EDGE, so whether a build hits one depends on
+  // the SELECTED entry's own source, not the artifact as a whole -- a code-only entry must
+  // build even when the artifact carries assets for OTHER entries. An entry that does import
+  // an asset fails at build time (esbuild can't resolve the un-graphed resource).
+  for (const [file, format] of artifact.formats ?? new Map()) {
+    if (!BUILDABLE_FORMATS.has(format)) {
+      throw new Error(`stasis build only supports JavaScript/TypeScript bundles (esbuild); ${label} carries a '${format}' file (${file})`)
+    }
+  }
+}
+
+// Pick which recorded entry to build. The build produces exactly one entry's bundle;
+// `entryArg` selects it. With a single recorded entry the selector is optional (that
+// entry is used); with several it is required, and an absent or unknown one is rejected
+// with the available list. The selector is matched against the artifact's recorded
+// (project-relative) entries -- only those are attested as graph roots, and the load
+// plugin's assertEntry rejects anything else -- accepting the recorded path verbatim, a
+// leading `./` stripped, or a cwd-relative path normalized into the project root.
+function selectEntry(entryArg, entries, { cwd, root, label }) {
+  const recorded = [...entries]
+  const list = recorded.map((e) => `  ${e}`).join('\n')
+  if (entryArg === undefined) {
+    if (recorded.length === 1) return recorded[0]
+    // length === 0 is impossible here (assertBuildable required >= 1 entry).
+    throw new Error(`stasis build: ${label} has ${recorded.length} entry points; pass one as the second argument:\n${list}`)
+  }
+  const candidates = new Set([
+    entryArg,
+    entryArg.replace(/^\.\//u, ''),
+    relative(root, resolve(cwd, entryArg)).split(sep).join('/'),
+  ])
+  const match = recorded.find((e) => candidates.has(e))
+  if (match === undefined) {
+    throw new Error(`stasis build: '${entryArg}' is not an entry point of ${label}; available:\n${list}`)
+  }
+  return match
+}
+
+// Build a bundle-load State that serves an in-memory Bundle -- the same shape StasisEsbuild's
+// load path reads from (state.sources / state.resources / state.formats / state.imports /
+// state.entries). skipDiscovery anchors the State at `root` and does NO filesystem discovery:
+// no package.json walk, no on-disk config, no stray stasis.code.br read. bundle=load +
+// lock=ignore serve the bundle's own bytes (self-attesting -- the lockfile path already
+// SHA-512-verified them in bundleFromLockfile). We mirror State's on-disk load (split
+// sources/resources by format) and fill the maps from `bundle`.
+function loadStateForBundle(root, bundle) {
+  const state = new State(root, { bundle: 'load', lock: 'ignore', scope: bundle.config.scope, skipDiscovery: true })
+  const sources = new Map()
+  const resources = new Map()
+  for (const [file, content] of bundle.sources) {
+    if (Bundle.isResourceFormat(bundle.formats.get(file))) resources.set(file, content)
+    else sources.set(file, content)
+  }
+  state.sources = sources
+  state.resources = resources
+  state.formats = bundle.formats
+  state.imports = bundle.imports
+  state.entries = new Set(bundle.entries)
+  // Not state.modules: the load path (getImport/getFile/getFormat/assertEntry) never reads
+  // it -- it's only written by the capture paths. The State's empty-Map default stands.
+  return state
+}
+
+// Run the `stasis build` CLI command end-to-end: take a stasis artifact (a `stasis.code.br`
+// bundle, or a `stasis.lock.json` lockfile whose attested files are read + verified from
+// disk) and an entry point, and run esbuild over that one entry, following the artifact's
+// recorded import graph EXACTLY rather than esbuild's own resolver.
+//
+// `entry` selects which recorded entry to build (see selectEntry): optional when the
+// artifact records one, required when it records several. `output` is required: a path
+// ending in `.js`/`.cjs`/`.mjs` writes a single file, anything else a directory.
+//
+// The build runs entirely in memory off the artifact -- no temp files, and no package.json
+// required. The artifact's relative paths anchor at the artifact's OWN directory: a bundle is
+// self-contained (root is just a keying prefix; nothing is read from disk), and a lockfile
+// records its paths relative to where it sits (its project root), so its sources are read +
+// verified from there. A project stasis.config.json is not consulted -- the build is driven
+// by the artifact, not by `stasis run` config.
+//
+// The recorded graph is forced via the stasis esbuild plugin in bundle-load mode: each import
+// resolves to the edge stasis recorded (a specifier the artifact doesn't record is handed back
+// to esbuild, which externalizes it like a built-in/`external`), and each module's bytes come
+// from the artifact -- so the output reflects what stasis attested, not what's on disk.
+//
+// `format` (esm/cjs/iife, default esm), `platform` (node/browser/neutral, default node),
+// `minify`, `sourcemap`, `define` (an esbuild define map), `external` (an array of esbuild
+// external patterns), and `loader` (an esbuild extension->loader map, e.g. { '.js': 'jsx' }
+// to parse JSX in .js files) are forwarded to esbuild; the import graph is fixed by the artifact.
+//
+// `external` is esbuild's native option: it only steers specifiers esbuild itself would
+// resolve -- i.e. the ones the bundle does NOT record (handed back to esbuild as a miss,
+// typically the externals that existed at capture time). It re-declares those so esbuild
+// leaves them as runtime imports instead of trying (and failing) to resolve them on disk.
+// A specifier the artifact DOES record is still followed from the artifact -- the recorded
+// graph wins, so `external` never silently un-inlines an attested edge.
+export async function buildCommand({
+  cwd = process.cwd(),
+  artifact,
+  entry,
+  output,
+  format = 'esm',
+  platform = 'node',
+  minify = false,
+  sourcemap = false,
+  define = {},
+  external = [],
+  loader = {},
+} = {}) {
+  if (!artifact) throw new Error('stasis build: an artifact (bundle or lockfile) is required')
+  if (!output) throw new Error('stasis build: --output is required (a .js/.cjs/.mjs file, or a directory)')
+  if (!Array.isArray(external)) throw new Error('stasis build: external must be an array of esbuild patterns')
+  const artifactAbs = resolve(cwd, artifact)
+  const { kind, artifact: parsed } = parseFileWithKind(artifactAbs)
+  assertBuildable(parsed, artifact)
+
+  // Anchor the artifact's relative paths at the artifact's OWN directory. A bundle is
+  // self-contained (root is just a keying prefix; nothing is read from disk), and a lockfile
+  // records its paths relative to where it sits -- its project root -- so its sources are
+  // read + verified from there. No package.json discovery, no project stasis.config.json.
+  const root = dirname(artifactAbs)
+  const selectedEntry = selectEntry(entry, parsed.entries, { cwd, root, label: artifact })
+
+  // The Bundle the load State serves, entirely in memory. A bundle artifact is already a
+  // parsed Bundle; a lockfile is reconstructed into one by reading + SHA-512-verifying its
+  // attested files from disk (bundleFromLockfile). The plugin drives off the in-memory State.
+  const bundle = kind === 'lockfile' ? bundleFromLockfile(parsed, { root }) : parsed
+  const state = loadStateForBundle(root, bundle)
+  // The selected entry is project-relative in the artifact; make it absolute against the
+  // State's root so esbuild's entry resolution is independent of the process cwd.
+  const entryPoint = resolve(state.root, selectedEntry)
+
+  const esbuild = await importEsbuild()
+  const outAbs = resolve(cwd, output)
+  // A `.js`/`.cjs`/`.mjs` --output names a single output file; anything else is a directory.
+  const asFile = /\.[cm]?js$/u.test(output)
+  // Absolute paths the artifact attests -- esbuild must NEVER overwrite one. A stray
+  // `--output=src/x.js` (or `--output=src`/`.` whose computed output basename collides with a
+  // recorded source) would otherwise destroy an attested file: esbuild's own "refusing to
+  // overwrite input file" check fires only AFTER it has written, and for a lockfile that
+  // permanently breaks the file's hash. So we build with write:false and write the outputs
+  // ourselves, refusing -- before touching disk -- to clobber any recorded file.
+  const attested = new Set([...state.sources.keys(), ...state.resources.keys()].map((f) => resolve(state.root, f)))
+
+  let result
+  try {
+    result = await esbuild.build({
+      entryPoints: [entryPoint],
+      absWorkingDir: state.root,
+      bundle: true,
+      write: false,
+      platform,
+      format,
+      logLevel: 'silent',
+      ...(minify ? { minify: true } : {}),
+      ...(sourcemap ? { sourcemap: true } : {}),
+      ...(external.length > 0 ? { external } : {}),
+      ...(Object.keys(define).length > 0 ? { define } : {}),
+      ...(asFile ? { outfile: outAbs } : { outdir: outAbs }),
+      // Per-extension loader overrides drive the stasis plugin's load-mode loader choice
+      // (the plugin serves and labels every in-bundle file, so esbuild's own `loader`
+      // option never sees them). e.g. { '.js': 'jsx' } to parse JSX in .js files.
+      plugins: [new StasisEsbuild(state, { loaders: new Map(Object.entries(loader)) })],
+    })
+  } catch (err) {
+    // esbuild rejects with a BuildFailure carrying a formatted `.errors` array under
+    // logLevel:'silent'. Surface those (rather than the bare wrapper) so the user sees the
+    // actual resolve/load failure -- including an entry that imports an un-buildable asset
+    // -- then fail the command.
+    if (Array.isArray(err?.errors) && err.errors.length > 0) {
+      const formatted = await esbuild.formatMessages(err.errors, { kind: 'error', color: false })
+      for (const line of formatted) process.stderr.write(line)
+      throw new Error(`stasis build failed: esbuild reported ${err.errors.length} error(s)`, { cause: err })
+    }
+    throw err
+  }
+
+  // The build succeeded. Refuse to clobber an attested source -- checked against esbuild's
+  // ACTUAL output paths (so it covers both `--output` file and directory), BEFORE any write,
+  // so a rejected build leaves every recorded file intact.
+  for (const file of result.outputFiles) {
+    if (attested.has(file.path)) {
+      throw new Error(
+        `stasis build: refusing to write '${relative(cwd, file.path)}' -- it is a source the artifact records; ` +
+        `choose an --output path outside the artifact's own files`
+      )
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    const formatted = await esbuild.formatMessages(result.warnings, { kind: 'warning', color: false })
+    for (const line of formatted) process.stderr.write(line)
+  }
+
+  for (const file of result.outputFiles) {
+    mkdirSync(dirname(file.path), { recursive: true })
+    writeFileSync(file.path, file.contents)
+  }
+
+  console.warn(`[stasis] Built ${selectedEntry} from ${kind} ${artifact} to ${output}`)
+  return { entry: selectedEntry, dir: asFile ? undefined : outAbs, outfile: asFile ? outAbs : undefined }
+}