@mannyc1/ts-release 0.0.7 → 0.3.0

package/src/drivers/errors.ts

@@ -0,0 +1,6 @@
+import * as Schema from "effect/Schema"
+
+export class DriverError
+  extends Schema.TaggedErrorClass<DriverError>()("DriverError", {
+    reason: Schema.String, commitment: Schema.Literals(["before-commit", "unknown"])
+  }) {}

package/src/drivers/glob.ts

@@ -0,0 +1,137 @@
+// Portable matcher for the documented archive `files` grammar: `*` and `?`
+// inside one segment, `**` as a whole segment spanning segments, `[...]`
+// classes, and `{a,b}` alternation. Patterns reach here already slash
+// normalized, so a backslash is only ever an explicit escape.
+// A malformed pattern (unclosed `[` or `{`) matches nothing, so a typo fails
+// loudly upstream as "patterns matched no workspace files".
+const alternativeLimit = 1024
+const metacharacters = new Set(["\\", "^", "$", ".", "*", "+", "?", "(", ")", "[", "]", "{", "}", "|", "/"])
+const literal = (value: string): string => metacharacters.has(value) ? `\\${value}` : value
+const classLiteral = (value: string): string => ["\\", "]", "^", "["].includes(value) ? `\\${value}` : value
+const classEnd = (pattern: string, open: number): number | undefined => {
+  let index = open + 1
+  if (pattern[index] === "!" || pattern[index] === "^") index += 1
+  if (pattern[index] === "]") index += 1
+  while (index < pattern.length) {
+    if (pattern[index] === "\\") index += 2
+    else if (pattern[index] === "]") return index
+    else index += 1
+  }
+  return undefined
+}
+const characterClass = (body: string): string => {
+  const negated = body.startsWith("!") || body.startsWith("^")
+  const members = negated ? body.slice(1) : body
+  let source = ""
+  let index = 0
+  while (index < members.length) {
+    const value = members[index]!
+    if (value === "\\" && index + 1 < members.length) {
+      source += `\\${members[index + 1]!}`
+      index += 2
+      continue
+    }
+    source += value === "-" ? "-" : classLiteral(value)
+    index += 1
+  }
+  return `[${negated ? "^" : ""}${source}]`
+}
+// `{a,b}` expands to whole alternative patterns because a branch may contain
+// separators (`{src/a,b}/x`); a class is copied verbatim so `,` inside it stays
+// a class member.
+const expand = (
+  pattern: string, start: number, depth: number
+): { readonly alternatives: ReadonlyArray<string>, readonly next: number } | undefined => {
+  const completed: Array<string> = []
+  let current: ReadonlyArray<string> = [""]
+  let index = start
+  const append = (text: string) => { current = current.map((value) => value + text) }
+  const flush = () => { completed.push(...current); current = [""] }
+  while (index < pattern.length) {
+    const value = pattern[index]!
+    if (value === "\\") {
+      if (index + 1 >= pattern.length) return undefined
+      append(pattern.slice(index, index + 2))
+      index += 2
+    } else if (value === "[") {
+      const end = classEnd(pattern, index)
+      if (end === undefined) return undefined
+      append(pattern.slice(index, end + 1))
+      index = end + 1
+    } else if (value === "{") {
+      const group = expand(pattern, index + 1, depth + 1)
+      if (group === undefined) return undefined
+      current = current.flatMap((prefix) => group.alternatives.map((suffix) => prefix + suffix))
+      if (current.length > alternativeLimit) return undefined
+      index = group.next
+    } else if (depth > 0 && value === "}") {
+      flush()
+      return { alternatives: completed, next: index + 1 }
+    } else if (depth > 0 && value === ",") {
+      flush()
+      index += 1
+    } else {
+      append(value)
+      index += 1
+    }
+  }
+  if (depth > 0) return undefined
+  flush()
+  return { alternatives: completed, next: index }
+}
+const globstarAt = (pattern: string, index: number): boolean =>
+  pattern.startsWith("**", index) &&
+  (index + 2 === pattern.length || pattern[index + 2] === "/")
+const compile = (pattern: string): RegExp | undefined => {
+  let source = "^"
+  let index = 0
+  while (index < pattern.length) {
+    const value = pattern[index]!
+    if (value === "\\") {
+      if (index + 1 >= pattern.length) return undefined
+      source += literal(pattern[index + 1]!)
+      index += 2
+    } else if (value === "[") {
+      const end = classEnd(pattern, index)
+      if (end === undefined) return undefined
+      source += characterClass(pattern.slice(index + 1, end))
+      index = end + 1
+    } else if (value === "*") {
+      let run = 1
+      while (pattern[index + run] === "*") run += 1
+      const whole = (index === 0 || pattern[index - 1] === "/") &&
+        (index + run === pattern.length || pattern[index + run] === "/")
+      const rest = index + run + 1
+      if (run === 2 && whole && index + run === pattern.length) source += ".*"
+      else if (run === 2 && whole) {
+        // `**/**` collapses; otherwise `**/` skips whole segments and whatever
+        // follows must still match at least one character, so `**/*` never
+        // matches a bare directory the way `a/*` does.
+        if (!globstarAt(pattern, rest)) {
+          source += rest === pattern.length ? "(?:[^/]*/)*" : "(?:[^/]*/)*(?=[\\s\\S])"
+        }
+        run += 1
+      } else source += "[^/]*"
+      index += run
+    } else if (value === "?") {
+      source += "[^/]"
+      index += 1
+    } else {
+      source += literal(value)
+      index += 1
+    }
+  }
+  // A reversed class range like [z-a] is legal glob text but an invalid
+  // regular expression; it matches nothing, like every other malformed pattern.
+  try {
+    return new RegExp(`${source}$`)
+  } catch {
+    return undefined
+  }
+}
+export const matchGlob = (pattern: string): (path: string) => boolean => {
+  const expanded = expand(pattern, 0, 0)
+  const compiled = expanded?.alternatives.map(compile)
+  if (compiled === undefined || compiled.some((item) => item === undefined)) return () => false
+  return (path) => compiled.some((item) => item!.test(path))
+}

