@gamecrate/cli 0.1.0 → 1.1.0

package/dist/lib.js

@@ -0,0 +1,320 @@
+// src/plugin.ts
+import { exports as exportsField, legacy } from "resolve.exports";
+
+// src/config/load.ts
+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/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";
+
+// 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(),
+  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)) {
+    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_OBJECT = z2.strictObject({
+  game: projectName.optional(),
+  defaultProfile: projectName.optional(),
+  profiles: z2.record(z2.string(), z2.unknown()).optional(),
+  settings: z2.record(z2.string(), z2.unknown()).optional(),
+  detach: projectBool.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" });
+var PROJECT_SCHEMA = PROJECT_OBJECT.check((ctx) => {
+  const { game, profiles, settings } = ctx.value;
+  if (game !== undefined)
+    return;
+  for (const [key, value] of [["profiles", profiles], ["settings", settings]]) {
+    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;
+export {
+  PLUGIN_API_VERSION
+};

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

@@ -0,0 +1,56 @@
+import { Command } from 'commander';
+import type { BuildPolicy, ParsedArgs, ProfileConfig, 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;
+/**
+ * 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/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/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/output.d.ts

@@ -0,0 +1,78 @@
+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, 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
+ * 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;
+/** 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/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,47 @@
+import type { GameConfig, ModEntry, ProfileConfig, ProjectDefaults, RootConfig, Settings } from '../types';
+import type { GamePlugin } from '../plugin';
+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 {
+    config: RootConfig;
+    plugins: Map<string, GamePlugin>;
+}
+/**
+ * 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, 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;
+/**
+ * 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[]>;
+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;
+/**
+ * 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/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/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,39 @@
+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, 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>;
+/**
+ * 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>;
+/** 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
+ * 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;