@projitect/cli-internals 0.0.0-stage → 1.0.0

package/src/filesystem-impl.ts

@@ -0,0 +1,230 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { Effect, Layer } from "effect"
+import { BlueprintFileSystem, Errors } from "@projitect/core"
+import type { Permission, BlueprintFileSystemShape } from "@projitect/core"
+import { isPermitted } from "./permissions.js"
+import type { FsOp } from "./permissions.js"
+
+/**
+ * Build the permission-gated `BlueprintFileSystem` Layer for one blueprint. The CLI provides a
+ * fresh layer per blueprint, baking in that blueprint's `id` and declared `permissions`. All FS
+ * paths get resolved relative to `projectRoot`; absolute paths or paths escaping `projectRoot`
+ * are rejected with `pjt.fs.permission-denied`.
+ *
+ * This is the **soft sandbox**. A worker-process replacement is a tracked v2 follow-up; this
+ * implementation enforces the same interface so the swap will be transparent to blueprint
+ * authors.
+ */
+export const makeRealLayer = (config: {
+  readonly blueprintId: string
+  readonly permissions: readonly Permission.Permission[]
+  readonly projectRoot: string
+}): Layer.Layer<BlueprintFileSystem> =>
+  makeDiskLayer({
+    blueprintId: config.blueprintId,
+    projectRoot: config.projectRoot,
+    isAllowed: (op, p) => isPermitted(config.permissions, op, p),
+  })
+
+/**
+ * The ungated project-root `BlueprintFileSystem` the engine itself uses to read and write the
+ * lockfile, diff the plan and apply changes. Same disk implementation as `makeRealLayer` with no
+ * permission check; paths that are absolute or escape `projectRoot` are still rejected.
+ */
+export const makeProjectRootLayer = (projectRoot: string): Layer.Layer<BlueprintFileSystem> =>
+  makeDiskLayer({ blueprintId: "pjt:engine", projectRoot, isAllowed: () => true })
+
+const makeDiskLayer = (config: {
+  readonly blueprintId: string
+  readonly projectRoot: string
+  readonly isAllowed: (op: FsOp, p: string) => boolean
+}): Layer.Layer<BlueprintFileSystem> => {
+  const { blueprintId, projectRoot, isAllowed } = config
+  const resolved = path.resolve(projectRoot)
+
+  const denied = (p: string, op: FsOp, message: string) =>
+    new Errors.FsPermissionDenied({
+      id: "pjt.fs.permission-denied",
+      path: p,
+      operation: op,
+      blueprintId,
+      message,
+    })
+
+  // Real path of `full`, or — when it does not exist yet (a write or mkdir target) — of its nearest
+  // existing ancestor with the missing remainder re-appended. A dangling symlink is followed to its
+  // (missing) target rather than treated as a missing name, so a link to a not-yet-created file
+  // outside the project cannot slip through; `hops` bounds circular links.
+  const maxLinkHops = 40
+  const realPathOf = async (full: string, hops = 0): Promise<string> => {
+    try {
+      return await fs.realpath(full)
+    } catch {
+      const parent = path.dirname(full)
+      const stat = await fs.lstat(full).catch(() => undefined)
+      if (stat?.isSymbolicLink() === true && hops < maxLinkHops) {
+        const target = await fs.readlink(full)
+        return realPathOf(path.resolve(await realPathOf(parent, hops), target), hops + 1)
+      }
+      if (parent === full) {
+        return full
+      }
+      return path.join(await realPathOf(parent, hops), path.basename(full))
+    }
+  }
+
+  // Accident-prevention, not hostile-code containment: the real path is resolved at check time, so
+  // a link swapped between the check and the FS call is not caught.
+  const resolvePath = (p: string, op: FsOp): Effect.Effect<string, Errors.FsPermissionDenied> =>
+    Effect.gen(function* () {
+      if (path.isAbsolute(p)) {
+        return yield* denied(p, op, `Absolute paths are not allowed in blueprints: ${p}`)
+      }
+      const full = path.resolve(resolved, p)
+      if (!full.startsWith(`${resolved}${path.sep}`) && full !== resolved) {
+        return yield* denied(p, op, `Path escapes project root: ${p}`)
+      }
+      if (!isAllowed(op, p)) {
+        return yield* denied(
+          p,
+          op,
+          `Blueprint ${blueprintId} did not declare ${op} permission for ${p}`,
+        )
+      }
+      const [realRoot, realFull] = yield* Effect.promise(() =>
+        Promise.all([realPathOf(resolved), realPathOf(full)]),
+      )
+      const realRelative = path.relative(realRoot, realFull).split(path.sep).join("/")
+      if (
+        realRelative === ".." ||
+        realRelative.startsWith("../") ||
+        path.isAbsolute(realRelative)
+      ) {
+        return yield* denied(p, op, `Path resolves outside project root via symlink: ${p}`)
+      }
+      if (!isAllowed(op, realRelative)) {
+        return yield* denied(
+          p,
+          op,
+          `Blueprint ${blueprintId} did not declare ${op} permission for ${p} (resolves to ${realRelative})`,
+        )
+      }
+      return full
+    })
+
+  const shape: BlueprintFileSystemShape = {
+    readFile: (p) =>
+      resolvePath(p, "read").pipe(
+        Effect.flatMap((full) =>
+          Effect.tryPromise({
+            try: () => fs.readFile(full, "utf8"),
+            catch: (e) =>
+              new Errors.FsReadFailed({
+                id: "pjt.fs.read-failed",
+                path: p,
+                cause: e instanceof Error ? e.message : String(e),
+                message: `Failed to read ${p}`,
+              }),
+          }),
+        ),
+      ),
+    writeFile: (p, content) =>
+      resolvePath(p, "write").pipe(
+        Effect.flatMap((full) =>
+          Effect.tryPromise({
+            try: async () => {
+              await fs.mkdir(path.dirname(full), { recursive: true })
+              await fs.writeFile(full, content, "utf8")
+            },
+            catch: (e) =>
+              new Errors.FsWriteFailed({
+                id: "pjt.fs.write-failed",
+                path: p,
+                cause: e instanceof Error ? e.message : String(e),
+                message: `Failed to write ${p}`,
+              }),
+          }),
+        ),
+      ),
+    exists: (p) =>
+      resolvePath(p, "exists").pipe(
+        Effect.flatMap((full) =>
+          Effect.tryPromise({
+            try: () =>
+              fs.access(full).then(
+                () => true,
+                () => false,
+              ),
+            catch: () => false as never,
+          }).pipe(Effect.orElseSucceed(() => false)),
+        ),
+      ),
+    // Non-recursive on purpose: removes a file or symlink, and fails on a directory so user content
+    // that now sits at the path survives.
+    remove: (p) =>
+      resolvePath(p, "remove").pipe(
+        Effect.flatMap((full) =>
+          Effect.tryPromise({
+            try: () => fs.rm(full, { force: true }),
+            catch: (e) =>
+              new Errors.FsWriteFailed({
+                id: "pjt.fs.write-failed",
+                path: p,
+                cause: e instanceof Error ? e.message : String(e),
+                message: `Failed to remove ${p}`,
+              }),
+          }),
+        ),
+      ),
+    // Non-recursive on purpose: `rmdir` is atomic about emptiness, so an entry created after the
+    // caller last looked is never deleted.
+    removeEmptyDir: (p) =>
+      resolvePath(p, "removeEmptyDir").pipe(
+        Effect.flatMap((full) =>
+          Effect.tryPromise({
+            try: () => fs.rmdir(full),
+            catch: (e) =>
+              new Errors.FsWriteFailed({
+                id: "pjt.fs.write-failed",
+                path: p,
+                cause: e instanceof Error ? e.message : String(e),
+                message: `Failed to remove empty directory ${p}`,
+              }),
+          }),
+        ),
+      ),
+    mkdir: (p) =>
+      resolvePath(p, "mkdir").pipe(
+        Effect.flatMap((full) =>
+          Effect.tryPromise({
+            try: () => fs.mkdir(full, { recursive: true }).then(() => undefined),
+            catch: (e) =>
+              new Errors.FsWriteFailed({
+                id: "pjt.fs.write-failed",
+                path: p,
+                cause: e instanceof Error ? e.message : String(e),
+                message: `Failed to mkdir ${p}`,
+              }),
+          }),
+        ),
+      ),
+    listDir: (p) =>
+      resolvePath(p, "listDir").pipe(
+        Effect.flatMap((full) =>
+          Effect.tryPromise({
+            try: () => fs.readdir(full),
+            catch: (e) =>
+              new Errors.FsReadFailed({
+                id: "pjt.fs.read-failed",
+                path: p,
+                cause: e instanceof Error ? e.message : String(e),
+                message: `Failed to list ${p}`,
+              }),
+          }),
+        ),
+      ),
+  }
+
+  return Layer.succeed(BlueprintFileSystem, shape)
+}

