@gamecrate/cli 0.1.0 → 1.0.0

package/src/mods/modindex.ts

@@ -1,539 +0,0 @@
-import { existsSync, readFileSync, statSync } from 'node:fs'
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
-import { homedir } from 'node:os'
-import { dirname, join, relative, resolve as resolvePath } from 'node:path'
-
-import picomatch from 'picomatch'
-
-import { expandHome } from '../config/load'
-import { GamecrateError, Exit, own } from '../types'
-import { contains } from './worktree'
-import type { GamePlugin } from '../plugin'
-import type {
-  GameConfig,
-  ModIndex,
-  ModManifest,
-  ModRecord,
-  ModSourceKind,
-  Problem,
-  ScanRoot,
-  WorktreeRequest,
-} from '../types'
-
-/** Cache lives outside the profile tree so `clean --all` can never invalidate it. */
-function cacheDir(): string {
-  return join(process.env['XDG_CACHE_HOME'] ?? join(homedir(), '.cache'), 'gamecrate')
-}
-
-/**
- * `**` spans separators, `*` and `?` do not; everything else is literal. Mod folders are
- * routinely named `[KV] Mod Manager`, so brackets and braces must not be glob syntax.
- */
-export function globMatch(pattern: string, path: string): boolean {
-  return picomatch.isMatch(path, pattern.replace(/[[\]{}()!,@+|^$.\\]/g, '\\$&'), { dot: true })
-}
-
-function excluded(patterns: string[], relativePath: string): boolean {
-  return patterns.some((p) => globMatch(p, relativePath) || globMatch(p, `${relativePath}/`))
-}
-
-// ---------------------------------------------------------------------- scan
-
-interface Candidate {
-  dir: string
-  kind: ModSourceKind
-  rootIndex: number
-  linkedWorktree: boolean
-  workshopId?: number
-}
-
-/**
- * Worktrees are opt-in, never ambient inventory: an abandoned agent tree must not be a
- * candidate for a launch nobody pointed at it. The overlay scan (rootIndex -1) skips these,
- * which is how a deliberately selected worktree still gets in.
- */
-const ALWAYS_EXCLUDE = ['**/.worktrees/**', '**/.claude/worktrees/**']
-
-/**
- * A `.git` file rather than a directory means a linked worktree or submodule. The walk stops
- * at the scan root because a scan root can hold many independent repos, not one.
- */
-function inLinkedWorktree(dir: string, stopAt: string): boolean {
-  let current = dir
-  for (;;) {
-    const git = join(current, '.git')
-    if (existsSync(git)) {
-      try {
-        if (statSync(git).isFile()) return true
-      } catch {
-        return false
-      }
-      return false
-    }
-    if (current === stopAt) return false
-    const parent = dirname(current)
-    if (parent === current) return false
-    current = parent
-  }
-}
-
-async function scanLocalRoot(
-  root: ScanRoot,
-  rootIndex: number,
-  manifestFile: string,
-  found: Candidate[],
-): Promise<void> {
-  const base = resolvePath(expandHome(root.path))
-  const exclude = [...(root.exclude ?? []), ...(rootIndex === -1 ? [] : ALWAYS_EXCLUDE)]
-
-  const walk = async (dir: string, depth: number): Promise<void> => {
-    const manifest = join(dir, manifestFile)
-    if (existsSync(manifest)) {
-      found.push({
-        dir,
-        kind: 'local',
-        rootIndex,
-        linkedWorktree: inLinkedWorktree(dir, base),
-      })
-      // Never descend into a mod: 93 of 325 workshop items ship per-version About files.
-      return
-    }
-    if (depth >= root.maxDepth) return
-
-    let entries
-    try {
-      entries = await readdir(dir, { withFileTypes: true })
-    } catch {
-      return
-    }
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith('.git')) continue
-      const child = join(dir, entry.name)
-      if (excluded(exclude, relative(base, child))) continue
-      await walk(child, depth + 1)
-    }
-  }
-
-  if (!existsSync(base)) return
-  await walk(base, 0)
-}
-
-/** Depth-exact at `<root>/<numericId>/About/About.<ext>`; recursing produces phantoms. */
-async function scanWorkshopRoot(
-  workshopRoot: string,
-  rootIndex: number,
-  manifestFile: string,
-  found: Candidate[],
-): Promise<void> {
-  const base = resolvePath(expandHome(workshopRoot))
-  let entries
-  try {
-    entries = await readdir(base, { withFileTypes: true })
-  } catch {
-    return
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) continue
-    const dir = join(base, entry.name)
-    if (!existsSync(join(dir, manifestFile))) continue
-    found.push({ dir, kind: 'workshop', rootIndex, linkedWorktree: false, workshopId: Number(entry.name) })
-  }
-}
-
-/** Core and the official expansions live inside the game install, one level under Data/. */
-async function scanGameData(
-  game: GameConfig,
-  rootIndex: number,
-  found: Candidate[],
-): Promise<void> {
-  const host = game.gameFiles.host
-  if (game.gameFiles.source !== 'mount' || host === undefined) return
-  const data = join(resolvePath(expandHome(host)), 'Data')
-  let entries
-  try {
-    entries = await readdir(data, { withFileTypes: true })
-  } catch {
-    return
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue
-    const dir = join(data, entry.name)
-    if (!existsSync(join(dir, game.manifest.file))) continue
-    found.push({ dir, kind: 'official', rootIndex, linkedWorktree: false })
-  }
-}
-
-// --------------------------------------------------------------------- index
-
-const CACHE_VERSION = 2
-
-interface CacheFile {
-  version: number
-  stamp: string
-  records: ModRecord[]
-}
-
-function workshopStamp(game: GameConfig): string | null {
-  if (game.workshopRoot === null) return null
-  const acf = join(dirname(dirname(resolvePath(expandHome(game.workshopRoot)))), `appworkshop_${game.steamAppId}.acf`)
-  try {
-    const info = statSync(acf)
-    return `${info.mtimeMs}:${info.size}`
-  } catch {
-    return null
-  }
-}
-
-async function readWorkshopCache(game: string, stamp: string): Promise<ModRecord[] | null> {
-  try {
-    const raw = JSON.parse(await readFile(join(cacheDir(), `${game}.workshop.json`), 'utf8')) as CacheFile
-    if (raw.version !== CACHE_VERSION || raw.stamp !== stamp) return null
-    return raw.records
-  } catch {
-    return null
-  }
-}
-
-async function writeWorkshopCache(game: string, stamp: string, records: ModRecord[]): Promise<void> {
-  const payload: CacheFile = { version: CACHE_VERSION, stamp, records }
-  try {
-    await mkdir(cacheDir(), { recursive: true })
-    await writeFile(join(cacheDir(), `${game}.workshop.json`), JSON.stringify(payload))
-  } catch {
-    // A cache that cannot be written is a slower launch, never a failed one.
-  }
-}
-
-function toRecord(candidate: Candidate, manifest: ModManifest, game: GameConfig): ModRecord {
-  const kind: ModSourceKind =
-    manifest.packageId.toLowerCase() === game.core.toLowerCase() ? 'core' : candidate.kind
-  const record: ModRecord = {
-    packageId: manifest.packageId,
-    dir: candidate.dir,
-    kind,
-    manifest,
-    linkedWorktree: candidate.linkedWorktree,
-    rootIndex: candidate.rootIndex,
-  }
-  if (candidate.workshopId !== undefined) record.workshopId = candidate.workshopId
-  return record
-}
-
-/** Selection first: naming a directory is the strongest statement of intent available. */
-function tier(r: ModRecord): number[] {
-  return [
-    r.overridden ?? Number.MAX_SAFE_INTEGER,
-    r.selectedWorktree ?? Number.MAX_SAFE_INTEGER,
-    r.kind === 'workshop' ? 1 : 0,
-    r.linkedWorktree ? 1 : 0,
-    r.rootIndex,
-  ]
-}
-
-function compareTiers(a: ModRecord, b: ModRecord): number {
-  const x = tier(a)
-  const y = tier(b)
-  for (let i = 0; i < x.length; i += 1) {
-    if (x[i] !== y[i]) return x[i]! - y[i]!
-  }
-  return 0
-}
-
-/** Selection, then non-workshop, then non-worktree, then scan-root order. */
-function rank(a: ModRecord, b: ModRecord): number {
-  return compareTiers(a, b) || (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0)
-}
-
-/**
- * Stamps every record inside a requested worktree, then scans the worktree itself so a tree
- * no scanRoot reaches still contributes. Only a caller who stood in, typed, or exported a
- * directory can produce `selectedWorktree`.
- */
-export async function applyWorktreeRequests(
-  index: ModIndex,
-  requests: WorktreeRequest[],
-  config: GameConfig,
-): Promise<void> {
-  if (requests.length === 0) return
-
-  const known = new Set<string>()
-  for (const bucket of index.byPackageId.values()) {
-    for (const record of bucket) {
-      known.add(record.dir)
-      for (const request of requests) {
-        if (!contains(request, record.dir)) continue
-        record.worktree = { root: request.root, branch: request.branch, source: request.source }
-        record.selectedWorktree = request.order
-        break
-      }
-    }
-  }
-
-  // Overlay scan: coverage by scanRoot is incidental, so never depend on it.
-  for (const request of requests) {
-    const found: Candidate[] = []
-    await scanLocalRoot(
-      { path: request.root, maxDepth: WORKTREE_SCAN_DEPTH, exclude: WORKTREE_EXCLUDE },
-      -1,
-      config.manifest.file,
-      found,
-    )
-    const fresh = found.filter((c) => !known.has(c.dir))
-    if (fresh.length === 0) continue
-    for (const record of await parseAll(fresh, config, index.plugin, index.problems)) {
-      record.worktree = { root: request.root, branch: request.branch, source: request.source }
-      record.selectedWorktree = request.order
-      insert(index, record)
-    }
-  }
-
-  for (const bucket of index.byPackageId.values()) bucket.sort(rank)
-}
-
-/** Deep enough for a repo-shaped worktree without walking a whole build tree. */
-const WORKTREE_SCAN_DEPTH = 5
-const WORKTREE_EXCLUDE = ['**/.retired/**', '**/node_modules/**', '**/bin/**', '**/obj/**']
-
-/**
- * Forces one packageId to come from a named directory, whatever the profile pinned. This is
- * the only override that reaches a mod already in preCore/core/dlc/base, because slot
- * expansion is first-wins and a later `--mod` entry for a present id is dropped.
- */
-export async function applySourceOverrides(
-  index: ModIndex,
-  overrides: string[],
-  config: GameConfig,
-): Promise<Problem[]> {
-  const problems: Problem[] = []
-  if (overrides.length === 0) return problems
-
-  for (const [order, spec] of overrides.entries()) {
-    const eq = spec.indexOf('=')
-    if (eq < 1) {
-      problems.push({ where: spec, message: '--use takes <packageId>=<path>' })
-      continue
-    }
-    const wanted = spec.slice(0, eq)
-    const dir = resolvePath(expandHome(spec.slice(eq + 1)))
-
-    const file = join(dir, config.manifest.file)
-    if (!existsSync(file)) {
-      problems.push({
-        where: spec,
-        message: `no ${config.manifest.file} under ${dir}`,
-        suggestion: 'point --use at the mod directory, not the repo root',
-      })
-      continue
-    }
-
-    let manifest: ModManifest | null
-    try {
-      manifest = index.plugin.parseManifest(readFileSync(file, 'utf8'))
-    } catch (error) {
-      problems.push({ where: file, message: `could not parse: ${String(error)}` })
-      continue
-    }
-    if (manifest === null) {
-      problems.push({ where: file, message: `${file} declares no packageId` })
-      continue
-    }
-
-    if (manifest.packageId.toLowerCase() !== wanted.toLowerCase()) {
-      problems.push({
-        where: spec,
-        message: `${dir} declares ${manifest.packageId}, not ${wanted}`,
-        suggestion: `use --use ${manifest.packageId}=${dir}`,
-      })
-      continue
-    }
-
-    const key = manifest.packageId.toLowerCase()
-    const existing = (index.byPackageId.get(key) ?? []).find((r) => r.dir === dir)
-    if (existing) {
-      existing.overridden = order
-    } else {
-      const record = toRecord({ dir, kind: 'local', rootIndex: -1, linkedWorktree: false }, manifest, config)
-      record.overridden = order
-      insert(index, record)
-    }
-    index.byPackageId.get(key)?.sort(rank)
-  }
-
-  return problems
-}
-
-function insert(index: ModIndex, record: ModRecord): void {
-  const key = record.packageId.toLowerCase()
-  const bucket = index.byPackageId.get(key)
-  if (bucket) bucket.push(record)
-  else index.byPackageId.set(key, [record])
-
-  if (record.workshopId !== undefined && !index.byWorkshopId.has(record.workshopId)) {
-    index.byWorkshopId.set(record.workshopId, record)
-  }
-
-  const short = key.split('.').pop()
-  if (short !== undefined && short.length > 0) {
-    const ids = index.byShortName.get(short)
-    if (ids) {
-      if (!ids.includes(record.packageId)) ids.push(record.packageId)
-    } else {
-      index.byShortName.set(short, [record.packageId])
-    }
-  }
-}
-
-/**
- * Scans the game install, then every scan root in declaration order, then the workshop root.
- * Local roots rescan every launch; only the workshop scan is cached, against the acf stamp.
- */
-export async function buildIndex(game: string, config: GameConfig, plugin: GamePlugin): Promise<ModIndex> {
-  const index: ModIndex = {
-    game,
-    plugin,
-    byPackageId: new Map(),
-    byWorkshopId: new Map(),
-    byShortName: new Map(),
-    problems: [],
-  }
-
-  const local: Candidate[] = []
-  await scanGameData(config, -1, local)
-  for (const [i, root] of config.scanRoots.entries()) {
-    await scanLocalRoot(root, i, config.manifest.file, local)
-  }
-  for (const record of await parseAll(local, config, plugin, index.problems)) insert(index, record)
-
-  if (config.workshopRoot !== null) {
-    const stamp = workshopStamp(config)
-    const cached = stamp === null ? null : await readWorkshopCache(game, stamp)
-    if (cached) {
-      for (const record of cached) insert(index, record)
-    } else {
-      const items: Candidate[] = []
-      await scanWorkshopRoot(config.workshopRoot, config.scanRoots.length, config.manifest.file, items)
-      const records = await parseAll(items, config, plugin, index.problems)
-      for (const record of records) insert(index, record)
-      if (stamp !== null) await writeWorkshopCache(game, stamp, records)
-    }
-  }
-
-  for (const bucket of index.byPackageId.values()) bucket.sort(rank)
-  return index
-}
-
-async function parseAll(
-  candidates: Candidate[],
-  config: GameConfig,
-  plugin: GamePlugin,
-  problems: Problem[],
-): Promise<ModRecord[]> {
-  const records = await Promise.all(
-    candidates.map(async (candidate): Promise<ModRecord | null> => {
-      const file = join(candidate.dir, config.manifest.file)
-      try {
-        const manifest = plugin.parseManifest(await readFile(file, 'utf8'))
-        // A scan walks into plenty of directories that were never mods. null is the plugin
-        // saying so; a thrown error means the file is broken and worth reporting.
-        return manifest === null ? null : toRecord(candidate, manifest, config)
-      } catch (error) {
-        problems.push({
-          where: file,
-          message: error instanceof Error ? error.message : String(error),
-        })
-        return null
-      }
-    }),
-  )
-  return records.filter((r): r is ModRecord => r !== null)
-}
-
-// ------------------------------------------------------------------- resolve
-
-/**
- * `path:` and `workshop:` are explicit; a bare string resolves as exact packageId, then the
- * game's alias map, then a CLI-only short name. Ambiguity that the ladder cannot break is fatal.
- */
-export function resolveModRef(index: ModIndex, ref: string, game: GameConfig): ModRecord | null {
-  return honorOverride(index, resolveRaw(index, ref, game))
-}
-
-/**
- * `--use` has to beat a `library` pin, and a pin resolves through byWorkshopId without ever
- * touching the ladder. So the override is applied after the ref resolves, by packageId.
- */
-function honorOverride(index: ModIndex, record: ModRecord | null): ModRecord | null {
-  if (record === null || record.overridden !== undefined) return record
-  const best = index.byPackageId.get(record.packageId.toLowerCase())?.[0]
-  return best?.overridden !== undefined ? best : record
-}
-
-function resolveRaw(index: ModIndex, ref: string, game: GameConfig): ModRecord | null {
-  if (ref.startsWith('path:')) return byPath(index, ref.slice(5), game)
-  if (ref.startsWith('workshop:')) {
-    const id = Number(ref.slice(9))
-    return Number.isInteger(id) ? index.byWorkshopId.get(id) ?? null : null
-  }
-
-  const direct = pick(index, ref.toLowerCase(), ref)
-  if (direct) return direct
-
-  const alias = own(game.aliases, ref) ?? own(game.aliases, ref.toLowerCase())
-  if (alias !== undefined && alias.toLowerCase() !== ref.toLowerCase()) {
-    return resolveRaw(index, alias, game)
-  }
-
-  const short = index.byShortName.get(ref.toLowerCase())
-  if (short && short.length === 1) return pick(index, short[0]!.toLowerCase(), ref)
-  if (short && short.length > 1) {
-    throw new GamecrateError(
-      `"${ref}" is a short name for ${short.length} mods`,
-      Exit.Resolution,
-      short.join(', '),
-    )
-  }
-  return null
-}
-
-function pick(index: ModIndex, key: string, ref: string): ModRecord | null {
-  const bucket = index.byPackageId.get(key)
-  const best = bucket?.[0]
-  if (!best) return null
-  const runnerUp = bucket![1]
-  if (runnerUp && compareTiers(best, runnerUp) === 0) {
-    // Two dirs inside one selected worktree is a user error. An unselected tie is a coin
-    // flip the plan already exposes via `shadowed`, so it warns rather than stopping a run.
-    if (best.selectedWorktree !== undefined || runnerUp.selectedWorktree !== undefined) {
-      throw new GamecrateError(
-        `"${ref}" is declared by ${bucket!.length} indistinguishable directories`,
-        Exit.Resolution,
-        bucket!.map((r) => r.dir).join('\n'),
-      )
-    }
-    index.problems.push({
-      where: ref,
-      message: `resolved by directory name: ${bucket!.length} candidates tie on every rule`,
-      suggestion: `using ${best.dir}`,
-    })
-  }
-  return best
-}
-
-/** An explicit path always wins, including one the scan never reached. */
-function byPath(index: ModIndex, raw: string, game: GameConfig): ModRecord | null {
-  const dir = resolvePath(expandHome(raw))
-  for (const bucket of index.byPackageId.values()) {
-    const hit = bucket.find((record) => record.dir === dir || record.dir === raw)
-    if (hit) return hit
-  }
-
-  const file = join(dir, game.manifest.file)
-  if (!existsSync(file)) return null
-  try {
-    const manifest = index.plugin.parseManifest(readFileSync(file, 'utf8'))
-    if (manifest === null) return null
-    return toRecord({ dir, kind: 'local', rootIndex: -1, linkedWorktree: false }, manifest, game)
-  } catch {
-    return null
-  }
-}

