@gamecrate/cli 0.1.0 → 1.0.0

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

@@ -0,0 +1,13 @@
+import type { LaunchPlan, Mount } from '../types';
+/**
+ * Wipes and rebuilds the staging tree, returning one read-only bind per mod.
+ * Never creates a symlink: a host symlink into a mod checkout dangles inside the container.
+ */
+export declare function stageMods(plan: LaunchPlan): Promise<Mount[]>;
+/** Pre-creates the profile skeleton as the caller, before docker can create it as root. */
+export declare function ensureProfileTree(plan: LaunchPlan): Promise<void>;
+/**
+ * Walks with lstat semantics, so a dangling symlink inside a mounted tree is reported
+ * rather than thrown. Stops once `limit` foreign paths are found.
+ */
+export declare function detectForeignOwnership(dir: string, uid: number, limit?: number): Promise<string[]>;

package/dist/types/lib.d.ts

@@ -0,0 +1,3 @@
+export type { GamePlugin, ModsConfigInput } from './plugin';
+export { PLUGIN_API_VERSION } from './plugin';
+export type { DataDirSpec, DisplayBackend, DynamicModEntry, GameConfig, GameFilesSpec, ImageSpec, InstanceConfig, LibraryEntry, LogFileSpec, ModEntry, ModEntryObject, ModManifest, ModeName, ModsDirSpec, NetworkPolicy, ProfileConfig, ScanRoot, Settings, } from './types';

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

@@ -0,0 +1,29 @@
+import type { GamePlugin } from '../plugin';
+import type { GameConfig, ModIndex, ModRecord, Problem, WorktreeRequest } from '../types';
+/**
+ * `**` spans separators, `*` and `?` do not; everything else is literal. Mod folders are
+ * routinely named `[KV] Mod Manager`, so brackets and braces must not be glob syntax.
+ */
+export declare function globMatch(pattern: string, path: string): boolean;
+/**
+ * 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
+ * directory can produce `selectedWorktree`.
+ */
+export declare function applyWorktreeRequests(index: ModIndex, requests: WorktreeRequest[], config: GameConfig): Promise<void>;
+/**
+ * Forces one packageId to come from a named directory, whatever the profile pinned. This is
+ * the only override that reaches a mod already in preCore/core/dlc/base, because slot
+ * expansion is first-wins and a later `--mod` entry for a present id is dropped.
+ */
+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.
+ */
+export declare function buildIndex(game: string, config: GameConfig, plugin: GamePlugin): 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.
+ */
+export declare function resolveModRef(index: ModIndex, ref: string, game: GameConfig): ModRecord | null;

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

@@ -0,0 +1,28 @@
+import type { StaleReport } from '../types';
+export interface Timestamped {
+    /** Relative to the mod directory. */
+    path: string;
+    mtimeMs: number;
+}
+export interface BuildTimes {
+    newestSource?: Timestamped;
+    newestAssembly?: Timestamped;
+    /** Every .cs mtime, so a report can count how many beat the assembly. */
+    sourceTimes: number[];
+}
+/** One walk answers both questions: is this stale, and which files say so. */
+export declare function scanBuildTimes(dir: string): Promise<BuildTimes>;
+/**
+ * Drives `--build auto`, so a mod that has never been compiled counts as stale. The warning
+ * is the stricter one: see staleReport.
+ */
+export declare function decideStale(times: BuildTimes): boolean;
+/**
+ * Null when there is nothing to say: no C#, no assemblies to compare against, or the build is
+ * current. A mod may legitimately ship XML only, so this never reports on one.
+ */
+export declare function staleReport(times: BuildTimes): StaleReport | null;
+export declare function staleWarning(packageId: string, report: StaleReport, now?: number): string;
+/** Coarse on purpose: "4m" is the whole signal, a duration to the second is noise. */
+export declare function duration(ms: number): string;
+export declare function ago(mtimeMs: number, now?: number): string;

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

