@gamecrate/cli 0.1.0 → 1.0.0

package/src/docker/run.ts

@@ -1,212 +0,0 @@
-import { spawn } from 'node:child_process'
-import type { ChildProcess, StdioOptions } from 'node:child_process'
-import { createWriteStream, mkdirSync } from 'node:fs'
-import { open, readdir, stat } from 'node:fs/promises'
-import { join } from 'node:path'
-import type { Readable, Writable } from 'node:stream'
-import { setTimeout as sleep } from 'node:timers/promises'
-import { TextDecoder } from 'node:util'
-import type { DockerRunSpec } from '../types'
-import { Exit } from '../types'
-import { toDockerArgs } from './spec'
-
-/** argv as one array, the way every caller here has it. */
-export function spawnArgv(argv: string[], stdio: StdioOptions): ChildProcess {
-  return spawn(argv[0]!, argv.slice(1), { stdio })
-}
-
-/** Rejects when the spawn itself fails, so a missing binary lands where a bad exit code would. */
-export function exited(proc: ChildProcess): Promise<number> {
-  return new Promise((resolve, reject) => {
-    proc.once('error', reject)
-    proc.once('close', (code) => resolve(code ?? 1))
-  })
-}
-
-export async function collect(stream: Readable): Promise<string> {
-  const chunks: Buffer[] = []
-  for await (const chunk of stream) chunks.push(chunk as Buffer)
-  return Buffer.concat(chunks).toString('utf8')
-}
-
-/**
- * Runs a short command and collects both streams. A missing binary is exit 127 with the spawn
- * error as stderr, so every caller can report it the same way rather than throwing.
- */
-export async function capture(argv: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
-  try {
-    const proc = spawnArgv(argv, ['ignore', 'pipe', 'pipe'])
-    const [stdout, stderr, code] = await Promise.all([
-      collect(proc.stdout!),
-      collect(proc.stderr!),
-      exited(proc),
-    ])
-    return { code, stdout, stderr }
-  } catch (error) {
-    return { code: 127, stdout: '', stderr: error instanceof Error ? error.message : String(error) }
-  }
-}
-
-/** The tee'd combined stream, and what waitForMarker watches. */
-export const STDOUT_LOG = 'stdout.log'
-
-const MARKER_POLL_MS = 200
-
-export interface RunOptions {
-  /** Run log directory; created if missing. Receives stdout.log. */
-  logDir: string
-  /** Passed to `docker stop --timeout` when a signal arrives. */
-  stopTimeoutSeconds?: number
-}
-
-/**
- * Spawns docker directly rather than through a pipeline, so the game's status is the status.
- * `exec docker run | tee` returns tee's code, which is why the old scripts always reported 0.
- */
-export async function runContainer(spec: DockerRunSpec, opts: RunOptions): Promise<number> {
-  const stopTimeout = opts.stopTimeoutSeconds ?? 10
-
-  mkdirSync(opts.logDir, { recursive: true })
-  const sink = createWriteStream(join(opts.logDir, STDOUT_LOG))
-
-  const proc = spawnArgv(['docker', ...toDockerArgs(spec)], ['inherit', 'pipe', 'pipe'])
-
-  let interrupted = false
-  const onSignal = () => {
-    if (interrupted) return
-    interrupted = true
-    void stopContainer(spec.name, stopTimeout)
-  }
-  process.on('SIGINT', onSignal)
-  process.on('SIGTERM', onSignal)
-
-  // Registered before the tees: an unhandled "error" event would take the process down, and
-  // draining the pipes first is what keeps a chatty container from filling them and stalling.
-  const code = exited(proc)
-  try {
-    await Promise.all([
-      tee(proc.stdout!, sink, process.stdout),
-      tee(proc.stderr!, sink, process.stderr),
-    ])
-    const status = await code
-    return interrupted ? Exit.Interrupted : status
-  } finally {
-    process.off('SIGINT', onSignal)
-    process.off('SIGTERM', onSignal)
-    await new Promise<void>((resolve) => sink.end(resolve))
-  }
-}
-
-export async function stopContainer(name: string, timeoutSeconds: number): Promise<void> {
-  const proc = spawnArgv(['docker', 'stop', '--timeout', String(timeoutSeconds), name], 'ignore')
-  await exited(proc).catch(() => {})
-}
-
-/**
- * Host-side marker watch. Watches container stdout AND the game's own log file: RimWorld
- * sends Verse.Log output to -logfile, never to stdout, so a stdout-only watch can never
- * match a RimWorld mod's message.
- */
-export async function waitForMarker(
-  sources: string[],
-  marker: string,
-  timeoutSeconds: number,
-): Promise<boolean> {
-  const deadline = Date.now() + timeoutSeconds * 1000
-  const carry = Math.max(marker.length - 1, 0)
-  const seen = new Map<string, Watched>()
-  const startedAt = Date.now()
-
-  while (true) {
-    for (const path of await expandSources(sources)) {
-      let state = seen.get(path)
-      if (state === undefined) {
-        // Logs/Player-prev.log holds the PREVIOUS run's marker verbatim, so its history
-        // would match instantly. Skip what a file already held before this watch began,
-        // keyed on mtime so a fresh stdout.log is still read from byte zero.
-        state = { offset: await staleSize(path, startedAt), tail: '', decoder: new TextDecoder() }
-        seen.set(path, state)
-      }
-
-      if (await scan(path, state, marker, carry)) return true
-    }
-
-    if (Date.now() >= deadline) return false
-    await sleep(Math.min(MARKER_POLL_MS, Math.max(deadline - Date.now(), 0)))
-  }
-}
-
-interface Watched {
-  offset: number
-  tail: string
-  /** Per path: a shared streaming decoder corrupts every file after the first. */
-  decoder: TextDecoder
-}
-
-/** Bytes to skip: a file last written before the watch started is a previous run's log. */
-async function staleSize(path: string, startedAt: number): Promise<number> {
-  return stat(path).then(
-    (info) => (info.mtimeMs < startedAt ? info.size : 0),
-    () => 0,
-  )
-}
-
-/** Never throws: one unreadable file must not reject the whole watch. */
-async function scan(
-  path: string,
-  state: Watched,
-  marker: string,
-  carry: number,
-): Promise<boolean> {
-  const handle = await open(path, 'r').catch(() => null)
-  if (handle === null) return false
-  try {
-    const { size } = await handle.stat()
-    if (size < state.offset) {
-      state.offset = 0
-      state.tail = ''
-      state.decoder = new TextDecoder()
-    }
-    if (size <= state.offset) return false
-
-    const buffer = Buffer.alloc(size - state.offset)
-    const { bytesRead } = await handle.read(buffer, 0, buffer.length, state.offset)
-    state.offset += bytesRead
-    const text = state.tail + state.decoder.decode(buffer.subarray(0, bytesRead), { stream: true })
-    if (text.includes(marker)) return true
-    state.tail = carry > 0 ? text.slice(-carry) : ''
-    return false
-  } catch {
-    return false
-  } finally {
-    await handle.close().catch(() => {})
-  }
-}
-
-/** A source is a file or a directory of logs; directories are rescanned every poll. */
-async function expandSources(sources: string[]): Promise<string[]> {
-  const out: string[] = []
-  for (const source of sources) {
-    const info = await stat(source).catch(() => null)
-    if (info === null) {
-      out.push(source)
-      continue
-    }
-    if (!info.isDirectory()) {
-      out.push(source)
-      continue
-    }
-    const entries = await readdir(source).catch((): string[] => [])
-    for (const entry of entries) {
-      if (entry.toLowerCase().endsWith('.log')) out.push(join(source, entry))
-    }
-  }
-  return out
-}
-
-async function tee(stream: Readable, sink: Writable, mirror: NodeJS.WriteStream): Promise<void> {
-  for await (const chunk of stream) {
-    mirror.write(chunk as Buffer)
-    sink.write(chunk as Buffer)
-  }
-}