package/src/drivers/process.ts

@@ -0,0 +1,339 @@
+import * as Effect from "effect/Effect"
+import * as Stream from "effect/Stream"
+import * as ChildProcess from "effect/unstable/process/ChildProcess"
+import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
+import { createHash } from "node:crypto"
+import {
+  accessSync,
+  chmodSync,
+  constants,
+  copyFileSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs"
+import { delimiter, isAbsolute, join, resolve } from "node:path"
+import { readEnvironment, readOptionalEnv } from "./environment.js"
+import { redactOutput, redactProtocolOutput } from "./redact.js"
+import { networkIsolationHelperSource } from "./seccomp-helper-source.js"
+import { failure } from "./utils.js"
+import { DriverError } from "./errors.js"
+import { makeCanonicalTemporaryDirectory } from "./workspace.js"
+
+export interface NetworkIsolationIdentity {
+  readonly protocol: "ts-release-seccomp-network-deny/v1"
+  readonly helperSha256: string
+  readonly librarySha256: string
+  readonly bunVersion: string
+  readonly bunSha256: string
+  readonly kernel: string
+  readonly architecture: string
+  readonly deniedSyscalls: ReadonlyArray<string>
+}
+
+export interface ExecutableIdentity {
+  readonly protocol: "ts-release-executable/v1"
+  readonly command: string
+  readonly sha256: string
+}
+
+export interface BunCompileRuntimeIdentity {
+  readonly protocol: "ts-release-bun-compile-runtime/v1"
+  readonly target: "bun-linux-x64" | "bun-linux-arm64" | "bun-darwin-x64" | "bun-darwin-arm64"
+  readonly bunVersion: string
+  readonly source: "executing-bun" | "host-cache-private-copy"
+  readonly cacheFile: string
+  readonly sha256: string
+}
+
+const helperDigest = createHash("sha256").update(networkIsolationHelperSource).digest("hex")
+
+export type CommandOutcome = {
+  readonly exitCode: number, readonly stdout: string, readonly stderr: string,
+  /** Present for the production process driver; protocol doubles may omit it. */
+  readonly tool?: ExecutableIdentity,
+  readonly networkIsolation?: NetworkIsolationIdentity,
+  readonly bunCompileRuntime?: BunCompileRuntimeIdentity
+}
+export type RunCommand = (command: {
+  readonly argv: ReadonlyArray<string>, readonly cwd: string,
+  readonly environmentNames: ReadonlyArray<string>,
+  /** Complete redacted stdout for an immediate machine-protocol decoder.
+   * The caller must not persist it as diagnostic output. */
+  readonly stdout?: "complete-protocol",
+  /** Generic commands require the fail-closed Linux/libseccomp filter;
+   * certified local-only tools additionally carry their own offline switch. */
+  readonly network: "deny" | "offline-cli"
+}) => Effect.Effect<CommandOutcome, DriverError>
+
+const collect = (stream: Stream.Stream<Uint8Array, unknown>) =>
+  Stream.mkString(Stream.decodeText(stream))
+
+const executableIdentity = (command: string, cwd: string, path: string | undefined): ExecutableIdentity => {
+  const candidates = command.includes("/")
+    ? [isAbsolute(command) ? command : resolve(cwd, command)]
+    : (path ?? "").split(delimiter).filter((entry) => entry.length > 0).map((entry) => resolve(entry, command))
+  const executable = candidates.find((candidate) => {
+    try {
+      accessSync(candidate, constants.X_OK)
+      return statSync(candidate).isFile()
+    } catch {
+      return false
+    }
+  })
+  if (executable === undefined) throw new Error(`Executable ${command} is unavailable in the closed PATH.`)
+  const canonical = realpathSync(executable)
+  return {
+    protocol: "ts-release-executable/v1",
+    command,
+    sha256: createHash("sha256").update(readFileSync(canonical)).digest("hex")
+  }
+}
+
+const isDigest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/u.test(value)
+const offlineBunInstallArgv = [
+  "bun",
+  "install",
+  "--offline",
+  "--frozen-lockfile",
+  "--ignore-scripts",
+  "--no-save",
+  "--linker=hoisted"
+] as const
+const isOfflineBunInstall = (command: Parameters<RunCommand>[0]): boolean =>
+  command.network === "offline-cli" && command.argv.length === offlineBunInstallArgv.length &&
+  command.argv.every((value, index) => value === offlineBunInstallArgv[index])
+
+const readBunCacheDirectory = Effect.fn("readBunCacheDirectory")(function*() {
+  const configured = yield* readOptionalEnv("BUN_INSTALL_CACHE_DIR")
+  const home = configured === undefined ? yield* readOptionalEnv("HOME") : undefined
+  const candidate = configured ?? (home === undefined ? undefined : join(home, ".bun", "install", "cache"))
+  if (candidate === undefined || candidate.length === 0) {
+    return yield* Effect.fail(failure(
+      "Certified Bun cache access requires BUN_INSTALL_CACHE_DIR or HOME so the host cache can be located."
+    ))
+  }
+  return yield* Effect.try({
+    try: () => {
+      if (!isAbsolute(candidate)) throw new Error("the cache path is not absolute")
+      const canonical = realpathSync(candidate)
+      if (!statSync(canonical).isDirectory()) throw new Error("the cache path is not a directory")
+      return canonical
+    },
+    catch: (cause) => failure(`The offline Bun install cache is unavailable: ${String(cause)}`)
+  })
+})
+
+const compileRuntimeFiles = {
+  "bun-linux-arm64": (version: string) => `bun-linux-aarch64-v${version}`,
+  "bun-darwin-x64": (version: string) => `bun-darwin-x64-v${version}`,
+  "bun-darwin-arm64": (version: string) => `bun-darwin-aarch64-v${version}`
+} as const
+
+type CertifiedBunCompileTarget = BunCompileRuntimeIdentity["target"]
+const certifiedBunCompileTargets = new Set<CertifiedBunCompileTarget>([
+  "bun-linux-x64",
+  "bun-linux-arm64",
+  "bun-darwin-x64",
+  "bun-darwin-arm64"
+])
+
+const certifiedBunCompileTarget = (command: Parameters<RunCommand>[0]): CertifiedBunCompileTarget | undefined => {
+  const argv = command.argv
+  if (command.network !== "deny" || (argv.length !== 8 && argv.length !== 9) ||
+      argv[0] !== "bun" || argv[1] !== "build" || argv[2]?.startsWith("-") !== false ||
+      argv[3] !== "--compile" || argv[4] !== "--target" || argv[6] !== "--outfile" ||
+      argv[7]?.startsWith("-") !== false || (argv.length === 9 && argv[8] !== "--minify")) return undefined
+  return certifiedBunCompileTargets.has(argv[5] as CertifiedBunCompileTarget)
+    ? argv[5] as CertifiedBunCompileTarget
+    : undefined
+}
+
+const resolveBunCompileRuntime = Effect.fn("resolveBunCompileRuntime")(function*(
+  target: CertifiedBunCompileTarget,
+  tool: ExecutableIdentity
+) {
+  const bunVersion = process.versions.bun
+  if (bunVersion === undefined || bunVersion.length === 0) {
+    return yield* Effect.fail(failure("Certified Bun compilation requires a Bun parent runtime."))
+  }
+  if (target === "bun-linux-x64") {
+    return {
+      sourcePath: undefined,
+      identity: {
+        protocol: "ts-release-bun-compile-runtime/v1",
+        target,
+        bunVersion,
+        source: "executing-bun",
+        cacheFile: "executing-bun",
+        sha256: tool.sha256
+      } satisfies BunCompileRuntimeIdentity
+    }
+  }
+  const cache = yield* readBunCacheDirectory()
+  const cacheFile = compileRuntimeFiles[target](bunVersion)
+  return yield* Effect.try({
+    try: () => {
+      const sourcePath = join(cache, cacheFile)
+      if (lstatSync(sourcePath).isSymbolicLink() || !lstatSync(sourcePath).isFile() ||
+          realpathSync(sourcePath) !== sourcePath) {
+        throw new Error("the target runtime is not a canonical regular file")
+      }
+      return {
+        sourcePath,
+        identity: {
+          protocol: "ts-release-bun-compile-runtime/v1",
+          target,
+          bunVersion,
+          source: "host-cache-private-copy",
+          cacheFile,
+          sha256: createHash("sha256").update(readFileSync(sourcePath)).digest("hex")
+        } satisfies BunCompileRuntimeIdentity
+      }
+    },
+    catch: (cause) => failure(`The certified Bun compile runtime is unavailable: ${String(cause)}`)
+  })
+})
+
+const parseIsolationIdentity = (path: string): NetworkIsolationIdentity => {
+  const value: unknown = JSON.parse(readFileSync(path, "utf8"))
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("isolation identity is not an object")
+  const item = value as Record<string, unknown>
+  if (item.protocol !== "ts-release-seccomp-network-deny/v1" || item.helperSha256 !== helperDigest ||
+      !isDigest(item.helperSha256) || !isDigest(item.librarySha256) || !isDigest(item.bunSha256) ||
+      typeof item.bunVersion !== "string" || item.bunVersion.length === 0 || typeof item.kernel !== "string" ||
+      item.kernel.length === 0 || typeof item.architecture !== "string" || item.architecture.length === 0 ||
+      !Array.isArray(item.deniedSyscalls) || item.deniedSyscalls.some((name) => typeof name !== "string")) {
+    throw new Error("isolation identity is malformed or disagrees with the embedded helper")
+  }
+  return item as unknown as NetworkIsolationIdentity
+}
+
+// Spawning is the capability that differs across hosts, so it arrives as a
+// service. The runner is built once per live layer and closes over the
+// spawner, keeping DriverCatalog method requirements at never.
+export const makeRunCommand: Effect.Effect<RunCommand, never, ChildProcessSpawner> =
+  Effect.gen(function*() {
+    const spawner = yield* ChildProcessSpawner
+    return (command) => Effect.gen(function*() {
+      const baseEnvironment = yield* readEnvironment(command.environmentNames)
+      const env = isOfflineBunInstall(command)
+        ? {
+          ...Object.fromEntries(Object.entries(baseEnvironment).filter(([name]) => name !== "HOME")),
+          BUN_INSTALL_CACHE_DIR: yield* readBunCacheDirectory()
+        }
+        : baseEnvironment
+      const executable = command.network === "deny" ? "bun" : command.argv[0]!
+      const tool = yield* Effect.try({
+        try: () => executableIdentity(executable, command.cwd, env.PATH),
+        catch: (cause) => failure(String(cause))
+      })
+      const compileTarget = certifiedBunCompileTarget(command)
+      const compileRuntime = compileTarget === undefined
+        ? undefined
+        : yield* resolveBunCompileRuntime(compileTarget, tool)
+      const compileResources = compileRuntime === undefined
+        ? undefined
+        : yield* Effect.acquireRelease(
+          Effect.sync(() => {
+            const directory = makeCanonicalTemporaryDirectory("ts-release-bun-runtime-")
+            const cache = join(directory, "cache")
+            mkdirSync(cache, { mode: 0o700 })
+            if (compileRuntime.sourcePath !== undefined) {
+              copyFileSync(compileRuntime.sourcePath, join(cache, compileRuntime.identity.cacheFile))
+              chmodSync(join(cache, compileRuntime.identity.cacheFile), 0o500)
+            }
+            chmodSync(cache, 0o500)
+            return { directory, cache }
+          }),
+          ({ cache, directory }) => Effect.sync(() => {
+            chmodSync(cache, 0o700)
+            rmSync(directory, { recursive: true, force: true })
+          })
+        )
+      const isolationResources = command.network === "deny"
+        ? yield* Effect.acquireRelease(
+          Effect.sync(() => {
+            const directory = makeCanonicalTemporaryDirectory("ts-release-seccomp-")
+            const helper = join(directory, "network-deny.mjs")
+            const identity = join(directory, "identity.json")
+            writeFileSync(helper, networkIsolationHelperSource, { mode: 0o500 })
+            return { directory, helper, identity }
+          }),
+          ({ directory }) => Effect.sync(() => rmSync(directory, { recursive: true, force: true }))
+        )
+        : undefined
+      const argv = command.network === "deny"
+        ? ["--no-env-file", "--no-install", isolationResources!.helper, ...command.argv]
+        : [...command.argv.slice(1)]
+      const commandEnvironment = compileResources === undefined
+        ? env
+        : { ...env, BUN_INSTALL_CACHE_DIR: compileResources.cache }
+      const handle = yield* spawner.spawn(ChildProcess.make(
+        executable,
+        argv,
+        {
+          cwd: command.cwd,
+          env: isolationResources === undefined ? commandEnvironment : {
+            ...commandEnvironment,
+            TS_RELEASE_NETWORK_IDENTITY_FILE: isolationResources.identity,
+            TS_RELEASE_NETWORK_HELPER_SHA256: helperDigest,
+            TS_RELEASE_NETWORK_LIBRARY: "libseccomp.so.2"
+          },
+          stdin: "ignore", stdout: "pipe", stderr: "pipe"
+        }
+      ))
+      const output = yield* Effect.all({
+        stdout: collect(handle.stdout),
+        stderr: collect(handle.stderr),
+        exitCode: handle.exitCode
+      }, { concurrency: "unbounded" })
+      // Redaction lives here, where the env values are in hand: every
+      // consumer of child output (Exec failures, publisher stdout/stderr)
+      // is covered at the source and no driver can forget.
+      const networkIsolation = isolationResources === undefined
+        ? undefined
+        : yield* Effect.try({
+          try: () => parseIsolationIdentity(isolationResources.identity),
+          catch: (cause) => failure(String(cause))
+        })
+      if (networkIsolation !== undefined && networkIsolation.bunSha256 !== tool.sha256) {
+        return yield* Effect.fail(failure("The Bun executable changed between parent resolution and the isolation helper."))
+      }
+      if (compileResources !== undefined && compileRuntime !== undefined) yield* Effect.try({
+        try: () => {
+          const entries = readdirSync(compileResources.cache)
+          const expected = compileRuntime.sourcePath === undefined ? [] : [compileRuntime.identity.cacheFile]
+          if (entries.length !== expected.length || entries.some((entry, index) => entry !== expected[index])) {
+            throw new Error("the private runtime cache changed shape")
+          }
+          if (expected[0] !== undefined) {
+            const runtime = join(compileResources.cache, expected[0])
+            if (lstatSync(runtime).isSymbolicLink() || !lstatSync(runtime).isFile() ||
+                createHash("sha256").update(readFileSync(runtime)).digest("hex") !== compileRuntime.identity.sha256) {
+              throw new Error("the private runtime cache changed bytes or type")
+            }
+          }
+        },
+        catch: (cause) => failure(`Certified Bun compilation did not preserve its private runtime cache: ${String(cause)}`)
+      })
+      return {
+        stdout: command.stdout === "complete-protocol"
+          ? redactProtocolOutput(output.stdout, commandEnvironment)
+          : redactOutput(output.stdout, commandEnvironment),
+        stderr: redactOutput(output.stderr, commandEnvironment),
+        exitCode: Number(output.exitCode),
+        tool,
+        ...(networkIsolation === undefined ? {} : { networkIsolation }),
+        ...(compileRuntime === undefined ? {} : { bunCompileRuntime: compileRuntime.identity })
+      }
+    }).pipe(
+      Effect.scoped,
+      Effect.mapError((cause) => cause instanceof DriverError ? cause : failure(String(cause)))
+    )
+  })

package/src/drivers/python-wheel.ts

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto"
+import type { ArchiveEntry } from "./archive.js"
+import { zip } from "./archive.js"
+import {
+  bunArtifactTargets,
+  type BunArtifactTargetId
+} from "../model/bun-targets.js"
+
+export interface EmbeddedPythonWheelTarget {
+  readonly id: BunArtifactTargetId
+  readonly format: "elf" | "mach-o"
+  readonly architecture: "x86_64" | "aarch64"
+  readonly wheelTag: string
+}
+
+const wheelTags = {
+  "linux-x64": "py3-none-manylinux_2_17_x86_64",
+  "linux-arm64": "py3-none-manylinux_2_17_aarch64",
+  "darwin-x64": "py3-none-macosx_13_0_x86_64",
+  "darwin-arm64": "py3-none-macosx_13_0_arm64"
+} as const satisfies Readonly<Record<BunArtifactTargetId, string>>
+
+export const embeddedPythonWheelTargets: ReadonlyArray<EmbeddedPythonWheelTarget> = Object.freeze(
+  bunArtifactTargets.map((target) => Object.freeze({
+    id: target.id,
+    format: target.format,
+    architecture: target.architecture,
+    wheelTag: wheelTags[target.id]
+  }))
+)
+
+const encoder = new TextEncoder()
+const bytes = (value: string): Uint8Array => encoder.encode(value)
+const safeMetadata = (name: string, value: string): string => {
+  if (value.length === 0 || /[\r\n\0]/u.test(value)) {
+    throw new Error(`Python wheel ${name} must be a nonempty single-line value.`)
+  }
+  return value
+}
+const normalizedVersion = (version: string): string =>
+  safeMetadata("version", version).replaceAll("-", "_")
+const distribution = "ts_release"
+const moduleName = "ts_release"
+const projectName = "ts-release"
+const consoleScript = "ts-release"
+
+export const embeddedPythonWheelFilename = (
+  target: EmbeddedPythonWheelTarget,
+  version: string
+): string => `${distribution}-${normalizedVersion(version)}-${target.wheelTag}.whl`
+
+const launcher = `"""Launch the platform-specific ts-release executable bundled in this wheel."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from importlib import resources
+
+
+def main() -> int:
+    try:
+        executable = resources.files("${moduleName}").joinpath("bin", "${consoleScript}")
+        with resources.as_file(executable) as binary:
+            if not binary.is_file():
+                raise RuntimeError(f"Bundled ${consoleScript} executable was not found: {binary}")
+            binary_path = os.fspath(binary)
+            os.chmod(binary_path, os.stat(binary_path).st_mode | stat.S_IXUSR)
+            os.execv(binary_path, [binary_path, *sys.argv[1:]])
+    except Exception as error:
+        print(f"${consoleScript} launcher error: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+`
+
+export interface EmbeddedPythonWheelInput {
+  readonly target: EmbeddedPythonWheelTarget
+  readonly version: string
+  readonly summary: string
+  readonly homepage: string
+  readonly license: string
+  readonly binary: Uint8Array
+}
+
+export const embeddedPythonWheelEntries = (
+  input: EmbeddedPythonWheelInput
+): ReadonlyArray<ArchiveEntry> => {
+  const version = safeMetadata("version", input.version)
+  const summary = safeMetadata("summary", input.summary)
+  const homepage = safeMetadata("homepage", input.homepage)
+  const license = safeMetadata("license", input.license)
+  if (input.binary.length === 0) throw new Error("Python wheel executable cannot be empty.")
+  const distInfo = `${distribution}-${normalizedVersion(version)}.dist-info`
+  const metadata = [
+    "Metadata-Version: 2.4",
+    `Name: ${projectName}`,
+    `Version: ${version}`,
+    `Summary: ${summary}`,
+    `Home-page: ${homepage}`,
+    `License-Expression: ${license}`,
+    "Requires-Python: >=3.9",
+    "Description-Content-Type: text/plain",
+    "",
+    summary,
+    ""
+  ].join("\n")
+  const entries: ArchiveEntry[] = [
+    { path: `${moduleName}/__init__.py`, data: bytes(`__version__ = ${JSON.stringify(version)}\n`), mode: 0o100644 },
+    { path: `${moduleName}/cli.py`, data: bytes(launcher), mode: 0o100644 },
+    { path: `${moduleName}/bin/${consoleScript}`, data: input.binary, mode: 0o100755 },
+    { path: `${distInfo}/METADATA`, data: bytes(metadata), mode: 0o100644 },
+    {
+      path: `${distInfo}/WHEEL`,
+      data: bytes([
+        "Wheel-Version: 1.0",
+        "Generator: ts-release",
+        "Root-Is-Purelib: false",
+        `Tag: ${input.target.wheelTag}`,
+        ""
+      ].join("\n")),
+      mode: 0o100644
+    },
+    {
+      path: `${distInfo}/entry_points.txt`,
+      data: bytes(`[console_scripts]\n${consoleScript} = ${moduleName}.cli:main\n`),
+      mode: 0o100644
+    },
+    { path: `${distInfo}/top_level.txt`, data: bytes(`${moduleName}\n`), mode: 0o100644 }
+  ]
+  entries.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
+  const recordPath = `${distInfo}/RECORD`
+  const record = entries.map((entry) =>
+    `${entry.path},sha256=${createHash("sha256").update(entry.data).digest("base64url")},${entry.data.length}`
+  )
+  record.push(`${recordPath},,`)
+  entries.push({ path: recordPath, data: bytes(`${record.join("\n")}\n`), mode: 0o100644 })
+  return entries
+}
+
+export const buildEmbeddedPythonWheel = (input: EmbeddedPythonWheelInput): Uint8Array =>
+  zip(embeddedPythonWheelEntries(input), "deflate")

package/src/drivers/redact.ts

@@ -0,0 +1,31 @@
+import { secretPatterns } from "../model/secret-patterns.js"
+
+const EXCERPT_LIMIT = 2000
+
+const redact = (text: string, env: Readonly<Record<string, string>>): string => {
+  let out = text
+  for (const [name, value] of Object.entries(env)
+    .filter(([name, value]) => name !== "PATH" && value.length >= 6)
+    .sort((left, right) => right[1].length - left[1].length)) {
+    out = out.split(value).join(`[redacted:${name}]`)
+  }
+  for (const pattern of secretPatterns) {
+    out = out.replace(new RegExp(pattern.source, `${pattern.flags.replace("u", "")}gu`), "[redacted:token]")
+  }
+  return out
+}
+
+// Redacts KNOWN values (the exact env values the child received, longest
+// first, except PATH) and known token shapes, then bounds the excerpt. Child
+// output enters a durable diagnostic ledger only through this bounded form.
+export const redactOutput = (
+  text: string, env: Readonly<Record<string, string>>
+): string => {
+  const out = redact(text, env)
+  return out.length > EXCERPT_LIMIT ? `${out.slice(0, EXCERPT_LIMIT)}…[truncated]` : out
+}
+
+/** Complete redacted machine-protocol output for immediate decoding only. */
+export const redactProtocolOutput = (
+  text: string, env: Readonly<Record<string, string>>
+): string => redact(text, env)