@playfast/muxmaxing-config

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 creates for your repo). Declare a typed hostInput payload, collect it on the host (env, CLIs, logins), and act on unit lifecycle moments with it. Hooks are Effect-native and run host-side in a Bun Worker, only for repos the user has explicitly approved.

Example — preconfigure the Doppler CLI in every work unit

// muxmaxing.config.ts (repo root, committed)
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 }))

export default defineConfig({
  hostInput: S.Struct({ dopplerToken: S.String, tokenSlug: S.String }),

  // Runs ON THE HOST: mint an ephemeral read-only token with the user's own login.
  collectHostDeviceInput: ({ host, unit }) =>
    Effect.gen(function* () {
      const minted = yield* host.bash(
        `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 }
    }),

  // Runs when the unit is up: `ctx.unit.bash` execs INSIDE the unit.
  onWorkUnitMachineCreated: (ctx) =>
    Effect.gen(function* () {
      yield* ctx.unit.bash(
        `doppler configure set token ${ctx.hostInput.dopplerToken} --scope ${ctx.unit.workspaceFolder}`,
      )
      yield* ctx.log('doppler CLI preconfigured')
    }),

  // Runs at teardown ON THE HOST: revoke exactly the token this unit was minted.
  onWorkUnitRemoved: (ctx) =>
    ctx.host.bash(
      `doppler configs tokens revoke --slug ${ctx.hostInput.tokenSlug} --project my-app --config dev`,
    ),
})

Contract

• hostInput — an Effect Schema; its encoded side must be plain JSON (it crosses the worker boundary and is cached memory-only by the engine between hooks).
• collectHostDeviceInput(ctx) — runs once per unit on the host; produces the payload.
• onWorkUnitMachineCreated(ctx) / onNewTerminal(ctx) — ctx.unit.bash execs in the unit, ctx.host.bash on the host, ctx.log writes to the unit's creation pane.
• onWorkUnitRemoved(ctx) — host-side cleanup; the unit may already be gone (no unit bash).
• A bash result is { stdout, stderr, exitCode }; a non-zero exit is not an error — only a transport failure fails the Effect.

Trust model: hooks run on the host in a Bun Worker — a thread boundary, not a security sandbox. muxmaxing runs them only for repos the user approved (Settings → Hooks).