@gamecrate/cli 1.4.0 → 2.0.0

package/dist/lib.js

@@ -33,6 +33,7 @@ class GamecrateError extends Error {
 var NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
 // src/cli/args.ts
+var ACTIVE = new WeakMap;
 function parseResolution(value) {
   const match = /^(\d+)x(\d+)$/i.exec(value);
   const width = Number(match?.[1]);
@@ -181,6 +182,8 @@ var profile = obj({
   alias: str.optional(),
   aliases: strArray.optional(),
   description: str.optional(),
+  gameVersion: str.optional(),
+  image: str.optional(),
   detach: bool.optional(),
   replace: bool.optional(),
   build: oneOf(["auto", "always", "never"]).optional()
@@ -225,6 +228,95 @@ var libraryEntry = obj({
     push('"subdir" must be a relative path inside the repo, with no ".." segment', ["subdir"]);
   }
 });
+function repeats(entries, key) {
+  const seen = new Set;
+  const found = [];
+  entries.forEach((entry, index) => {
+    const name = entry?.[key];
+    if (typeof name !== "string")
+      return;
+    if (seen.has(name))
+      found.push({ index, name });
+    else
+      seen.add(name);
+  });
+  return found;
+}
+var TAG_COMPONENT = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+function steamBuildRules(ctx) {
+  const push = (message, path, suggestion) => {
+    ctx.issues.push({
+      code: "custom",
+      message,
+      path,
+      input: ctx.value,
+      ...suggestion === undefined ? {} : { params: { suggestion } }
+    });
+  };
+  const branches = ctx.value["branches"];
+  const variants = ctx.value["variants"];
+  if (Array.isArray(variants) && variants.length === 0) {
+    push("steamBuild.variants cannot be empty", ["variants"]);
+  }
+  if (Array.isArray(branches)) {
+    if (branches.length === 0)
+      push("steamBuild.branches cannot be empty", ["branches"]);
+    for (const dup of repeats(branches, "name")) {
+      push(`duplicate branch name "${dup.name}"`, ["branches", dup.index, "name"]);
+    }
+    branches.forEach((branch, index) => {
+      const name = branch?.["name"];
+      if (typeof name === "string" && !TAG_COMPONENT.test(name)) {
+        push(`branch name "${name}" must match ${TAG_COMPONENT.source}`, ["branches", index, "name"]);
+      }
+      const tags = branch?.["tags"];
+      if (!Array.isArray(tags))
+        return;
+      tags.forEach((tag, at) => {
+        if (typeof tag !== "string" || TAG_COMPONENT.test(tag))
+          return;
+        push(`branch tag "${String(tag)}" must match ${TAG_COMPONENT.source}`, ["branches", index, "tags", at]);
+      });
+    });
+  }
+  if (!Array.isArray(variants))
+    return;
+  for (const dup of repeats(variants, "name")) {
+    push(`duplicate variant name "${dup.name}"`, ["variants", dup.index, "name"]);
+  }
+  variants.forEach((variant, index) => {
+    const v = variant;
+    const base = v?.["base"];
+    if (base !== "xvfb" && base !== "proton")
+      return;
+    const depot = v?.["depot"] ?? "linux";
+    if (depot === "macos") {
+      push("a macos depot cannot be runnable", ["variants", index, "base"], 'set base to "none"; no macos container runtime exists');
+      return;
+    }
+    const wants = depot === "windows" ? "proton" : "xvfb";
+    if (base === wants)
+      return;
+    push(`a ${String(depot)} depot cannot run on the "${base}" base`, ["variants", index, "base"], depot === "windows" ? 'set base to "proton"; it is the only base with wine' : 'set base to "xvfb", or set depot to "windows" if the image should run under wine');
+  });
+}
+var steamBuildSchema = obj({
+  branches: z.array(obj({
+    name: str,
+    password: bool.optional(),
+    tags: strArray.optional(),
+    executable: z.record(str, str).optional()
+  }), {
+    error: "expected an array"
+  }),
+  variants: z.array(obj({
+    name: str,
+    depot: oneOf(["linux", "windows", "macos"]).optional(),
+    base: oneOf(["xvfb", "proton", "none"]),
+    include: strArray,
+    executable: str.optional()
+  }), { error: "expected an array" })
+}).check(steamBuildRules);
 var game = obj({
   gameFiles: obj({ source: oneOf(["mount", "image"]), host: str.optional(), container: str }).check(requiredWhen("host", (v) => v["source"] === "mount")),
   dataDir: obj({
@@ -235,7 +327,12 @@ var game = obj({
   }).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")),
+  image: obj({
+    ref: str,
+    acquire: oneOf(["pull", "build"]),
+    context: str.optional(),
+    updates: obj({ check: bool.optional(), everyHours: num.optional() }).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" }),
@@ -245,6 +342,8 @@ var game = obj({
   manifest: obj({ file: str }),
   modsConfig: obj({ file: str }),
   prefs: obj({ file: str }),
+  version: obj({ file: str }),
+  steamBuild: steamBuildSchema,
   saveExtensions: strArray,
   core: str,
   dlc: strArray,
@@ -343,7 +442,7 @@ var PROJECT_SCHEMA = PROJECT_OBJECT.check((ctx) => {
 });
 
 // src/plugin.ts
-var PLUGIN_API_VERSION = 1;
+var PLUGIN_API_VERSION = 2;
 export {
   PLUGIN_API_VERSION
 };

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

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import type { BuildPolicy, ParsedArgs, ProfileConfig, ProjectDefaults } from '../types';
 export type PositionalSlot = 'game' | 'profile' | 'rest';
 export interface SubcommandSpec {
@@ -19,10 +19,13 @@ 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.
+ * A root that carries the run flags, because a bare game name means run, plus one command per
+ * verb carrying only its own. enablePositionalOptions is what makes that a fence: without it
+ * commander hands a flag typed after a verb back to the root and accepts it.
  */
 export declare function buildProgram(): Command;
+/** Every command's options, for the checks that have to see the whole vocabulary. */
+export declare function allOptions(program: Command): Option[];
 export interface ParseOptions {
     env?: Record<string, string | undefined>;
     defaults?: ProjectDefaults;

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

@@ -20,7 +20,7 @@ export interface PlanModPayload {
     containerDir: string;
     origin: 'explicit' | 'auto';
     stale: boolean;
-    staleReport?: ResolvedMod['staleReport'];
+    staleReport?: NonNullable<ResolvedMod['staleReport']>;
     workshopId?: number;
 }
 export interface PlanPayload {

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

@@ -1,6 +1,11 @@
-import type { ParsedArgs, ProjectDefaults } from '../types';
+import type { GameConfig, 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;
+/**
+ * The launch path, where a silent fallback to modless drops every mod the game needs. With no
+ * profile configured there is nothing to be ambiguous about, so modless still answers.
+ */
+export declare function launchProfile(args: ParsedArgs, defaults: ProjectDefaults, game: GameConfig): string;

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

@@ -0,0 +1,27 @@
+import type { GamePlugin } from '../plugin';
+import type { ParsedArgs, RootConfig } from '../types';
+export interface SteamContext {
+    config: RootConfig;
+    plugins: Map<string, GamePlugin>;
+    /** Where a bare plugin specifier resolves from. Injectable so tests need no chdir. */
+    cwd: string;
+    /** The file loadConfig read, so config.plugins resolves here the way it does there. */
+    configFile?: string;
+}
+/**
+ * Every layout a steamcmd writes config.vdf into, measured 2026-09-23: the arch wrapper writes
+ * .steam/config, the docker image writes .local/share/Steam/config, a valve tarball writes Steam/config.
+ */
+export declare function sessionPaths(home: string): string[];
+export declare function findSession(home: string): string | undefined;
+/**
+ * STEAM_CONFIG_VDF, then the file `steam login` wrote, then a hand-primed session in the user's
+ * own home. An expired session reports as a missing one: from out here the two files look identical.
+ */
+export declare function resolveSession(config: RootConfig, env?: Record<string, string | undefined>): string;
+export declare function steamBuildCommand(args: ParsedArgs, ctx: SteamContext): Promise<number>;
+/**
+ * The one interactive path in gamecrate: steamcmd gets the TTY so it can ask for the password and
+ * the 2FA code itself. Neither ever passes through an argv we build.
+ */
+export declare function steamLogin(args: ParsedArgs, ctx: SteamContext): Promise<number>;

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

@@ -39,6 +39,11 @@ export declare function profileKey(game: GameConfig, name: string): string | und
 /** 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;
+/**
+ * deepMerge, then the one array that concatenates. `branches[0]` gets the bare tag, so a
+ * replacing override would move it silently and drop the plugin's other branches.
+ */
+export declare function mergeUserConfig(base: RootConfig, user: unknown): RootConfig;
 /**
  * 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.

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

@@ -1,5 +1,28 @@
+import { z } from 'zod';
 import type { Problem, RootConfig } from '../types';
 type Bag = Record<string, unknown>;
+/** Exported so a config-less `steam build` gets the same refusals a config file would. */
+export declare const steamBuildSchema: z.ZodObject<{
+    branches: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        password: z.ZodOptional<z.ZodBoolean>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        executable: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+    variants: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        depot: z.ZodOptional<z.ZodEnum<{
+            linux: "linux";
+            windows: "windows";
+            macos: "macos";
+        }>>;
+        base: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        include: z.ZodArray<z.ZodString>;
+        executable: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 /**
  * Phase one checks shape, phase two checks cross-references. Every problem is
  * collected with a JSON Pointer; nothing throws on the first failure.

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

@@ -1,3 +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[]>;
+export declare function preflight(plan: LaunchPlan, asShell?: boolean): Promise<Problem[]>;

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

@@ -15,6 +15,14 @@ export declare function capture(argv: string[]): Promise<{
     stdout: string;
     stderr: string;
 }>;
+/**
+ * Streams a child's output while keeping it, for a caller that parses it too. Both streams as
+ * one string because the parse reads them as one, and to stderr because --json owns stdout.
+ */
+export declare function captureLive(argv: string[], env?: NodeJS.ProcessEnv): Promise<{
+    code: number;
+    text: string;
+}>;
 /** The tee'd combined stream, and what waitForMarker watches. */
 export declare const STDOUT_LOG = "stdout.log";
 export interface RunOptions {

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

@@ -1,9 +1,19 @@
-import type { DockerRunSpec, Identity, LaunchPlan, Mount } from '../types';
+import type { DockerRunSpec, Identity, LaunchPlan, ModeName, 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;
+/** What the image says about starting itself. Absent means fall back to config. */
+export interface ImageLaunch {
+    launcher?: 'direct' | 'proton';
+    executable?: string;
+}
+/**
+ * Explorer detaches under wine, so a proton image has no headed path at all. run() calls this
+ * before the marker gate, so the mode is the first thing a person reads.
+ */
+export declare function refuseProtonHeaded(game: string, mode: ModeName, image?: ImageLaunch): void;
+export declare function buildRunSpec(plan: LaunchPlan, modMounts: Mount[], identity: Identity, image?: ImageLaunch): 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. */

package/dist/types/image/base.d.ts

@@ -0,0 +1,11 @@
+export type BaseKind = 'xvfb' | 'proton' | 'none';
+/**
+ * Pinned by digest, never by tag: a rebuilt base would otherwise change under released code.
+ * These are the linux/amd64 manifests, not the index a push reports. See landmines.md.
+ */
+export declare const RUNTIME_BASE: Readonly<Record<'xvfb' | 'proton', string>>;
+/**
+ * The ref a variant's layer gets appended onto. null for 'none': a reference image
+ * appends onto scratch and never runs, so `--base` does not make one runnable.
+ */
+export declare function resolveBase(kind: BaseKind, override?: string): string | null;

package/dist/types/image/build.d.ts

@@ -0,0 +1,26 @@
+import type { RootConfig } from '../types';
+import type { SteamBuildInput } from './input';
+export interface CellResult {
+    branch: string;
+    variant: string;
+    status: 'built' | 'skipped' | 'failed';
+    reason: string;
+    tags: string[];
+}
+export interface SteamBuildOptions {
+    config: RootConfig;
+    push: boolean;
+    load: boolean;
+    platform: string;
+    baseOverride?: string;
+    force: boolean;
+    /** --beta, repeatable. Undefined or empty means every declared branch. */
+    onlyBranches?: string[];
+    /** --variant, repeatable. Undefined or empty means every declared variant. */
+    onlyVariants?: string[];
+}
+/**
+ * One row per cell attempted, in branch order then variant order. A cell failure is a row and
+ * never a throw, because a throw would lose the rows for the cells that worked.
+ */
+export declare function steamBuild(input: SteamBuildInput, opts: SteamBuildOptions): Promise<CellResult[]>;

package/dist/types/image/crane.d.ts

@@ -0,0 +1,27 @@
+/** The debug tag, because the default one has no shell and the tar step needs one. */
+export declare const CRANE_IMAGE = "gcr.io/go-containerregistry/crane:debug";
+/**
+ * Runs before the first download. Only a helper covering the push target is a problem: its binary
+ * is not in the crane container, so the push would go out anonymous for no visible reason.
+ */
+export declare function checkRegistryAuthEarly(ref: string): void;
+export declare function craneAppend(opts: {
+    gameDir: string;
+    /** Subpaths to include. Empty means the whole game. */
+    include: string[];
+    /** Where the game goes inside the image, e.g. /game. */
+    gamePath: string;
+    /** null appends onto an empty base, which is what a reference image wants. */
+    base: string | null;
+    platform: string;
+    /** The name the tar carries. crane refuses an append without one, and docker load reads it. */
+    tag: string;
+    out: string;
+}): Promise<void>;
+/** The one call that retries. A 502 from a registry should not cost a two gigabyte download. */
+export declare function cranePush(tar: string, ref: string): Promise<void>;
+/** Runs after the push, never before. A moving tag only moves once the real tag is there. */
+export declare function craneTag(ref: string, tag: string): Promise<void>;
+export declare function craneMutateLabels(ref: string, labels: Record<string, string>): Promise<void>;
+/** null when the image or its config cannot be read. An empty record means no labels. */
+export declare function craneLabels(ref: string): Promise<Record<string, string> | null>;

package/dist/types/image/gate.d.ts

@@ -0,0 +1,18 @@
+export interface GateInput {
+    /** What steam says the branch is at. null when steamcmd reported none for this branch. */
+    published: string | null;
+    /** False when no image exists yet. */
+    imagePresent: boolean;
+    /** The steam.buildid label, null when absent. Ignored when imagePresent is false. */
+    labelled: string | null;
+    force: boolean;
+}
+export interface GateDecision {
+    build: boolean;
+    reason: 'forced' | 'no-image' | 'no-label' | 'buildid-changed' | 'up-to-date' | 'unknown-published';
+}
+/**
+ * A skip needs proof, so everything short of two matching buildids builds.
+ * Callers pass `imagePresent: labels !== null`, `labelled: labels?.['steam.buildid'] ?? null`.
+ */
+export declare function decideGate(input: GateInput): GateDecision;

package/dist/types/image/input.d.ts

@@ -0,0 +1,40 @@
+import type { RootConfig, SteamBranch, SteamVariant } from '../types';
+export interface SteamBuildInput {
+    game: string;
+    steamAppId: number;
+    versionFile: string;
+    gamePath: string;
+    executable: string;
+    branches: SteamBranch[];
+    variants: SteamVariant[];
+    /** Target repo, never a tag. p3-t1 supplies the tags. */
+    image: string;
+}
+export interface SteamBuildOverrides {
+    /** --image, a repo with no tag. */
+    image?: string;
+    /** --plugin, repeatable. Skips the @gamecrate/<game> convention. */
+    plugins?: string[];
+    /** --push. Only a push makes --image mandatory. */
+    push?: boolean;
+}
+/** "1.5-test" -> "STEAM_BRANCH_PASSWORD_1_5_TEST" */
+export declare function branchPasswordKey(branch: string): string;
+/**
+ * The keyed variable names its branch, so it answers whatever the config says. The bare one hits
+ * every branch in a build, so it stays behind `password: true`.
+ */
+export declare function branchPassword(branch: SteamBranch): string | undefined;
+/**
+ * `configured` is --image if given, else the config's ref. --load gets a default because a local
+ * build has no registry to name; --push refuses, because a guessed path pushes to the wrong account.
+ */
+export declare function resolveImage(flags: {
+    load: boolean;
+    push: boolean;
+}, game: string, configured: string | undefined): string;
+/**
+ * Plugin defaults, then games.<game> when a config exists, then the flags. The same
+ * one-direction merge the loader already does, over fewer fields.
+ */
+export declare function resolveSteamBuildInput(game: string, config: RootConfig | null, overrides: SteamBuildOverrides, cwd: string, configFile?: string): Promise<SteamBuildInput>;

package/dist/types/image/tags.d.ts

@@ -0,0 +1,23 @@
+export interface TagInput {
+    version: string;
+    branch: string;
+    variant: string;
+    /** True when this branch is the first entry of steamBuild.branches. */
+    defaultBranch: boolean;
+    /** True when this variant is the first entry of steamBuild.variants. */
+    defaultVariant: boolean;
+    /** Branch aliases, so a moving "2.0" can point at whatever beta is today. */
+    aliases?: string[];
+}
+/**
+ * An OCI tag takes no space, so the first whitespace-delimited field is the version and the
+ * rest of the line is dropped. "1.6.4871 rev598" becomes "1.6.4871".
+ */
+export declare function sanitizeVersion(raw: string, fallback: string): string;
+/**
+ * The moving prefixes of a dotted version: 1.6.4871 gives 1 and 1.6, never the whole thing.
+ * A prefix follows the newest build that carries it, the way `latest` does.
+ */
+export declare function versionPrefixes(version: string): string[];
+/** Every tag this cell writes. Versioned forms first, latest forms after. */
+export declare function tagsFor(input: TagInput): string[];

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

@@ -0,0 +1,45 @@
+import type { ImageLaunch } from '../docker/spec';
+import type { ModeName, Problem } from '../types';
+import type { GameConfig } from '../types';
+/** What an image says about itself. Every field is null for an image gamecrate did not build. */
+export interface ImageFacts {
+    present: boolean;
+    /** gamecrate.runtime: the base digest a steam build appended onto. */
+    runtime: string | null;
+    launcher: string | null;
+    executable: string | null;
+    /** The cell that produced this image, and the steam build it carries. */
+    branch: string | null;
+    variant: string | null;
+    buildid: string | null;
+}
+export declare function readImageFacts(ref: string): Promise<ImageFacts>;
+/** The labels buildRunSpec reads. An unknown launcher is dropped, not passed through. */
+export declare function imageLaunch(facts: ImageFacts): ImageLaunch;
+export declare function imageProblem(input: {
+    game: string;
+    ref: string;
+    mode: ModeName;
+    facts: ImageFacts;
+}): Problem | null;
+/**
+ * Explorer detaches under wine, so the game's exit code never reaches gamecrate. A marker is the
+ * only success signal a proton variant has, and without one a crash reads like a clean run.
+ */
+export declare function markerProblem(input: {
+    game: string;
+    facts: ImageFacts;
+    marker: string | undefined;
+}): Problem | null;
+/**
+ * The flag wins, then the profile's own ref, then its version tag on the game's repository.
+ * A profile that names neither leaves the configured ref alone.
+ */
+export declare function imageFor(game: GameConfig, profile: string, flag?: string): string | undefined;
+/** The ref without its tag. A colon after the last slash is a tag; before it, a registry port. */
+export declare function repoOf(ref: string): string;
+/**
+ * `--image <ref>` launches one gamecrate-built image. The game lives inside such an image, so
+ * the host mount goes with it: a bind over /game would shadow what the image carries.
+ */
+export declare function withImageOverride(game: GameConfig, ref?: string): GameConfig;

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

@@ -1,21 +1,15 @@
 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>;
+/** One file out of an image, for a fact the host copy would answer wrongly. */
+export declare function readFromImage(ref: string, path: string): Promise<string | null>;
+/** One label off an image, or null when the image or the label is missing. */
+export declare function imageLabel(ref: string, label: 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

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

@@ -0,0 +1,35 @@
+import type { ImageFacts } from './image';
+import type { ParsedArgs, RootConfig } from '../types';
+import type { UpdateCheckSpec } from '../types';
+export interface CheckInput {
+    facts: ImageFacts;
+    spec: UpdateCheckSpec | undefined;
+    /** null when this image has never been checked. */
+    lastCheckedAt: number | null;
+    now: number;
+}
+export type SkipReason = 'disabled' | 'not-ours' | 'throttled';
+/**
+ * An update check spends four seconds and needs a steam session, so it runs only for an image
+ * gamecrate built, only when asked, and only once per window.
+ */
+export declare function shouldCheck(input: CheckInput): {
+    check: boolean;
+    reason?: SkipReason;
+};
+export declare function lastCheckedAt(imageId: string): number | null;
+export declare function recordCheck(imageId: string, now: number): void;
+/**
+ * The throttled staleness check a launch runs. Rebuilds the one cell this image came from,
+ * after asking, because a rebuild is a multi-gigabyte download nobody asked for by typing a
+ * game name.
+ */
+export declare function offerRebuild(input: {
+    game: string;
+    config: RootConfig;
+    args: ParsedArgs;
+    facts: ImageFacts;
+    cwd: string;
+    configFile?: string;
+    ask: (question: string) => Promise<boolean>;
+}): Promise<void>;

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

@@ -15,6 +15,13 @@ export type SteamcmdRunner = {
 };
 /** HOME for steamcmd. Everything it writes hangs off here, so it is per-dataRoot, not the user's. */
 export declare function steamHome(dataRoot: string): string;
+/** Where `steam login` records the account it signed in with, so a build needs no variable. */
+export declare function accountFile(dataRoot: string): string;
+/**
+ * One answer to "who is logging in": STEAM_USERNAME for CI, else the name `steam login` wrote.
+ * Neither is an error rather than a null, because a null reads downstream as "steam said nothing".
+ */
+export declare function steamAccount(dataRoot: string): string;
 /**
  * Where downloads land. `run` pins it with `+force_install_dir`, so this is our layout rather
  * than whichever one the steamcmd on this machine would have picked: measured 2026-09-21, the
@@ -59,3 +66,30 @@ export interface DownloadReport {
  * unavailable item pays the 3.4s connect for every pass that will never succeed.
  */
 export declare function downloadItems(config: RootConfig, game: GameConfig, dataRoot: string, ids: string[]): Promise<DownloadReport>;
+/**
+ * Per branch and per depot, not per variant: `linux` and `linux-ref` come out of one +app_update.
+ * A shared directory means the second +app_update rewrites the first one's files.
+ */
+export declare function appDownloadRoot(dataRoot: string, appId: number, branch: string, depot?: string): string;
+export interface AppDownload {
+    dir: string;
+    warnings: string[];
+}
+/**
+ * A wrong -betapassword and a branch that does not exist look identical from outside: steam
+ * reports both as the branch being unavailable, so the error names both.
+ */
+export declare function downloadApp(config: RootConfig, opts: {
+    steamAppId: number;
+    branch: string;
+    depot?: 'linux' | 'windows' | 'macos';
+    password?: string;
+    dataRoot: string;
+}): Promise<AppDownload>;
+/** null when steam reports no buildid for that branch. A missing account throws, it is not a null. */
+export declare function publishedBuildId(config: RootConfig, appId: number, branch: string): Promise<string | null>;
+/**
+ * The buildid sits at depots -> branches -> <branch> -> buildid, and the branch name shows up
+ * elsewhere too, so anchor on "branches", then the branch key, then its first "buildid".
+ */
+export declare function buildIdFor(output: string, branch: string): string | null;

package/dist/types/plugin.d.ts

@@ -1,6 +1,6 @@
 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 declare const PLUGIN_API_VERSION = 2;
 export interface ModsConfigInput {
     version: string;
     buildNumber: number;