@@ -0,0 +1,18 @@
+import type { Problem, WorktreeRequest, WorktreeSource } from '../types';
+/**
+ * Resolves one worktree request. Returns null when `dir` is not inside a LINKED worktree,
+ * which is what keeps a primary checkout, a non-repo directory and a pruned gitdir from
+ * counting as a selection.
+ */
+export declare function resolveWorktree(dir: string, source: WorktreeSource, order: number): WorktreeRequest | Problem;
+/** True when `dir` is the worktree root or lives underneath it. */
+export declare function contains(request: WorktreeRequest, dir: string): boolean;
+/**
+ * Assembles every request in precedence order: explicit flags first (left to right), then the
+ * env var, then cwd. Only a linked worktree survives; everything else becomes an ignorable
+ * Problem so the caller can decide how loudly to say so.
+ */
+export declare function collectRequests(flags: string[], env: string | undefined, cwd: string, disabled: boolean): {
+    requests: WorktreeRequest[];
+    problems: Problem[];
+};

package/dist/types/plugin.d.ts

@@ -0,0 +1,35 @@
+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 interface ModsConfigInput {
+    version: string;
+    buildNumber: number;
+    /** Lowercased packageIds, load order. */
+    activeMods: string[];
+    knownExpansions: string[];
+}
+/**
+ * A game's file formats plus the parts of its config that describe the game, not this machine.
+ * Everything here takes plain data and throws plain Errors, so no plugin links the core runtime.
+ */
+export interface GamePlugin {
+    apiVersion: number;
+    /** The key this game answers to on the command line. */
+    game: string;
+    /** Merged under the user's `games.<game>` block, so a user only writes what is theirs. */
+    defaults: Partial<GameConfig>;
+    /** null means "this file is not a mod manifest". A malformed file throws. */
+    parseManifest(text: string): ModManifest | null;
+    renderModsConfig(input: ModsConfigInput): string;
+    mergePrefs(existing: string | null, owned: Record<string, string>): string;
+    /** Prefs keys that put the game in a window instead of fullscreen. */
+    windowedPrefs: Record<string, string>;
+    /** Version.txt as the engine writes it. null when it does not parse. */
+    parseVersion(text: string): {
+        version: string;
+        buildNumber: number;
+    } | null;
+}
+/** Keyed by game name. A second plugin claiming a name already taken is a config error. */
+export declare function loadPlugins(specs: string[], configFile: string): Promise<Map<string, GamePlugin>>;
+export declare function requirePlugin(plugins: Map<string, GamePlugin>, game: string): GamePlugin;

package/dist/types/types.d.ts

