@gamecrate/cli 1.1.0 → 1.3.0

package/dist/lib.js

@@ -194,6 +194,37 @@ var profile = obj({
     });
   }
 });
+var libraryEntry = obj({
+  workshop: num.optional(),
+  path: str.optional(),
+  git: str.optional(),
+  branch: str.optional(),
+  tag: str.optional(),
+  commit: str.optional(),
+  subdir: str.optional()
+}).check((ctx) => {
+  const v = ctx.value;
+  const push = (message, path) => {
+    ctx.issues.push({ code: "custom", message, input: v, ...path === undefined ? {} : { path } });
+  };
+  const sources = ["workshop", "path", "git"].filter((k) => v[k] !== undefined);
+  if (sources.length === 0)
+    push('library entry needs a "workshop" id, a "path", or a "git" url');
+  if (sources.length > 1)
+    push(`library entry takes only one of ${sources.join(", ")}`);
+  const refs = ["branch", "tag", "commit"].filter((k) => v[k] !== undefined);
+  if (refs.length > 1)
+    push(`library entry takes only one of branch, tag or commit, got ${refs.join(", ")}`);
+  if (v["git"] === undefined) {
+    for (const key of [...refs, ...v["subdir"] === undefined ? [] : ["subdir"]]) {
+      push(`"${key}" needs a "git" url`, [key]);
+    }
+  }
+  const subdir = v["subdir"];
+  if (typeof subdir === "string" && (subdir.startsWith("/") || subdir.split("/").includes(".."))) {
+    push('"subdir" must be a relative path inside the repo, with no ".." segment', ["subdir"]);
+  }
+});
 var game = obj({
   gameFiles: obj({ source: oneOf(["mount", "image"]), host: str.optional(), container: str }).check(requiredWhen("host", (v) => v["source"] === "mount")),
   dataDir: obj({
@@ -219,15 +250,7 @@ var game = obj({
   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(),
+  library: z.record(z.string(), libraryEntry, { error: "expected an object" }).optional(),
   modes: z.array(modeName, { error: "expected a non-empty array" }).min(1, {
     error: "expected a non-empty array"
   }),
@@ -240,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) {
@@ -268,6 +292,7 @@ var PROJECT_OBJECT = z2.strictObject({
   defaultProfile: projectName.optional(),
   profiles: z2.record(z2.string(), z2.unknown()).optional(),
   settings: z2.record(z2.string(), z2.unknown()).optional(),
+  library: z2.record(z2.string(), z2.unknown()).optional(),
   detach: projectBool.optional(),
   mods: projectList.optional(),
   without: projectList.optional(),
@@ -298,10 +323,14 @@ var PROJECT_OBJECT = z2.strictObject({
   resolution: projectResolution.optional()
 }, { error: "expected an object" });
 var PROJECT_SCHEMA = PROJECT_OBJECT.check((ctx) => {
-  const { game, profiles, settings } = ctx.value;
+  const { game, profiles, settings, library } = ctx.value;
   if (game !== undefined)
     return;
-  for (const [key, value] of [["profiles", profiles], ["settings", settings]]) {
+  for (const [key, value] of [
+    ["profiles", profiles],
+    ["settings", settings],
+    ["library", library]
+  ]) {
     if (value === undefined)
       continue;
     ctx.issues.push({

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

@@ -9,6 +9,8 @@ export interface SubcommandSpec {
     positionals: PositionalSlot[];
     /** Flag names beyond the global set, in the order help should show them. */
     flags: readonly string[];
+    /** Slots to use instead of `positionals` when the next word is one of these. */
+    subverbs?: Readonly<Record<string, PositionalSlot[]>>;
 }
 /** The subcommand table. `modless` is reserved as a built-in profile, not a verb. */
 export declare const SUBCOMMANDS: readonly SubcommandSpec[];

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

@@ -0,0 +1,18 @@
+import type { GamePlugin } from '../plugin';
+import type { ParsedArgs, ProjectDefaults, RootConfig } from '../types';
+export interface ModsContext {
+    config: RootConfig;
+    plugins: Map<string, GamePlugin>;
+    defaults: ProjectDefaults;
+    /** Where findProjectConfig starts walking. Injectable so tests need no chdir. */
+    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>;
+export declare function modsAdd(args: ParsedArgs, ctx: ModsContext): Promise<number>;
+export declare function modsRm(args: ParsedArgs, ctx: ModsContext): Promise<number>;
+export declare function modsSync(args: ParsedArgs, ctx: ModsContext): Promise<number>;

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

@@ -0,0 +1,14 @@
+/** A value of `undefined` deletes the key rather than writing an undefined. */
+export interface ConfigEdit {
+    path: (string | number)[];
+    value: unknown;
+}
+/**
+ * jsonc-parser never sniffs the file, so an inserted block lands with whatever width it is
+ * handed. A file indented with tabs and edited with spaces reads as two files.
+ */
+export declare function detectIndent(text: string): {
+    tabSize: number;
+    insertSpaces: boolean;
+};
+export declare function writeConfig(file: string, edits: ConfigEdit[]): Promise<void>;

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

@@ -18,7 +18,7 @@ export declare function runtimeLayerRef(ref: string): string;
 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
+ * 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>;

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

@@ -10,7 +10,12 @@ export interface ResolveOptions {
     index?: ModIndex;
     /** Overrides process.cwd() for ambient worktree detection; tests set it. */
     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[];
 }
+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
@@ -18,10 +23,11 @@ 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 workshop root.
- * Local roots rescan every launch; only the workshop scan is cached, against the acf stamp.
+ * Scans the game install, then every scan root in declaration order, then the source cache,
+ * 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): 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

@@ -0,0 +1,61 @@
+import type { GameConfig, LibraryEntry, ModEntry, ParsedArgs, ProfileConfig } from '../types';
+export type GitRef = {
+    kind: 'branch' | 'tag' | 'commit';
+    value: string;
+};
+/**
+ * A library pin by id, case-blind. Exact then lowercase covers every normal config without a
+ * scan; the scan is the only way to reach a mixed-case key from a ref spelled differently.
+ */
+export declare function libraryPin(game: GameConfig, id: string): LibraryEntry | undefined;
+export declare function sourcesRoot(dataRoot: string): string;
+export declare function normalizeUrl(url: string): string;
+export declare function cloneDir(dataRoot: string, url: string, ref: GitRef): string;
+export interface GitPin {
+    url: string;
+    ref?: GitRef;
+    subdir?: string;
+}
+export type SyncMode = 'use' | 'fetch' | 'force';
+export interface SyncResult {
+    dir: string;
+    warning?: string;
+}
+export declare function isMoving(ref: GitRef): boolean;
+export declare function gitRefOf(pin: {
+    branch?: string;
+    tag?: string;
+    commit?: string;
+}): 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 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`. */
+    dirs: Map<string, string>;
+    warnings: string[];
+    /** One entry per distinct clone this call handled, fetched or reused. Makes dedupe testable. */
+    fetched: string[];
+    /** 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
+ * the scan answers by packageId instead, which is a coin flip between two directories of one
+ * repo. An unpinned entry has no ref to derive a directory from, so it takes the one `branch-*`
+ * clone already on disk.
+ */
+export declare function cachedSources(game: GameConfig, profileName: string, args: Partial<ParsedArgs>, dataRoot: string): Map<string, string>;
+/**
+ * Clones or fetches every git-pinned mod the run will ask for, before the index is built, and
+ * keeps one lock per clone until the caller releases it. `git()` is spawnSync, so these
+ * serialize whatever this function looks like.
+ */
+export declare function prepareSources(game: GameConfig, profileName: string, args: ParsedArgs, dataRoot: string, allowFetch: boolean): Promise<PreparedSources>;

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

@@ -0,0 +1,56 @@
+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;
+/**
+ * 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

@@ -110,6 +110,11 @@ export interface ScanRoot {
 export interface LibraryEntry {
     workshop?: number;
     path?: string;
+    git?: string;
+    branch?: string;
+    tag?: string;
+    commit?: string;
+    subdir?: string;
 }
 /** Matches a family of mods by pattern instead of naming each one. */
 export interface DynamicModEntry {
@@ -194,6 +199,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';
@@ -235,6 +244,11 @@ export interface ModRecord {
     };
     /** Which scanRoot produced it, for the precedence ladder. */
     rootIndex: number;
+    /**
+     * The clone directory's mtime. Source-cache records only, which is what keeps it from
+     * reordering a user's checkout against anything.
+     */
+    clonedAt?: number;
 }
 export type WorktreeSource = 'flag' | 'env' | 'cwd' | 'ref';
 export interface WorktreeRequest {
@@ -405,14 +419,38 @@ export interface ParsedArgs {
     supervised: boolean;
     /** `-f`: keep printing as the run writes, instead of dumping what is there. */
     follow: boolean;
+    /** The write verb under `mods`. Unset means the read verb. */
+    subverb?: 'add' | 'rm' | 'sync';
+    /** Where `mods add` pulls the mod from. */
+    source?: {
+        kind: 'path';
+        value: string;
+    } | {
+        kind: 'workshop';
+        value: number;
+    } | {
+        kind: 'git';
+        url: string;
+        ref?: {
+            kind: 'branch' | 'tag' | 'commit';
+            value: string;
+        };
+        subdir?: string;
+    };
+    /** Which config file a write lands in. */
+    target?: 'global' | 'project';
+    /** Overwrite an existing entry instead of refusing. */
+    force?: boolean;
     rest: string[];
 }
-export type ProjectDefaults = Partial<Omit<ParsedArgs, 'subcommand' | 'cleanTier' | 'yes' | 'help' | 'rest' | 'profile' | 'supervised' | 'noDetach' | 'noReplace' | 'follow'>> & {
+export type ProjectDefaults = Partial<Omit<ParsedArgs, 'subcommand' | 'cleanTier' | 'yes' | 'help' | 'rest' | 'profile' | 'supervised' | 'noDetach' | 'noReplace' | 'follow' | 'subverb' | 'source' | 'target' | 'force'>> & {
     /** Replaces the old `profile:` key. Falls back to the first entry in `profiles`. */
     defaultProfile?: string;
     /** Validated by validateConfig after the splice, not here. */
     profiles?: Record<string, unknown>;
     settings?: Record<string, unknown>;
+    /** Spliced per id over games.<game>.library, so a repo pin replaces a global one whole. */
+    library?: Record<string, unknown>;
     /** Profile keys in source order. Object.keys sorts integer-like names to the front. */
     profileOrder?: string[];
     /** The file these came from. Four suffixes are legal, so output must not guess the name. */

package/package.json

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