@gamecrate/cli 1.0.0 → 1.2.0

package/dist/lib.js

@@ -2,7 +2,6 @@
 import { exports as exportsField, legacy } from "resolve.exports";
 
 // src/config/load.ts
-import { parse as parseYaml } from "yaml";
 import { z as z2 } from "zod";
 
 // src/cli/args.ts
@@ -21,7 +20,6 @@ var Exit = {
   Stale: 8,
   Interrupted: 130
 };
-
 class GamecrateError extends Error {
   code;
   detail;
@@ -74,6 +72,10 @@ function distance(a, b) {
   return prev[b.length];
 }
 
+// src/config/read.ts
+import { parseTree } from "jsonc-parser";
+import { isMap, parse as parseYaml, parseDocument } from "yaml";
+
 // src/config/jsonc.ts
 import { parse, printParseErrorCode } from "jsonc-parser";
 
@@ -177,7 +179,11 @@ var profile = obj({
     error: "expected an object"
   }).optional(),
   alias: str.optional(),
-  aliases: strArray.optional()
+  aliases: strArray.optional(),
+  description: str.optional(),
+  detach: bool.optional(),
+  replace: bool.optional(),
+  build: oneOf(["auto", "always", "never"]).optional()
 }).check((ctx) => {
   const v = ctx.value;
   if (v.alias !== undefined && (v.extends !== undefined || v.mods !== undefined)) {
@@ -188,6 +194,37 @@ var profile = obj({
     });
   }
 });