@@ -0,0 +1,394 @@
+import type { GamePlugin } from './plugin';
+/**
+ * Shared contract for every module. Units code against this and nothing else;
+ * if a signature here is wrong, fix it here rather than working around it locally.
+ */
+export declare const Exit: {
+    readonly Ok: 0;
+    readonly GameFailed: 1;
+    readonly Usage: 2;
+    readonly Config: 3;
+    readonly Resolution: 4;
+    readonly Environment: 5;
+    readonly MarkerTimeout: 6;
+    /** Refused: this profile+instance is already running. `--replace` is the way past it. */
+    readonly Refused: 7;
+    /** `verify`: a bound mod's sources are newer than its assemblies. */
+    readonly Stale: 8;
+    readonly Interrupted: 130;
+};
+export type ExitCode = (typeof Exit)[keyof typeof Exit];
+/** Every failure the tool raises deliberately. Anything else is a bug. */
+export declare class GamecrateError extends Error {
+    readonly code: ExitCode;
+    readonly detail?: string | undefined;
+    constructor(message: string, code: ExitCode, detail?: string | undefined);
+}
+/** Collected and reported together, so one run surfaces every problem at once. */
+export interface Problem {
+    /** JSON Pointer into profiles.json, or a file path, or a mod id. */
+    where: string;
+    message: string;
+    /** Populated by did-you-mean matching where it applies. */
+    suggestion?: string;
+}
+export type ModeName = 'headed' | 'headless' | 'screenshot';
+export type PullPolicy = 'always' | 'missing' | 'never';
+export type BuildPolicy = 'auto' | 'always' | 'never';
+export type NetworkPolicy = 'none' | 'bridge' | 'host';
+export type DisplayBackend = 'x11' | 'wayland';
+export interface Settings {
+    width: number;
+    height: number;
+    devMode: boolean;
+    runInBackground: boolean;
+    /** Forced false when written; see landmine 5. */
+    resetModsConfigOnCrash: boolean;
+    gpu: boolean;
+    audio: boolean;
+    input: boolean;
+    network: NetworkPolicy;
+    /** Which display server a headed run talks to. x11 is the one an outside tool can retitle. */
+    display: DisplayBackend;
+    memory: string;
+    cpus: number;
+    pidsLimit: number;
+    /** Verbatim passthrough into the generated Prefs file. */
+    prefsExtra?: Record<string, string>;
+    gameArgs?: string[];
+    dockerArgs?: string[];
+}
+export interface GameFilesSpec {
+    source: 'mount' | 'image';
+    /** Required when source is "mount". */
+    host?: string;
+    container: string;
+}
+export interface ImageSpec {
+    ref: string;
+    acquire: 'pull' | 'build';
+    /** Required when acquire is "build". */
+    context?: string;
+}
+/** How the engine is told where its data directory is. Verified per game. */
+export type DataDirSpec = {
+    container: string;
+    mode: 'arg';
+    arg: string;
+} | {
+    container: string;
+    mode: 'env';
+    env: Record<string, string>;
+};
+export interface ModsDirSpec {
+    /** Where the staged mod tree is bind-mounted. NOT necessarily under dataDir. */
+    container: string;
+    /** Extra mod roots inside the image that must be masked with a tmpfs. */
+    mask?: string[];
+}
+export type LogFileSpec = {
+    mode: 'arg';
+    arg: string;
+} | {
+    mode: 'copy-out';
+    from: string;
+};
+export interface ScanRoot {
+    path: string;
+    maxDepth: number;
+    exclude?: string[];
+}
+export interface LibraryEntry {
+    workshop?: number;
+    path?: string;
+}
+/** Matches a family of mods by pattern instead of naming each one. */
+export interface DynamicModEntry {
+    match: string;
+    first?: string[];
+    sort?: 'alpha' | 'none';
+    minMatches?: number;
+}
+export interface ModEntryObject {
+    id: string;
+    workshop?: number;
+    path?: string;
+    optional?: boolean;
+}
+/** A bare string is a packageId; `workshop:` and `path:` prefixes disambiguate. */
+export type ModEntry = string | ModEntryObject | DynamicModEntry;
+/**
+ * A named sub-run of a profile with its own data directory, lock and container, so several
+ * can run at once. Selected with `--instance`, or derived from an explicit `--worktree`.
+ */
+export interface InstanceConfig {
+    /** Promoted ahead of every other worktree request when this instance is selected. */
+    worktree?: string;
+    settings?: Partial<Settings>;
+}
+export interface ProfileConfig {
+    mods?: ModEntry[];
+    extends?: string;
+    exclude?: string[];
+    includeBase?: boolean;
+    autoDependencies?: boolean;
+    settings?: Partial<Settings>;
+    instances?: Record<string, InstanceConfig>;
+    /** Marks this profile as another name for an existing one. */
+    alias?: string;
+    /** Extra names this profile answers to, so one entry covers several spellings. */
+    aliases?: string[];
+}
+export interface GameConfig {
+    gameFiles: GameFilesSpec;
+    dataDir: DataDirSpec;
+    modsDir: ModsDirSpec;
+    logFile: LogFileSpec;
+    image: ImageSpec;
+    executable: string;
+    steamAppId: number;
+    workshopRoot: string | null;
+    scanRoots: ScanRoot[];
+    manifest: {
+        file: string;
+    };
+    modsConfig: {
+        file: string;
+    };
+    prefs: {
+        file: string;
+    };
+    /** Filename suffixes that mean "a save". `clean --all` counts them before it deletes. */
+    saveExtensions: string[];
+    core: string;
+    dlc: string[];
+    preCore?: string[];
+    base?: string[];
+    library?: Record<string, LibraryEntry>;
+    modes: ModeName[];
+    aliases?: Record<string, string>;
+    settings?: Partial<Settings>;
+    /** The engine claims WM_DELETE_WINDOW and drops it, so the titlebar X does nothing. */
+    ignoresWmDelete?: boolean;
+    profiles: Record<string, ProfileConfig>;
+}
+export interface RootConfig {
+    /** Package names or paths, resolved from the config file's directory. One per game. */
+    plugins?: string[];
+    dataRoot: string;
+    defaults?: {
+        settings?: Partial<Settings>;
+    };
+    games: Record<string, GameConfig>;
+}
+export type ModSourceKind = 'local' | 'workshop' | 'official' | 'core';
+export interface ModManifest {
+    packageId: string;
+    name?: string;
+    modDependencies: {
+        packageId: string;
+        steamWorkshopUrl?: string;
+    }[];
+    loadAfter: string[];
+    loadBefore: string[];
+    forceLoadAfter: string[];
+    forceLoadBefore: string[];
+    incompatibleWith: string[];
+}
+export interface ModRecord {
+    /** Manifest casing, preserved. Match on the lowercased form. */
+    packageId: string;
+    dir: string;
+    kind: ModSourceKind;
+    manifest: ModManifest;
+    /** Workshop item id when kind is "workshop". */
+    workshopId?: number;
+    /** True when dir sits inside a linked git worktree; ranked below primaries. */
+    linkedWorktree: boolean;
+    /**
+     * Request order when a caller deliberately selected the worktree this record lives in.
+     * The scanner can never set it, which is what stops an unselected worktree from winning.
+     */
+    selectedWorktree?: number;
+    /** Request order when `--use <packageId>=<dir>` named this record. Outranks a worktree. */
+    overridden?: number;
+    /** Set only for a selected worktree; the branch costs a git spawn, so it is not scanned for. */
+    worktree?: {
+        root: string;
+        branch: string;
+        source: WorktreeSource;
+    };
+    /** Which scanRoot produced it, for the precedence ladder. */
+    rootIndex: number;
+}
+export type WorktreeSource = 'flag' | 'env' | 'cwd' | 'ref';
+export interface WorktreeRequest {
+    /** realpath'd worktree toplevel. */
+    root: string;
+    branch: string;
+    source: WorktreeSource;
+    /** Lower wins. */
+    order: number;
+}
+export interface ModIndex {
+    game: string;
+    plugin: GamePlugin;
+    /** Keyed by lowercased packageId. Several records means a collision to resolve. */
+    byPackageId: Map<string, ModRecord[]>;
+    byWorkshopId: Map<number, ModRecord>;
+    /** Lowercased last dot-segment -> packageIds. CLI matching only. */
+    byShortName: Map<string, string[]>;
+    problems: Problem[];
+}
+/** Why a mod looks stale, in enough detail to name the file that says so. */
+export interface StaleReport {
+    /** Mod-relative path of the newest .cs. */
+    newestSource: string;
+    newestSourceMs: number;
+    /** Mod-relative path of the newest assembly it should have been compiled into. */
+    assembly: string;
+    assemblyMs: number;
+    newerCount: number;
+}
+export interface ResolvedMod {
+    packageId: string;
+    hostDir: string;
+    containerDir: string;
+    kind: ModSourceKind;
+    workshopId?: number;
+    /** False when the entry came from autoDependencies rather than the profile. */
+    explicit: boolean;
+    /** Set when a .cs file is newer than the staged assembly. */
+    stale?: boolean;
+    /** Set only when there is an assembly to be stale against; drives the launch warning. */
+    staleReport?: StaleReport;
+    /** Present when this mod came out of a linked worktree. */
+    worktree?: {
+        root: string;
+        branch: string;
+        source: WorktreeSource;
+        selected: boolean;
+    };
+    /** Other directories that declared this packageId and lost. Always emitted. */
+    shadowed?: string[];
+}
+export interface LaunchPlan {
+    game: string;
+    gameConfig: GameConfig;
+    plugin: GamePlugin;
+    profile: string;
+    settings: Settings;
+    mods: ResolvedMod[];
+    /** Absolute host path: <dataRoot>/<game>/<profile>. */
+    profileDir: string;
+    /** Undefined for the base profile; a name when several runs share one profile. */
+    instance?: string;
+    /** profileDir, or <profileDir>/instances/<instance>. Everything a run writes hangs off it. */
+    instanceDir: string;
+    dataDirHost: string;
+    /** <profileDir>/config. Shared by every instance, and holds the XDG dirs. */
+    configDirHost: string;
+    stageDirHost: string;
+    logsDirHost: string;
+    /** <logsDirHost>/runs/<ts>, bound into the container so Player.log lands with stdout.log. */
+    runDirHost: string;
+    mode: ModeName;
+    marker?: string;
+    timeoutSeconds: number;
+    renderWaitSeconds: number;
+    /** False under --no-stale-check. The check still runs, so staleReport stays truthful. */
+    warnOnStale: boolean;
+    warnings: string[];
+}
+export interface Identity {
+    uid: number;
+    gid: number;
+    home: string;
+    user: string;
+}
+export interface Mount {
+    type: 'bind' | 'tmpfs';
+    source?: string;
+    target: string;
+    readonly?: boolean;
+    /** tmpfs only. */
+    size?: string;
+    uid?: number;
+    gid?: number;
+    mode?: string;
+}
+export interface DockerRunSpec {
+    image: string;
+    name: string;
+    labels: Record<string, string>;
+    identity: Identity;
+    env: Record<string, string>;
+    mounts: Mount[];
+    devices: string[];
+    deviceCgroupRules: string[];
+    network: NetworkPolicy;
+    memory: string;
+    memorySwap: string;
+    cpus: number;
+    pidsLimit: number;
+    ulimits: string[];
+    workdir: string;
+    /** The host's, when set: KWin appends `<@name>` to a caption from a foreign machine. */
+    hostname?: string;
+    /** argv after the image name. */
+    command: string[];
+    extraArgs: string[];
+}
+export interface ParsedArgs {
+    subcommand: string;
+    game?: string;
+    profile?: string;
+    mods: string[];
+    without: string[];
+    only: string[];
+    mode?: ModeName;
+    marker?: string;
+    timeout?: number;
+    renderWait?: number;
+    resolution?: {
+        width: number;
+        height: number;
+    };
+    network?: NetworkPolicy;
+    log?: string;
+    pull?: PullPolicy;
+    build?: BuildPolicy;
+    sort?: 'topo' | 'none';
+    /** `clean` only: --staging is the default, --all additionally requires --yes. */
+    cleanTier?: 'staging' | 'logs' | 'all';
+    dockerArgs: string[];
+    gameArgs: string[];
+    dryRun: boolean;
+    printPlan: boolean;
+    json: boolean;
+    root: boolean;
+    yes: boolean;
+    help: boolean;
+    /** Repeatable; earlier flags outrank later ones. */
+    worktree: string[];
+    /** Names the sub-run: its own data directory, lock and container. */
+    instance?: string;
+    /** Repeatable `packageId=path`; forces one mod's source, whatever the profile says. */
+    use: string[];
+    /** Suppresses ambient cwd selection and the env var. */
+    noWorktree: boolean;
+    /** Suppresses the sources-newer-than-assemblies warning. The check itself still runs. */
+    noStaleCheck: boolean;
+    /** Stops whatever holds this profile+instance, then launches. Never refuses. */
+    replace: boolean;
+    rest: string[];
+}
+export type ProjectDefaults = Partial<Omit<ParsedArgs, 'subcommand' | 'cleanTier' | 'yes' | 'help' | 'rest'>>;
+/** Names that can never be a game or profile key. Enforced at config load. */
+export declare const RESERVED_NAMES: readonly string[];
+export declare const NAME_PATTERN: RegExp;
+/**
+ * Lookup in a bag keyed by user input. A bare index hands back Object.prototype members, so
+ * `--mod constructor` or a profile named `toString` would resolve to an inherited function.
+ */
+export declare function own<T>(bag: Record<string, T> | undefined, key: string): T | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamecrate/cli",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Run a modded game in a container, with mods resolved from your local checkouts.",
   "license": "MIT",
   "type": "module",