package/src/git.ts

@@ -0,0 +1,87 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { spawn } from "node:child_process"
+import { Effect } from "effect"
+import { Errors } from "@projitect/core"
+
+/**
+ * Returns true if `<projectRoot>/.git` exists (file or directory). Used by `pjt init` and
+ * `pjt build --force` as a hard prerequisite.
+ */
+export const isGitRepo = (projectRoot: string): Effect.Effect<boolean> =>
+  Effect.promise(() =>
+    fs.access(path.join(projectRoot, ".git")).then(
+      () => true,
+      () => false,
+    ),
+  )
+
+/**
+ * Result of `git status --porcelain`. `clean === true` means there are no uncommitted changes
+ * (including untracked files); `lines` is the parsed porcelain output for diagnostics.
+ */
+export interface GitStatus {
+  readonly clean: boolean
+  readonly lines: readonly string[]
+}
+
+/**
+ * Shell out to `git status --porcelain` and parse. Wraps process spawn failures (non-zero exit,
+ * git not installed) as `pjt.git.command-failed`. Callers ensure `.git/` exists first.
+ */
+export const gitStatus = (params: {
+  readonly projectRoot: string
+}): Effect.Effect<GitStatus, Errors.GitCommandFailed> => {
+  const { projectRoot } = params
+  return Effect.tryPromise({
+    try: () =>
+      new Promise<GitStatus>((resolve, reject) => {
+        const child = spawn("git", ["status", "--porcelain"], { cwd: projectRoot })
+        let stdout = ""
+        let stderr = ""
+        child.stdout.on("data", (chunk: Buffer) => {
+          stdout = stdout + chunk.toString("utf8")
+        })
+        child.stderr.on("data", (chunk: Buffer) => {
+          stderr = stderr + chunk.toString("utf8")
+        })
+        child.on("error", reject)
+        child.on("close", (code) => {
+          if (code !== 0) {
+            reject(new Error(`git status exited with ${String(code)}: ${stderr.trim()}`))
+            return
+          }
+          const lines = stdout
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0)
+          resolve({ clean: lines.length === 0, lines })
+        })
+      }),
+    catch: (e) =>
+      new Errors.GitCommandFailed({
+        id: "pjt.git.command-failed",
+        command: "git status --porcelain",
+        cause: e instanceof Error ? e.message : String(e),
+        message: `Failed to run \`git status --porcelain\` in ${projectRoot}`,
+      }),
+  })
+}
+
+/**
+ * Raise `pjt.git.not-a-repo` if `<projectRoot>/.git` is missing.
+ */
+export const ensureGitRepo = (params: {
+  readonly projectRoot: string
+}): Effect.Effect<void, Errors.GitNotARepo> =>
+  Effect.gen(function* () {
+    const ok = yield* isGitRepo(params.projectRoot)
+    if (ok) {
+      return
+    }
+    return yield* new Errors.GitNotARepo({
+      id: "pjt.git.not-a-repo",
+      projectRoot: params.projectRoot,
+      message: `No \`.git\` directory at ${params.projectRoot}. \`pjt build --force\` requires a git repository so destructive operations are recoverable. Run \`git init\` (or \`pjt init --yes\`), commit, then re-run.`,
+    })
+  })

