@exodus/stasis 1.0.0-beta.2 → 1.0.0-beta.5

package/src/json-stream.js

@@ -0,0 +1,283 @@
+// Incremental JSON parser over UTF-8 bytes, holding only the value being built and one token in flight.
+// Exactly JSON.parse(Buffer.concat(chunks).toString('utf8')) for any chunking (json-stream.test.js checks it),
+// so a bundle read in a stream can't parse differently from one read whole. Pure: no Node builtins.
+// Not mirrored: Node 24+'s JSON.parse can return a stale escaped key cached by an earlier call (a V8 bug).
+
+const QUOTE = 0x22
+const BACKSLASH = 0x5c
+
+// What the next significant byte may be.
+const VALUE = 0 // any value: the top level, after ':' or after an array's ','
+const ARRAY_FIRST = 1 // after '[': a value or ']'
+const OBJECT_FIRST = 2 // after '{': a key or '}'
+const KEY = 3 // after an object's ',': a key
+const COLON = 4
+const AFTER = 5 // after a member or element: ',' or the container's closer
+const DONE = 6 // the top-level value is complete: whitespace only
+// Inside a token that can straddle chunks.
+const STRING = 7
+const NUMBER = 8
+const LITERAL = 9
+
+const NUMBER_RE = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/u
+const LITERALS = new Map([['true', true], ['false', false], ['null', null]])
+
+const isWhitespace = (b) => b === 0x20 || b === 0x0a || b === 0x0d || b === 0x09
+// The bytes a number can span; NUMBER_RE checks its grammar once it ends.
+const isNumberByte = (b) => (b >= 0x30 && b <= 0x39) || b === 0x2d || b === 0x2b || b === 0x2e || b === 0x65 || b === 0x45
+const isLetter = (b) => b >= 0x61 && b <= 0x7a
+
+const hasControlByte = (bytes) => {
+  for (let i = 0; i < bytes.length; i++) if (bytes[i] < 0x20) return true
+  return false
+}
+
+const indexOrEnd = (bytes, byte, from) => {
+  const at = bytes.indexOf(byte, from)
+  return at === -1 ? bytes.length : at
+}
+
+const concat = (parts) => {
+  let length = 0
+  for (const part of parts) length += part.length
+  const out = new Uint8Array(length)
+  let offset = 0
+  for (const part of parts) {
+    out.set(part, offset)
+    offset += part.length
+  }
+  return out
+}
+
+export class JsonStreamParser {
+  // ignoreBOM keeps a leading U+FEFF, as Buffer#toString does; no UTF-8 sequence spans a quote, so per-string decoding is exact.
+  #decoder = new TextDecoder('utf-8', { ignoreBOM: true })
+  #onString
+  #state = VALUE
+  #stack = [] // open containers, innermost last
+  #path = [] // #path[d]: the key or index #stack[d]'s in-flight member lands at
+  #result
+  #offset = 0 // bytes consumed by earlier writes, for error positions
+  #closed = false
+  // Cached indexOf results in the current chunk (-1: not searched yet; its length: none left).
+  #nextQuote = -1
+  #nextBackslash = -1
+  #tokenStart = 0
+  #isKey = false
+  #parts = [] // copied bytes of a string straddling chunks
+  #escaped = false
+  #pendingEscape = false // a chunk ended on a string's backslash
+  #word = '' // a number or literal straddling chunks
+
+  // onString(value, path) sees each string value (never a key) and its return is stored instead.
+  // `path` is the live key/index path: read it, never keep or mutate it.
+  constructor({ onString } = {}) {
+    this.#onString = onString
+  }
+
+  // A chunk may be reused once write() returns: the bytes of a token left open are copied.
+  write(bytes) {
+    if (this.#closed) throw new Error('JsonStreamParser: write after end or failure')
+    if (!ArrayBuffer.isView(bytes)) throw new TypeError('JsonStreamParser: write() takes a Uint8Array')
+    // A plain Uint8Array view: a Buffer's slice() doesn't copy, and its indexOf/subarray are slower.
+    const view = bytes.constructor === Uint8Array ? bytes : new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+    try {
+      this.#consume(view)
+    } catch (error) {
+      this.#closed = true
+      throw error
+    }
+    this.#offset += view.length
+  }
+
+  end() {
+    if (this.#closed) throw new Error('JsonStreamParser: end after end or failure')
+    this.#closed = true
+    if (this.#state === NUMBER || this.#state === LITERAL) this.#finishWord()
+    if (this.#state !== DONE) throw new SyntaxError(`Unexpected end of JSON input at byte ${this.#offset}`)
+    const result = this.#result
+    this.#result = undefined
+    return result
+  }
+
+  #fail(message, i) {
+    throw new SyntaxError(`${message} at byte ${this.#offset + i}`)
+  }
+
+  #consume(bytes) {
+    const n = bytes.length
+    this.#nextQuote = -1
+    this.#nextBackslash = -1
+    let i = 0
+    while (i < n) {
+      const state = this.#state
+      if (state === STRING) {
+        i = this.#string(bytes, i)
+      } else if (state === NUMBER || state === LITERAL) {
+        i = this.#scanWord(bytes, i)
+      } else if (isWhitespace(bytes[i])) {
+        i += 1
+      } else {
+        i = this.#structural(bytes[i], i)
+      }
+    }
+  }
+
+  #structural(b, i) {
+    const state = this.#state
+    const isArray = Array.isArray(this.#stack.at(-1))
+    if ((state === AFTER || state === ARRAY_FIRST || state === OBJECT_FIRST) && b === (isArray ? 0x5d : 0x7d)) {
+      this.#close()
+      return i + 1
+    }
+    if (state === AFTER) {
+      if (b !== 0x2c) this.#fail(`Unexpected byte 0x${b.toString(16)} after a value`, i)
+      this.#state = isArray ? VALUE : KEY
+      return i + 1
+    }
+    if (state === COLON) {
+      if (b !== 0x3a) this.#fail(`Expected ':' after a key, got byte 0x${b.toString(16)}`, i)
+      this.#state = VALUE
+      return i + 1
+    }
+    if (state === OBJECT_FIRST || state === KEY) {
+      if (b !== QUOTE) this.#fail(`Expected a string key, got byte 0x${b.toString(16)}`, i)
+      this.#startToken(STRING, i)
+      this.#isKey = true
+      return i + 1
+    }
+    if (state === DONE) this.#fail(`Unexpected byte 0x${b.toString(16)} after the JSON value`, i)
+    // VALUE or ARRAY_FIRST
+    if (isArray) this.#path[this.#stack.length - 1] = this.#stack.at(-1).length
+    if (b === QUOTE) {
+      this.#startToken(STRING, i)
+      this.#isKey = false
+      return i + 1
+    }
+    if (b === 0x7b || b === 0x5b) {
+      this.#stack.push(b === 0x7b ? {} : [])
+      this.#path.push(undefined)
+      this.#state = b === 0x7b ? OBJECT_FIRST : ARRAY_FIRST
+      return i + 1
+    }
+    if (b === 0x2d || (b >= 0x30 && b <= 0x39)) {
+      this.#startToken(NUMBER, i)
+      return i
+    }
+    if (b === 0x74 || b === 0x66 || b === 0x6e) {
+      this.#startToken(LITERAL, i)
+      return i
+    }
+    return this.#fail(`Unexpected byte 0x${b.toString(16)} where a value was expected`, i)
+  }
+
+  #startToken(state, i) {
+    this.#state = state
+    this.#tokenStart = this.#offset + i
+  }
+
+  #string(bytes, start) {
+    const n = bytes.length
+    let i = start
+    if (this.#pendingEscape) {
+      this.#pendingEscape = false
+      i += 1
+    }
+    for (;;) {
+      if (this.#nextQuote < i) this.#nextQuote = indexOrEnd(bytes, QUOTE, i)
+      if (this.#nextBackslash < i) this.#nextBackslash = indexOrEnd(bytes, BACKSLASH, i)
+      const quote = this.#nextQuote
+      const backslash = this.#nextBackslash
+      if (backslash < quote) {
+        this.#escaped = true
+        if (backslash + 1 === n) {
+          this.#pendingEscape = true
+          break
+        }
+        i = backslash + 2
+      } else if (quote === n) {
+        break
+      } else {
+        this.#finishString(bytes.subarray(start, quote))
+        return quote + 1
+      }
+    }
+    this.#parts.push(bytes.slice(start))
+    return n
+  }
+
+  #finishString(tail) {
+    let bytes = tail
+    if (this.#parts.length > 0) {
+      this.#parts.push(tail)
+      bytes = concat(this.#parts)
+      this.#parts = []
+    }
+    let value = this.#decoder.decode(bytes)
+    if (this.#escaped) {
+      // JSON.parse handles the escapes, and rejects raw control bytes.
+      this.#escaped = false
+      try {
+        value = JSON.parse(`"${value}"`)
+      } catch (cause) {
+        throw new SyntaxError(`Bad string at byte ${this.#tokenStart}`, { cause })
+      }
+    } else if (hasControlByte(bytes)) {
+      throw new SyntaxError(`Bad control character in string at byte ${this.#tokenStart}`)
+    }
+    if (this.#isKey) {
+      this.#path[this.#path.length - 1] = value
+      this.#state = COLON
+    } else {
+      this.#value(this.#onString === undefined ? value : this.#onString(value, this.#path))
+    }
+  }
+
+  #scanWord(bytes, i) {
+    const n = bytes.length
+    const isNumber = this.#state === NUMBER
+    let j = i
+    while (j < n && (isNumber ? isNumberByte(bytes[j]) : isLetter(bytes[j]))) j += 1
+    this.#word += this.#decoder.decode(bytes.subarray(i, j))
+    if (j === n) return n
+    this.#finishWord()
+    return j
+  }
+
+  #finishWord() {
+    const word = this.#word
+    this.#word = ''
+    if (this.#state === NUMBER) {
+      if (!NUMBER_RE.test(word)) throw new SyntaxError(`Bad number at byte ${this.#tokenStart}`)
+      this.#value(Number(word))
+    } else {
+      if (!LITERALS.has(word)) throw new SyntaxError(`Bad literal at byte ${this.#tokenStart}`)
+      this.#value(LITERALS.get(word))
+    }
+  }
+
+  #close() {
+    this.#path.pop()
+    this.#value(this.#stack.pop())
+  }
+
+  #value(value) {
+    const depth = this.#stack.length
+    if (depth === 0) {
+      this.#result = value
+      this.#state = DONE
+      return
+    }
+    const container = this.#stack[depth - 1]
+    const key = this.#path[depth - 1]
+    if (Array.isArray(container)) {
+      container.push(value)
+    } else if (key === '__proto__') {
+      // JSON.parse defines an own data property; assignment would hit Object.prototype's setter.
+      Object.defineProperty(container, key, { value, writable: true, enumerable: true, configurable: true })
+    } else {
+      container[key] = value
+    }
+    this.#state = AFTER
+  }
+}

