@critical-labs/qa-conductor 0.0.0-stage → 0.3.0

package/lib/config.mjs

@@ -0,0 +1,245 @@
+// Generic conductor configuration: parse `.env.qa` (plain KEY=value lines)
+// into the settings the CORE needs. There are no app defaults here: a
+// consuming platform passes its own `defaults` (and any keys it must insist
+// on as `required`) and reads its app-specific keys (image repo, database
+// identity, ...) from the returned raw `env` map. See the homefree platform's
+// config-homefree.mjs for the reference reader.
+
+import { readFileSync } from 'node:fs'
+
+import { normalizeLogins } from './identity.mjs'
+import { hostPort, isLoopbackHost, requireFetchMetadata, webOrigin } from './net.mjs'
+
+// Where the harness is served under its origin. Fixed: public/index.html and
+// public/harness.js load and call /qa/... .
+export const HARNESS_PATH = '/qa'
+
+// QA_EXPOSURE / cfg.exposure. `tailscale`: fronted by tailscale serve on this
+// host, so every server answers only QA_ALLOWED_LOGINS and must listen on
+// loopback. `none`: no identity gate (0.2's behaviour).
+export const EXPOSURE_MODES = ['none', 'tailscale']
+
+// QA_EXPOSURE_INTERVAL_MINUTES / cfg.exposureIntervalMinutes: the minutes
+// between the conductor's exposure reconcile passes. At most 35791, the
+// largest whole number of minutes whose milliseconds fit setInterval's
+// 2^31-1 limit: above it Node fires every 1 ms, and the loop would run the
+// front door's CLI back to back. Fractions are fine.
+export const MAX_EXPOSURE_INTERVAL_MINUTES = 35791
+
+export function isExposureInterval(minutes) {
+  return typeof minutes === 'number' && Number.isFinite(minutes) && minutes > 0 && minutes <= MAX_EXPOSURE_INTERVAL_MINUTES
+}
+
+// The rule both loadConfig and startConductor state when they refuse one.
+export const EXPOSURE_INTERVAL_RULE = `must be a number of minutes above 0 and at most ${MAX_EXPOSURE_INTERVAL_MINUTES} (the longest a timer can wait)`
+
+// The hostname of an http(s) origin, or null for anything else.
+function originHostname(value) {
+  try { return new URL(webOrigin(value)).hostname } catch { return null }
+}
+
+// The exposure mode for a layout that names none: tailscale when anything
+// the conductor answers to or listens on is off loopback, since it is then
+// meant to be reached from another machine; else none. The inputs are the
+// harness origin as resolved at start (null, on port 0 or off loopback,
+// adds nothing: the bind host counts on its own), both pane origins (a
+// missing or unparseable one counts), the public host and every allowed
+// host, which widen the Host allowlist, and the bind host. `because` names
+// the first one off loopback, for error messages, else null. The public
+// host goes first, since the derived origins come from it.
+export function defaultExposure({ harnessOrigin = null, paneOrigins, publicHost = null, allowedHosts = [], host = '127.0.0.1' } = {}) {
+  const inputs = []
+  if (publicHost) inputs.push([`QA_PUBLIC_HOST=${publicHost}`, publicHost])
+  if (harnessOrigin != null) inputs.push([`QA_HARNESS_ORIGIN=${harnessOrigin}`, originHostname(harnessOrigin)])
+  for (const [role, key] of [['base', 'QA_BASE_ORIGIN'], ['pr', 'QA_PR_ORIGIN']]) {
+    const value = paneOrigins?.[role]
+    const hostname = originHostname(value)
+    const shown = value == null ? `${key} (unset)` : hostname === null ? `${key}=${JSON.stringify(String(value))}` : `${key}=${value}`
+    inputs.push([shown, hostname])
+  }
+  for (const entry of allowedHosts ?? []) {
+    // a blank entry matches no Host, so it widens nothing
+    if (String(entry).trim()) inputs.push([`the QA_ALLOWED_HOSTS entry ${entry}`, String(entry).trim()])
+  }
+  inputs.push([`QA_BIND_HOST=${host}`, host])
+  const first = inputs.find(([, name]) => !isLoopbackHost(name))
+  return first ? { mode: 'tailscale', because: first[0] } : { mode: 'none', because: null }
+}
+
+// The harness origin when none is configured: :8444 on the public host, else
+// the loopback address the harness listens on, else null (on port 0 the
+// conductor derives it from the bound port; off loopback it can't be known).
+export function defaultHarnessOrigin({ publicHost, host, port }) {
+  if (publicHost) return webOrigin(`https://${publicHost}:8444`, 'the harness origin derived from QA_PUBLIC_HOST')
+  if (isLoopbackHost(host) && port > 0) return new URL(`http://${hostPort(host, port)}`).origin
+  return null
+}
+
+export function parseEnvFile(envFilePath) {
+  const env = {}
+  for (const line of readFileSync(envFilePath, 'utf8').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq === -1) continue
+    env[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim()
+  }
+  return env
+}
+
+const num = (value, fallback) => (value ? Number(value) : fallback)
+
+const list = value => String(value ?? '').split(',').map(s => s.trim()).filter(Boolean)
+
+// The harness and the panes each act for the operator, so none may be
+// same-origin with another: a pane's page (PR code) would then drive the
+// harness API or the other pane. Throws naming the first pair that collides.
+function checkDistinct(origins, envFilePath) {
+  const seen = new Map()
+  for (const [name, origin] of Object.entries(origins)) {
+    if (origin === null) continue
+    if (seen.has(origin)) {
+      throw new Error(
+        `the harness and the two panes must be three different origins, but the ${seen.get(origin)} and ${name} are both ${origin} ` +
+          `in ${envFilePath} (QA_HARNESS_ORIGIN, QA_BASE_ORIGIN, QA_PR_ORIGIN)`,
+      )
+    }
+    seen.set(origin, name)
+  }
+}
+
+// QA_EXPOSURE, else the default for this layout. `explicit` and `because`
+// say why, for the errors below.
+function exposureOf(value, layout, envFilePath) {
+  if (!value) return { ...defaultExposure(layout), explicit: false }
+  if (!EXPOSURE_MODES.includes(value)) {
+    throw new Error(`QA_EXPOSURE must be none or tailscale, got ${JSON.stringify(value)} in ${envFilePath}`)
+  }
+  return { mode: value, because: null, explicit: true }
+}
+
+// The identity gate trusts Tailscale-User-Login only because nothing but
+// tailscale serve on this host can reach a loopback listener; on any other
+// address a client could send its own. And an empty allowlist would refuse
+// everyone. The bind is checked first, so its error names the way out too.
+function checkTailscale({ explicit, because }, host, allowedLogins, envFilePath) {
+  const avoid = 'set QA_EXPOSURE=none if another front door authenticates'
+  if (!isLoopbackHost(host)) {
+    const why = explicit ? 'QA_EXPOSURE=tailscale is set' : `QA_EXPOSURE defaults to tailscale because ${because} is not loopback`
+    throw new Error(
+      `${why}, so QA_BIND_HOST must be a loopback address: tailscale serve on this host is the only supported front ` +
+        `(got ${JSON.stringify(host)} in ${envFilePath}; use 127.0.0.1, ::1 or localhost), or ${avoid}`,
+    )
+  }
+  if (allowedLogins.length === 0) {
+    const reason = explicit ? 'set' : `${because} is not loopback`
+    throw new Error(
+      `QA_ALLOWED_LOGINS is empty in ${envFilePath} and QA_EXPOSURE is tailscale (${reason}): the harness and both panes would refuse everyone. ` +
+        'Set it to the comma-separated Tailscale logins allowed in (to find one, run `tailscale whois <device tailnet ip>`), ' +
+        `or ${avoid}.`,
+    )
+  }
+}
+
+// Keys the core cannot run without. QA_PUBLIC_HOST joins them only when it is
+// needed to derive a pane origin that wasn't given explicitly.
+function requiredKeys(env, extra) {
+  const keys = new Set(['GITHUB_QA_TOKEN', 'QA_REPO', ...extra])
+  if (!(env.QA_BASE_ORIGIN && env.QA_PR_ORIGIN)) keys.add('QA_PUBLIC_HOST')
+  return keys
+}
+
+export function loadConfig(envFilePath, { defaults = {}, required = [] } = {}) {
+  const env = { ...defaults, ...parseEnvFile(envFilePath) }
+  for (const key of requiredKeys(env, required)) {
+    if (!env[key]) throw new Error(`${key} missing in ${envFilePath}`)
+  }
+  const publicHost = env.QA_PUBLIC_HOST || null
+  // listen() takes an IPv6 literal bare: `[::1]`, as a URL writes it, is ::1.
+  // Left bracketed, it would pass every loopback check and then fail to listen.
+  const host = (env.QA_BIND_HOST || '127.0.0.1').replace(/^\[(.*)\]$/, '$1')
+  const ports = {
+    harness: num(env.QA_HARNESS_PORT, 3100),
+    base: num(env.QA_BASE_PROXY_PORT, 3101),
+    pr: num(env.QA_PR_PROXY_PORT, 3102),
+  }
+  const paneOrigins = {
+    base: env.QA_BASE_ORIGIN
+      ? webOrigin(env.QA_BASE_ORIGIN, 'QA_BASE_ORIGIN')
+      : webOrigin(`https://${publicHost}:8443`, 'QA_BASE_ORIGIN (derived from QA_PUBLIC_HOST)'),
+    pr: env.QA_PR_ORIGIN
+      ? webOrigin(env.QA_PR_ORIGIN, 'QA_PR_ORIGIN')
+      : webOrigin(`https://${publicHost}:10000`, 'QA_PR_ORIGIN (derived from QA_PUBLIC_HOST)'),
+  }
+  const harnessOrigin = env.QA_HARNESS_ORIGIN
+    ? webOrigin(env.QA_HARNESS_ORIGIN, 'QA_HARNESS_ORIGIN')
+    : defaultHarnessOrigin({ publicHost, host, port: ports.harness })
+  if (harnessOrigin === null && !(isLoopbackHost(host) && ports.harness === 0)) {
+    throw new Error(
+      `QA_HARNESS_ORIGIN missing in ${envFilePath}: with QA_BIND_HOST=${host} and no QA_PUBLIC_HOST, ` +
+        'the origin viewers open the harness at cannot be derived (for example https://qa.example.com:8444)',
+    )
+  }
+  // The derived origins are https or loopback; an explicit one may be neither.
+  if (harnessOrigin !== null) requireFetchMetadata(harnessOrigin, 'QA_HARNESS_ORIGIN', 'harness API guard')
+  requireFetchMetadata(paneOrigins.base, 'QA_BASE_ORIGIN', 'pane request guard')
+  requireFetchMetadata(paneOrigins.pr, 'QA_PR_ORIGIN', 'pane request guard')
+  checkDistinct({ harness: harnessOrigin, base: paneOrigins.base, pr: paneOrigins.pr }, envFilePath)
+  const frameAncestors = list(env.QA_FRAME_ANCESTORS).map(v => webOrigin(v, 'QA_FRAME_ANCESTORS'))
+  const allowedHosts = list(env.QA_ALLOWED_HOSTS)
+  const exposure = exposureOf(env.QA_EXPOSURE, { harnessOrigin, paneOrigins, publicHost, allowedHosts, host }, envFilePath)
+  const allowedLogins = normalizeLogins(list(env.QA_ALLOWED_LOGINS))
+  if (exposure.mode === 'tailscale') checkTailscale(exposure, host, allowedLogins, envFilePath)
+  const exposureIntervalMinutes = num(env.QA_EXPOSURE_INTERVAL_MINUTES, 5)
+  if (!isExposureInterval(exposureIntervalMinutes)) {
+    throw new Error(`QA_EXPOSURE_INTERVAL_MINUTES ${EXPOSURE_INTERVAL_RULE}, got ${JSON.stringify(env.QA_EXPOSURE_INTERVAL_MINUTES)} in ${envFilePath}`)
+  }
+
+  return {
+    env,
+    githubToken: env.GITHUB_QA_TOKEN,
+    // The GHCR token, for createGithub({ packagesToken }) (package version
+    // listings) and a platform's registry login. A fine-grained
+    // GITHUB_QA_TOKEN cannot call the Packages API, so QA_GHCR_TOKEN (a
+    // classic PAT with read:packages) can take those over. Unset,
+    // GITHUB_QA_TOKEN does both.
+    ghcrToken: env.QA_GHCR_TOKEN || env.GITHUB_QA_TOKEN,
+    operatorEmail: env.QA_OPERATOR_EMAIL || null,
+    repo: env.QA_REPO,
+    publicHost,
+    idleMinutes: num(env.QA_IDLE_MINUTES, 30),
+    // The address all three servers listen on. Loopback by default, and
+    // always in tailscale mode: in none mode the API is unauthenticated, and
+    // a pane proxy is a signed-in pane session either way.
+    host,
+    // Extra Host-header hostnames the servers answer to, beyond loopback, the
+    // public host and the pane origins (DNS-rebinding defence).
+    allowedHosts,
+    // 'tailscale' (the identity gate is on) or 'none'; see EXPOSURE_MODES.
+    exposure: exposure.mode,
+    // Tailscale logins (as tailscale serve reports them, e.g. alice@github)
+    // allowed in when the identity gate is on. Empty refuses everyone, so
+    // tailscale mode requires some.
+    allowedLogins,
+    // Minutes between exposure reconcile passes, when the platform passes
+    // an Exposure adapter (adapters.exposure); see MAX_EXPOSURE_INTERVAL_MINUTES.
+    exposureIntervalMinutes,
+    // Listen ports: the harness UI/API and the two pane proxies.
+    ports,
+    // The external origin a viewer reaches each pane at: the TLS terminator in
+    // front of the pane proxies. Defaults match a tailscale-serve layout.
+    paneOrigins,
+    // The origin viewers open the harness at (its page is HARNESS_PATH/ under
+    // it). Only it, the panes themselves and frameAncestors may frame a pane,
+    // a navigation into a pane from another site must come from it, and the
+    // mirror bridge talks only to it. null: derived from the bound port.
+    harnessOrigin,
+    // Extra origins allowed to frame the panes, for a harness that is itself
+    // framed (self-QA's inner demos). CSP only: no Referer or bridge trust.
+    frameAncestors,
+    verdictLabels: {
+      accept: env.QA_LABEL_ACCEPT || 'qa-approved',
+      reject: env.QA_LABEL_REJECT || 'qa-changes-requested',
+    },
+  }
+}