package/src/index.ts

@@ -0,0 +1,54 @@
+export { rootCommand, type RootCommand } from "./commands/dispatch.js"
+export { inspect, type InspectResult } from "./commands/inspect.js"
+export { remodel, type RemodelResult } from "./commands/remodel.js"
+export { init, type InitResult } from "./commands/init.js"
+export { explain } from "./commands/explain.js"
+export { build } from "./commands/build.js"
+export { add } from "./commands/add.js"
+export { resolveConfig, parseEnv } from "./config-cascade.js"
+export {
+  loadBlueprintFile,
+  pjt,
+  isEffectTree,
+  type ProjitectFile,
+  type BlueprintTree,
+} from "./loader.js"
+export {
+  buildPlan,
+  diffLockfile,
+  type ProjectPlan,
+  type FilePlan,
+  type ByBlueprint,
+  type UpgradeRecord,
+} from "./plan.js"
+export {
+  diffPlan,
+  renderPlanDiff,
+  renderInspectReport,
+  type PlanDiff,
+  type FileDiff,
+} from "./differ.js"
+export { applyPlan } from "./applier.js"
+export { applyRemovals } from "./remover.js"
+export { readLockfile, writeLockfile, blueprintIds } from "./lockfile.js"
+export { makeRealLayer, makeProjectRootLayer } from "./filesystem-impl.js"
+export {
+  NodePlatformLive,
+  FileSystemLive,
+  StdioLive,
+  TerminalLive,
+  runCommand,
+  nodeSpawner,
+  type ProcessSpawner,
+  type CommandOutput,
+} from "./platform/index.js"
+export { splice } from "./edit-pjt.js"
+export {
+  detect as detectPackageManager,
+  installDev,
+  readProjitectMetadata,
+  type PackageManager,
+} from "./pm.js"
+export type { ProjitectPackageMetadata } from "@projitect/blueprint"
+export { isGitRepo, gitStatus, ensureGitRepo } from "./git.js"
+export * as Ipc from "./ipc/index.js"

