@gamecrate/cli 0.1.0 → 1.1.0

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

@@ -0,0 +1,50 @@
+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;
+    /** Set for an engine that claims WM_DELETE_WINDOW and ignores it, RimWorld being the one. */
+    stripDelete: boolean;
+    /** Called once the window a stripDelete run adopted is gone. */
+    onClosed: () => void;
+}
+/**
+ * Retitles the window a headed X11 run opens and fixes what the WM knows about it. Snapshots
+ * 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. 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.` */
+export declare function parseAtoms(stdout: string): string[];

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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

@@ -0,0 +1,8 @@
+import type { LaunchPlan } from '../types';
+/** Rewritten in full every launch; the resolved list is the only source of truth. */
+export declare function generateModsConfig(plan: LaunchPlan): Promise<string>;
+/**
+ * Merges key-by-key. The live Prefs holds ~40 tuned keys, so a rewrite destroys
+ * volumeMaster, uiScale, langFolderName and the nested screenShakeIntensity block.
+ */
+export declare function mergePrefs(plan: LaunchPlan): Promise<string>;

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

@@ -0,0 +1,20 @@
+import type { ParsedArgs, Problem, ProfileConfig, Settings, WorktreeRequest } from '../types';
+export interface InstanceSelection {
+    /** Undefined for the base profile. */
+    name?: string;
+    /** profileDir, or <profileDir>/instances/<name>. */
+    dir: string;
+    requests: WorktreeRequest[];
+    problems: Problem[];
+    settings?: Partial<Settings>;
+}
+export interface InstanceOptions {
+    profileDir: string;
+    /** Absent when the caller only has a profile name, as `clean` on an unknown profile does. */
+    profile?: ProfileConfig;
+    args: Partial<ParsedArgs>;
+    cwd?: string;
+    env?: string;
+}
+/** Decides which sub-run of a profile this is. Any worktree in the set forks one. */
+export declare function resolveInstance(options: InstanceOptions): InstanceSelection;

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

@@ -0,0 +1,87 @@
+import type { BuildPolicy, GameConfig, LaunchPlan, PullPolicy } from '../types';
+/** Resolved image id, so `launches.jsonl` records what actually ran, not a floating tag. */
+export declare function imageDigest(ref: string): Promise<string | null>;
+/**
+ * Pulls or builds per policy. Shared by the `build` subcommand and `run`, so a launch can no
+ * longer proceed against an image the user asked to refresh.
+ */
+export declare function acquireImage(game: string, config: GameConfig, pull: PullPolicy): Promise<void>;
+/**
+ * Tag for the derived image, keeping the registry path readable. A tag only exists after the
+ * last `/`: before it a colon is a registry port, and an `@` means a digest no suffix can ride.
+ */
+export declare function runtimeLayerRef(ref: string): string;
+/**
+ * Builds (once) a thin layer over the adapter's image carrying an X server and imagemagick.
+ * Detects the package manager so a debian-based game image works the same as an Arch one.
+ */
+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
+ * 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>;
+/**
+ * Per-instance launch lock. Two concurrent runs would both `rm -rf` the same stage tree, so
+ * the second is refused rather than allowed to race. Separate instances never meet here.
+ */
+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>;
+/**
+ * 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.
+ */
+export declare function captureScreenshot(container: string, plan: LaunchPlan): Promise<string | null>;
+export declare function writeLaunchRecord(plan: LaunchPlan, image: string): Promise<void>;

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

@@ -0,0 +1,17 @@
+import type { GamePlugin } from '../plugin';
+import type { LaunchPlan, ModIndex, ParsedArgs, Problem, RootConfig } from '../types';
+export interface ResolveOptions {
+    game: string;
+    profile: string;
+    root: RootConfig;
+    plugins: Map<string, GamePlugin>;
+    args?: Partial<ParsedArgs>;
+    /** Prebuilt index; buildIndex runs when absent. */
+    index?: ModIndex;
+    /** Overrides process.cwd() for ambient worktree detection; tests set it. */
+    cwd?: string;
+}
+export declare function resolvePlan(options: ResolveOptions): Promise<{
+    plan: LaunchPlan;
+    problems: Problem[];
+}>;

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