package/src/loader-mock.js

@@ -1,19 +1,12 @@
-// stasis's `--mock` run-time loader entry (used by `stasis run --mock`). The
-// import order is load-bearing:
-//   1. the @exodus/stasis-core hooks lib -- evaluating it snapshots stasis's own
-//      node:fs/path/etc. bindings off the *real* builtins (state.js destructures
-//      them at module-eval time), so stasis keeps reading/writing through real fs;
-//   2. ./mock.js -- which neutralizes the network/timer builtins and fs writers in
-//      JS and calls module.syncBuiltinESMExports() so user code's later ESM imports
-//      resolve to the mocked builtins.
-// Only THEN install() the hooks. Running mock.js before registration keeps it from
-// going through the hooks (so it never becomes the bundle entry), and running it
-// after the lib's snapshots leaves stasis's own bindings untouched. This static
-// composition is what lets core stay mock-agnostic with no env-var coordination.
+// stasis's `--mock` loader entry. The import order is load-bearing:
+//   1. the core hooks lib -- evaluating it snapshots stasis's own fs bindings off the *real*
+//      builtins, so stasis keeps reading/writing through real fs;
+//   2. ./mock.js -- neutralizes the network/timer builtins and fs writers, then calls
+//      syncBuiltinESMExports() so user code's later ESM imports resolve to the mocks.
+// Only THEN install() the hooks (so mock.js never goes through them / becomes the bundle entry).
 import { install } from '@exodus/stasis-core/hooks'
