@gamecrate/cli 0.1.0 → 1.0.0

package/src/mods/worktree.ts

@@ -1,107 +0,0 @@
-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

@@ -1,152 +0,0 @@
-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

@@ -1,423 +0,0 @@
-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
-}