+var libraryEntry = obj({
+  workshop: num.optional(),
+  path: str.optional(),
+  git: str.optional(),
+  branch: str.optional(),
+  tag: str.optional(),
+  commit: str.optional(),
+  subdir: str.optional()
+}).check((ctx) => {
+  const v = ctx.value;
+  const push = (message, path) => {
+    ctx.issues.push({ code: "custom", message, input: v, ...path === undefined ? {} : { path } });
+  };
+  const sources = ["workshop", "path", "git"].filter((k) => v[k] !== undefined);
+  if (sources.length === 0)
+    push('library entry needs a "workshop" id, a "path", or a "git" url');
+  if (sources.length > 1)
+    push(`library entry takes only one of ${sources.join(", ")}`);
+  const refs = ["branch", "tag", "commit"].filter((k) => v[k] !== undefined);
+  if (refs.length > 1)
+    push(`library entry takes only one of branch, tag or commit, got ${refs.join(", ")}`);
+  if (v["git"] === undefined) {
+    for (const key of [...refs, ...v["subdir"] === undefined ? [] : ["subdir"]]) {
+      push(`"${key}" needs a "git" url`, [key]);
+    }
+  }
+  const subdir = v["subdir"];
+  if (typeof subdir === "string" && (subdir.startsWith("/") || subdir.split("/").includes(".."))) {
+    push('"subdir" must be a relative path inside the repo, with no ".." segment', ["subdir"]);
+  }
+});
 var game = obj({
   gameFiles: obj({ source: oneOf(["mount", "image"]), host: str.optional(), container: str }).check(requiredWhen("host", (v) => v["source"] === "mount")),
   dataDir: obj({
@@ -213,15 +250,7 @@ var game = obj({
   dlc: strArray,
   preCore: strArray.optional(),
   base: strArray.optional(),
-  library: z.record(z.string(), obj({ workshop: num.optional(), path: str.optional() }).check((ctx) => {
-    if (ctx.value["workshop"] === undefined && ctx.value["path"] === undefined) {
-      ctx.issues.push({
-        code: "custom",
-        message: 'library entry needs a "workshop" id or a "path"',
-        input: ctx.value
-      });
-    }
-  }), { error: "expected an object" }).optional(),
+  library: z.record(z.string(), libraryEntry, { error: "expected an object" }).optional(),
   modes: z.array(modeName, { error: "expected a non-empty array" }).min(1, {
     error: "expected a non-empty array"
   }),
@@ -257,9 +286,13 @@ var projectResolution = z2.string({ error: "expected dimensions like 1920x1080"
     ctx.issues.push({ code: "custom", message: error.message, input: ctx.value });
   }
 }).transform(parseResolution);
-var PROJECT_SCHEMA = z2.strictObject({
+var PROJECT_OBJECT = z2.strictObject({
   game: projectName.optional(),
-  profile: projectName.optional(),
+  defaultProfile: projectName.optional(),
+  profiles: z2.record(z2.string(), z2.unknown()).optional(),
+  settings: z2.record(z2.string(), z2.unknown()).optional(),
+  library: z2.record(z2.string(), z2.unknown()).optional(),
+  detach: projectBool.optional(),
   mods: projectList.optional(),
   without: projectList.optional(),
   only: projectList.optional(),
@@ -288,6 +321,25 @@ var PROJECT_SCHEMA = z2.strictObject({
   }).optional(),
   resolution: projectResolution.optional()
 }, { error: "expected an object" });
+var PROJECT_SCHEMA = PROJECT_OBJECT.check((ctx) => {
+  const { game, profiles, settings, library } = ctx.value;
+  if (game !== undefined)
+    return;
+  for (const [key, value] of [
+    ["profiles", profiles],
+    ["settings", settings],
+    ["library", library]
+  ]) {
+    if (value === undefined)
+      continue;
+    ctx.issues.push({
+      code: "custom",
+      path: [key],
+      message: "needs a top-level game: to say which game it belongs to",
+      input: ctx.value
+    });
+  }
+});
 
 // src/plugin.ts
 var PLUGIN_API_VERSION = 1;

package/dist/types/cli/args.d.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import type { ParsedArgs, ProjectDefaults } from '../types';
+import type { BuildPolicy, ParsedArgs, ProfileConfig, ProjectDefaults } from '../types';
 export type PositionalSlot = 'game' | 'profile' | 'rest';
 export interface SubcommandSpec {
     name: string;
@@ -9,6 +9,8 @@ export interface SubcommandSpec {
     positionals: PositionalSlot[];
     /** Flag names beyond the global set, in the order help should show them. */
     flags: readonly string[];
+    /** Slots to use instead of `positionals` when the next word is one of these. */
+    subverbs?: Readonly<Record<string, PositionalSlot[]>>;
 }
 /** The subcommand table. `modless` is reserved as a built-in profile, not a verb. */
 export declare const SUBCOMMANDS: readonly SubcommandSpec[];
@@ -32,9 +34,25 @@ export interface ParseOptions {
  * defaulting to `run`. Game args come after a bare `--` and nowhere else.
  */
 export declare function parseArgs(argv: string[], opts?: ParseOptions): ParsedArgs;
+/**
+ * Any layer can ask for this; the --no-detach flag is the only refusal. The supervisor is
+ * already the fork, and a profile or project `detach: true` reaches it too: it never forks again.
+ */
+export declare function wantsDetach(args: ParsedArgs, profile: ProfileConfig): boolean;
+/** The parent already replaced the previous run, and the only lock left is the child's own. */
+export declare function wantsReplace(args: ParsedArgs, profile: ProfileConfig): boolean;
+/** Three-way, so first defined wins. --no-build already arrives as 'never'. */
+export declare function buildPolicy(args: ParsedArgs, profile: ProfileConfig): BuildPolicy;
 export declare function parseResolution(value: string): {
     width: number;
     height: number;
 };
 /** Closest candidate within an edit distance that scales with word length. */
 export declare function suggest(word: string, candidates: readonly string[]): string | undefined;
+/**
+ * The argv that re-execs this same gamecrate as a supervisor. The compiled binary reports
+ * a virtual /$bunfs path as argv[1], which the child would read as a game name.
+ */
+export declare function supervisorArgv(userArgs: string[], instanceDir: string, self?: string[], execPath?: string): string[];
+/** Read straight off argv: the recovery path runs before anything is parsed or loaded. */
+export declare function supervisedDir(argv: string[]): string | undefined;

package/dist/types/cli/game.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs, RootConfig } from '../types';
+export declare function requireGame(args: ParsedArgs, config: RootConfig): string;

package/dist/types/cli/list.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs, ProjectDefaults, RootConfig } from '../types';
+export declare function list(args: ParsedArgs, config: RootConfig, defaults: ProjectDefaults): number;

package/dist/types/cli/mods.d.ts

@@ -0,0 +1,16 @@
+import type { GamePlugin } from '../plugin';
+import type { ParsedArgs, ProjectDefaults, RootConfig } from '../types';
+export interface ModsContext {
+    config: RootConfig;
+    plugins: Map<string, GamePlugin>;
+    defaults: ProjectDefaults;
+    /** Where findProjectConfig starts walking. Injectable so tests need no chdir. */
+    cwd: string;
+    /** The resolved global config path, or where to create one. Injectable for the same reason. */
+    globalPath: string;
+}
+/** The same fallback loadConfig uses, so an error names the file `config edit` would open. */
+export declare function globalConfigPath(): Promise<string>;
+export declare function modsAdd(args: ParsedArgs, ctx: ModsContext): Promise<number>;
+export declare function modsRm(args: ParsedArgs, ctx: ModsContext): Promise<number>;
+export declare function modsSync(args: ParsedArgs, ctx: ModsContext): Promise<number>;

package/dist/types/cli/output.d.ts

@@ -6,7 +6,7 @@ export declare function warn(message: string): void;
 export interface OutputRedirect {
     close(): void;
 }
-export declare function redirectOutput(path: string): OutputRedirect;
+export declare function redirectOutput(path: string, keep?: boolean): OutputRedirect;
 export declare function forwardOutput(stream: Readable, target: NodeJS.WriteStream): Promise<void>;
 /**
  * Every collected failure at once, grouped by location. Resolution stops before any
@@ -52,5 +52,27 @@ export declare function printPlan(plan: LaunchPlan, asJson: boolean): void;
 export declare function runTimestamp(now?: Date): string;
 /** Makes <logsDir>/runs/<ts>, repoints `current` at it, rotates the old ones, returns the dir. */
 export declare function openRunLog(logsDir: string, now?: Date): string;
+/** Below the first a wait is not worth mentioning; the log normally appears in milliseconds. */
+export interface NoticeSchedule {
+    firstMs: number;
+    everyMs: number;
+}
+export declare const WAIT_NOTICE: NoticeSchedule;
+/**
+ * The elapsed label when a wait is due a line, else undefined. Driven by elapsed time and not
+ * by poll count: a quarter-second poll would scroll a line per pass and read as its own kind
+ * of broken, while a silent ten-minute image build looks exactly like a hang. Both branches
+ * floor, so the label never claims more time than has passed.
+ */
+export declare function waitNotice(waitedMs: number, lastNoticeMs: number, schedule?: NoticeSchedule): string | undefined;
+/** Inverse of runTimestamp. Anchored at the start, so the -2 collision suffix is tolerated. */
+export declare function runStartedAt(name: string): number | undefined;
+/** linkCurrent keeps `current` pointed at the newest run, so the run dir is never guessed. */
+export declare function currentLog(instanceDir: string): string;
+/**
+ * tail -f never ends on its own, so a live run gets --pid and tail leaves when the holder
+ * does. With no live holder nothing will write again, so -f is dropped or it hangs forever.
+ */
+export declare function tailArgv(file: string, fromStart: boolean, livePid?: number): string[];
 /** Landmine 7: a 180MB Player-prev.log was 68% of a profile tree. Retention is the cap. */
 export declare function rotateRuns(logsDir: string, keep: number): string[];

package/dist/types/cli/profile.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedArgs, ProjectDefaults } from '../types';
+/**
+ * Not in parseArgs: filling a default there would erase the difference between a typed
+ * profile and a defaulted one, which clean and fix-perms both need.
+ */
+export declare function profileOf(args: ParsedArgs, defaults: ProjectDefaults): string;

package/dist/types/config/load.d.ts

@@ -1,6 +1,7 @@
 import type { GameConfig, ModEntry, ProfileConfig, ProjectDefaults, RootConfig, Settings } from '../types';
 import type { GamePlugin } from '../plugin';
-export declare function defaultConfigPath(): string;
+export declare function globalConfigDir(): string;
+export declare function findGlobalConfig(): Promise<string | undefined>;
 export declare function findProjectConfig(start?: string): Promise<string | undefined>;
 export declare function loadProjectDefaults(start?: string): Promise<ProjectDefaults>;
 export interface LoadedConfig {
@@ -8,10 +9,10 @@ export interface LoadedConfig {
     plugins: Map<string, GamePlugin>;
 }
 /**
- * Reads profiles.json, loads the plugins it lists, then merges the user's blocks over each
+ * Reads the global config, loads the plugins it lists, then merges the user's blocks over each
  * plugin's defaults. A missing file means no games, which every non-launch subcommand survives.
  */
-export declare function loadConfig(path?: string): Promise<LoadedConfig>;
+export declare function loadConfig(path?: string, project?: ProjectDefaults): Promise<LoadedConfig>;
 /** defaults -> games.<game> -> profile -> instance -> CLI. Scalars replace, arrays concatenate. */
 export declare function resolveSettings(root: RootConfig, game: GameConfig, profile: ProfileConfig, ...overrides: (Partial<Settings> | undefined)[]): Settings;
 /**
@@ -34,6 +35,7 @@ export declare function profileDataDir(root: RootConfig, game: string, profile:
  * verbatim: a directory name is already a path, and canonicalizing it skips odd-cased ones.
  */
 export declare function profileDirs(root: RootConfig, game: string, profile?: string): Promise<string[]>;
+export declare function profileKey(game: GameConfig, name: string): string | undefined;
 /** Removes entries whose id matches an exclusion. Dynamic entries are filtered after expansion. */
 export declare function subtract(mods: ModEntry[], exclude: string[]): ModEntry[];
 export declare function globToRegExp(pattern: string): RegExp;

package/dist/types/config/read.d.ts

@@ -0,0 +1,11 @@
+/** Probe order. yaml first: it is what `config edit` writes and what the docs show. */
+export declare const CONFIG_SUFFIXES: readonly [".yml", ".yaml", ".json", ".jsonc"];
+export declare function readConfigText(text: string, path: string): unknown;
+/** Undefined when the file is not there; every other read error propagates. */
+export declare function readConfigFile(path: string): Promise<unknown>;
+/**
+ * Source order of the keys under one top-level object. Object.keys sorts all-integer keys
+ * to the front, and NAME_PATTERN lets a profile be called 2024, so the syntax tree is the
+ * only honest answer to "which profile was written first".
+ */
+export declare function orderedKeys(text: string, path: string, key: string): string[];

package/dist/types/config/write.d.ts

@@ -0,0 +1,14 @@
+/** A value of `undefined` deletes the key rather than writing an undefined. */
+export interface ConfigEdit {
+    path: (string | number)[];
+    value: unknown;
+}
+/**
+ * jsonc-parser never sniffs the file, so an inserted block lands with whatever width it is
+ * handed. A file indented with tabs and edited with spaces reads as two files.
+ */
+export declare function detectIndent(text: string): {
+    tabSize: number;
+    insertSpaces: boolean;
+};
+export declare function writeConfig(file: string, edits: ConfigEdit[]): Promise<void>;

package/dist/types/docker/run.d.ts

@@ -2,7 +2,7 @@ import type { ChildProcess, StdioOptions } from 'node:child_process';
 import type { Readable } from 'node:stream';
 import type { DockerRunSpec } from '../types';
 /** argv as one array, the way every caller here has it. */
-export declare function spawnArgv(argv: string[], stdio: StdioOptions): ChildProcess;
+export declare function spawnArgv(argv: string[], stdio: StdioOptions, detached?: boolean): ChildProcess;
 /** Rejects when the spawn itself fails, so a missing binary lands where a bad exit code would. */
 export declare function exited(proc: ChildProcess): Promise<number>;
 export declare function collect(stream: Readable): Promise<string>;
@@ -28,6 +28,8 @@ export interface RunOptions {
  * `exec docker run | tee` returns tee's code, which is why the old scripts always reported 0.
  */
 export declare function runContainer(spec: DockerRunSpec, opts: RunOptions): Promise<number>;
+/** Grace docker gives the game before SIGKILL, and the budget every teardown is measured against. */
+export declare const STOP_TIMEOUT_SECONDS = 10;
 export declare function stopContainer(name: string, timeoutSeconds: number): Promise<void>;
 /**
  * Host-side marker watch. Watches container stdout AND the game's own log file: RimWorld

package/dist/types/docker/window.d.ts

@@ -1,6 +1,34 @@
 export interface WindowWatch {
     stop: () => void;
 }
+export interface Toplevel {
+    id: string;
+    wmClass: string;
+}
+/** Every window that appeared since the snapshot and belongs to this game, in wmctrl's order. */
+export declare function newMatches(now: Toplevel[], seen: Set<string>, executable: string): Toplevel[];
+export declare function parseWindowPid(stdout: string): number | undefined;
+/**
+ * Another supervisor's window. Our own claim, or a dead or non-gamecrate pid, is not.
+ * Deliberately not `isRunning`: the cmdline read already throws for a dead pid, and it stays
+ * readable for a supervisor owned by another user, where a signal check is denied and would
+ * have us steal that run's window.
+ *
+ * Matched on each argument's own basename rather than anywhere in the raw cmdline, so a
+ * gamecrate log path or data directory in an unrelated process's arguments is not a peer. An
+ * editor opened on a directory literally named gamecrate still is; nothing in /proc separates
+ * those two.
+ *
+ * It also stops matching `bun run src/index.ts`, where the old substring match caught the repo
+ * directory in the script path. Installed users are unaffected, the bin and gamecrate.js both
+ * match; it costs peer detection between two concurrent from-source dev runs.
+ *
+ * Residual: before adoption `_NET_WM_PID` is the container's pid namespace, so this looks a
+ * container-local number up in the host's `/proc`. A false hit makes the run skip its own
+ * window for the whole wait. Container game pids are small and low host pids are kernel
+ * threads with an empty cmdline, so in practice the read returns nothing and no match happens.
+ */
+export declare function isPeerClaim(pid: number, self: number): boolean;
 export interface AdoptOptions {
     executable: string;
     title: string;
@@ -14,7 +42,8 @@ export interface AdoptOptions {
  * the screen first and takes the first window that was not there: an X client inside a
  * container reports a container-local _NET_WM_PID and hostname, so neither of those identifies
  * the run from out here. The WM_CLASS comes from the executable, which narrows it to this game
- * rather than any window that opened.
+ * rather than any window that opened. Once adopted, _NET_WM_PID holds our pid, so a second run
+ * starting at the same time can see the window is already spoken for and keep waiting for its own.
  */
 export declare function adoptNewWindow(opts: AdoptOptions): Promise<WindowWatch>;
 /** `WM_PROTOCOLS(ATOM): protocols  WM_DELETE_WINDOW, WM_TAKE_FOCUS`, or `:  not found.` */

package/dist/types/launch/prepare.d.ts

@@ -18,7 +18,7 @@ export declare function runtimeLayerRef(ref: string): string;
 export declare function ensureRuntimeLayer(ref: string): Promise<string>;
 /**
  * Builds local mods before launch. `always` builds every local mod; `auto` builds only the
- * ones resolution flagged stale; `never` skips. A build failure stops the launch — shipping
+ * ones resolution flagged stale; `never` skips. A build failure stops the launch, shipping
  * the previous DLL after a failed compile is how you debug code that is not running.
  */
 export declare function buildLocalMods(plan: LaunchPlan, policy: BuildPolicy): Promise<void>;
@@ -29,13 +29,56 @@ export declare function buildLocalMods(plan: LaunchPlan, policy: BuildPolicy): P
 export interface ProfileLock {
     release: () => Promise<void>;
 }
+/**
+ * Refuses when this profile and instance are already up, and clears a lock whose holder is
+ * gone. Detach runs this before it forks, so a stale lock cannot strand the child.
+ */
+export declare function clearLock(plan: LaunchPlan): Promise<void>;
+/** The parent wrote this lock with the child's pid, so the child only has to drop it. */
+export declare function heldLock(plan: LaunchPlan): ProfileLock;
 export declare function takeLock(plan: LaunchPlan): Promise<ProfileLock>;
+/** Everything ps, stop, attach and wait need about a run, without reopening the container. */
+export interface LockRecord {
+    pid: number;
+    container: string;
+    game: string;
+    profile: string;
+    instance?: string;
+    detached: boolean;
+    mode?: string;
+    startedAt: string;
+}
+export declare function lockPath(plan: LaunchPlan): string;
+export declare function readLock(path: string): Promise<LockRecord | undefined>;
+/** wx fails rather than truncating, which is what makes this a lock and not a note. */
+export declare function writeLock(plan: LaunchPlan, record: Omit<LockRecord, 'startedAt'>): Promise<void>;
 /**
- * `--replace`: stops the container for this profile and instance only, so a parallel worktree
- * run is untouched. Waits for the holder to release before forcing, because its own release
- * would otherwise unlink the lock we are about to take.
+ * A signalled supervisor cannot finish before its own `docker stop --timeout` does, so the
+ * budget is derived from that rather than guessed alongside it.
+ */
+export declare const STOP_RELEASE_WAIT_MS: number;
+/**
+ * What stopRun did, because "the supervisor took the signal" and "the lock was stale anyway"
+ * are not the same answer and the caller has to say which one it is.
+ */
+export type StopOutcome = 'signalled' | 'orphaned' | 'held';
+/**
+ * Signals the supervisor, not the container. runContainer turns SIGTERM into a docker stop and
+ * returns 130, so the run records itself as stopped rather than crashed. Only a run whose
+ * supervisor is already gone gets the container stopped out from under it.
+ */
+export declare function stopRun(record: LockRecord, lockFile: string): Promise<StopOutcome>;
+/**
+ * `--replace`: ends the run for this profile and instance only, so a parallel worktree run is
+ * untouched. Goes through stopRun so the replaced run reports `stopped`; a raw docker stop
+ * would land as 137 instead.
  */
 export declare function replacePrevious(plan: LaunchPlan): Promise<void>;
+/**
+ * A pid alone is not proof. Detach leaves a long-lived process per run, so a recycled number
+ * would refuse every future launch and give ps a ghost with an invented uptime.
+ */
+export declare function isRunning(pid: number, startedAt?: string): boolean;
 /**
  * Grabs one frame from inside the running container. The run dir is already bind-mounted at
  * CONTAINER_LOG_DIR, so the png lands next to that run's logs with no extra mount.

package/dist/types/launch/resolve.d.ts

@@ -1,5 +1,5 @@
 import type { GamePlugin } from '../plugin';
-import type { LaunchPlan, ModIndex, ParsedArgs, Problem, RootConfig } from '../types';
+import type { GameConfig, LaunchPlan, ModIndex, ParsedArgs, Problem, RootConfig } from '../types';
 export interface ResolveOptions {
     game: string;
     profile: string;
@@ -10,7 +10,14 @@ export interface ResolveOptions {
     index?: ModIndex;
     /** Overrides process.cwd() for ambient worktree detection; tests set it. */
     cwd?: string;
+    /** Lowercased packageId to the clone directory prepared for its git pin. */
+    sources?: ReadonlyMap<string, string>;
 }
+/**
+ * doctor resolves the modless profile, so no mod ref is ever resolved there. Read the config
+ * instead: library pins, plus every profile's mods in both the object and bare-string forms.
+ */
+export declare function workshopRootProblem(gameName: string, game: GameConfig): Problem | null;
 export declare function resolvePlan(options: ResolveOptions): Promise<{
     plan: LaunchPlan;
     problems: Problem[];

package/dist/types/launch/supervisor.d.ts

@@ -0,0 +1,48 @@
+import type { NoticeSchedule } from '../cli/output';
+import type { LockRecord } from './prepare';
+import type { ExitReason, LaunchPlan, LaunchResult } from '../types';
+/**
+ * Written once, after the spawn, with the child's pid: a take-then-rewrite would leave a dead
+ * pid over a live child, and the next launcher would unlink it and race the same stage tree.
+ * Writing first is not open either, since a placeholder pid reads as "no lock" everywhere.
+ *
+ * So the child is killed when the write loses the `wx` race, because a supervisor with no lock
+ * runs unguarded and its release would drop the winner's lock.
+ *
+ * Residual: a parent killed between the spawn and the write leaves that child unguarded, with
+ * nothing left to kill it. That window spans a fork and an exec, so milliseconds.
+ */
+export declare function forkSupervisor(plan: LaunchPlan, argv: string[]): Promise<number>;
+export declare function recordExit(plan: LaunchPlan, result: LaunchResult): Promise<void>;
+/**
+ * The supervisor has no terminal and its stdio is discarded, so the exit record is the only way
+ * a caller ever learns it died. The lock goes only once that record is on disk, so a failed
+ * write leaves it: clearLock takes a dead holder on the next launch, while a cleared lock with
+ * no record makes wait answer "no run recorded" for a run that really failed.
+ */
+export declare function supervisorFailed(dir: string, code: number): Promise<number>;
+export interface ExitRecord {
+    at: string;
+    code: number;
+    reason: ExitReason;
+    container?: string;
+    runDir?: string;
+}
+/** The other half of writeExit. Missing or corrupt reads as "no exit recorded", never a throw. */
+export declare function lastExit(instanceDir: string): Promise<ExitRecord | undefined>;
+/**
+ * Blocks while a live holder has the lock. `orphaned` is a holder that died without recording
+ * anything, which is reachable with SIGKILL; `absent` is a run that never happened. Neither
+ * can ever produce an exit code, so neither may keep waiting for one.
+ *
+ * Once a lock has been seen, the pid outranks the file: the lock can vanish because someone
+ * else cleared it, but a live pid still owes us a record.
+ */
+export declare function awaitExit(instanceDir: string, poll?: number): Promise<ExitRecord | 'orphaned' | 'absent'>;
+/**
+ * The lock is written right after the spawn, but the supervisor only opens its run log after
+ * preflight, staging and the image, so `current` can point at the previous run for as long as
+ * a pull takes. tail follows a descriptor, so starting there would watch a finished run and
+ * never catch up. Waiting is bounded by the holder: if it dies first, there is nothing coming.
+ */
+export declare function awaitRunLog(instanceDir: string, lock: LockRecord, poll?: number, notice?: NoticeSchedule): Promise<boolean>;

package/dist/types/mods/modindex.d.ts

@@ -18,10 +18,11 @@ export declare function applyWorktreeRequests(index: ModIndex, requests: Worktre
  */
 export declare function applySourceOverrides(index: ModIndex, overrides: string[], config: GameConfig): Promise<Problem[]>;
 /**
- * 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.
+ * Scans the game install, then every scan root in declaration order, then the source cache,
+ * then the workshop root. Local roots rescan every launch; only the workshop scan is cached,
+ * against the acf stamp.
  */
-export declare function buildIndex(game: string, config: GameConfig, plugin: GamePlugin): Promise<ModIndex>;
+export declare function buildIndex(game: string, config: GameConfig, plugin: GamePlugin, sourcesDir?: string): Promise<ModIndex>;
 /**
  * `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.

package/dist/types/mods/source.d.ts

@@ -0,0 +1,56 @@
+import type { GameConfig, LibraryEntry, ParsedArgs } from '../types';
+export type GitRef = {
+    kind: 'branch' | 'tag' | 'commit';
+    value: string;
+};
+/**
+ * A library pin by id, case-blind. Exact then lowercase covers every normal config without a
+ * scan; the scan is the only way to reach a mixed-case key from a ref spelled differently.
+ */
+export declare function libraryPin(game: GameConfig, id: string): LibraryEntry | undefined;
+export declare function sourcesRoot(dataRoot: string): string;
+export declare function normalizeUrl(url: string): string;
+export declare function cloneDir(dataRoot: string, url: string, ref: GitRef): string;
+export interface GitPin {
+    url: string;
+    ref?: GitRef;
+    subdir?: string;
+}
+export type SyncMode = 'use' | 'fetch' | 'force';
+export interface SyncResult {
+    dir: string;
+    warning?: string;
+}
+export declare function isMoving(ref: GitRef): boolean;
+export declare function gitRefOf(pin: {
+    branch?: string;
+    tag?: string;
+    commit?: string;
+}): GitRef | undefined;
+export declare function defaultBranch(url: string): GitRef;
+export declare function ensureClone(dataRoot: string, pin: GitPin, ref: GitRef, mode: SyncMode): Promise<SyncResult>;
+export declare function lockClone(dir: string): Promise<() => Promise<void>>;
+export declare function unlinkOrphan(path: string, seen: string): Promise<boolean>;
+export interface PreparedSources {
+    /** lowercased packageId -> clone directory. Handed to resolvePlan as `sources`. */
+    dirs: Map<string, string>;
+    warnings: string[];
+    /** One entry per distinct clone this call handled, fetched or reused. Makes dedupe testable. */
+    fetched: string[];
+    /** Released by execute(), and by run()'s finally. Never before buildLocalMods. */
+    release: () => Promise<void>;
+}
+/**
+ * The map `prepareSources` builds, read off the cache alone: no lock, no clone, no network.
+ * `mods` and `verify` must not fetch, but with no map at all a git pin's `subdir` is dropped and
+ * the scan answers by packageId instead, which is a coin flip between two directories of one
+ * repo. An unpinned entry has no ref to derive a directory from, so it takes the one `branch-*`
+ * clone already on disk.
+ */
+export declare function cachedSources(game: GameConfig, profileName: string, args: Partial<ParsedArgs>, dataRoot: string): Map<string, string>;
+/**
+ * Clones or fetches every git-pinned mod the run will ask for, before the index is built, and
+ * keeps one lock per clone until the caller releases it. `git()` is spawnSync, so these
+ * serialize whatever this function looks like.
+ */
+export declare function prepareSources(game: GameConfig, profileName: string, args: ParsedArgs, dataRoot: string, allowFetch: boolean): Promise<PreparedSources>;

package/dist/types/run/registry.d.ts

@@ -0,0 +1,22 @@
+import type { LockRecord } from '../launch/prepare';
+export interface RunRecord {
+    game: string;
+    profile: string;
+    instance?: string;
+    container: string;
+    pid?: number;
+    mode?: string;
+    startedAt?: string;
+    uptime?: string;
+    status: 'running' | 'starting' | 'orphaned';
+}
+export declare function parseDockerRuns(stdout: string): RunRecord[];
+/** <dataRoot>/<game>/<profile>/.gamecrate/lock, plus one level of instances under each. */
+export declare function walkLocks(dataRoot: string): Promise<LockRecord[]>;
+type Docker = () => Promise<string>;
+/**
+ * Docker answers for anything with a container. The lock walk covers the phase before one
+ * exists (pull, build, stage) and a lock whose container is already gone.
+ */
+export declare function listRuns(dataRoot: string, docker?: Docker): Promise<RunRecord[]>;
+export {};