@playfast/muxmaxing-config 0.1.1 → 0.2.0

package/README.md

@@ -13,7 +13,7 @@ host-side in a Bun Worker, only for repos the user has explicitly approved.
 import { defineConfig } from '@playfast/muxmaxing-config'
 import { Effect, Schema as S } from 'effect'
 
-const TokenJson = S.parseJson(S.Struct({ key: S.String, slug: S.String }))
+const TokenJson = S.parseJson(S.Struct({ token: S.String, slug: S.String }))
 
 export default defineConfig({
   hostInput: S.Struct({ dopplerToken: S.String, tokenSlug: S.String }),
@@ -25,7 +25,7 @@ export default defineConfig({
         `doppler configs tokens create mux-${unit.id} --project my-app --config dev --max-age 24h --json`,
       )
       const token = yield* S.decode(TokenJson)(minted.stdout)
-      return { dopplerToken: token.key, tokenSlug: token.slug }
+      return { dopplerToken: token.token, tokenSlug: token.slug }
     }),
 
   // Runs when the unit is up: `ctx.unit.bash` execs INSIDE the unit.

package/package.json

@@ -1,50 +1,48 @@
 {
   "name": "@playfast/muxmaxing-config",
-  "version": "0.1.1",
-  "type": "module",
+  "version": "0.2.0",
   "description": "Author API for muxmaxing.config.ts — a repo-committed hook bridge between the host device and muxmaxing work units: typed host-input collection plus Effect-native lifecycle hooks (machine created, new terminal, removed) with bash bridged into the unit.",
   "keywords": [
-    "muxmaxing",
+    "devcontainer",
     "effect",
     "hooks",
-    "devcontainer",
+    "muxmaxing",
     "provisioning"
   ],
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/playfast/reform.git",
     "directory": "packages/muxmaxing-config"
   },
-  "bugs": {
-    "url": "https://github.com/playfast/reform/issues"
-  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
   "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": "./src/index.ts",
     "./*": "./src/*.ts"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "clean": "rm -rf dist .tsbuildinfo",
     "check": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
     "lint": "oxlint src",
     "lint:fix": "oxlint --fix src"
   },
-  "peerDependencies": {
-    "effect": "*"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.14"
   },
-  "publishConfig": {
-    "access": "public"
+  "peerDependencies": {
+    "effect": "*"
   }
 }

package/src/index.ts

@@ -1,27 +1,12 @@
 import { type Cause, Data, type Effect, Schema as S } from 'effect'
 
-// The author API for a repo-committed `muxmaxing.config.ts` — a HOOK BRIDGE between the
-// host device (the machine running mux) and a work unit (the pod/VM muxmaxing created for
-// the repo). The author declares a typed `hostInput` payload, collects it ON THE HOST
-// (read host env, exec host CLIs — e.g. mint an ephemeral Doppler token with the user's
-// own login), and acts on unit lifecycle moments with it (`ctx.bash` execs IN the unit).
-//
-// Hooks are Effect-native: each returns an `Effect`, never a Promise. They run host-side
-// in a Bun Worker — a THREAD boundary, not a security sandbox — so muxmaxing only runs
-// them for repos the user has explicitly approved.
-
-/** The captured streams + exit code of a bridged bash execution (unit or host). A
- *  non-zero exit is NOT an error — it's a successful run whose `exitCode` the hook
- *  interprets; only a transport failure (the command could not RUN) fails the Effect. */
 export interface BashResult {
   readonly stdout: string
   readonly stderr: string
   readonly exitCode: number
 }
 
-/** The constructor shape `Data.TaggedError(tag)<A>` produces, named so the generated
- *  `.d.ts` can describe the `extends` base under `isolatedDeclarations` (which forbids
- *  an inferred expression in an extends clause) — the reform-db errors pattern. */
+// isolatedDeclarations forbids an inferred expression in an extends clause.
 type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = new (
   args: A,
 ) => Cause.YieldableError & { readonly _tag: Tag } & Readonly<A>
@@ -29,48 +14,33 @@ type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = n
 const HookBashErrorBase: TaggedErrorClass<'HookBashError', { readonly reason: string }> =
   Data.TaggedError('HookBashError')<{ readonly reason: string }>
 
-/** Transport failure of a bridged bash call — the command could not be executed at all
- *  (unit unreachable, host spawn failed, bridge torn down). */
 export class HookBashError extends HookBashErrorBase {
-  // Surface `reason` wherever the error is rendered (`Cause.pretty` would otherwise
-  // print the generic "An error has occurred" — the reform-db errors gotcha).
+  // Cause.pretty would otherwise print the generic "An error has occurred".
   override get message(): string {
     return this.reason
   }
 }
 
-/** The host-device side of the bridge: exec on the machine running mux + its env. */
 export interface HostBridge {
-  /** Run a bash command ON THE HOST DEVICE. */
   readonly bash: (command: string) => Effect.Effect<BashResult, HookBashError>
-  /** The host process env (hooks share the host process — no sandbox). */
   readonly env: Readonly<Record<string, string | undefined>>
 }
 
-/** The work unit a hook invocation is about. */
 export interface UnitInfo {
   readonly id: string
-  /** The unit-side folder the repo is checked out under (bash cwd for unit execs). */
   readonly workspaceFolder: string
 }
 
-/** The work-unit side of the bridge: the unit's identity + exec INSIDE it — the mirror
- *  of `HostBridge`, so hooks read as `ctx.host.bash(...)` / `ctx.unit.bash(...)`. */
 export interface UnitBridge extends UnitInfo {
-  /** Run a bash command INSIDE the work unit. */
   readonly bash: (command: string) => Effect.Effect<BashResult, HookBashError>
 }
 
-/** Ctx for `collectHostDeviceInput` — host-only (the payload doesn't exist yet). */
 export interface CollectCtx {
   readonly host: HostBridge
   readonly unit: UnitInfo
-  /** Surface a line in the unit's creation pane. */
   readonly log: (line: string) => Effect.Effect<void>
 }
 
-/** Ctx for unit-lifecycle hooks: the decoded `hostInput` + both sides of the bridge
- *  (`ctx.unit.bash` execs in the unit, `ctx.host.bash` on the host device). */
 export interface HookCtx<A> {
   readonly hostInput: A
   readonly host: HostBridge
@@ -78,8 +48,6 @@ export interface HookCtx<A> {
   readonly log: (line: string) => Effect.Effect<void>
 }
 
-/** Ctx for `onWorkUnitRemoved` — the unit may already be gone, so there is no unit
- *  bash; cleanup acts on the host (e.g. revoke the token minted at collect time). */
 export interface RemovedCtx<A> {
   readonly hostInput: A
   readonly host: HostBridge
@@ -87,36 +55,19 @@ export interface RemovedCtx<A> {
   readonly log: (line: string) => Effect.Effect<void>
 }
 
-/** The `muxmaxing.config.ts` contract. `A` is the decoded host-input payload; its
- *  ENCODED side `I` must be plain JSON — it crosses the worker boundary and is cached
- *  (memory-only) by the engine between hooks.
- *
- *  `ExternalApi` postfix: this shape is authored by EXTERNAL repos (their
- *  `muxmaxing.config.ts`), where optional hook fields are the ergonomic contract. */
+// ExternalApi: optional hooks are the ergonomic contract for external repos.
 export interface MuxmaxingConfigExternalApi<A, I> {
-  /** The Schema of the payload that crosses host → hooks (encoded side: plain JSON). */
   readonly hostInput: S.Schema<A, I, never>
-  /** Runs ON THE HOST when the unit machine comes up; produces the `hostInput` every
-   *  later hook receives. Collected ONCE per unit and cached by the engine. */
   readonly collectHostDeviceInput: (ctx: CollectCtx) => Effect.Effect<A, unknown>
-  /** Fired when the unit is up and reachable (after devcontainer lifecycle hooks). */
   readonly onWorkUnitMachineCreated?: (ctx: HookCtx<A>) => Effect.Effect<void, unknown>
-  /** Fired when a terminal opens in the unit. */
   readonly onNewTerminal?: (ctx: HookCtx<A>) => Effect.Effect<void, unknown>
-  /** Fired at unit teardown — host-side cleanup (revoke what collect minted). */
   readonly onWorkUnitRemoved?: (ctx: RemovedCtx<A>) => Effect.Effect<void, unknown>
 }
 
-/** The public name for the config contract. */
 export type MuxmaxingConfig<A, I> = MuxmaxingConfigExternalApi<A, I>
 
-/** Identity with types — the `defineConfig` a repo's `muxmaxing.config.ts` default-exports. */
-export const defineConfig = <A, I>(config: MuxmaxingConfig<A, I>): MuxmaxingConfig<A, I> =>
-  config
+export const defineConfig = <A, I>(config: MuxmaxingConfig<A, I>): MuxmaxingConfig<A, I> => config
 
-/** Runtime narrowing for the worker entry: the default export of a fetched config module,
- *  checked structurally (schema + functions). The `hostInput` Schema remains the real
- *  gate for the DATA; this predicate gates the SHAPE. */
 export const isMuxmaxingConfig = (
   candidate: unknown,
 ): candidate is MuxmaxingConfig<unknown, unknown> => {

package/src/protocol.ts

@@ -1,15 +1,6 @@
 import { Schema as S } from 'effect'
 
-// The postMessage wire protocol between the engine (main thread) and the per-invocation
-// hook worker. Every message is encoded before `postMessage` and decoded on receipt via
-// these schemas — plain JSON only (structured clone fast path, no class prototypes on
-// the wire). One worker serves exactly ONE `RunHook`; `Bash` requests stream back from
-// the worker while its hook runs, each answered by a `BashReply`.
-//
-// Annotated `TaggedStruct` consts (not `S.TaggedClass`) so the declarations survive
-// `isolatedDeclarations` — the same reason reform-db's errors annotate their base.
-
-/** Which hook the worker should run. `collect` produces the hostInput; the rest consume it. */
+// TaggedStruct consts (not TaggedClass) so declarations survive isolatedDeclarations.
 export const HookName: S.Literal<['collect', 'machineCreated', 'newTerminal', 'removed']> =
   S.Literal('collect', 'machineCreated', 'newTerminal', 'removed')
 export type HookName = typeof HookName.Type
@@ -18,10 +9,6 @@ export const UnitRef: S.Struct<{ id: typeof S.String; workspaceFolder: typeof S.
   S.Struct({ id: S.String, workspaceFolder: S.String })
 export type UnitRef = typeof UnitRef.Type
 
-// ── engine → worker ───────────────────────────────────────────────────────────
-
-/** The single invocation a worker serves. `configPath` is the materialised config module
- *  to import; `hostInput` is the ENCODED payload (`null` for `collect`, which creates it). */
 export const RunHookRequest: S.TaggedStruct<
   'RunHook',
   {
@@ -44,11 +31,12 @@ export const BashOk: S.TaggedStruct<
 > = S.TaggedStruct('BashOk', { stdout: S.String, stderr: S.String, exitCode: S.Number })
 export type BashOk = typeof BashOk.Type
 
-export const BashFailed: S.TaggedStruct<'BashFailed', { reason: typeof S.String }> =
-  S.TaggedStruct('BashFailed', { reason: S.String })
+export const BashFailed: S.TaggedStruct<'BashFailed', { reason: typeof S.String }> = S.TaggedStruct(
+  'BashFailed',
+  { reason: S.String },
+)
 export type BashFailed = typeof BashFailed.Type
 
-/** The engine's answer to one `Bash` request, correlated by `id`. */
 export const BashReply: S.TaggedStruct<
   'BashReply',
   { id: typeof S.Number; result: S.Union<[typeof BashOk, typeof BashFailed]> }
@@ -61,10 +49,6 @@ export const EngineToWorker: S.Union<[typeof RunHookRequest, typeof BashReply]>
 )
 export type EngineToWorker = typeof EngineToWorker.Type
 
-// ── worker → engine ───────────────────────────────────────────────────────────
-
-/** A bridged bash execution request: `unit` execs inside the work unit, `host` on the
- *  host device. The engine replies with a `BashReply` carrying the same `id`. */
 export const BashRequest: S.TaggedStruct<
   'Bash',
   {
@@ -79,22 +63,19 @@ export const BashRequest: S.TaggedStruct<
 })
 export type BashRequest = typeof BashRequest.Type
 
-/** A line for the unit's creation pane (the hook's `ctx.log`). */
-export const LogMessage: S.TaggedStruct<'Log', { line: typeof S.String }> = S.TaggedStruct(
-  'Log',
-  { line: S.String },
-)
+export const LogMessage: S.TaggedStruct<'Log', { line: typeof S.String }> = S.TaggedStruct('Log', {
+  line: S.String,
+})
 export type LogMessage = typeof LogMessage.Type
 
-/** The hook finished. `hostInput` carries the freshly ENCODED payload for `collect`
- *  (the engine caches it, memory-only) and is `null` for every other hook. */
 export const HookDone: S.TaggedStruct<'HookDone', { hostInput: S.NullOr<typeof S.Unknown> }> =
   S.TaggedStruct('HookDone', { hostInput: S.NullOr(S.Unknown) })
 export type HookDone = typeof HookDone.Type
 
-/** The hook (or the config module itself) failed — best-effort reporting, never retried. */
-export const HookFailed: S.TaggedStruct<'HookFailed', { reason: typeof S.String }> =
-  S.TaggedStruct('HookFailed', { reason: S.String })
+export const HookFailed: S.TaggedStruct<'HookFailed', { reason: typeof S.String }> = S.TaggedStruct(
+  'HookFailed',
+  { reason: S.String },
+)
 export type HookFailed = typeof HookFailed.Type
 
 export const WorkerToEngine: S.Union<

package/src/worker-entry.ts

@@ -1,4 +1,5 @@
 import { Cause, Data, Effect, Either, Match, Option, Ref, Schema as S } from 'effect'
+import { parentPort } from 'node:worker_threads'
 import {
   type BashReply,
   BashRequest,
@@ -8,7 +9,7 @@ import {
   LogMessage,
   type RunHookRequest,
   WorkerToEngine,
-} from './protocol'
+} from '@playfast/muxmaxing-config/protocol'
 import {
   type BashResult,
   HookBashError,
@@ -16,35 +17,37 @@ import {
   isMuxmaxingConfig,
   type MuxmaxingConfig,
   type UnitInfo,
-} from './index'
-
-// The per-invocation hook worker: serves exactly ONE `RunHook`, bridging the hook's
-// `ctx.bash`/`ctx.host.bash` back to the engine over postMessage (the engine owns the
-// actual pod-exec / host-spawn). When the hook settles, the worker reports `HookDone`
-// (or `HookFailed`), drops its message listener so the event loop drains, and exits;
-// the engine's scope finalizer additionally calls `worker.terminate()`.
+} from '@playfast/muxmaxing-config'
 
 declare const self: Worker
 
+const hasWebWorkerScope = typeof self !== 'undefined'
+
 class WorkerHookError extends Data.TaggedError('WorkerHookError')<{
   readonly reason: string
 }> {
-  // Without this getter `Cause.pretty` renders the generic "An error has occurred",
-  // hiding the actual failure from the HookFailed report (the reform-db errors gotcha).
+  // Cause.pretty would otherwise print the generic "An error has occurred".
   override get message(): string {
     return this.reason
   }
 }
 
 const send = (message: WorkerToEngine): void => {
-  self.postMessage(S.encodeSync(WorkerToEngine)(message))
+  const encoded = S.encodeSync(WorkerToEngine)(message)
+  if (hasWebWorkerScope) {
+    self.postMessage(encoded)
+    return
+  }
+  if (parentPort !== null) {
+    parentPort.postMessage(encoded)
+    return
+  }
+  Effect.runSync(Effect.dieMessage('worker entry has no parent message port'))
 }
 
 const describe = (cause: unknown): string =>
   cause instanceof Error ? cause.message : String(cause)
 
-// One in-flight resolver per bridged bash `id` — the engine answers each `Bash` with a
-// correlated `BashReply`. Hooks run their bash calls through `Effect.async` below.
 const pendingBash = new Map<number, (reply: BashReply) => void>()
 
 const makeBridgedBash =
@@ -63,8 +66,7 @@ const makeBridgedBash =
                       stderr: ok.stderr,
                       exitCode: ok.exitCode,
                     }),
-                  BashFailed: (failed) =>
-                    Effect.fail(new HookBashError({ reason: failed.reason })),
+                  BashFailed: (failed) => Effect.fail(new HookBashError({ reason: failed.reason })),
                 }),
                 Match.exhaustive,
               ),