package/src/ipc/client.ts

@@ -0,0 +1,108 @@
+import { Effect, Layer, Match } from "effect"
+import { BlueprintFileSystem } from "@projitect/core"
+import type { BlueprintFileSystemShape } from "@projitect/core"
+import { decodeResponse, encodeRequest } from "./protocol.js"
+import type { FsError, Request, Response } from "./protocol.js"
+import type { Transport } from "./transport.js"
+
+type Pending = (response: Response) => void
+
+/**
+ * Child side: a `BlueprintFileSystemShape` that forwards each call to the parent-side server over
+ * `transport` and decodes the reply, re-raising failures as the original typed error.
+ */
+export const makeClient = (transport: Transport): BlueprintFileSystemShape => {
+  const pending = new Map<number, Pending>()
+  let nextId = 0
+
+  transport.onMessage((frame) => {
+    Effect.runFork(
+      decodeResponse(frame).pipe(
+        Effect.tap((response) =>
+          Effect.sync(() => {
+            pending.get(response.id)?.(response)
+            pending.delete(response.id)
+          }),
+        ),
+        Effect.ignore,
+      ),
+    )
+  })
+
+  const call = (
+    build: (id: number) => Request,
+  ): Effect.Effect<Exclude<Response, { readonly _tag: "Failure" }>, FsError> =>
+    Effect.gen(function* () {
+      const id = nextId++
+      const encoded = yield* Effect.orDie(encodeRequest(build(id)))
+      const response = yield* Effect.callback<Response>((resume) => {
+        pending.set(id, (reply) => {
+          resume(Effect.succeed(reply))
+        })
+        transport.send(encoded)
+        return Effect.sync(() => pending.delete(id))
+      })
+      return yield* Match.value(response).pipe(
+        Match.tag("Failure", ({ error }) => Effect.fail(error)),
+        Match.orElse((ok) => Effect.succeed(ok)),
+      )
+    })
+
+  // The server only emits a method's own failure tags; the other tag is unreachable by protocol.
+  const noRead = <A>(effect: Effect.Effect<A, FsError>) =>
+    Effect.catch(effect, (error) =>
+      Match.value(error).pipe(
+        Match.tag("FsReadFailed", (unreachable) => Effect.die(unreachable)),
+        Match.orElse((rest) => Effect.fail(rest)),
+      ),
+    )
+  const noWrite = <A>(effect: Effect.Effect<A, FsError>) =>
+    Effect.catch(effect, (error) =>
+      Match.value(error).pipe(
+        Match.tag("FsWriteFailed", (unreachable) => Effect.die(unreachable)),
+        Match.orElse((rest) => Effect.fail(rest)),
+      ),
+    )
+  const onlyDenied = <A>(effect: Effect.Effect<A, FsError>) =>
+    Effect.catch(effect, (error) =>
+      Match.value(error).pipe(
+        Match.tag("FsReadFailed", "FsWriteFailed", (unreachable) => Effect.die(unreachable)),
+        Match.orElse((rest) => Effect.fail(rest)),
+      ),
+    )
+
+  return {
+    readFile: (path) =>
+      call((id) => ({ _tag: "ReadFile", id, path })).pipe(
+        Effect.flatMap((r) =>
+          r._tag === "ReadFileOk" ? Effect.succeed(r.value) : Effect.die(unexpected(r)),
+        ),
+        noWrite,
+      ),
+    writeFile: (path, content) =>
+      call((id) => ({ _tag: "WriteFile", id, path, content })).pipe(Effect.asVoid, noRead),
+    exists: (path) =>
+      call((id) => ({ _tag: "Exists", id, path })).pipe(
+        Effect.flatMap((r) =>
+          r._tag === "ExistsOk" ? Effect.succeed(r.value) : Effect.die(unexpected(r)),
+        ),
+        onlyDenied,
+      ),
+    remove: (path) => call((id) => ({ _tag: "Remove", id, path })).pipe(Effect.asVoid, noRead),
+    removeEmptyDir: (path) =>
+      call((id) => ({ _tag: "RemoveEmptyDir", id, path })).pipe(Effect.asVoid, noRead),
+    mkdir: (path) => call((id) => ({ _tag: "Mkdir", id, path })).pipe(Effect.asVoid, noRead),
+    listDir: (path) =>
+      call((id) => ({ _tag: "ListDir", id, path })).pipe(
+        Effect.flatMap((r) =>
+          r._tag === "ListDirOk" ? Effect.succeed(r.value) : Effect.die(unexpected(r)),
+        ),
+        noWrite,
+      ),
+  }
+}
+
+const unexpected = (response: Response): string => `Unexpected IPC response: ${response._tag}`
+
+export const makeClientLayer = (transport: Transport): Layer.Layer<BlueprintFileSystem> =>
+  Layer.succeed(BlueprintFileSystem, makeClient(transport))