package/lib/docker.mjs

@@ -0,0 +1,233 @@
+// Docker CLI wrappers for QA sessions. All effects go through the injected
+// execFileFn (promisified child_process.execFile shape: resolves { stdout }),
+// so tests assert exact argv without touching docker.
+
+const SAFE_NAME = /^[a-z0-9_-]+$/i
+const DEFAULT_LABEL = 'qa-conductor-session'
+const DEFAULT_POSTGRES = { image: 'postgres:16', user: 'qa', password: 'qa', db: 'postgres' }
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function assertSafe(value, what) {
+  if (!SAFE_NAME.test(value)) throw new Error(`unsafe ${what}: ${JSON.stringify(value)}`)
+}
+
+// `label` marks every conductor-owned container/network (the startup sweep
+// removes whatever carries it); `postgres` is the pane database identity.
+// A consuming app that clones a real database passes its own superuser here.
+export function createDocker({ execFileFn, label = DEFAULT_LABEL, postgres = DEFAULT_POSTGRES }) {
+  const pg = { ...DEFAULT_POSTGRES, ...postgres }
+  async function run(argv) {
+    const { stdout } = await execFileFn('docker', argv)
+    return stdout
+  }
+
+  return {
+    run,
+
+    // Log the daemon into GHCR with the conductor's own token so pane image
+    // pulls never depend on a manually-seeded (and expiring) host credential.
+    // Token travels via the child env, never argv. Merge (not replace) the
+    // parent env so HOME survives — docker login writes ~/.docker/config.json,
+    // and docker pull/run must read the SAME HOME or the credential is lost.
+    async login(user, token) {
+      assertSafe(user, 'registry user')
+      // biome-ignore lint/nursery/noProcessEnv: must inherit HOME so docker login/pull share a config
+      const parentEnv = globalThis.process?.env ?? {}
+      await execFileFn('sh', ['-c', 'printf %s "$GHCR_TOKEN" | docker login ghcr.io -u "$GHCR_USER" --password-stdin'], {
+        env: { ...parentEnv, GHCR_USER: user, GHCR_TOKEN: token },
+      })
+    },
+
+    async imagePresent(image) {
+      try {
+        await run(['image', 'inspect', image])
+        return true
+      } catch {
+        return false
+      }
+    },
+
+    // Make an image local before it's run. No-op if already present; otherwise
+    // pull with retries, re-logging-in before each retry so a transient
+    // registry 'denied' (seen live — same token pulls fine seconds later)
+    // self-heals instead of killing the boot.
+    async ensureImage(image, { retries = 3, sleepFn = defaultSleep, relogin } = {}) {
+      if (await this.imagePresent(image)) return
+      let lastErr
+      for (let attempt = 0; attempt < retries; attempt++) {
+        try {
+          await run(['pull', image])
+          return
+        } catch (err) {
+          lastErr = err
+          if (relogin) await relogin().catch(() => {})
+          await sleepFn(3000)
+        }
+      }
+      throw new Error(`pull ${image} failed after ${retries} attempts: ${lastErr?.message ?? ''}`)
+    },
+
+    async runPg(name, network) {
+      return run([
+        'run', '-d',
+        '--name', name,
+        '--network', network,
+        '--label', label,
+        '-e', `POSTGRES_USER=${pg.user}`,
+        '-e', `POSTGRES_PASSWORD=${pg.password}`,
+        '-e', `POSTGRES_DB=${pg.db}`,
+        pg.image,
+      ])
+    },
+
+    // postgres:16's entrypoint starts a TEMPORARY server during initdb, stops
+    // it, then starts the real one. pg_isready can pass against the temporary
+    // server, so require two consecutive successful probes (with a real query)
+    // separated by a beat — the shutdown gap fails one of them and resets.
+    async waitHealthyPg(name, { retries = 30, sleepFn = defaultSleep } = {}) {
+      let consecutive = 0
+      for (let attempt = 1; attempt <= retries; attempt++) {
+        try {
+          await run(['exec', name, 'pg_isready', '-U', pg.user])
+          await run(['exec', name, 'psql', '-U', pg.user, '-d', pg.db, '-c', 'SELECT 1'])
+          consecutive += 1
+          if (consecutive >= 2) return
+        } catch {
+          consecutive = 0
+          if (attempt === retries) break
+        }
+        await sleepFn(1000)
+      }
+      throw new Error(`postgres ${name} not ready after ${retries} attempts`)
+    },
+
+    // CREATE DATABASE in a pane pg container, tolerating already-exists and
+    // retrying through the postgres-init restart window. Extracted from cloneDb
+    // so the Provisioner seam can own DB creation while the Seed seam owns data
+    // movement (extraction Stage 1). cloneDb keeps its behavior by composing the
+    // two.
+    async createDatabase(toContainer, db, { retries = 10, sleepFn = defaultSleep } = {}) {
+      assertSafe(toContainer, 'container name')
+      assertSafe(db, 'database name')
+      for (let attempt = 1; attempt <= retries; attempt++) {
+        try {
+          await run(['exec', toContainer, 'psql', '-U', pg.user, '-d', pg.db, '-c', `CREATE DATABASE ${db}`])
+          return
+        } catch (err) {
+          const detail = `${err.message ?? ''}\n${err.stderr ?? ''}`
+          if (detail.includes('already exists')) return
+          // Connection refusals can still occur in the entrypoint's restart
+          // window; retry those instead of failing the whole boot.
+          const transient = detail.includes('connection to server') || detail.includes('the database system is starting up')
+          if (!transient || attempt === retries) throw err
+          await sleepFn(1000)
+        }
+      }
+    },
+
+    // Copy one database from a source container into a pane container via a
+    // host-side pg_dump|psql pipe. This is a docker-topology detail the Seed
+    // adapter owns; kept here as the shared movement primitive.
+    async pipeDump(fromContainer, toContainer, db) {
+      assertSafe(fromContainer, 'container name')
+      assertSafe(toContainer, 'container name')
+      assertSafe(db, 'database name')
+      const pipeline =
+        `docker exec ${fromContainer} pg_dump -U ${pg.user} --clean --if-exists ${db}` +
+        ` | docker exec -i ${toContainer} psql -q -U ${pg.user} -d ${db}`
+      await execFileFn('sh', ['-c', pipeline])
+    },
+
+    async cloneDb(fromContainer, toContainer, db, opts = {}) {
+      // Validate all three up front so a bad source is rejected before any exec.
+      assertSafe(fromContainer, 'container name')
+      assertSafe(toContainer, 'container name')
+      assertSafe(db, 'database name')
+      await this.createDatabase(toContainer, db, opts)
+      await this.pipeDump(fromContainer, toContainer, db)
+    },
+
+    async runMigrate(image, network, envFile) {
+      return run([
+        'run', '--rm',
+        '--network', network,
+        '--label', label,
+        '--env-file', envFile,
+        image,
+      ])
+    },
+
+    async runApp(name, image, network, envFile, hostPort) {
+      return run([
+        'run', '-d',
+        '--name', name,
+        '--network', network,
+        '--label', label,
+        '--env-file', envFile,
+        '-p', `127.0.0.1:${hostPort}:3000`,
+        image,
+      ])
+    },
+
+    async waitHealthyApp(hostPort, { retries = 60, sleepFn = defaultSleep, fetchFn = fetch } = {}) {
+      const url = `http://127.0.0.1:${hostPort}/api/health`
+      for (let attempt = 1; attempt <= retries; attempt++) {
+        try {
+          const res = await fetchFn(url)
+          if (res.status === 200) return
+        } catch {
+          // app not listening yet
+        }
+        if (attempt < retries) await sleepFn(1000)
+      }
+      throw new Error(`app on port ${hostPort} not healthy after ${retries} attempts`)
+    },
+
+    async psql(container, db, sql) {
+      return run(['exec', container, 'psql', '-U', pg.user, '-d', db, '-t', '-A', '-c', sql])
+    },
+
+    async rmForce(names) {
+      if (!names.length) return
+      try {
+        await run(['rm', '-f', '-v', ...names])
+      } catch {
+        // teardown is idempotent: already-gone containers are fine
+      }
+    },
+
+    async createNetwork(name) {
+      return run(['network', 'create', '--label', label, name])
+    },
+
+    async rmNetwork(name) {
+      try {
+        await run(['network', 'rm', name])
+      } catch {
+        // already gone
+      }
+    },
+
+    async sweepQaContainers() {
+      const out = await run(['ps', '-aq', '--filter', `label=${label}`])
+      const ids = out.split('\n').map((s) => s.trim()).filter(Boolean)
+      if (ids.length) await this.rmForce(ids)
+      return ids
+    },
+
+    async inspectImageOf(container) {
+      const out = await run(['inspect', '--format', '{{.Config.Image}}', container])
+      return out.trim()
+    },
+
+    // Tail a container's recent log lines for triage. docker logs writes to
+    // both stdout and stderr, but the run() wrapper only surfaces stdout;
+    // that's acceptable here — return whatever stdout the exec yields.
+    async logsTail(name, n = 40) {
+      assertSafe(name, 'container name')
+      const result = await execFileFn('docker', ['logs', '--tail', String(n), name])
+      return result.stdout || ''
+    },
+  }
+}