@@ -0,0 +1,13 @@
+import type { LaunchPlan, Mount } from '../types';
+/**
+ * Wipes and rebuilds the staging tree, returning one read-only bind per mod.
+ * Never creates a symlink: a host symlink into a mod checkout dangles inside the container.
+ */
+export declare function stageMods(plan: LaunchPlan): Promise<Mount[]>;
+/** Pre-creates the profile skeleton as the caller, before docker can create it as root. */
+export declare function ensureProfileTree(plan: LaunchPlan): Promise<void>;
+/**
+ * Walks with lstat semantics, so a dangling symlink inside a mounted tree is reported
+ * rather than thrown. Stops once `limit` foreign paths are found.
+ */
+export declare function detectForeignOwnership(dir: string, uid: number, limit?: number): Promise<string[]>;

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/lib.d.ts

@@ -0,0 +1,3 @@
+export type { GamePlugin, ModsConfigInput } from './plugin';
+export { PLUGIN_API_VERSION } from './plugin';
+export type { DataDirSpec, DisplayBackend, DynamicModEntry, GameConfig, GameFilesSpec, ImageSpec, InstanceConfig, LibraryEntry, LogFileSpec, ModEntry, ModEntryObject, ModManifest, ModeName, ModsDirSpec, NetworkPolicy, ProfileConfig, ScanRoot, Settings, } from './types';

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

@@ -0,0 +1,29 @@
+import type { GamePlugin } from '../plugin';
+import type { GameConfig, ModIndex, ModRecord, Problem, WorktreeRequest } from '../types';
+/**
+ * `**` 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 declare function globMatch(pattern: string, path: string): boolean;
+/**
+ * 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 declare function applyWorktreeRequests(index: ModIndex, requests: WorktreeRequest[], config: GameConfig): Promise<void>;
+/**
+ * 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 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.
+ */
+export declare function buildIndex(game: string, config: GameConfig, plugin: GamePlugin): 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.
+ */
+export declare function resolveModRef(index: ModIndex, ref: string, game: GameConfig): ModRecord | null;

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

@@ -0,0 +1,28 @@
+import type { StaleReport } from '../types';
+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 declare function scanBuildTimes(dir: string): Promise<BuildTimes>;
+/**
+ * Drives `--build auto`, so a mod that has never been compiled counts as stale. The warning
+ * is the stricter one: see staleReport.
+ */
+export declare function decideStale(times: BuildTimes): boolean;
+/**
+ * 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 declare function staleReport(times: BuildTimes): StaleReport | null;
+export declare function staleWarning(packageId: string, report: StaleReport, now?: number): string;
+/** Coarse on purpose: "4m" is the whole signal, a duration to the second is noise. */
+export declare function duration(ms: number): string;
+export declare function ago(mtimeMs: number, now?: number): string;

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

@@ -0,0 +1,18 @@
+import type { Problem, WorktreeRequest, WorktreeSource } from '../types';
+/**
+ * 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 declare function resolveWorktree(dir: string, source: WorktreeSource, order: number): WorktreeRequest | Problem;
+/** True when `dir` is the worktree root or lives underneath it. */
+export declare function contains(request: WorktreeRequest, dir: string): boolean;
+/**
+ * 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 declare function collectRequests(flags: string[], env: string | undefined, cwd: string, disabled: boolean): {
+    requests: WorktreeRequest[];
+    problems: Problem[];
+};

package/dist/types/plugin.d.ts

@@ -0,0 +1,35 @@
+import type { GameConfig, ModManifest } from './types';
+/** Bumped when a change would make an older plugin misbehave rather than merely lag. */
+export declare 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;
+}
+/** Keyed by game name. A second plugin claiming a name already taken is a config error. */
+export declare function loadPlugins(specs: string[], configFile: string): Promise<Map<string, GamePlugin>>;
+export declare function requirePlugin(plugins: Map<string, GamePlugin>, game: string): GamePlugin;

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 {};