package/src/mods/staleness.ts

@@ -1,125 +0,0 @@
-import { readdir, stat } from 'node:fs/promises'
-import { join, relative } from 'node:path'
-
-import type { StaleReport } from '../types'
-
-/** Directories that never hold a mod's own sources or shipped assemblies. */
-const SKIP_DIRS = new Set(['.git', '.retired', '.vs', 'bin', 'node_modules', 'obj'])
-
-/**
- * A mod's Textures tree alone runs to five figures, so the cap has to clear it. A walk that
- * stops before it reaches Source/ reports "fresh" for a mod it never looked at.
- */
-const ENTRY_LIMIT = 20_000
-
-export interface Timestamped {
-  /** Relative to the mod directory. */
-  path: string
-  mtimeMs: number
-}
-
-export interface BuildTimes {
-  newestSource?: Timestamped
-  newestAssembly?: Timestamped
-  /** Every .cs mtime, so a report can count how many beat the assembly. */
-  sourceTimes: number[]
-}
-
-/** One walk answers both questions: is this stale, and which files say so. */
-export async function scanBuildTimes(dir: string): Promise<BuildTimes> {
-  const times: BuildTimes = { sourceTimes: [] }
-  let budget = ENTRY_LIMIT
-
-  const walk = async (current: string, inAssemblies: boolean): Promise<void> => {
-    let entries
-    try {
-      entries = await readdir(current, { withFileTypes: true })
-    } catch {
-      return
-    }
-    for (const entry of entries) {
-      if (budget-- <= 0) return
-      const path = join(current, entry.name)
-      if (entry.isDirectory()) {
-        if (SKIP_DIRS.has(entry.name.toLowerCase())) continue
-        // RimWorld ships per-version Assemblies dirs, so it is any depth, not just the root.
-        await walk(path, inAssemblies || entry.name === 'Assemblies')
-        continue
-      }
-      if (!entry.isFile()) continue
-      const lower = entry.name.toLowerCase()
-      const isSource = lower.endsWith('.cs')
-      const isAssembly = inAssemblies && lower.endsWith('.dll')
-      if (!isSource && !isAssembly) continue
-
-      let mtimeMs: number
-      try {
-        mtimeMs = (await stat(path)).mtimeMs
-      } catch {
-        continue
-      }
-      const found: Timestamped = { path: relative(dir, path), mtimeMs }
-      if (isSource) {
-        times.sourceTimes.push(mtimeMs)
-        if (mtimeMs > (times.newestSource?.mtimeMs ?? -1)) times.newestSource = found
-      } else if (mtimeMs > (times.newestAssembly?.mtimeMs ?? -1)) {
-        times.newestAssembly = found
-      }
-    }
-  }
-
-  await walk(dir, false)
-  return times
-}
-
-/**
- * Drives `--build auto`, so a mod that has never been compiled counts as stale. The warning
- * is the stricter one: see staleReport.
- */
-export function decideStale(times: BuildTimes): boolean {
-  const { newestSource, newestAssembly } = times
-  if (newestSource === undefined) return false
-  return newestAssembly === undefined || newestSource.mtimeMs > newestAssembly.mtimeMs
-}
-
-/**
- * Null when there is nothing to say: no C#, no assemblies to compare against, or the build is
- * current. A mod may legitimately ship XML only, so this never reports on one.
- */
-export function staleReport(times: BuildTimes): StaleReport | null {
-  const { newestSource, newestAssembly } = times
-  if (newestSource === undefined || newestAssembly === undefined) return null
-  if (newestSource.mtimeMs <= newestAssembly.mtimeMs) return null
-  return {
-    newestSource: newestSource.path,
-    newestSourceMs: newestSource.mtimeMs,
-    assembly: newestAssembly.path,
-    assemblyMs: newestAssembly.mtimeMs,
-    newerCount: times.sourceTimes.filter((t) => t > newestAssembly.mtimeMs).length,
-  }
-}
-
-/** Lines up the continuation under the message, past the `warning: ` that warn() adds. */
-const INDENT = ' '.repeat('warning: '.length)
-
-export function staleWarning(packageId: string, report: StaleReport, now = Date.now()): string {
-  const files = report.newerCount === 1 ? '1 source file' : `${report.newerCount} source files`
-  return [
-    `${packageId} has ${files} newer than ${report.assembly}`,
-    `${INDENT}newest: ${report.newestSource} (${ago(report.newestSourceMs, now)})`,
-    `${INDENT}you are probably running a stale build`,
-  ].join('\n')
-}
-
-/** Coarse on purpose: "4m" is the whole signal, a duration to the second is noise. */
-export function duration(ms: number): string {
-  const seconds = Math.max(0, Math.round(ms / 1000))
-  if (seconds < 60) return `${seconds}s`
-  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`
-  if (seconds < 86_400) return `${Math.floor(seconds / 3600)}h`
-  return `${Math.floor(seconds / 86_400)}d`
-}
-
-export function ago(mtimeMs: number, now = Date.now()): string {
-  return `${duration(now - mtimeMs)} ago`
-}