package/lib/exec.mjs

@@ -0,0 +1,23 @@
+// Promisified execFile with the { stdout } resolution shape the docker module
+// depends on (createDocker destructures { stdout } from every call). Kept as
+// its own module so the shape is unit-tested rather than assumed by wiring.
+//
+// A failure rejects with an Error whose message is "<cmd> <first arg>:
+// <execFile message>\n<stderr, first 2000 chars>" and which also carries the
+// full `stdout`, `stderr` and exit `code`, so a caller can build its own log
+// tail (an installer's output usually lands on stdout).
+import { execFile } from 'node:child_process'
+
+export function makeExecFileFn({ maxBuffer = 64 * 1024 * 1024 } = {}) {
+  return (cmd, args, opts) => new Promise((resolve, reject) => {
+    execFile(cmd, args, { maxBuffer, ...opts }, (err, stdout, stderr) => {
+      if (err) reject(execError(cmd, args, err, stdout, stderr))
+      else resolve({ stdout: String(stdout) })
+    })
+  })
+}
+
+function execError(cmd, args, err, stdout, stderr) {
+  const out = new Error(`${cmd} ${args?.[0] ?? ''}: ${err.message}\n${String(stderr).slice(0, 2000)}`, { cause: err })
+  return Object.assign(out, { stdout: String(stdout ?? ''), stderr: String(stderr ?? ''), code: err.code })
+}