@gamecrate/cli 1.1.0 → 1.2.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"
   }),
@@ -268,6 +291,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 +322,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,16 @@
+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;
+}
+/** 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

@@ -1,5 +1,5 @@
 import type { GamePlugin } from '../plugin';
-import type { LaunchPlan, ModIndex, ParsedArgs, Problem, RootConfig } from '../types';
+import type { GameConfig, LaunchPlan, ModIndex, ParsedArgs, Problem, RootConfig } from '../types';
 export interface ResolveOptions {
     game: string;
     profile: string;
@@ -10,7 +10,14 @@ 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>;
 }
+/**
+ * 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 resolvePlan(options: ResolveOptions): Promise<{
     plan: LaunchPlan;
     problems: Problem[];

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

@@ -18,10 +18,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 root. Local roots rescan every launch; only the workshop scan is cached,
+ * against the acf stamp.
  */
-export declare function buildIndex(game: string, config: GameConfig, plugin: GamePlugin): Promise<ModIndex>;
+export declare function buildIndex(game: string, config: GameConfig, plugin: GamePlugin, sourcesDir?: 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,56 @@
+import type { GameConfig, LibraryEntry, ParsedArgs } 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 lockClone(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>;
+}
+/**
+ * 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/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 {
@@ -235,6 +240,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 +415,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.2.0",
   "description": "Run a modded game in a container, with mods resolved from your local checkouts.",
   "license": "MIT",
   "type": "module",