@playfast/muxmaxing-config 0.1.1 → 0.1.2

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,6 +1,6 @@
 {
   "name": "@playfast/muxmaxing-config",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "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": [
@@ -33,8 +33,6 @@
     "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"
   },

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,20 @@ 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
 
-/** 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',
   {
@@ -48,7 +35,6 @@ 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 +47,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,20 +61,16 @@ 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 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 type HookFailed = typeof HookFailed.Type

package/src/worker-entry.ts

@@ -18,19 +18,12 @@ import {
   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()`.
-
 declare const self: Worker
 
 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
   }
@@ -43,8 +36,6 @@ const send = (message: WorkerToEngine): void => {
 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 =
@@ -136,7 +127,7 @@ const runRequested = Effect.fn('runRequested')(
     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.
+    // Undefined consuming hooks are intentional silent no-ops.
     const runOptional = <Ctx>(
       hookName: string,
       hook: ((ctx: Ctx) => Effect.Effect<void, unknown>) | undefined,
@@ -207,8 +198,7 @@ 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

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')
-    }
-  })
-})