@gamecrate/cli 0.1.0

package/src/mods/worktree.ts

@@ -0,0 +1,107 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, realpathSync } from 'node:fs'
+import { isAbsolute, resolve, sep } from 'node:path'
+
+import { expandHome } from '../config/load'
+import type { Problem, WorktreeRequest, WorktreeSource } from '../types'
+
+/**
+ * One spawn answers every question: where the tree starts, whether it is linked, and what
+ * branch it is on. `gitDir !== gitCommonDir` is the exact linked-worktree test.
+ */
+function inspect(dir: string): { toplevel: string; gitDir: string; gitCommonDir: string; branch: string } | null {
+  const r = spawnSync(
+    'git',
+    ['-C', dir, 'rev-parse', '--path-format=absolute', '--show-toplevel', '--git-dir', '--git-common-dir', '--abbrev-ref', 'HEAD'],
+    { encoding: 'utf8' },
+  )
+  if (r.status !== 0 || typeof r.stdout !== 'string') return null
+  const lines = r.stdout.trim().split('\n')
+  if (lines.length < 4) return null
+  const [toplevel, gitDir, gitCommonDir, branch] = lines as [string, string, string, string]
+  return { toplevel, gitDir, gitCommonDir, branch }
+}
+
+function canonical(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return resolve(p)
+  }
+}
+
+/**
+ * Resolves one worktree request. Returns null when `dir` is not inside a LINKED worktree,
+ * which is what keeps a primary checkout, a non-repo directory and a pruned gitdir from
+ * counting as a selection.
+ */
+export function resolveWorktree(dir: string, source: WorktreeSource, order: number): WorktreeRequest | Problem {
+  const raw = expandHome(dir)
+  const abs = isAbsolute(raw) ? raw : resolve(process.cwd(), raw)
+
+  if (!existsSync(abs)) {
+    return { where: abs, message: `--worktree path does not exist`, suggestion: 'check the path, or drop the flag' }
+  }
+
+  const info = inspect(abs)
+  if (info === null) {
+    return source === 'cwd'
+      ? { where: abs, message: 'not a git repository', suggestion: 'ignored' }
+      : { where: abs, message: 'not a git repository, or its gitdir has been pruned', suggestion: 'run `git worktree prune` in the parent repo' }
+  }
+
+  if (info.gitDir === info.gitCommonDir) {
+    return source === 'cwd'
+      ? { where: abs, message: 'primary checkout, not a linked worktree', suggestion: 'ignored' }
+      : {
+          where: abs,
+          message: 'is the primary checkout, not a linked worktree',
+          suggestion: 'nothing to promote; drop --worktree',
+        }
+  }
+
+  return { root: canonical(info.toplevel), branch: info.branch, source, order }
+}
+
+/** True when `dir` is the worktree root or lives underneath it. */
+export function contains(request: WorktreeRequest, dir: string): boolean {
+  const target = canonical(dir)
+  return target === request.root || target.startsWith(request.root + sep)
+}
+
+/**
+ * Assembles every request in precedence order: explicit flags first (left to right), then the
+ * env var, then cwd. Only a linked worktree survives; everything else becomes an ignorable
+ * Problem so the caller can decide how loudly to say so.
+ */
+export function collectRequests(
+  flags: string[],
+  env: string | undefined,
+  cwd: string,
+  disabled: boolean,
+): { requests: WorktreeRequest[]; problems: Problem[] } {
+  if (disabled) return { requests: [], problems: [] }
+
+  const requests: WorktreeRequest[] = []
+  const problems: Problem[] = []
+  let order = 0
+
+  const add = (dir: string, source: WorktreeSource): void => {
+    const got = resolveWorktree(dir, source, order)
+    if ('root' in got) {
+      // A directory named twice is one request, at its strongest position.
+      if (!requests.some((r) => r.root === got.root)) {
+        requests.push(got)
+        order += 1
+      }
+    } else if (source !== 'cwd') {
+      problems.push(got)
+    }
+  }
+
+  for (const f of flags) add(f, 'flag')
+  if (env !== undefined && env !== '' && env !== 'off') add(env, 'env')
+  add(cwd, 'cwd')
+
+  return { requests, problems }
+}