package/src/docker/spec.ts

@@ -1,357 +0,0 @@
-import { existsSync, realpathSync } from 'node:fs'
-import { homedir, hostname } from 'node:os'
-import { basename, join } from 'node:path'
-import type {
-  DataDirSpec,
-  DockerRunSpec,
-  Identity,
-  LaunchPlan,
-  Mount,
-} from '../types'
-import { GamecrateError, Exit } from '../types'
-
-/** Container-side XDG_RUNTIME_DIR. A sized tmpfs; display and audio sockets land inside it. */
-export const CONTAINER_RUNTIME_DIR = '/tmp/xdg'
-
-/** Where the run directory is bound, so `-logfile /logs/Player.log` lands beside stdout.log. */
-export const CONTAINER_LOG_DIR = '/logs'
-
-/** X11's well-known socket directory. The path is the same on both sides or DISPLAY lies. */
-const X11_SOCKET_DIR = '/tmp/.X11-unix'
-
-/** Outside XDG_RUNTIME_DIR on purpose: that is a tmpfs, and a bind under it races the tmpfs. */
-const CONTAINER_XAUTHORITY = '/tmp/xauth'
-
-/** Persistent XDG root. Outside HOME because HOME is a tmpfs and a bind under it races. */
-const CONTAINER_XDG_DIR = '/xdg'
-
-const RUNTIME_DIR_SIZE = '64m'
-const HOME_SIZE = '64m'
-const MASK_SIZE = '1m'
-
-export function buildRunSpec(
-  plan: LaunchPlan,
-  modMounts: Mount[],
-  identity: Identity,
-): DockerRunSpec {
-  const { gameConfig: game, settings } = plan
-  const headed = plan.mode === 'headed'
-
-  const mounts: Mount[] = []
-  const env: Record<string, string> = {
-    HOME: identity.home,
-    USER: identity.user,
-    LOGNAME: identity.user,
-  }
-
-  if (game.gameFiles.source === 'mount') {
-    if (!game.gameFiles.host) {
-      throw new GamecrateError(
-        `gameFiles.source is "mount" but no host path is set for ${plan.game}`,
-        Exit.Config,
-      )
-    }
-    mounts.push({ type: 'bind', source: hostPath(game.gameFiles.host), target: game.gameFiles.container, readonly: true })
-  }
-
-  mounts.push({ type: 'bind', source: hostPath(plan.stageDirHost), target: game.modsDir.container, readonly: true })
-  // Nested per-mod binds sit inside the staged tree; the game never writes to a mod source.
-  for (const mount of modMounts) {
-    mounts.push(mount.type === 'bind' ? { ...mount, readonly: true } : mount)
-  }
-
-  // Read-write on purpose: both engines Create() subdirectories at boot and a ro mount fails there.
-  mounts.push({ type: 'bind', source: hostPath(plan.dataDirHost), target: game.dataDir.container })
-
-  // xvfb-run -a picks a free display itself, which removes both the hardcoded :99 and the
-  // startup race the old launch.sh papered over with `sleep 2`.
-  const command = headed
-    ? [game.executable]
-    : [
-        'xvfb-run',
-        '-a',
-        `--server-args=-screen 0 ${settings.width}x${settings.height}x24`,
-        game.executable,
-      ]
-
-  if (game.dataDir.mode === 'arg') {
-    command.push(validateDataDirArg(game.dataDir))
-  } else {
-    Object.assign(env, game.dataDir.env)
-  }
-
-  if (game.logFile.mode === 'arg') {
-    mounts.push({ type: 'bind', source: hostPath(plan.runDirHost), target: CONTAINER_LOG_DIR })
-    command.push(game.logFile.arg, `${CONTAINER_LOG_DIR}/Player.log`)
-  }
-
-  // Unconditional, independent of the uid mode: a game may read mods from both roots.
-  for (const target of game.modsDir.mask ?? []) {
-    mounts.push({ type: 'tmpfs', target, size: MASK_SIZE, uid: identity.uid, gid: identity.gid, mode: '755' })
-  }
-
-  if (identity.uid !== 0) {
-    mounts.push({ type: 'tmpfs', target: identity.home, size: HOME_SIZE, uid: identity.uid, gid: identity.gid, mode: '700' })
-  }
-
-  mounts.push({
-    type: 'tmpfs',
-    target: CONTAINER_RUNTIME_DIR,
-    size: RUNTIME_DIR_SIZE,
-    uid: identity.uid,
-    gid: identity.gid,
-    mode: '700',
-  })
-  env.XDG_RUNTIME_DIR = CONTAINER_RUNTIME_DIR
-
-  // HOME is a tmpfs, so $HOME/.config and $HOME/.local/share are empty every run and .NET's
-  // GetFolderPath hands back "" for a missing directory. Point XDG at a per-profile bind
-  // instead. A game that already sets XDG_DATA_HOME to its save dir never gets
-  // overwritten.
-  mounts.push({ type: 'bind', source: hostPath(plan.configDirHost), target: CONTAINER_XDG_DIR })
-  env.XDG_CONFIG_HOME = `${CONTAINER_XDG_DIR}/config`
-  env.XDG_CACHE_HOME = `${CONTAINER_XDG_DIR}/cache`
-  env.XDG_DATA_HOME ??= `${CONTAINER_XDG_DIR}/data`
-
-  if (headed) {
-    if (settings.display === 'x11') {
-      const x11 = x11Session()
-      if (x11) {
-        mounts.push({ type: 'bind', source: X11_SOCKET_DIR, target: X11_SOCKET_DIR })
-        env.DISPLAY = x11.display
-        env.XDG_SESSION_TYPE = 'x11'
-        env.SDL_VIDEODRIVER = 'x11'
-        env.QT_QPA_PLATFORM = 'xcb'
-        if (x11.xauthority) {
-          mounts.push({ type: 'bind', source: x11.xauthority, target: CONTAINER_XAUTHORITY, readonly: true })
-          env.XAUTHORITY = CONTAINER_XAUTHORITY
-        }
-      }
-    } else {
-      const wayland = waylandSocket()
-      if (wayland) {
-        const target = `${CONTAINER_RUNTIME_DIR}/${wayland.name}`
-        mounts.push({ type: 'bind', source: wayland.source, target })
-        env.WAYLAND_DISPLAY = wayland.name
-        env.XDG_SESSION_TYPE = 'wayland'
-        env.SDL_VIDEODRIVER = 'wayland'
-        env.QT_QPA_PLATFORM = 'wayland'
-      }
-    }
-    if (settings.audio) {
-      for (const socket of audioSockets()) {
-        mounts.push({ type: 'bind', source: socket.source, target: `${CONTAINER_RUNTIME_DIR}/${socket.name}` })
-      }
-      env.PULSE_SERVER = `unix:${CONTAINER_RUNTIME_DIR}/pulse/native`
-    }
-  }
-  // Offscreen modes get their X server from xvfb-run below; DISPLAY is set by it, not by us.
-
-  const deviceCgroupRules: string[] = []
-  if (settings.input) {
-    mounts.push({ type: 'bind', source: '/dev/input', target: '/dev/input', readonly: true })
-    deviceCgroupRules.push('c 13:* rmw')
-  }
-
-  const devices: string[] = []
-  if (settings.gpu) devices.push('nvidia.com/gpu=all')
-  Object.assign(env, glEnv(settings.gpu))
-
-  command.push(...(settings.gameArgs ?? []))
-
-  return {
-    image: game.image.ref,
-    name: containerName(plan),
-    labels: {
-      'gamecrate.game': plan.game,
-      'gamecrate.profile': plan.profile,
-      ...(plan.instance === undefined ? {} : { 'gamecrate.instance': plan.instance }),
-    },
-    identity,
-    env,
-    mounts,
-    devices,
-    deviceCgroupRules,
-    network: settings.network,
-    memory: settings.memory,
-    memorySwap: settings.memory,
-    cpus: settings.cpus,
-    pidsLimit: settings.pidsLimit,
-    ulimits: ['core=0'],
-    workdir: game.gameFiles.container,
-    // An X client whose WM_CLIENT_MACHINE is foreign gets ` <@name>` stapled to its caption.
-    ...(headed && settings.display === 'x11' ? { hostname: hostname() } : {}),
-    command,
-    extraArgs: [...(settings.dockerArgs ?? [])],
-  }
-}
-
-/** Instances of one profile run side by side, so the name has to carry which one this is. */
-export function containerName(plan: LaunchPlan): string {
-  const base = `gamecrate-${plan.game}-${plan.profile}`
-  return plan.instance === undefined ? base : `${base}-${plan.instance}`
-}
-
-/** What the window is renamed to, so a taskbar full of worktrees is readable. */
-export function windowTitle(plan: LaunchPlan): string {
-  const base = `${plan.game} ${plan.profile}`
-  return plan.instance === undefined ? base : `${base} / ${plan.instance}`
-}
-
-export function toDockerArgs(spec: DockerRunSpec): string[] {
-  const args = ['run', '--rm', '--init', '--name', spec.name]
-  if (spec.hostname !== undefined) args.push('--hostname', spec.hostname)
-
-  for (const [key, value] of Object.entries(spec.labels)) args.push('--label', `${key}=${value}`)
-  args.push('--user', `${spec.identity.uid}:${spec.identity.gid}`)
-  for (const [key, value] of Object.entries(spec.env)) args.push('--env', `${key}=${value}`)
-  for (const mount of spec.mounts) args.push(...mountArgs(mount))
-  for (const device of spec.devices) args.push('--device', device)
-  for (const rule of spec.deviceCgroupRules) args.push('--device-cgroup-rule', rule)
-  for (const ulimit of spec.ulimits) args.push('--ulimit', ulimit)
-
-  args.push('--network', spec.network)
-  args.push('--memory', spec.memory)
-  args.push('--memory-swap', spec.memorySwap)
-  args.push('--cpus', String(spec.cpus))
-  args.push('--pids-limit', String(spec.pidsLimit))
-  args.push('--workdir', spec.workdir)
-  args.push(...spec.extraArgs)
-  // Acquisition is an earlier explicit step; the run must never fetch a different digest.
-  args.push('--pull=never')
-  // The image's own ENTRYPOINT is not ours to trust: RimWorld's is ["/bin/bash"], which
-  // would run the game's ELF as a shell script. State it explicitly every time.
-  const [entrypoint, ...rest] = spec.command
-  if (entrypoint !== undefined) args.push('--entrypoint', entrypoint)
-  args.push(spec.image, ...rest)
-
-  return args
-}
-
-/**
- * `--mount` for binds so a missing source errors instead of being created root-owned;
- * `--tmpfs` for tmpfs because `--mount type=tmpfs` has no uid=/gid= options.
- */
-function mountArgs(mount: Mount): string[] {
-  if (mount.type === 'tmpfs') {
-    const opts = ['rw']
-    if (mount.uid !== undefined) opts.push(`uid=${mount.uid}`)
-    if (mount.gid !== undefined) opts.push(`gid=${mount.gid}`)
-    if (mount.mode) opts.push(`mode=${mount.mode}`)
-    opts.push(`size=${mount.size ?? RUNTIME_DIR_SIZE}`)
-    return ['--tmpfs', `${mount.target}:${opts.join(',')}`]
-  }
-
-  if (!mount.source) {
-    throw new GamecrateError(`bind mount at ${mount.target} has no source`, Exit.Config)
-  }
-  const fields = [`type=bind`, `src=${mount.source}`, `dst=${mount.target}`]
-  if (mount.readonly) fields.push('readonly')
-  return ['--mount', fields.map(csvField).join(',')]
-}
-
-/** Docker parses the option string as CSV, so a comma in a path has to be quoted. */
-function csvField(field: string): string {
-  if (!field.includes(',') && !field.includes('"')) return field
-  return `"${field.replaceAll('"', '""')}"`
-}
-
-/**
- * RimWorld's TryGetCommandLineArg splits argv on `=` and requires exactly two parts. A path
- * with `=` falls back to an ephemeral in-container path and `--rm` takes the save with it (L10).
- */
-function validateDataDirArg(dataDir: Extract<DataDirSpec, { mode: 'arg' }>): string {
-  if (dataDir.container.includes('=')) {
-    throw new GamecrateError(
-      `container data path contains "=": ${dataDir.container}`,
-      Exit.Config,
-      'RimWorld silently ignores -savedatafolder when the argv element does not split into exactly two parts, and the save is lost with --rm.',
-    )
-  }
-
-  const parts = dataDir.arg.split('=')
-  if (parts.length !== 2) {
-    throw new GamecrateError(
-      `dataDir.arg must contain exactly one "=": ${dataDir.arg}`,
-      Exit.Config,
-    )
-  }
-
-  if (trimSlash(parts[1] ?? '') !== trimSlash(dataDir.container)) {
-    throw new GamecrateError(
-      `dataDir.arg points at ${parts[1]} but the mount target is ${dataDir.container}`,
-      Exit.Config,
-      'The engine would write to a path that is not the mounted data directory.',
-    )
-  }
-
-  return dataDir.arg
-}
-
-function trimSlash(path: string): string {
-  return path.length > 1 ? path.replace(/\/+$/, '') : path
-}
-
-/** The image bakes llvmpipe, so the tool states the whole GL story rather than inheriting it. */
-function glEnv(gpu: boolean): Record<string, string> {
-  if (!gpu) return { LIBGL_ALWAYS_SOFTWARE: '1', GALLIUM_DRIVER: 'llvmpipe' }
-
-  const env: Record<string, string> = { LIBGL_ALWAYS_SOFTWARE: '0', GALLIUM_DRIVER: '' }
-  if (hasNvidia()) {
-    env.__GLX_VENDOR_LIBRARY_NAME = 'nvidia'
-    env.__NV_PRIME_RENDER_OFFLOAD = '1'
-  }
-  return env
-}
-
-/** Gated on the detected vendor, not on the game: this class of host also carries radeon_icd. */
-function hasNvidia(): boolean {
-  return (
-    existsSync('/dev/nvidiactl') ||
-    existsSync('/etc/cdi/nvidia.yaml') ||
-    existsSync('/usr/share/vulkan/icd.d/nvidia_icd.json')
-  )
-}
-
-/**
- * The host X session a headed run joins. The cookie is looked up separately from the socket
- * because XWayland under a display manager keeps it in XDG_RUNTIME_DIR, not ~/.Xauthority.
- * Whether the socket directory is really there is checkBindSources' job, as with every bind.
- */
-export function x11Session(): { display: string; xauthority: string | null } | null {
-  const display = process.env.DISPLAY
-  if (!display) return null
-
-  const cookie = process.env.XAUTHORITY ?? join(homedir(), '.Xauthority')
-  return { display, xauthority: existsSync(cookie) ? cookie : null }
-}
-
-export function waylandSocket(): { source: string; name: string } | null {
-  const display = process.env.WAYLAND_DISPLAY
-  const runtime = process.env.XDG_RUNTIME_DIR
-  if (!display) return null
-
-  const source = display.startsWith('/') ? display : runtime ? join(runtime, display) : null
-  if (!source || !existsSync(source)) return null
-  return { source, name: basename(source) }
-}
-
-function audioSockets(): { source: string; name: string }[] {
-  const runtime = process.env.XDG_RUNTIME_DIR
-  if (!runtime) return []
-
-  const found: { source: string; name: string }[] = []
-  for (const name of ['pipewire-0', 'pulse/native']) {
-    const source = join(runtime, name)
-    if (existsSync(source)) found.push({ source, name })
-  }
-  return found
-}
-
-function hostPath(path: string): string {
-  try {
-    return realpathSync(path)
-  } catch {
-    return path
-  }
-}