package/src/ipc/index.ts

@@ -0,0 +1,12 @@
+export { makeClient, makeClientLayer } from "./client.js"
+export { serve } from "./server.js"
+export { makeInProcessPair, type Transport } from "./transport.js"
+export {
+  Request,
+  Response,
+  FsError,
+  encodeRequest,
+  decodeRequest,
+  encodeResponse,
+  decodeResponse,
+} from "./protocol.js"

package/src/ipc/protocol.ts

@@ -0,0 +1,48 @@
+import { Schema } from "effect"
+import { Errors } from "@projitect/core"
+
+/**
+ * Wire frames for marshalling `BlueprintFileSystem` calls across a process boundary. Every frame
+ * carries a correlation `id`; one request form exists per service method. Failures travel as the
+ * existing `Schema.TaggedError` classes, so class, id and fields survive the round trip.
+ */
+
+export const Request = Schema.Union([
+  Schema.TaggedStruct("ReadFile", { id: Schema.Number, path: Schema.String }),
+  Schema.TaggedStruct("WriteFile", {
+    id: Schema.Number,
+    path: Schema.String,
+    content: Schema.String,
+  }),
+  Schema.TaggedStruct("Exists", { id: Schema.Number, path: Schema.String }),
+  Schema.TaggedStruct("Remove", { id: Schema.Number, path: Schema.String }),
+  Schema.TaggedStruct("RemoveEmptyDir", { id: Schema.Number, path: Schema.String }),
+  Schema.TaggedStruct("Mkdir", { id: Schema.Number, path: Schema.String }),
+  Schema.TaggedStruct("ListDir", { id: Schema.Number, path: Schema.String }),
+])
+export type Request = typeof Request.Type
+
+export const FsError = Schema.Union([
+  Errors.FsPermissionDenied,
+  Errors.FsReadFailed,
+  Errors.FsWriteFailed,
+])
+export type FsError = typeof FsError.Type
+
+export const Response = Schema.Union([
+  Schema.TaggedStruct("ReadFileOk", { id: Schema.Number, value: Schema.String }),
+  Schema.TaggedStruct("WriteFileOk", { id: Schema.Number }),
+  Schema.TaggedStruct("ExistsOk", { id: Schema.Number, value: Schema.Boolean }),
+  Schema.TaggedStruct("RemoveOk", { id: Schema.Number }),
+  Schema.TaggedStruct("RemoveEmptyDirOk", { id: Schema.Number }),
+  Schema.TaggedStruct("MkdirOk", { id: Schema.Number }),
+  Schema.TaggedStruct("ListDirOk", { id: Schema.Number, value: Schema.Array(Schema.String) }),
+  Schema.TaggedStruct("Failure", { id: Schema.Number, error: FsError }),
+])
+export type Response = typeof Response.Type
+
+/** Frames cross the transport in their encoded (JSON-compatible) form. */
+export const encodeRequest = Schema.encodeEffect(Request)
+export const decodeRequest = Schema.decodeUnknownEffect(Request)
+export const encodeResponse = Schema.encodeEffect(Response)
+export const decodeResponse = Schema.decodeUnknownEffect(Response)

