@gamecrate/cli 1.2.0 → 1.4.0

package/dist/lib.js

@@ -263,6 +263,7 @@ var root = obj({
   plugins: strArray.optional(),
   dataRoot: str,
   defaults: obj({ settings: settings.optional() }).optional(),
+  steamcmd: obj({ path: str.optional() }).optional(),
   games: z.unknown()
 });
 function isObj(v) {

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

@@ -8,6 +8,8 @@ export interface ModsContext {
     cwd: string;
     /** The resolved global config path, or where to create one. Injectable for the same reason. */
     globalPath: string;
+    /** What `checkDrift` asks steam with. Injectable so tests never reach the network. */
+    fetch?: typeof fetch;
 }
 /** The same fallback loadConfig uses, so an error names the file `config edit` would open. */
 export declare function globalConfigPath(): Promise<string>;

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

@@ -1,5 +1,5 @@
 import type { GamePlugin } from '../plugin';
-import type { GameConfig, LaunchPlan, ModIndex, ParsedArgs, Problem, RootConfig } from '../types';
+import type { LaunchPlan, ModIndex, ParsedArgs, Problem, RootConfig } from '../types';
 export interface ResolveOptions {
     game: string;
     profile: string;
@@ -12,12 +12,10 @@ export interface ResolveOptions {
     cwd?: string;
     /** Lowercased packageId to the clone directory prepared for its git pin. */
     sources?: ReadonlyMap<string, string>;
+    /** Workshop ids a real launch would fetch, which this command did not. */
+    unfetched?: string[];
 }
-/**
- * doctor resolves the modless profile, so no mod ref is ever resolved there. Read the config
- * instead: library pins, plus every profile's mods in both the object and bare-string forms.
- */
-export declare function workshopRootProblem(gameName: string, game: GameConfig): Problem | null;
+export declare function notFetched(id: string): string;
 export declare function resolvePlan(options: ResolveOptions): Promise<{
     plan: LaunchPlan;
     problems: Problem[];

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

@@ -0,0 +1,19 @@
+/**
+ * Valve's KeyValues text format, as Steam writes it to `appworkshop_<appid>.acf`. Steam owns
+ * that file, so every failure here degrades to an empty result instead of throwing.
+ */
+export type AcfNode = {
+    [key: string]: string | AcfNode;
+};
+type Installed = {
+    manifest: string;
+    timeupdated: number;
+};
+/** Parses KeyValues text. A malformed file is an empty object, never a throw. */
+export declare function parseAcf(text: string): AcfNode;
+/**
+ * The installed workshop items, keyed by item id. Manifest ids stay strings: they run past
+ * Number.MAX_SAFE_INTEGER and parsing one as a number corrupts it silently.
+ */
+export declare function installedItems(text: string): Map<string, Installed>;
+export {};

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

@@ -5,6 +5,11 @@ import type { GameConfig, ModIndex, ModRecord, Problem, WorktreeRequest } from '
  * routinely named `[KV] Mod Manager`, so brackets and braces must not be glob syntax.
  */
 export declare function globMatch(pattern: string, path: string): boolean;
+/**
+ * Content hash across every download root, mtime for `game.workshopRoot`. The steam client owns
+ * that one and leaves it alone when idle, and an unreadable acf there still means no caching.
+ */
+export declare function workshopStamp(game: GameConfig, dataRoot: string | undefined): string | null;
 /**
  * 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
@@ -19,10 +24,10 @@ export declare function applyWorktreeRequests(index: ModIndex, requests: Worktre
 export declare function applySourceOverrides(index: ModIndex, overrides: string[], config: GameConfig): Promise<Problem[]>;
 /**
  * Scans the game install, then every scan root in declaration order, then the source cache,
- * then the workshop root. Local roots rescan every launch; only the workshop scan is cached,
- * against the acf stamp.
+ * then the workshop roots. Local roots rescan every launch; only the workshop scan is cached,
+ * against the acf stamps. Without `dataRoot` there is no download root to scan.
  */
-export declare function buildIndex(game: string, config: GameConfig, plugin: GamePlugin, sourcesDir?: string): Promise<ModIndex>;
+export declare function buildIndex(game: string, config: GameConfig, plugin: GamePlugin, sourcesDir?: string, dataRoot?: string): Promise<ModIndex>;
 /**
  * `path:` and `workshop:` are explicit; a bare string resolves as exact packageId, then the
  * game's alias map, then a CLI-only short name. Ambiguity that the ladder cannot break is fatal.

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

@@ -1,4 +1,4 @@
-import type { GameConfig, LibraryEntry, ParsedArgs } from '../types';
+import type { GameConfig, LibraryEntry, ModEntry, ParsedArgs, ProfileConfig } from '../types';
 export type GitRef = {
     kind: 'branch' | 'tag' | 'commit';
     value: string;
@@ -29,7 +29,7 @@ export declare function gitRefOf(pin: {
 }): GitRef | undefined;
 export declare function defaultBranch(url: string): GitRef;
 export declare function ensureClone(dataRoot: string, pin: GitPin, ref: GitRef, mode: SyncMode): Promise<SyncResult>;
-export declare function lockClone(dir: string): Promise<() => Promise<void>>;
+export declare function lockDir(dir: string): Promise<() => Promise<void>>;
 export declare function unlinkOrphan(path: string, seen: string): Promise<boolean>;
 export interface PreparedSources {
     /** lowercased packageId -> clone directory. Handed to resolvePlan as `sources`. */
@@ -40,6 +40,11 @@ export interface PreparedSources {
     /** Released by execute(), and by run()'s finally. Never before buildLocalMods. */
     release: () => Promise<void>;
 }
+/**
+ * Every entry a launch of this profile reaches, in collectSlots order, minus what `exclude` and
+ * `--without` drop by id. A `match:` glob has no id to drop by, so it survives to the index.
+ */
+export declare function reachedEntries(game: GameConfig, profile: ProfileConfig, args: Partial<ParsedArgs>): ModEntry[];
 /**
  * The map `prepareSources` builds, read off the cache alone: no lock, no clone, no network.
  * `mods` and `verify` must not fetch, but with no map at all a git pin's `subdir` is dropped and

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

@@ -0,0 +1,61 @@
+import type { GameConfig, RootConfig } from '../types';
+export declare const STEAMCMD_IMAGE = "steamcmd/steamcmd";
+/**
+ * `host` spawns argv directly with env; `docker` already carries the bind and the user mapping.
+ * Either way a caller appends steamcmd's own flags to argv.
+ */
+export type SteamcmdRunner = {
+    kind: 'host';
+    argv: string[];
+    env: Record<string, string>;
+} | {
+    kind: 'docker';
+    argv: string[];
+    env: Record<string, string>;
+};
+/** 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 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
+ * arch wrapper writes .steam/SteamApps, the docker image writes .local/share/Steam/steamapps,
+ * and a plain Valve tarball writes $HOME/Steam. Pinning makes all three land here.
+ */
+export declare function downloadRoot(dataRoot: string, game: GameConfig): string;
+/**
+ * Drops a game's downloaded items and the .acf beside them. Never the steamcmd install above
+ * those: that is 200MB of bootstrap which would re-download for nothing. Returns what it did.
+ */
+export declare function removeDownloads(root: string, steamAppId: number): Promise<string>;
+/**
+ * Configured path if set, else PATH, else the docker image. A configured path that is not an
+ * executable file is an error, not a fallback. Docker gets `--user`: without it the tree
+ * comes back root-owned and the next run with a host binary cannot write it. The bind is an
+ * identity bind so the paths steamcmd prints are valid on the host too.
+ */
+export declare function resolveSteamcmd(config: RootConfig): SteamcmdRunner;
+/** The published file id out of a workshop url, or undefined if it is not one. */
+export declare function workshopUrlId(url: string | undefined): string | undefined;
+export type DownloadOutcome = {
+    ok: true;
+    dir: string;
+    bytes: number;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface DownloadReport {
+    items: Map<string, DownloadOutcome>;
+    warnings: string[];
+}
+/**
+ * Downloads every id in one steamcmd invocation. Connect is 3.4s of a 3.5s single-item run, so a
+ * hundred ids cost about what one does plus the transfer.
+ *
+ * A failed item is a warning, not a throw: whatever is already on disk stays usable.
+ *
+ * An anonymous download can fail transiently and succeed untouched on a second pass, so the
+ * misses get one re-run before they count as failures. Two passes, not more: a genuinely
+ * 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>;

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

@@ -0,0 +1,15 @@
+import type { GamePlugin } from '../plugin';
+import type { GameConfig, ParsedArgs, Problem, RootConfig } from '../types';
+export interface PreparedWorkshop {
+    /** Every id this walk inspected: the profile's own, plus the dependencies it reached. */
+    ids: Set<string>;
+    warnings: string[];
+    problems: Problem[];
+    /** Inspected ids with no directory under any mounted root when the walk finished. */
+    unfetched: string[];
+}
+/**
+ * Downloads every workshop item the profile names and every workshop dependency of those,
+ * recursively, before the mod index is built. Never throws for a download that failed.
+ */
+export declare function prepareWorkshop(game: GameConfig, profileName: string, args: ParsedArgs, config: RootConfig, allowFetch: boolean, plugin: GamePlugin, sources: ReadonlyMap<string, string>): Promise<PreparedWorkshop>;

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

@@ -0,0 +1,13 @@
+export interface DriftReport {
+    /** Ids that need steamcmd, because they drifted, are absent from the .acf, or are not on disk. */
+    needed: string[];
+    /** Ids steam will not serve: removed, private or hidden. Not the same as up to date. */
+    unavailable: string[];
+    warnings: string[];
+}
+/**
+ * Which of these items changed, without spawning anything. `roots` is every workshop content
+ * root, what `downloadRoots` returns, and none of them has to exist. The whole check is best
+ * effort: any failure downgrades to the items that are not on disk, never to fetching everything.
+ */
+export declare function checkDrift(ids: string[], roots: string[], fetchImpl?: typeof fetch): Promise<DriftReport>;

package/dist/types/types.d.ts

@@ -145,6 +145,7 @@ export interface ProfileConfig {
     extends?: string;
     exclude?: string[];
     includeBase?: boolean;
+    /** Default true. False keeps the mod list literal, dependencies and all. */
     autoDependencies?: boolean;
     settings?: Partial<Settings>;
     instances?: Record<string, InstanceConfig>;
@@ -199,6 +200,10 @@ export interface RootConfig {
     defaults?: {
         settings?: Partial<Settings>;
     };
+    /** Where the steamcmd binary is. Root level, not per game, because it names a host tool. */
+    steamcmd?: {
+        path?: string;
+    };
     games: Record<string, GameConfig>;
 }
 export type ModSourceKind = 'local' | 'workshop' | 'official' | 'core';
@@ -385,7 +390,7 @@ export interface ParsedArgs {
     build?: BuildPolicy;
     sort?: 'topo' | 'none';
     /** `clean` only: --staging is the default, --all additionally requires --yes. */
-    cleanTier?: 'staging' | 'logs' | 'all';
+    cleanTier?: 'staging' | 'logs' | 'all' | 'downloads';
     dockerArgs: string[];
     gameArgs: string[];
     dryRun: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamecrate/cli",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Run a modded game in a container, with mods resolved from your local checkouts.",
   "license": "MIT",
   "type": "module",