package/src/plugin.ts

@@ -0,0 +1,152 @@
+import { readFileSync, statSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { exports as exportsField, legacy } from 'resolve.exports'
+
+import { expandHome } from './config/load'
+import { GamecrateError, Exit } from './types'
+import type { GameConfig, ModManifest } from './types'
+
+/** Bumped when a change would make an older plugin misbehave rather than merely lag. */
+export const PLUGIN_API_VERSION = 1
+
+export interface ModsConfigInput {
+  version: string
+  buildNumber: number
+  /** Lowercased packageIds, load order. */
+  activeMods: string[]
+  knownExpansions: string[]
+}
+
+/**
+ * A game's file formats plus the parts of its config that describe the game, not this machine.
+ * Everything here takes plain data and throws plain Errors, so no plugin links the core runtime.
+ */
+export interface GamePlugin {
+  apiVersion: number
+  /** The key this game answers to on the command line. */
+  game: string
+  /** Merged under the user's `games.<game>` block, so a user only writes what is theirs. */
+  defaults: Partial<GameConfig>
+  /** null means "this file is not a mod manifest". A malformed file throws. */
+  parseManifest(text: string): ModManifest | null
+  renderModsConfig(input: ModsConfigInput): string
+  mergePrefs(existing: string | null, owned: Record<string, string>): string
+  /** Prefs keys that put the game in a window instead of fullscreen. */
+  windowedPrefs: Record<string, string>
+  /** Version.txt as the engine writes it. null when it does not parse. */
+  parseVersion(text: string): { version: string; buildNumber: number } | null
+}
+
+const REQUIRED_FUNCTIONS = [
+  'parseManifest',
+  'renderModsConfig',
+  'mergePrefs',
+  'parseVersion',
+] as const
+
+function fail(spec: string, message: string, detail?: string): never {
+  throw new GamecrateError(`plugin "${spec}": ${message}`, Exit.Config, detail)
+}
+
+/**
+ * A directory's entry point, read from its own package.json. A compiled binary must do this by
+ * hand: Bun's resolver never reads the target package.json there, so it only finds index.js.
+ */
+function entryOf(dir: string): string {
+  let manifest: unknown
+  try {
+    manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+  } catch {
+    // A directory with no package.json still has an index to try.
+    return resolve(dir, 'index.js')
+  }
+  let entry: string | undefined
+  try {
+    entry = exportsField(manifest, '.', { conditions: ['bun'] })?.[0]
+  } catch {
+    // No condition matched, so fall through to the legacy fields.
+  }
+  entry ??= legacy(manifest, { fields: ['module', 'main'] }) as string | undefined
+  return resolve(dir, entry ?? 'index.js')
+}
+
+/**
+ * Walks node_modules upward by hand. require.resolve refuses "<pkg>/package.json" the moment a
+ * package has an exports map, and that file is the only thing that tells entryOf where to go.
+ */
+function packageDir(spec: string, from: string): string | null {
+  let dir = resolve(from)
+  for (;;) {
+    const candidate = join(dir, 'node_modules', spec)
+    if (statSync(join(candidate, 'package.json'), { throwIfNoEntry: false })?.isFile()) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** A path is anything that looks like one; everything else is a package. */
+function locate(spec: string, from: string): string {
+  const expanded = expandHome(spec)
+  let target: string | null
+  if (expanded.startsWith('.') || isAbsolute(expanded)) {
+    target = resolve(from, expanded)
+  } else {
+    target = packageDir(expanded, from)
+    if (target === null) {
+      fail(spec, `cannot be resolved from ${from}`, 'install it, or give a path starting with ./')
+    }
+  }
+  return statSync(target, { throwIfNoEntry: false })?.isDirectory() ? entryOf(target) : target
+}
+
+function check(spec: string, value: unknown): GamePlugin {
+  if (typeof value !== 'object' || value === null) fail(spec, 'has no default export')
+  const plugin = value as Partial<GamePlugin>
+  if (plugin.apiVersion !== PLUGIN_API_VERSION) {
+    fail(spec, `speaks apiVersion ${String(plugin.apiVersion)}, this build speaks ${PLUGIN_API_VERSION}`)
+  }
+  if (typeof plugin.game !== 'string' || plugin.game === '') fail(spec, 'declares no game name')
+  const missing = REQUIRED_FUNCTIONS.filter((name) => typeof plugin[name] !== 'function')
+  if (missing.length > 0) fail(spec, `is missing ${missing.join(', ')}`)
+  if (typeof plugin.defaults !== 'object' || plugin.defaults === null) {
+    fail(spec, 'declares no defaults object')
+  }
+  if (typeof plugin.windowedPrefs !== 'object' || plugin.windowedPrefs === null) {
+    fail(spec, 'declares no windowedPrefs object')
+  }
+  return plugin as GamePlugin
+}
+
+/** Keyed by game name. A second plugin claiming a name already taken is a config error. */
+export async function loadPlugins(specs: string[], configFile: string): Promise<Map<string, GamePlugin>> {
+  const from = dirname(configFile)
+  const out = new Map<string, GamePlugin>()
+  for (const spec of specs) {
+    const target = locate(spec, from)
+    let module: { default?: unknown }
+    try {
+      module = (await import(pathToFileURL(target).href)) as { default?: unknown }
+    } catch (error) {
+      fail(spec, `failed to load ${target}`, error instanceof Error ? error.message : String(error))
+    }
+    const plugin = check(spec, module.default)
+    if (out.has(plugin.game)) fail(spec, `also claims the game "${plugin.game}"`)
+    out.set(plugin.game, plugin)
+  }
+  return out
+}
+
+export function requirePlugin(plugins: Map<string, GamePlugin>, game: string): GamePlugin {
+  const plugin = plugins.get(game)
+  if (plugin === undefined) {
+    throw new GamecrateError(
+      `no plugin provides the game "${game}"`,
+      Exit.Config,
+      `loaded plugins: ${[...plugins.keys()].join(', ') || '(none)'}`,
+    )
+  }
+  return plugin
+}

package/src/types.ts

@@ -0,0 +1,423 @@
+import type { GamePlugin } from './plugin'
+
+/**
+ * Shared contract for every module. Units code against this and nothing else;
+ * if a signature here is wrong, fix it here rather than working around it locally.
+ */
+
+// ---------------------------------------------------------------- exit codes
+
+export const Exit = {
+  Ok: 0,
+  GameFailed: 1,
+  Usage: 2,
+  Config: 3,
+  Resolution: 4,
+  Environment: 5,
+  MarkerTimeout: 6,
+  /** Refused: this profile+instance is already running. `--replace` is the way past it. */
+  Refused: 7,
+  /** `verify`: a bound mod's sources are newer than its assemblies. */
+  Stale: 8,
+  Interrupted: 130,
+} as const
+
+export type ExitCode = (typeof Exit)[keyof typeof Exit]
+
+/** Every failure the tool raises deliberately. Anything else is a bug. */
+export class GamecrateError extends Error {
+  constructor(
+    message: string,
+    readonly code: ExitCode,
+    readonly detail?: string,
+  ) {
+    super(message)
+    this.name = 'GamecrateError'
+  }
+}
+
+/** Collected and reported together, so one run surfaces every problem at once. */
+export interface Problem {
+  /** JSON Pointer into profiles.json, or a file path, or a mod id. */
+  where: string
+  message: string
+  /** Populated by did-you-mean matching where it applies. */
+  suggestion?: string
+}
+
+// -------------------------------------------------------------------- config
+
+export type ModeName = 'headed' | 'headless' | 'screenshot'
+export type PullPolicy = 'always' | 'missing' | 'never'
+export type BuildPolicy = 'auto' | 'always' | 'never'
+export type NetworkPolicy = 'none' | 'bridge' | 'host'
+export type DisplayBackend = 'x11' | 'wayland'
+
+export interface Settings {
+  width: number
+  height: number
+  devMode: boolean
+  runInBackground: boolean
+  /** Forced false when written; see landmine 5. */
+  resetModsConfigOnCrash: boolean
+  gpu: boolean
+  audio: boolean
+  input: boolean
+  network: NetworkPolicy
+  /** Which display server a headed run talks to. x11 is the one an outside tool can retitle. */
+  display: DisplayBackend
+  memory: string
+  cpus: number
+  pidsLimit: number
+  /** Verbatim passthrough into the generated Prefs file. */
+  prefsExtra?: Record<string, string>
+  gameArgs?: string[]
+  dockerArgs?: string[]
+}
+
+export interface GameFilesSpec {
+  source: 'mount' | 'image'
+  /** Required when source is "mount". */
+  host?: string
+  container: string
+}
+
+export interface ImageSpec {
+  ref: string
+  acquire: 'pull' | 'build'
+  /** Required when acquire is "build". */
+  context?: string
+}
+
+/** How the engine is told where its data directory is. Verified per game. */
+export type DataDirSpec =
+  | { container: string; mode: 'arg'; arg: string }
+  | { container: string; mode: 'env'; env: Record<string, string> }
+
+export interface ModsDirSpec {
+  /** Where the staged mod tree is bind-mounted. NOT necessarily under dataDir. */
+  container: string
+  /** Extra mod roots inside the image that must be masked with a tmpfs. */
+  mask?: string[]
+}
+
+export type LogFileSpec =
+  | { mode: 'arg'; arg: string }
+  | { mode: 'copy-out'; from: string }
+
+export interface ScanRoot {
+  path: string
+  maxDepth: number
+  exclude?: string[]
+}
+
+export interface LibraryEntry {
+  workshop?: number
+  path?: string
+}
+
+/** Matches a family of mods by pattern instead of naming each one. */
+export interface DynamicModEntry {
+  match: string
+  first?: string[]
+  sort?: 'alpha' | 'none'
+  minMatches?: number
+}
+
+export interface ModEntryObject {
+  id: string
+  workshop?: number
+  path?: string
+  optional?: boolean
+}
+
+/** A bare string is a packageId; `workshop:` and `path:` prefixes disambiguate. */
+export type ModEntry = string | ModEntryObject | DynamicModEntry
+
+/**
+ * A named sub-run of a profile with its own data directory, lock and container, so several
+ * can run at once. Selected with `--instance`, or derived from an explicit `--worktree`.
+ */
+export interface InstanceConfig {
+  /** Promoted ahead of every other worktree request when this instance is selected. */
+  worktree?: string
+  settings?: Partial<Settings>
+}
+
+export interface ProfileConfig {
+  mods?: ModEntry[]
+  extends?: string
+  exclude?: string[]
+  includeBase?: boolean
+  autoDependencies?: boolean
+  settings?: Partial<Settings>
+  instances?: Record<string, InstanceConfig>
+  /** Marks this profile as another name for an existing one. */
+  alias?: string
+  /** Extra names this profile answers to, so one entry covers several spellings. */
+  aliases?: string[]
+}
+
+export interface GameConfig {
+  gameFiles: GameFilesSpec
+  dataDir: DataDirSpec
+  modsDir: ModsDirSpec
+  logFile: LogFileSpec
+  image: ImageSpec
+  executable: string
+  steamAppId: number
+  workshopRoot: string | null
+  scanRoots: ScanRoot[]
+  manifest: { file: string }
+  modsConfig: { file: string }
+  prefs: { file: string }
+  /** Filename suffixes that mean "a save". `clean --all` counts them before it deletes. */
+  saveExtensions: string[]
+  core: string
+  dlc: string[]
+  preCore?: string[]
+  base?: string[]
+  library?: Record<string, LibraryEntry>
+  modes: ModeName[]
+  aliases?: Record<string, string>
+  settings?: Partial<Settings>
+  /** The engine claims WM_DELETE_WINDOW and drops it, so the titlebar X does nothing. */
+  ignoresWmDelete?: boolean
+  profiles: Record<string, ProfileConfig>
+}
+
+export interface RootConfig {
+  /** Package names or paths, resolved from the config file's directory. One per game. */
+  plugins?: string[]
+  dataRoot: string
+  defaults?: { settings?: Partial<Settings> }
+  games: Record<string, GameConfig>
+}
+
+// ----------------------------------------------------------------- mod index
+
+export type ModSourceKind = 'local' | 'workshop' | 'official' | 'core'
+
+export interface ModManifest {
+  packageId: string
+  name?: string
+  modDependencies: { packageId: string; steamWorkshopUrl?: string }[]
+  loadAfter: string[]
+  loadBefore: string[]
+  forceLoadAfter: string[]
+  forceLoadBefore: string[]
+  incompatibleWith: string[]
+}
+
+export interface ModRecord {
+  /** Manifest casing, preserved. Match on the lowercased form. */
+  packageId: string
+  dir: string
+  kind: ModSourceKind
+  manifest: ModManifest
+  /** Workshop item id when kind is "workshop". */
+  workshopId?: number
+  /** True when dir sits inside a linked git worktree; ranked below primaries. */
+  linkedWorktree: boolean
+  /**
+   * Request order when a caller deliberately selected the worktree this record lives in.
+   * The scanner can never set it, which is what stops an unselected worktree from winning.
+   */
+  selectedWorktree?: number
+  /** Request order when `--use <packageId>=<dir>` named this record. Outranks a worktree. */
+  overridden?: number
+  /** Set only for a selected worktree; the branch costs a git spawn, so it is not scanned for. */
+  worktree?: { root: string; branch: string; source: WorktreeSource }
+  /** Which scanRoot produced it, for the precedence ladder. */
+  rootIndex: number
+}
+
+export type WorktreeSource = 'flag' | 'env' | 'cwd' | 'ref'
+
+export interface WorktreeRequest {
+  /** realpath'd worktree toplevel. */
+  root: string
+  branch: string
+  source: WorktreeSource
+  /** Lower wins. */
+  order: number
+}
+
+export interface ModIndex {
+  game: string
+  plugin: GamePlugin
+  /** Keyed by lowercased packageId. Several records means a collision to resolve. */
+  byPackageId: Map<string, ModRecord[]>
+  byWorkshopId: Map<number, ModRecord>
+  /** Lowercased last dot-segment -> packageIds. CLI matching only. */
+  byShortName: Map<string, string[]>
+  problems: Problem[]
+}
+
+// ---------------------------------------------------------------- resolution
+
+/** Why a mod looks stale, in enough detail to name the file that says so. */
+export interface StaleReport {
+  /** Mod-relative path of the newest .cs. */
+  newestSource: string
+  newestSourceMs: number
+  /** Mod-relative path of the newest assembly it should have been compiled into. */
+  assembly: string
+  assemblyMs: number
+  newerCount: number
+}
+
+export interface ResolvedMod {
+  packageId: string
+  hostDir: string
+  containerDir: string
+  kind: ModSourceKind
+  workshopId?: number
+  /** False when the entry came from autoDependencies rather than the profile. */
+  explicit: boolean
+  /** Set when a .cs file is newer than the staged assembly. */
+  stale?: boolean
+  /** Set only when there is an assembly to be stale against; drives the launch warning. */
+  staleReport?: StaleReport
+  /** Present when this mod came out of a linked worktree. */
+  worktree?: { root: string; branch: string; source: WorktreeSource; selected: boolean }
+  /** Other directories that declared this packageId and lost. Always emitted. */
+  shadowed?: string[]
+}
+
+export interface LaunchPlan {
+  game: string
+  gameConfig: GameConfig
+  plugin: GamePlugin
+  profile: string
+  settings: Settings
+  mods: ResolvedMod[]
+  /** Absolute host path: <dataRoot>/<game>/<profile>. */
+  profileDir: string
+  /** Undefined for the base profile; a name when several runs share one profile. */
+  instance?: string
+  /** profileDir, or <profileDir>/instances/<instance>. Everything a run writes hangs off it. */
+  instanceDir: string
+  dataDirHost: string
+  /** <profileDir>/config. Shared by every instance, and holds the XDG dirs. */
+  configDirHost: string
+  stageDirHost: string
+  logsDirHost: string
+  /** <logsDirHost>/runs/<ts>, bound into the container so Player.log lands with stdout.log. */
+  runDirHost: string
+  mode: ModeName
+  marker?: string
+  timeoutSeconds: number
+  renderWaitSeconds: number
+  /** False under --no-stale-check. The check still runs, so staleReport stays truthful. */
+  warnOnStale: boolean
+  warnings: string[]
+}
+
+// -------------------------------------------------------------------- docker
+
+export interface Identity {
+  uid: number
+  gid: number
+  home: string
+  user: string
+}
+
+export interface Mount {
+  type: 'bind' | 'tmpfs'
+  source?: string
+  target: string
+  readonly?: boolean
+  /** tmpfs only. */
+  size?: string
+  uid?: number
+  gid?: number
+  mode?: string
+}
+
+export interface DockerRunSpec {
+  image: string
+  name: string
+  labels: Record<string, string>
+  identity: Identity
+  env: Record<string, string>
+  mounts: Mount[]
+  devices: string[]
+  deviceCgroupRules: string[]
+  network: NetworkPolicy
+  memory: string
+  memorySwap: string
+  cpus: number
+  pidsLimit: number
+  ulimits: string[]
+  workdir: string
+  /** The host's, when set: KWin appends `<@name>` to a caption from a foreign machine. */
+  hostname?: string
+  /** argv after the image name. */
+  command: string[]
+  extraArgs: string[]
+}
+
+// ----------------------------------------------------------------------- cli
+
+export interface ParsedArgs {
+  subcommand: string
+  game?: string
+  profile?: string
+  mods: string[]
+  without: string[]
+  only: string[]
+  mode?: ModeName
+  marker?: string
+  timeout?: number
+  renderWait?: number
+  resolution?: { width: number; height: number }
+  network?: NetworkPolicy
+  log?: string
+  pull?: PullPolicy
+  build?: BuildPolicy
+  sort?: 'topo' | 'none'
+  /** `clean` only: --staging is the default, --all additionally requires --yes. */
+  cleanTier?: 'staging' | 'logs' | 'all'
+  dockerArgs: string[]
+  gameArgs: string[]
+  dryRun: boolean
+  printPlan: boolean
+  json: boolean
+  root: boolean
+  yes: boolean
+  help: boolean
+  /** Repeatable; earlier flags outrank later ones. */
+  worktree: string[]
+  /** Names the sub-run: its own data directory, lock and container. */
+  instance?: string
+  /** Repeatable `packageId=path`; forces one mod's source, whatever the profile says. */
+  use: string[]
+  /** Suppresses ambient cwd selection and the env var. */
+  noWorktree: boolean
+  /** Suppresses the sources-newer-than-assemblies warning. The check itself still runs. */
+  noStaleCheck: boolean
+  /** Stops whatever holds this profile+instance, then launches. Never refuses. */
+  replace: boolean
+  rest: string[]
+}
+
+export type ProjectDefaults = Partial<
+  Omit<ParsedArgs, 'subcommand' | 'cleanTier' | 'yes' | 'help' | 'rest'>
+>
+
+/** Names that can never be a game or profile key. Enforced at config load. */
+export const RESERVED_NAMES: readonly string[] = [
+  'run', 'list', 'mods', 'doctor', 'clean', 'clone', 'logs', 'build',
+  'shell', 'config', 'fix-perms', 'verify', 'help', 'version', 'modless',
+]
+
+export const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+/**
+ * Lookup in a bag keyed by user input. A bare index hands back Object.prototype members, so
+ * `--mod constructor` or a profile named `toString` would resolve to an inherited function.
+ */
+export function own<T>(bag: Record<string, T> | undefined, key: string): T | undefined {
+  return bag !== undefined && Object.hasOwn(bag, key) ? bag[key] : undefined
+}