package/src/ipc/server.ts

@@ -0,0 +1,62 @@
+import { Effect, Match, pipe } from "effect"
+import type { BlueprintFileSystemShape } from "@projitect/core"
+import { decodeRequest, encodeResponse } from "./protocol.js"
+import type { Request, Response } from "./protocol.js"
+import type { Transport } from "./transport.js"
+
+const respond = (shape: BlueprintFileSystemShape, request: Request): Effect.Effect<Response> => {
+  const failure = (error: Extract<Response, { readonly _tag: "Failure" }>["error"]): Response => ({
+    _tag: "Failure",
+    id: request.id,
+    error,
+  })
+  return pipe(
+    request,
+    Match.value,
+    Match.tag("ReadFile", ({ id, path }) =>
+      Effect.map(shape.readFile(path), (value): Response => ({ _tag: "ReadFileOk", id, value })),
+    ),
+    Match.tag("WriteFile", ({ id, path, content }) =>
+      Effect.map(shape.writeFile(path, content), (): Response => ({ _tag: "WriteFileOk", id })),
+    ),
+    Match.tag("Exists", ({ id, path }) =>
+      Effect.map(shape.exists(path), (value): Response => ({ _tag: "ExistsOk", id, value })),
+    ),
+    Match.tag("Remove", ({ id, path }) =>
+      Effect.map(shape.remove(path), (): Response => ({ _tag: "RemoveOk", id })),
+    ),
+    Match.tag("RemoveEmptyDir", ({ id, path }) =>
+      Effect.map(shape.removeEmptyDir(path), (): Response => ({ _tag: "RemoveEmptyDirOk", id })),
+    ),
+    Match.tag("Mkdir", ({ id, path }) =>
+      Effect.map(shape.mkdir(path), (): Response => ({ _tag: "MkdirOk", id })),
+    ),
+    Match.tag("ListDir", ({ id, path }) =>
+      Effect.map(shape.listDir(path), (value): Response => ({ _tag: "ListDirOk", id, value })),
+    ),
+    Match.exhaustive,
+    Effect.catch((error) => Effect.succeed(failure(error))),
+  )
+}
+
+/**
+ * Parent side: decode each request frame, run it against the (permission-gated) `shape` and send
+ * the encoded response back. Frames that fail to decode are dropped — the client only ever sends
+ * well-formed frames, and a correlation id cannot be recovered from a malformed one.
+ */
+export const serve = (transport: Transport, shape: BlueprintFileSystemShape): void => {
+  transport.onMessage((frame) => {
+    Effect.runFork(
+      decodeRequest(frame).pipe(
+        Effect.flatMap((request) => respond(shape, request)),
+        Effect.flatMap(encodeResponse),
+        Effect.tap((encoded) =>
+          Effect.sync(() => {
+            transport.send(encoded)
+          }),
+        ),
+        Effect.ignore,
+      ),
+    )
+  })
+}

package/src/ipc/transport.ts

@@ -0,0 +1,28 @@
+/**
+ * A minimal message channel between the parent-side server and the child-side client. Frames are
+ * JSON-compatible values, so any process IPC channel can implement it; `makeInProcessPair` backs
+ * the tests.
+ */
+export interface Transport {
+  readonly send: (frame: unknown) => void
+  readonly onMessage: (handler: (frame: unknown) => void) => void
+}
+
+/** Two connected transports: whatever one end sends, the other end's handler receives. */
+export const makeInProcessPair = (): readonly [Transport, Transport] => {
+  const handlers: [((frame: unknown) => void)[], ((frame: unknown) => void)[]] = [[], []]
+  const endpoint = (self: 0 | 1): Transport => ({
+    send: (frame) => {
+      const peer = self === 0 ? 1 : 0
+      queueMicrotask(() => {
+        for (const handler of handlers[peer]) {
+          handler(frame)
+        }
+      })
+    },
+    onMessage: (handler) => {
+      handlers[self].push(handler)
+    },
+  })
+  return [endpoint(0), endpoint(1)]
+}