@@ -21,21 +21,26 @@
     "gamecrate": "./dist/gamecrate.js"
   },
   "exports": {
-    ".": "./src/lib.ts"
+    ".": {
+      "types": "./dist/types/lib.d.ts",
+      "default": "./dist/lib.js"
+    }
   },
-  "types": "./src/lib.ts",
+  "types": "./dist/types/lib.d.ts",
   "files": [
-    "src",
-    "dist/gamecrate.js"
+    "dist/gamecrate.js",
+    "dist/lib.js",
+    "dist/types"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "build": "npm run build:node && npm run build:binary",
-    "build:node": "bun build ./src/index.ts --target=node --packages=external --outfile dist/gamecrate.js",
-    "build:binary": "bun build ./src/index.ts --compile --outfile dist/gamecrate",
-    "prepare": "npm run build:node",
-    "prepack": "npm run build:node"
+    "build": "npm run build:node && npm run build:types && npm run build:binary",
+    "build:node": "bun build ./src/index.ts --target=node --packages=external --define __VERSION__='\"'${npm_package_version:-0.0.0-dev}'\"' --outfile dist/gamecrate.js && bun build ./src/lib.ts --target=node --packages=external --outfile dist/lib.js",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build:binary": "bun build ./src/index.ts --compile --define __VERSION__='\"'${npm_package_version:-0.0.0-dev}'\"' --outfile dist/gamecrate",
+    "prepare": "npm run build:node && npm run build:types",
+    "prepack": "npm run build:node && npm run build:types"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",