@gamecrate/cli 0.1.0 → 1.0.0

package/dist/lib.js

@@ -0,0 +1,296 @@
+// src/plugin.ts
+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
+import { Command, CommanderError, Option } from "commander";
+
+// src/types.ts
+var Exit = {
+  Ok: 0,
+  GameFailed: 1,
+  Usage: 2,
+  Config: 3,
+  Resolution: 4,
+  Environment: 5,
+  MarkerTimeout: 6,
+  Refused: 7,
+  Stale: 8,
+  Interrupted: 130
+};
+
+class GamecrateError extends Error {
+  code;
+  detail;
+  constructor(message, code, detail) {
+    super(message);
+    this.code = code;
+    this.detail = detail;
+    this.name = "GamecrateError";
+  }
+}
+var NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+// src/cli/args.ts
+function parseResolution(value) {
+  const match = /^(\d+)x(\d+)$/i.exec(value);
+  const width = Number(match?.[1]);
+  const height = Number(match?.[2]);
+  if (!Number.isSafeInteger(width) || width <= 0 || !Number.isSafeInteger(height) || height <= 0) {
+    throw usage(`--resolution takes positive dimensions like 1920x1080, got ${value}`);
+  }
+  return { width, height };
+}
+function usage(message, suggestion) {
+  return new GamecrateError(message, Exit.Usage, suggestion ? `did you mean ${suggestion}?` : undefined);
+}
+function suggest(word, candidates) {
+  const target = word.toLowerCase();
+  const limit = Math.max(2, Math.floor(target.length / 3));
+  let best;
+  let bestDistance = Infinity;
+  for (const candidate of candidates) {
+    const d = distance(target, candidate.toLowerCase());
+    if (d < bestDistance && d <= limit) {
+      best = candidate;
+      bestDistance = d;
+    }
+  }
+  return best;
+}
+function distance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1;i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1;j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      row[j] = Math.min(row[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = row;
+  }
+  return prev[b.length];
+}
+
+// src/config/jsonc.ts
+import { parse, printParseErrorCode } from "jsonc-parser";
+
+// src/config/validate.ts
+import { z } from "zod";
+var MODES = ["headed", "headless", "screenshot"];
+var HINTS = "\x00gamecrate/hints:";
+function obj(shape) {
+  const known = Object.keys(shape);
+  return z.strictObject(shape, {
+    error: (issue) => issue.code === "unrecognized_keys" ? HINTS + JSON.stringify(issue.keys.map((key) => suggest(key, known) ?? null)) : "expected an object"
+  });
+}
+function requiredWhen(key, when) {
+  return (ctx) => {
+    if (!when(ctx.value) || ctx.value[key] !== undefined)
+      return;
+    ctx.issues.push({ code: "custom", message: `missing required key "${key}"`, path: [key], input: ctx.value });
+  };
+}
+var str = z.string({ error: "expected a string" });
+var num = z.number({ error: "expected a number" });
+var bool = z.boolean({ error: "expected a boolean" });
+var strArray = z.array(z.string({ error: "expected an array of strings" }), {
+  error: "expected an array of strings"
+});
+var strMap = z.record(z.string(), z.string({ error: "expected an object of string values" }), {
+  error: "expected an object of string values"
+});
+function oneOf(values) {
+  return z.enum(values, { error: `expected one of ${values.join(", ")}` });
+}
+var modeName = z.unknown().check((ctx) => {
+  const value = ctx.value;
+  if (typeof value === "string" && MODES.includes(value))
+    return;
+  const hint = typeof value === "string" ? suggest(value, MODES) : undefined;
+  ctx.issues.push({
+    code: "custom",
+    message: `expected one of ${MODES.join(", ")}`,
+    input: value,
+    ...hint === undefined ? {} : { params: { suggestion: `did you mean "${hint}"?` } }
+  });
+});
+var settings = obj({
+  width: num.optional(),
+  height: num.optional(),
+  devMode: bool.optional(),
+  runInBackground: bool.optional(),
+  resetModsConfigOnCrash: bool.optional(),
+  gpu: bool.optional(),
+  audio: bool.optional(),
+  input: bool.optional(),
+  network: oneOf(["none", "bridge", "host"]).optional(),
+  display: oneOf(["x11", "wayland"]).optional(),
+  memory: str.optional(),
+  cpus: num.optional(),
+  pidsLimit: num.optional(),
+  prefsExtra: strMap.optional(),
+  gameArgs: strArray.optional(),
+  dockerArgs: strArray.optional()
+});
+var dynamicModEntry = obj({
+  match: str,
+  first: strArray.optional(),
+  sort: oneOf(["alpha", "none"]).optional(),
+  minMatches: num.optional()
+});
+var objectModEntry = obj({
+  id: str,
+  workshop: num.optional(),
+  path: str.optional(),
+  optional: bool.optional()
+});
+var modEntry = z.unknown().check((ctx) => {
+  const value = ctx.value;
+  if (typeof value === "string") {
+    if (value.trim() === "")
+      ctx.issues.push({ code: "custom", message: "mod entry is empty", input: value });
+    return;
+  }
+  if (!isObj(value)) {
+    ctx.issues.push({ code: "custom", message: "expected a packageId string or an object", input: value });
+    return;
+  }
+  const schema = value["match"] !== undefined ? dynamicModEntry : objectModEntry;
+  const result = schema.safeParse(value);
+  if (result.success)
+    return;
+  for (const issue of result.error.issues)
+    ctx.issues.push({ ...issue, input: value });
+});
+var profile = obj({
+  mods: z.array(modEntry, { error: "expected an array" }).optional(),
+  extends: str.optional(),
+  exclude: strArray.optional(),
+  includeBase: bool.optional(),
+  autoDependencies: bool.optional(),
+  settings: settings.optional(),
+  instances: z.record(z.string(), obj({ worktree: str.optional(), settings: settings.optional() }), {
+    error: "expected an object"
+  }).optional(),
+  alias: str.optional(),
+  aliases: strArray.optional()
+}).check((ctx) => {
+  const v = ctx.value;
+  if (v.alias !== undefined && (v.extends !== undefined || v.mods !== undefined)) {
+    ctx.issues.push({
+      code: "custom",
+      message: 'an alias profile cannot also declare "mods" or "extends"',
+      input: v
+    });
+  }
+});
+var game = obj({
+  gameFiles: obj({ source: oneOf(["mount", "image"]), host: str.optional(), container: str }).check(requiredWhen("host", (v) => v["source"] === "mount")),
+  dataDir: obj({
+    container: str,
+    mode: oneOf(["arg", "env"]),
+    arg: str.optional(),
+    env: strMap.optional()
+  }).check(requiredWhen("arg", (v) => v["mode"] === "arg"), requiredWhen("env", (v) => v["mode"] === "env")),
+  modsDir: obj({ container: str, mask: strArray.optional() }),
+  logFile: obj({ mode: oneOf(["arg", "copy-out"]), arg: str.optional(), from: str.optional() }).check(requiredWhen("arg", (v) => v["mode"] === "arg"), requiredWhen("from", (v) => v["mode"] === "copy-out")),
+  image: obj({ ref: str, acquire: oneOf(["pull", "build"]), context: str.optional() }).check(requiredWhen("context", (v) => v["acquire"] === "build")),
+  executable: str,
+  steamAppId: num,
+  workshopRoot: z.union([z.string(), z.null()], { error: "expected a string or null" }),
+  scanRoots: z.array(obj({ path: str, maxDepth: num, exclude: strArray.optional() }), {
+    error: "expected an array"
+  }),
+  manifest: obj({ file: str }),
+  modsConfig: obj({ file: str }),
+  prefs: obj({ file: str }),
+  saveExtensions: strArray,
+  core: str,
+  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(),
+  modes: z.array(modeName, { error: "expected a non-empty array" }).min(1, {
+    error: "expected a non-empty array"
+  }),
+  aliases: strMap.optional(),
+  settings: settings.optional(),
+  ignoresWmDelete: bool.optional(),
+  profiles: z.record(z.string(), profile, { error: "expected an object" })
+});
+var root = obj({
+  plugins: strArray.optional(),
+  dataRoot: str,
+  defaults: obj({ settings: settings.optional() }).optional(),
+  games: z.unknown()
+});
+function isObj(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// src/config/load.ts
+var projectName = z2.custom((v) => typeof v === "string" && NAME_PATTERN.test(v), "expected a name");
+var projectStr = z2.string({ error: "expected a string" });
+var projectBool = z2.boolean({ error: "expected true or false" });
+var projectList = z2.custom((v) => Array.isArray(v) && v.every((entry) => typeof entry === "string"), "expected an array of strings");
+var projectSeconds = z2.custom((v) => Number.isSafeInteger(v) && v >= 0, "expected a whole number of seconds");
+function oneOf2(values) {
+  return z2.enum(values, { error: `expected one of ${values.join(", ")}` });
+}
+var BUILD_POLICIES = ["auto", "always", "never"];
+var projectResolution = z2.string({ error: "expected dimensions like 1920x1080" }).check((ctx) => {
+  try {
+    parseResolution(ctx.value);
+  } catch (error) {
+    ctx.issues.push({ code: "custom", message: error.message, input: ctx.value });
+  }
+}).transform(parseResolution);
+var PROJECT_SCHEMA = z2.strictObject({
+  game: projectName.optional(),
+  profile: projectName.optional(),
+  mods: projectList.optional(),
+  without: projectList.optional(),
+  only: projectList.optional(),
+  dockerArgs: projectList.optional(),
+  gameArgs: projectList.optional(),
+  worktree: projectList.optional(),
+  use: projectList.optional(),
+  marker: projectStr.optional(),
+  instance: projectStr.optional(),
+  log: projectStr.optional(),
+  timeout: projectSeconds.optional(),
+  renderWait: projectSeconds.optional(),
+  dryRun: projectBool.optional(),
+  printPlan: projectBool.optional(),
+  json: projectBool.optional(),
+  root: projectBool.optional(),
+  noWorktree: projectBool.optional(),
+  noStaleCheck: projectBool.optional(),
+  replace: projectBool.optional(),
+  mode: oneOf2(["headed", "headless", "screenshot"]).optional(),
+  pull: oneOf2(["always", "missing", "never"]).optional(),
+  sort: oneOf2(["topo", "none"]).optional(),
+  network: oneOf2(["none", "bridge", "host"]).optional(),
+  build: z2.union([z2.boolean().transform((on) => on ? "always" : "never"), z2.enum(BUILD_POLICIES)], {
+    error: `expected one of ${BUILD_POLICIES.join(", ")}`
+  }).optional(),
+  resolution: projectResolution.optional()
+}, { error: "expected an object" });
+
+// src/plugin.ts
+var PLUGIN_API_VERSION = 1;
+export {
+  PLUGIN_API_VERSION
+};

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

@@ -0,0 +1,40 @@
+import { Command } from 'commander';
+import type { ParsedArgs, ProjectDefaults } from '../types';
+export type PositionalSlot = 'game' | 'profile' | 'rest';
+export interface SubcommandSpec {
+    name: string;
+    summary: string;
+    /** Rendered after the subcommand word in usage lines. */
+    usage: string;
+    positionals: PositionalSlot[];
+    /** Flag names beyond the global set, in the order help should show them. */
+    flags: readonly string[];
+}
+/** The subcommand table. `modless` is reserved as a built-in profile, not a verb. */
+export declare const SUBCOMMANDS: readonly SubcommandSpec[];
+/** Shown for every subcommand. */
+export declare const GLOBAL_FLAGS: readonly ["--json", "--help"];
+/** The GAMECRATE_ vars, by the flag they stand in for. Fallbacks only; a flag always wins. */
+export declare const FLAG_ENV: Record<string, string>;
+/**
+ * Every flag, in the order help lists them. The only source of truth for what the CLI
+ * accepts: help and completion read it back off the program.
+ */
+export declare function buildProgram(): Command;
+export interface ParseOptions {
+    env?: Record<string, string | undefined>;
+    defaults?: ProjectDefaults;
+    /** Game names from the loaded config; enables did-you-mean on the first positional. */
+    games?: readonly string[];
+}
+/**
+ * `gamecrate <game> [profile] [flags] [-- game args]`, with the subcommand slot
+ * defaulting to `run`. Game args come after a bare `--` and nowhere else.
+ */
+export declare function parseArgs(argv: string[], opts?: ParseOptions): ParsedArgs;
+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;

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

@@ -0,0 +1,7 @@
+import type { RootConfig } from '../types';
+/**
+ * Three levels: no topic gives the top level, a subcommand name gives its usage,
+ * a game name gives that game's profiles and modes.
+ */
+export declare function renderHelp(topic?: string, config?: RootConfig): string;
+export declare function renderCompletion(shell: 'bash' | 'zsh'): string;

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

@@ -0,0 +1,56 @@
+import type { Readable } from 'node:stream';
+import type { LaunchPlan, Problem, ResolvedMod } from '../types';
+/** Tool status. Never stdout: stdout belongs to the game. */
+export declare function status(message: string): void;
+export declare function warn(message: string): void;
+export interface OutputRedirect {
+    close(): void;
+}
+export declare function redirectOutput(path: string): OutputRedirect;
+export declare function forwardOutput(stream: Readable, target: NodeJS.WriteStream): Promise<void>;
+/**
+ * Every collected failure at once, grouped by location. Resolution stops before any
+ * side effect, so reporting the first problem only would hide the rest.
+ */
+export declare function reportProblems(problems: Problem[]): never;
+export interface PlanModPayload {
+    packageId: string;
+    kind: ResolvedMod['kind'];
+    hostDir: string;
+    containerDir: string;
+    origin: 'explicit' | 'auto';
+    stale: boolean;
+    staleReport?: ResolvedMod['staleReport'];
+    workshopId?: number;
+}
+export interface PlanPayload {
+    game: string;
+    profile: string;
+    instance?: string;
+    mode: string;
+    marker?: string;
+    timeoutSeconds: number;
+    renderWaitSeconds: number;
+    profileDir: string;
+    instanceDir: string;
+    containerName: string;
+    dataDirHost: string;
+    stageDirHost: string;
+    logsDirHost: string;
+    mods: PlanModPayload[];
+    warnings: string[];
+}
+/**
+ * Regenerated from the mods rather than stored, because a successful `--build` clears a stale
+ * report and the warning has to disappear with it.
+ */
+export declare function planWarnings(plan: LaunchPlan): string[];
+/** The `--print-plan --json` payload. Bind mounts leave no host-readable link to assert on. */
+export declare function planPayload(plan: LaunchPlan): PlanPayload;
+export declare function printPlan(plan: LaunchPlan, asJson: boolean): void;
+/** Sortable lexicographically and safe on every filesystem: 20260730T142335123Z. */
+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;
+/** 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/config/builtin.d.ts

@@ -0,0 +1,3 @@
+import type { Settings } from '../types';
+export declare const DEFAULT_DATA_ROOT = "~/.local/share/gamecrate";
+export declare const DEFAULT_SETTINGS: Settings;

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

@@ -0,0 +1,5 @@
+/**
+ * JSON with line and block comments and trailing commas. jsonc-parser recovers from
+ * syntax errors and still returns a value, so the error list is the only success signal.
+ */
+export declare function parseJsonc(text: string): unknown;

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

@@ -0,0 +1,45 @@
+import type { GameConfig, ModEntry, ProfileConfig, ProjectDefaults, RootConfig, Settings } from '../types';
+import type { GamePlugin } from '../plugin';
+export declare function defaultConfigPath(): string;
+export declare function findProjectConfig(start?: string): Promise<string | undefined>;
+export declare function loadProjectDefaults(start?: string): Promise<ProjectDefaults>;
+export interface LoadedConfig {
+    config: RootConfig;
+    plugins: Map<string, GamePlugin>;
+}
+/**
+ * Reads profiles.json, 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>;
+/** 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;
+/**
+ * Flattens `alias` and the `extends` chain into one profile. `exclude` survives on
+ * the result so the caller can subtract it from preCore/core/dlc/base too.
+ */
+export declare function resolveProfile(game: GameConfig, name: string): ProfileConfig;
+/**
+ * The name a profile stores its data under. An alias must not get its own data directory,
+ * or your saves split depending on which spelling you typed.
+ */
+export declare function canonicalProfile(game: GameConfig, name: string): string;
+/**
+ * The one place a profile's data directory is named. Every subcommand goes through it, so
+ * `logs`, `clean` and `clone` land on the directory `run` actually used, alias or not.
+ */
+export declare function profileDataDir(root: RootConfig, game: string, profile: string): string;
+/**
+ * The directories a command should touch for one game. With no profile it lists what is on disk,
+ * 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[]>;
+/** 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;
+/**
+ * A later list replaces an earlier one, so a user can shorten a plugin's `dlc` or `modes`.
+ * `concatArrays` is the settings ladder's rule, where gameArgs accumulate across layers.
+ */
+export declare function deepMerge<T>(base: T, over: unknown, concatArrays?: boolean): T;
+export declare function expandHome(p: string): string;

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

@@ -0,0 +1,12 @@
+import type { Problem, RootConfig } from '../types';
+type Bag = Record<string, unknown>;
+/**
+ * Phase one checks shape, phase two checks cross-references. Every problem is
+ * collected with a JSON Pointer; nothing throws on the first failure.
+ */
+export declare function validateConfig(cfg: unknown): {
+    config: RootConfig;
+    problems: Problem[];
+};
+export declare function isObj(v: unknown): v is Bag;
+export {};

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

@@ -0,0 +1,6 @@
+import type { Identity } from '../types';
+/**
+ * The single source of truth for `--user`, HOME, and every tmpfs uid=/gid=.
+ * Out-of-sync values give a blank window with no error, so nothing else may guess.
+ */
+export declare function resolveIdentity(useRoot: boolean): Identity;

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

@@ -0,0 +1,3 @@
+import type { LaunchPlan, Problem } from '../types';
+/** Every check the launch depends on, collected so one run reports all of them at once. */
+export declare function preflight(plan: LaunchPlan): Promise<Problem[]>;

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

@@ -0,0 +1,37 @@
+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;
+/** 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>;
+/**
+ * Runs a short command and collects both streams. A missing binary is exit 127 with the spawn
+ * error as stderr, so every caller can report it the same way rather than throwing.
+ */
+export declare function capture(argv: string[]): Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+/** The tee'd combined stream, and what waitForMarker watches. */
+export declare const STDOUT_LOG = "stdout.log";
+export interface RunOptions {
+    /** Run log directory; created if missing. Receives stdout.log. */
+    logDir: string;
+    /** Passed to `docker stop --timeout` when a signal arrives. */
+    stopTimeoutSeconds?: number;
+}
+/**
+ * Spawns docker directly rather than through a pipeline, so the game's status is the status.
+ * `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>;
+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
+ * sends Verse.Log output to -logfile, never to stdout, so a stdout-only watch can never
+ * match a RimWorld mod's message.
+ */
+export declare function waitForMarker(sources: string[], marker: string, timeoutSeconds: number): Promise<boolean>;

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

@@ -0,0 +1,24 @@
+import type { DockerRunSpec, Identity, LaunchPlan, Mount } from '../types';
+/** Container-side XDG_RUNTIME_DIR. A sized tmpfs; display and audio sockets land inside it. */
+export declare const CONTAINER_RUNTIME_DIR = "/tmp/xdg";
+/** Where the run directory is bound, so `-logfile /logs/Player.log` lands beside stdout.log. */
+export declare const CONTAINER_LOG_DIR = "/logs";
+export declare function buildRunSpec(plan: LaunchPlan, modMounts: Mount[], identity: Identity): DockerRunSpec;
+/** Instances of one profile run side by side, so the name has to carry which one this is. */
+export declare function containerName(plan: LaunchPlan): string;
+/** What the window is renamed to, so a taskbar full of worktrees is readable. */
+export declare function windowTitle(plan: LaunchPlan): string;
+export declare function toDockerArgs(spec: DockerRunSpec): string[];
+/**
+ * The host X session a headed run joins. The cookie is looked up separately from the socket
+ * because XWayland under a display manager keeps it in XDG_RUNTIME_DIR, not ~/.Xauthority.
+ * Whether the socket directory is really there is checkBindSources' job, as with every bind.
+ */
+export declare function x11Session(): {
+    display: string;
+    xauthority: string | null;
+} | null;
+export declare function waylandSocket(): {
+    source: string;
+    name: string;
+} | null;

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

@@ -0,0 +1,21 @@
+export interface WindowWatch {
+    stop: () => void;
+}
+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.
+ */
+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,44 @@
+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>;
+}
+export declare function takeLock(plan: LaunchPlan): Promise<ProfileLock>;
+/**
+ * `--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.
+ */
+export declare function replacePrevious(plan: LaunchPlan): Promise<void>;
+/**
+ * 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[];
+}>;