-// `export *` (mock.js has no exports) rather than a bare side-effect import only
-// to satisfy the no-unassigned-import lint rule; ESM still evaluates it here, in
-// source order, after the hooks lib above and before install() below.
+// `export *` (mock.js has no exports) rather than a bare side-effect import, to satisfy the
+// no-unassigned-import lint rule; ESM still evaluates it here in source order.
 export * from './mock.js'
 
 install()

package/src/loaders/bash.js

@@ -1,30 +1,25 @@
-// Bash loader: produces a `{ sources, resolutions, missing }` triple from a
-// set of shell scripts, mirroring the Solidity loader's interface (see
-// ./solidity.js). A reference to a .sh/.bash file by a path that lands INSIDE
-// the bundle root (`./lib.sh`, `dir/lib.sh`) must resolve to an in-set script;
-// when it doesn't it lands in `missing` so the bundle builder can reject the
-// dangling dependency. Everything else is best-effort and dropped: PATH
-// commands (`grep`), `$VAR` paths, extensionless `source ./env`, absolute
-// `source /etc/x.sh`, and `../` paths that escape the root — none is bundle-able.
-// A `source "${VAR}/x.sh"` whose path can't be evaluated statically is picked
-// up from its `# shellcheck source=...` directive when one is present.
-
-import { realpathSync, statSync } from 'node:fs'
+// Bash loader: `{ sources, resolutions, missing }` from a set of scripts. A
+// .sh/.bash reference landing INSIDE the bundle root must resolve to an in-set
+// script, else it lands in `missing`; everything else (PATH commands, `$VAR`
+// paths, absolute/escaping paths) is best-effort and dropped. A dynamically
+// sourced path can be pinned by a `# shellcheck source=...` directive.
+
+import { isUtf8 } from 'node:buffer'
+import { realpathSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path'
+import { dirname, extname, join, resolve } from 'node:path'
 
 import { assertRealPathWithinBase } from '@exodus/stasis-core/util'
+import { isFile } from '../resolve-typescript.js'
+import { applyToDir, assertWithinBase } from './paths.js'
 
-// The capture class excludes `` ` ``, `(`, `)` (on top of whitespace, quotes,
-// `;`, `&`, `|`, `#`) so a reference inside a command substitution —
-// `` `source x.sh` `` or `$(bash x.sh)` — doesn't swallow the closing delimiter
-// into the path (which would silently drop the edge from the bundle).
+// The capture class excludes backtick/`(`/`)` so a ref inside a command
+// substitution (`` `source x.sh` ``, `$(bash x.sh)`) doesn't swallow the closing delimiter.
 
 // `source script.sh`, `. script.sh`, `. ./script.sh`
 const SOURCE_RE = /(?:^|\n|;|&&|\|\||`|\$\()\s*(?:source|\.)\s+["']?([^\s"';&|#`()]+)["']?/gu
 
-// `bash script.sh`, `sh script.sh`, `/usr/bin/env bash script.sh`,
-// `/bin/sh script.sh`, `/usr/bin/bash script.sh`, etc.
+// `bash`/`sh script.sh`, incl. `/usr/bin/env bash`, `/bin/sh`, `/usr/bin/bash`.
 const EXEC_RE = /(?:^|\n|;|&&|\|\||`|\$\()\s*(?:\/usr\/bin\/env\s+|\/bin\/|\/usr\/bin\/)?(?:ba)?sh\s+["']?([^\s"';&|#`()]+)["']?/gu
 
 // Direct invocation: `./script.sh`, `../lib/helper.bash`, `/path/to/script.sh`
@@ -33,21 +28,13 @@ const DIRECT_RE = /(?:^|\n|;|&&|\|\||`|\$\()\s*["']?(\.\.?\/[^\s"';&|#`()]+\.(?:
 // Dependency hint comment: `# Depends on: example.sh`
 const COMMENT_RE = /^# Depends on: ([^ ]+\.(?:sh|bash))( |$)/gmu
 
-// shellcheck `source=` directive: `# shellcheck source=../lib/config.sh`
-// (optionally alongside other directives, e.g. `# shellcheck disable=SC1091 source=lib/x.sh`).
-// This is the standard, explicit way to tell tooling where a dynamically
-// sourced file lives — e.g. `source "${LIB_DIR}/config.sh"`, whose path is a
-// `$VAR` expansion that can't be evaluated statically. The path is resolved
-// relative to the script (matching shellcheck's default). `source=/dev/null`
-// is shellcheck's "don't follow this source" sentinel and is ignored below.
+// shellcheck `source=` directive: `# shellcheck source=../lib/config.sh`, the
+// explicit way to point at a dynamically sourced (`$VAR`) file. Resolved relative
+// to the script. `source=/dev/null` is shellcheck's "don't follow" sentinel, ignored below.
 const SHELLCHECK_SOURCE_RE = /#\s*shellcheck\s[^\n]*?\bsource=["']?([^\s"'#]+)["']?/gu
 
-// Extract every file-like reference from a script's text. Variable
-// expansions (`$VAR`, `${VAR}`, `$HOME/x.sh`) and flags (`-c`) are dropped
-// here — they are never bundle-able file paths; a `source "${VAR}/x.sh"` whose
-// real location can't be computed statically should carry a `# shellcheck
-// source=` directive instead. The remaining strings are candidate references;
-// resolveBashCall decides which name a real file.
+// Extract candidate file references. `$VAR` expansions and `-flags` are dropped
+// (never bundle-able); resolveBashCall decides which of the rest name a real file.
 export function extractBashCalls(content) {
   const calls = new Set()
   for (const re of [SOURCE_RE, EXEC_RE, DIRECT_RE, COMMENT_RE, SHELLCHECK_SOURCE_RE]) {
@@ -60,63 +47,27 @@ export function extractBashCalls(content) {
   return [...calls]
 }
 
-// Resolve a bash reference to a baseDir-relative POSIX path. Existence is
-// checked against `knownFiles` (tree mode, used once every script is in
-// hand) or the filesystem under `baseDir` (walk mode, while discovering the
-// graph); with neither, only path computation happens and unvalidated names
-// return null.
-//
-// Reference kinds are treated differently:
-//   - absolute (`/x`): mapped to project-relative by stripping the leading
-//     slash, accepted only if that file actually exists in the set/on disk
-//     (so system paths like /etc/profile.d/x.sh are dropped, not bundled).
-//   - relative / project-relative WITH a slash (`./x`, `../x`, `lib/x.sh`):
-//     resolved against the caller's directory and returned as a computed
-//     path WITHOUT an existence check — the walk's readFile surfaces a
-//     missing target and the tree flags or drops it, mirroring the Solidity
-//     loader. Traversal above baseDir returns null rather than clamping, so
-//     an escaping `../x.sh` is treated as external (never flagged missing).
-//   - bare name (`helper.sh`, but also `grep`, `node`): could be a sibling
-//     script or a PATH command, so it is accepted only when it names a real
-//     file — caller's dir, then project root, then (knownFiles only) any
-//     in-set file by basename.
+// Resolve a bash reference to a baseDir-relative POSIX path. Existence is checked
+// against `knownFiles` (tree mode) or the filesystem under `baseDir` (walk mode);
+// with neither, only path computation happens. Handling differs by kind (below).
 export function resolveBashCall(ref, fromFile, { knownFiles, baseDir } = {}) {
   const present = (p) => {
     if (!p) return false
     if (knownFiles) return knownFiles.has(p)
-    if (baseDir) {
-      try {
-        return statSync(join(baseDir, p)).isFile()
-      } catch {
-        return false
-      }
-    }
+    if (baseDir) return isFile(join(baseDir, p))
     return false
   }
 
-  const fromDir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : ''
-  const resolveRel = (r) => {
-    const parts = [...(fromDir ? fromDir.split('/') : []), ...r.split('/')]
-    const out = []
-    for (const part of parts) {
-      if (part === '.' || part === '') continue
-      if (part === '..') {
-        if (out.length === 0) return null // escapes baseDir
-        out.pop()
-      } else {
-        out.push(part)
-      }
-    }
-    return out.join('/') || null
-  }
+  // Null when it escapes baseDir or names baseDir itself.
+  const resolveRel = (r) => applyToDir(fromFile, r.split('/')) || null
 
-  // Absolute → project-relative, validated.
+  // Absolute → project-relative, accepted only if it exists (so `/etc/...` is dropped).
   if (ref.startsWith('/')) {
     const stripped = ref.replace(/^\/+/u, '')
     return present(stripped) ? stripped : null
   }
 
-  // Path with a slash → computed, validation deferred to the caller.
+  // Path with a slash → computed against the caller's dir; existence deferred to the caller.
   if (ref.includes('/')) return resolveRel(ref)
 
   // Bare name → only accept a real file.
@@ -132,19 +83,13 @@ export function resolveBashCall(ref, fromFile, { knownFiles, baseDir } = {}) {
   return null
 }
 
-// A `.sh`/`.bash` extension marks a reference as a shell script (as opposed to
-// an extensionless `source ./env`, which we don't treat as a missing script
-// when absent).
+// True for `.sh`/`.bash` refs; an extensionless `source ./env` isn't flagged missing when absent.
 const hasShellScriptExt = (ref) => ref.endsWith('.sh') || ref.endsWith('.bash')
 
-// Build the { sources, resolutions, missing } triple from a Map of
-// already-loaded scripts. A reference is recorded in `missing` (which the
-// bundle builder treats as fatal) only when it resolves to a path INSIDE the
-// bundle root that wasn't collected — i.e. a dangling `source ./lib.sh`.
-// References that resolve to null are external and tolerated: bare names
-// (PATH commands / runtime-cwd scripts), absolute `/etc/...` paths, `$VAR`
-// paths, and `../` paths that escape the root — none can live in the bundle.
-// Self-references and non-script extensions are dropped without flagging.
+// Build the triple from already-loaded scripts. A ref is `missing` (fatal) only
+// when it resolves INSIDE the bundle root but wasn't collected (a dangling
+// `source ./lib.sh`); null-resolving refs are external and tolerated, and
+// self-refs/non-script exts are dropped silently.
 export function buildBashTree(sources) {
   const knownFiles = new Set(sources.keys())
   const resolutions = new Map()
@@ -152,9 +97,8 @@ export function buildBashTree(sources) {
   for (const [path, content] of sources) {
     const specMap = new Map()
     for (const ref of extractBashCalls(content)) {
-      // In tree mode the slash branch returns a computed in-bundle path
-      // without checking existence, so a non-null target that isn't a known
-      // file is a genuine dangling local dependency; a null target is external.
+      // Slash branch returns an unchecked in-bundle path, so a non-null target not
+      // in knownFiles is a genuine dangling dep; a null target is external.
       const target = resolveBashCall(ref, path, { knownFiles })
       if (target && knownFiles.has(target)) {
         if (target !== path) specMap.set(ref, target) // drop self-references
@@ -168,12 +112,15 @@ export function buildBashTree(sources) {
   return { sources, resolutions, missing }
 }
 
-// Walk the filesystem from `entries`, following resolved source/exec/direct
-// references and reading each reachable script exactly once. Files in the
-// same wave are read in parallel; the next wave depends on references found
-// in the previous one. A reference that resolves to a path missing on disk
-// warns and is skipped (the graph stays partial but the walk continues);
-// unresolved references (commands, dynamic paths) are silently ignored.
+// A script's text. One that isn't UTF-8 is refused rather than carried with U+FFFD in it.
+async function readScript(baseDir, relPath) {
+  const bytes = await readFile(join(baseDir, relPath))
+  if (!isUtf8(bytes)) throw new Error(`Shell script is not valid UTF-8: ${relPath}`)
+  return bytes.toString('utf8')
+}
+
+// Walk from `entries` following resolved refs, reading each script once; a ref
+// missing on disk warns and is skipped without aborting the walk.
 export async function collectBashFilesFromDisk(baseDir, entries) {
   const sources = new Map()
   const realBase = realpathSync(baseDir)
@@ -185,14 +132,13 @@ export async function collectBashFilesFromDisk(baseDir, entries) {
       toLoad.map(async (relPath) => {
         try {
           assertRealPathWithinBase(realBase, baseDir, relPath)
-          return [relPath, await readFile(join(baseDir, relPath), 'utf8')]
+          return [relPath, await readScript(baseDir, relPath)]
         } catch (err) {
           if (err.code === 'ENOENT') {
             console.warn(`[loader.bash] Missing file: ${relPath}`)
             return null
           }
-          // A slash-bearing ref can resolve to a directory (e.g. `source ./lib`);
-          // readFile then throws EISDIR. Skip it rather than aborting the walk.
+          // A slash ref can resolve to a directory (`source ./lib`) → EISDIR; skip, don't abort.
           if (err.code === 'EISDIR') {
             console.warn(`[loader.bash] Skipping directory reference: ${relPath}`)
             return null
@@ -218,22 +164,9 @@ export async function collectBashFilesFromDisk(baseDir, entries) {
   return sources
 }
 
-// Reject absolute paths and `..`-escaping paths in a `.sh.txt` listing so a
-// malicious or sloppy listing can't trick the loader into reading arbitrary
-// files outside the listing's own directory.
-function assertWithinBase(baseDir, candidate, label) {
-  if (isAbsolute(candidate)) throw new Error(`${label} must not be absolute: ${candidate}`)
-  const rel = relative(baseDir, resolve(baseDir, candidate)).split(/[\\/]/u).join('/')
-  if (rel.startsWith('..') || isAbsolute(rel)) {
-    throw new Error(`${label} escapes baseDir: ${candidate}`)
-  }
-}
-
-// High-level: takes a `.sh.txt` listing file whose lines are the scripts to
-// load (`.sh`, `.bash`, or extensionless), resolved relative to the listing.
-// Unlike loadSolidity, the listing is the authoritative manifest — bash
-// sourcing is too dynamic to walk reliably — so exactly the listed files are
-// read and resolutions are computed among them. Returns { sources, resolutions, missing }.
+// High-level entry: reads the scripts named in a `.sh.txt` listing (relative to
+// it). Unlike loadRust, the listing is authoritative — bash sourcing is too
+// dynamic to walk — so exactly the listed files are read, resolutions computed among them.
 export async function loadBash(shTxtFile) {
   const baseDir = dirname(resolve(shTxtFile))
   const listing = await readFile(shTxtFile, 'utf8')
@@ -250,7 +183,7 @@ export async function loadBash(shTxtFile) {
   const reads = await Promise.all(
     lines.map(async (relPath) => {
       assertRealPathWithinBase(realBase, baseDir, relPath)
-      return [relPath, await readFile(join(baseDir, relPath), 'utf8')]
+      return [relPath, await readScript(baseDir, relPath)]
     }),
   )
   return buildBashTree(new Map(reads))