@@ -83,18 +85,14 @@ const loadConfig = (
 ): Effect.Effect<MuxmaxingConfig<unknown, unknown>, WorkerHookError> =>
   Effect.tryPromise({
     try: (): Promise<unknown> => import(configPath),
-    catch: (cause) =>
-      new WorkerHookError({ reason: `config import failed: ${describe(cause)}` }),
+    catch: (cause) => new WorkerHookError({ reason: `config import failed: ${describe(cause)}` }),
   }).pipe(
     Effect.flatMap((moduleExports) => {
       const record: Record<string, unknown> =
-        typeof moduleExports === 'object' && moduleExports !== null
-          ? { ...moduleExports }
-          : {}
+        typeof moduleExports === 'object' && moduleExports !== null ? { ...moduleExports } : {}
       const defaulted = Option.fromNullable(record['default'])
       return Option.match(defaulted, {
-        onNone: () =>
-          Effect.fail(new WorkerHookError({ reason: 'config has no default export' })),
+        onNone: () => Effect.fail(new WorkerHookError({ reason: 'config has no default export' })),
         onSome: (config) => {
           if (isMuxmaxingConfig(config)) {
             return Effect.succeed(config)
@@ -125,80 +123,80 @@ const hookFailure =
   (cause: unknown): WorkerHookError =>
     new WorkerHookError({ reason: `${hookName} failed: ${describe(cause)}` })
 
-const runRequested = Effect.fn('runRequested')(
-  function* (request: RunHookRequest): Effect.fn.Return<HookDone, WorkerHookError> {
-    const config = yield* loadConfig(request.configPath)
-    const idRef = yield* Ref.make(0)
-    const unit: UnitInfo = {
-      id: request.unit.id,
-      workspaceFolder: request.unit.workspaceFolder,
-    }
-    const host: HostBridge = { bash: makeBridgedBash(idRef, 'host'), env: Bun.env }
-    const unitBridge = { ...unit, bash: makeBridgedBash(idRef, 'unit') }
-
-    // A consuming hook that the config leaves undefined is a silent no-op success.
-    const runOptional = <Ctx>(
-      hookName: string,
-      hook: ((ctx: Ctx) => Effect.Effect<void, unknown>) | undefined,
-      makeCtx: (hostInput: unknown) => Ctx,
-    ): Effect.Effect<HookDone, WorkerHookError> =>
-      Option.match(Option.fromNullable(hook), {
-        onNone: () => Effect.succeed(HookDone.make({ hostInput: null })),
-        onSome: (run) =>
-          decodeHostInput(config, request.hostInput).pipe(
-            Effect.flatMap((hostInput) =>
-              run(makeCtx(hostInput)).pipe(Effect.mapError(hookFailure(hookName))),
-            ),
-            Effect.map(() => HookDone.make({ hostInput: null })),
+const runRequested = Effect.fn('runRequested')(function* (
+  request: RunHookRequest,
+): Effect.fn.Return<HookDone, WorkerHookError> {
+  const config = yield* loadConfig(request.configPath)
+  const idRef = yield* Ref.make(0)
+  const unit: UnitInfo = {
+    id: request.unit.id,
+    workspaceFolder: request.unit.workspaceFolder,
+  }
+  const workerEnv = typeof Bun === 'undefined' ? process.env : Bun.env
+  const host: HostBridge = { bash: makeBridgedBash(idRef, 'host'), env: workerEnv }
+  const unitBridge = { ...unit, bash: makeBridgedBash(idRef, 'unit') }
+
+  // Undefined consuming hooks are intentional silent no-ops.
+  const runOptional = <Ctx>(
+    hookName: string,
+    hook: ((ctx: Ctx) => Effect.Effect<void, unknown>) | undefined,
+    makeCtx: (hostInput: unknown) => Ctx,
+  ): Effect.Effect<HookDone, WorkerHookError> =>
+    Option.match(Option.fromNullable(hook), {
+      onNone: () => Effect.succeed(HookDone.make({ hostInput: null })),
+      onSome: (run) =>
+        decodeHostInput(config, request.hostInput).pipe(
+          Effect.flatMap((hostInput) =>
+            run(makeCtx(hostInput)).pipe(Effect.mapError(hookFailure(hookName))),
           ),
-      })
-
-    return yield* Match.value(request.hook).pipe(
-      Match.when('collect', () =>
-        config
-          .collectHostDeviceInput({ host, unit, log })
-          .pipe(
-            Effect.mapError(hookFailure('collectHostDeviceInput')),
-            Effect.flatMap((collected) =>
-              S.encodeUnknown(config.hostInput)(collected).pipe(
-                Effect.mapError(
-                  (issue) =>
-                    new WorkerHookError({
-                      reason: `hostInput encode failed: ${String(issue)}`,
-                    }),
-                ),
-              ),
+          Effect.map(() => HookDone.make({ hostInput: null })),
+        ),
+    })
+
+  return yield* Match.value(request.hook).pipe(
+    Match.when('collect', () =>
+      config.collectHostDeviceInput({ host, unit, log }).pipe(
+        Effect.mapError(hookFailure('collectHostDeviceInput')),
+        Effect.flatMap((collected) =>
+          S.encodeUnknown(config.hostInput)(collected).pipe(
+            Effect.mapError(
+              (issue) =>
+                new WorkerHookError({
+                  reason: `hostInput encode failed: ${String(issue)}`,
+                }),
             ),
-            Effect.map((encoded) => HookDone.make({ hostInput: encoded ?? null })),
           ),
+        ),
+        Effect.map((encoded) => HookDone.make({ hostInput: encoded ?? null })),
       ),
-      Match.when('machineCreated', () =>
-        runOptional('onWorkUnitMachineCreated', config.onWorkUnitMachineCreated, (hostInput) => ({
-          hostInput,
-          host,
-          unit: unitBridge,
-          log,
-        })),
-      ),
-      Match.when('newTerminal', () =>
-        runOptional('onNewTerminal', config.onNewTerminal, (hostInput) => ({
-          hostInput,
-          host,
-          unit: unitBridge,
-          log,
-        })),
-      ),
-      Match.when('removed', () =>
-        runOptional('onWorkUnitRemoved', config.onWorkUnitRemoved, (hostInput) => ({
-          hostInput,
-          host,
-          unit,
-          log,
-        })),
-      ),
-      Match.exhaustive,
-    )
-  })
+    ),
+    Match.when('machineCreated', () =>
+      runOptional('onWorkUnitMachineCreated', config.onWorkUnitMachineCreated, (hostInput) => ({
+        hostInput,
+        host,
+        unit: unitBridge,
+        log,
+      })),
+    ),
+    Match.when('newTerminal', () =>
+      runOptional('onNewTerminal', config.onNewTerminal, (hostInput) => ({
+        hostInput,
+        host,
+        unit: unitBridge,
+        log,
+      })),
+    ),
+    Match.when('removed', () =>
+      runOptional('onWorkUnitRemoved', config.onWorkUnitRemoved, (hostInput) => ({
+        hostInput,
+        host,
+        unit,
+        log,
+      })),
+    ),
+    Match.exhaustive,
+  )
+})
 
 const handleRunHook = (request: RunHookRequest): void => {
   void Effect.runPromise(
@@ -207,19 +205,24 @@ const handleRunHook = (request: RunHookRequest): void => {
       Effect.catchAllCause((cause) =>
         Effect.sync(() => send(HookFailed.make({ reason: Cause.pretty(cause) }))),
       ),
-      // Drop the listener so the event loop drains and the worker exits on its own;
-      // the engine's scope finalizer also terminates it (belt and suspenders).
+      // Drop the listener so the event loop drains and the worker exits.
       Effect.ensuring(
         Effect.sync(() => {
-          self.onmessage = null
+          if (hasWebWorkerScope) {
+            self.onmessage = null
+            return
+          }
+          if (parentPort !== null) {
+            parentPort.close()
+          }
         }),
       ),
     ),
   )
 }
 
-self.onmessage = (event: MessageEvent): void => {
-  Either.match(S.decodeUnknownEither(EngineToWorker)(event.data), {
+const handleMessage = (payload: unknown): void => {
+  Either.match(S.decodeUnknownEither(EngineToWorker)(payload), {
     onLeft: () => send(HookFailed.make({ reason: 'undecodable engine message' })),
     onRight: (message) =>
       Match.value(message).pipe(
@@ -235,3 +238,13 @@ self.onmessage = (event: MessageEvent): void => {
       ),
   })
 }
+
+if (hasWebWorkerScope) {
+  self.onmessage = (event: MessageEvent): void => handleMessage(event.data)
+}
+if (!hasWebWorkerScope && parentPort !== null) {
+  parentPort.on('message', handleMessage)
+}
+if (!hasWebWorkerScope && parentPort === null) {
+  Effect.runSync(Effect.dieMessage('worker entry has no parent message port'))
+}

package/src/fixtures/sample.config.ts

@@ -1,35 +0,0 @@
-import { Effect, Schema as S, String as Str } from 'effect'
-import { defineConfig, type MuxmaxingConfig } from '@playfast/muxmaxing-config'
-
-// The worker-entry test fixture — shaped like a real repo's `muxmaxing.config.ts`
-// (imports the package by name, exercises host bash, unit bash, log, and hostInput).
-// The explicit annotation is only for THIS package's `isolatedDeclarations` check —
-// a real repo's config just default-exports `defineConfig({...})`.
-
-interface SampleInput {
-  readonly token: string
-  readonly slug: string
-}
-
-const config: MuxmaxingConfig<SampleInput, SampleInput> = defineConfig({
-  hostInput: S.Struct({ token: S.String, slug: S.String }),
-
-  collectHostDeviceInput: ({ host, unit }) =>
-    Effect.gen(function* () {
-      const minted = yield* host.bash(`fake-mint ${unit.id}`)
-      return { token: Str.trim(minted.stdout), slug: `slug-${unit.id}` }
-    }),
-
-  onWorkUnitMachineCreated: (ctx) =>
-    Effect.gen(function* () {
-      yield* ctx.log('configuring')
-      const configured = yield* ctx.unit.bash(`configure ${ctx.hostInput.token}`)
-      if (configured.exitCode !== 0) {
-        return yield* Effect.fail(`configure exited ${configured.exitCode}`)
-      }
-    }),
-
-  onWorkUnitRemoved: (ctx) => Effect.asVoid(ctx.host.bash(`revoke ${ctx.hostInput.slug}`)),
-})
-
-export default config

package/src/worker-entry.test.ts

@@ -1,159 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { Schema as S } from 'effect'
-import { fileURLToPath } from 'node:url'
-import {
-  BashReply,
-  EngineToWorker,
-  type HookName,
-  RunHookRequest,
-  WorkerToEngine,
-} from './protocol'
-
-// Drives the REAL worker entry end-to-end: spawn a Bun Worker on `worker-entry.ts`,
-// point it at the fixture config (which imports the package by name, like a real repo),
-// answer its bridged Bash requests with canned results, and assert the final message.
-// Needs the Bun runtime (`bun --bun run vitest`) for the `Worker` global.
-
-const workerUrl = new URL('./worker-entry.ts', import.meta.url)
-// fileURLToPath so the SPACE in this repo's path survives (URL.pathname would %20 it).
-const fixtureConfigPath = fileURLToPath(new URL('./fixtures/sample.config.ts', import.meta.url))
-
-const encodeToWorker = S.encodeSync(EngineToWorker)
-const decodeFromWorker = S.decodeUnknownSync(WorkerToEngine)
-
-interface DrivenHook {
-  /** Every worker→engine message, in arrival order (Bash/Log/HookDone/HookFailed). */
-  readonly messages: ReadonlyArray<WorkerToEngine>
-}
-
-/** Run ONE hook through a fresh worker, answering each `Bash` via `answerBash`. */
-const driveHook = (input: {
-  readonly hook: HookName
-  readonly hostInput: unknown
-  readonly answerBash: (request: { target: string; command: string }) => BashReply['result']
-}): Promise<DrivenHook> =>
-  new Promise((resolve, reject) => {
-    const worker = new Worker(workerUrl)
-    const seen: Array<WorkerToEngine> = []
-    const finish = (outcome: DrivenHook): void => {
-      worker.terminate()
-      resolve(outcome)
-    }
-    const timer = setTimeout(() => {
-      worker.terminate()
-      reject(new Error(`hook ${input.hook} timed out; saw ${JSON.stringify(seen)}`))
-    }, 15_000)
-    worker.onmessage = (event: MessageEvent): void => {
-      const message = decodeFromWorker(event.data)
-      seen.push(message)
-      if (message._tag === 'Bash') {
-        worker.postMessage(
-          encodeToWorker(
-            BashReply.make({
-              id: message.id,
-              result: input.answerBash({ target: message.target, command: message.command }),
-            }),
-          ),
-        )
-        return
-      }
-      if (message._tag === 'HookDone' || message._tag === 'HookFailed') {
-        clearTimeout(timer)
-        finish({ messages: seen })
-      }
-    }
-    worker.postMessage(
-      encodeToWorker(
-        RunHookRequest.make({
-          hook: input.hook,
-          configPath: fixtureConfigPath,
-          hostInput: input.hostInput,
-          unit: { id: 'unit-1', workspaceFolder: '/workspace/repo' },
-        }),
-      ),
-    )
-  })
-
-const okBash = (stdout: string): BashReply['result'] => ({
-  _tag: 'BashOk',
-  stdout,
-  stderr: '',
-  exitCode: 0,
-})
-
-describe('worker-entry', () => {
-  it('collect: runs collectHostDeviceInput on the host bridge and returns encoded hostInput', async () => {
-    const driven = await driveHook({
-      hook: 'collect',
-      hostInput: null,
-      answerBash: (request) => {
-        expect(request.target).toBe('host')
-        expect(request.command).toBe('fake-mint unit-1')
-        return okBash('tok-123\n')
-      },
-    })
-    const done = driven.messages.at(-1)
-    expect(done?._tag).toBe('HookDone')
-    if (done?._tag === 'HookDone') {
-      expect(done.hostInput).toEqual({ token: 'tok-123', slug: 'slug-unit-1' })
-    }
-  })
-
-  it('machineCreated: decodes hostInput, logs, and bashes into the unit', async () => {
-    const driven = await driveHook({
-      hook: 'machineCreated',
-      hostInput: { token: 'tok-123', slug: 'slug-unit-1' },
-      answerBash: (request) => {
-        expect(request.target).toBe('unit')
-        expect(request.command).toBe('configure tok-123')
-        return okBash('')
-      },
-    })
-    const tags = driven.messages.map((message) => message._tag)
-    expect(tags).toEqual(['Log', 'Bash', 'HookDone'])
-  })
-
-  it('newTerminal: a hook the config leaves undefined is a silent no-op success', async () => {
-    const driven = await driveHook({
-      hook: 'newTerminal',
-      hostInput: { token: 'tok-123', slug: 'slug-unit-1' },
-      answerBash: () => okBash(''),
-    })
-    expect(driven.messages.map((message) => message._tag)).toEqual(['HookDone'])
-  })
-
-  it('removed: cleanup runs on the HOST bridge with the cached hostInput', async () => {
-    const driven = await driveHook({
-      hook: 'removed',
-      hostInput: { token: 'tok-123', slug: 'slug-unit-1' },
-      answerBash: (request) => {
-        expect(request.target).toBe('host')
-        expect(request.command).toBe('revoke slug-unit-1')
-        return okBash('')
-      },
-    })
-    expect(driven.messages.at(-1)?._tag).toBe('HookDone')
-  })
-
-  it('malformed hostInput fails the hook (Schema is the gate), reported as HookFailed', async () => {
-    const driven = await driveHook({
-      hook: 'machineCreated',
-      hostInput: { token: 42 },
-      answerBash: () => okBash(''),
-    })
-    expect(driven.messages.at(-1)?._tag).toBe('HookFailed')
-  })
-
-  it('a failing unit bash surfaces the hook error as HookFailed', async () => {
-    const driven = await driveHook({
-      hook: 'machineCreated',
-      hostInput: { token: 'tok-123', slug: 'slug-unit-1' },
-      answerBash: () => ({ _tag: 'BashFailed', reason: 'pod unreachable' }),
-    })
-    const failed = driven.messages.at(-1)
-    expect(failed?._tag).toBe('HookFailed')
-    if (failed?._tag === 'HookFailed') {
-      expect(failed.reason).toContain('pod unreachable')
-    }
-  })
-})