@gamecrate/cli 0.1.0 → 1.1.0

package/dist/types/types.d.ts

@@ -0,0 +1,428 @@
+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];
+export type ExitReason = 'exited' | 'marker' | 'marker-timeout' | 'stopped' | 'window-closed' | 'timeout'
+/** The run never reached docker: staging, a pull or a build failed. */
+ | 'failed';
+export interface LaunchResult {
+    code: number;
+    reason: ExitReason;
+}
+/** 130 means runContainer caught a signal and stopped the container, not that the game died. */
+export declare function reasonFor(code: number): ExitReason;
+/** 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 the global config, 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[];
+    /** A one-line note for `gamecrate list`. Never read by the launcher. */
+    description?: string;
+    /** Launch defaults for this profile. The matching --no-* flag overrides each one. */
+    detach?: boolean;
+    replace?: boolean;
+    build?: BuildPolicy;
+}
+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;
+    /** Runs in the background: this process forks a supervisor and returns the prompt. */
+    detach: boolean;
+    /** One-run overrides. Only these turn the matching boolean back off. */
+    noDetach: boolean;
+    noReplace: boolean;
+    /** Set on the forked supervisor only. Never a config key, never in help. */
+    supervised: boolean;
+    /** `-f`: keep printing as the run writes, instead of dumping what is there. */
+    follow: boolean;
+    rest: string[];
+}
+export type ProjectDefaults = Partial<Omit<ParsedArgs, 'subcommand' | 'cleanTier' | 'yes' | 'help' | 'rest' | 'profile' | 'supervised' | 'noDetach' | 'noReplace' | 'follow'>> & {
+    /** 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>;
+    /** 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. */
+    configPath?: string;
+};
+/** 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.1.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",