@gamecrate/cli 1.0.0 → 1.1.0

package/dist/lib.js

@@ -2,7 +2,6 @@
 import { exports as exportsField, legacy } from "resolve.exports";
 
 // src/config/load.ts
-import { parse as parseYaml } from "yaml";
 import { z as z2 } from "zod";
 
 // src/cli/args.ts
@@ -21,7 +20,6 @@ var Exit = {
   Stale: 8,
   Interrupted: 130
 };
-
 class GamecrateError extends Error {
   code;
   detail;
@@ -74,6 +72,10 @@ function distance(a, b) {
   return prev[b.length];
 }
 
+// src/config/read.ts
+import { parseTree } from "jsonc-parser";
+import { isMap, parse as parseYaml, parseDocument } from "yaml";
+
 // src/config/jsonc.ts
 import { parse, printParseErrorCode } from "jsonc-parser";
 
@@ -177,7 +179,11 @@ var profile = obj({
     error: "expected an object"
   }).optional(),
   alias: str.optional(),
-  aliases: strArray.optional()
+  aliases: strArray.optional(),
+  description: str.optional(),
+  detach: bool.optional(),
+  replace: bool.optional(),
+  build: oneOf(["auto", "always", "never"]).optional()
 }).check((ctx) => {
   const v = ctx.value;
   if (v.alias !== undefined && (v.extends !== undefined || v.mods !== undefined)) {
@@ -257,9 +263,12 @@ var projectResolution = z2.string({ error: "expected dimensions like 1920x1080"
     ctx.issues.push({ code: "custom", message: error.message, input: ctx.value });
   }
 }).transform(parseResolution);
-var PROJECT_SCHEMA = z2.strictObject({
+var PROJECT_OBJECT = z2.strictObject({
   game: projectName.optional(),
-  profile: projectName.optional(),
+  defaultProfile: projectName.optional(),
+  profiles: z2.record(z2.string(), z2.unknown()).optional(),
+  settings: z2.record(z2.string(), z2.unknown()).optional(),
+  detach: projectBool.optional(),
   mods: projectList.optional(),
   without: projectList.optional(),
   only: projectList.optional(),
@@ -288,6 +297,21 @@ var PROJECT_SCHEMA = z2.strictObject({
   }).optional(),
   resolution: projectResolution.optional()
 }, { error: "expected an object" });
+var PROJECT_SCHEMA = PROJECT_OBJECT.check((ctx) => {
+  const { game, profiles, settings } = ctx.value;
+  if (game !== undefined)
+    return;
+  for (const [key, value] of [["profiles", profiles], ["settings", settings]]) {
+    if (value === undefined)
+      continue;
+    ctx.issues.push({
+      code: "custom",
+      path: [key],
+      message: "needs a top-level game: to say which game it belongs to",
+      input: ctx.value
+    });
+  }
+});
 
 // src/plugin.ts
 var PLUGIN_API_VERSION = 1;

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

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import type { ParsedArgs, ProjectDefaults } from '../types';
+import type { BuildPolicy, ParsedArgs, ProfileConfig, ProjectDefaults } from '../types';
 export type PositionalSlot = 'game' | 'profile' | 'rest';
 export interface SubcommandSpec {
     name: string;
@@ -32,9 +32,25 @@ export interface ParseOptions {
  * defaulting to `run`. Game args come after a bare `--` and nowhere else.
  */
 export declare function parseArgs(argv: string[], opts?: ParseOptions): ParsedArgs;
+/**
+ * Any layer can ask for this; the --no-detach flag is the only refusal. The supervisor is
+ * already the fork, and a profile or project `detach: true` reaches it too: it never forks again.
+ */
+export declare function wantsDetach(args: ParsedArgs, profile: ProfileConfig): boolean;
+/** The parent already replaced the previous run, and the only lock left is the child's own. */
+export declare function wantsReplace(args: ParsedArgs, profile: ProfileConfig): boolean;
+/** Three-way, so first defined wins. --no-build already arrives as 'never'. */
+export declare function buildPolicy(args: ParsedArgs, profile: ProfileConfig): BuildPolicy;
 export declare function parseResolution(value: string): {
     width: number;
     height: number;
 };
 /** Closest candidate within an edit distance that scales with word length. */
 export declare function suggest(word: string, candidates: readonly string[]): string | undefined;
+/**
+ * The argv that re-execs this same gamecrate as a supervisor. The compiled binary reports
+ * a virtual /$bunfs path as argv[1], which the child would read as a game name.
+ */
+export declare function supervisorArgv(userArgs: string[], instanceDir: string, self?: string[], execPath?: string): string[];
+/** Read straight off argv: the recovery path runs before anything is parsed or loaded. */
+export declare function supervisedDir(argv: string[]): string | undefined;

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

@@ -0,0 +1,2 @@
+import type { ParsedArgs, RootConfig } from '../types';
+export declare function requireGame(args: ParsedArgs, config: RootConfig): string;

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

@@ -0,0 +1,2 @@
+import type { ParsedArgs, ProjectDefaults, RootConfig } from '../types';
+export declare function list(args: ParsedArgs, config: RootConfig, defaults: ProjectDefaults): number;

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

@@ -6,7 +6,7 @@ export declare function warn(message: string): void;
 export interface OutputRedirect {
     close(): void;
 }
-export declare function redirectOutput(path: string): OutputRedirect;
+export declare function redirectOutput(path: string, keep?: boolean): OutputRedirect;
 export declare function forwardOutput(stream: Readable, target: NodeJS.WriteStream): Promise<void>;
 /**
  * Every collected failure at once, grouped by location. Resolution stops before any
@@ -52,5 +52,27 @@ export declare function printPlan(plan: LaunchPlan, asJson: boolean): void;
 export declare function runTimestamp(now?: Date): string;
 /** Makes <logsDir>/runs/<ts>, repoints `current` at it, rotates the old ones, returns the dir. */
 export declare function openRunLog(logsDir: string, now?: Date): string;
+/** Below the first a wait is not worth mentioning; the log normally appears in milliseconds. */
+export interface NoticeSchedule {
+    firstMs: number;
+    everyMs: number;
+}
+export declare const WAIT_NOTICE: NoticeSchedule;
+/**
+ * The elapsed label when a wait is due a line, else undefined. Driven by elapsed time and not
+ * by poll count: a quarter-second poll would scroll a line per pass and read as its own kind
+ * of broken, while a silent ten-minute image build looks exactly like a hang. Both branches
+ * floor, so the label never claims more time than has passed.
+ */
+export declare function waitNotice(waitedMs: number, lastNoticeMs: number, schedule?: NoticeSchedule): string | undefined;
+/** Inverse of runTimestamp. Anchored at the start, so the -2 collision suffix is tolerated. */
+export declare function runStartedAt(name: string): number | undefined;
+/** linkCurrent keeps `current` pointed at the newest run, so the run dir is never guessed. */
+export declare function currentLog(instanceDir: string): string;
+/**
+ * tail -f never ends on its own, so a live run gets --pid and tail leaves when the holder
+ * does. With no live holder nothing will write again, so -f is dropped or it hangs forever.
+ */
+export declare function tailArgv(file: string, fromStart: boolean, livePid?: number): string[];
 /** Landmine 7: a 180MB Player-prev.log was 68% of a profile tree. Retention is the cap. */
 export declare function rotateRuns(logsDir: string, keep: number): string[];

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

@@ -0,0 +1,6 @@
+import type { ParsedArgs, ProjectDefaults } from '../types';
+/**
+ * Not in parseArgs: filling a default there would erase the difference between a typed
+ * profile and a defaulted one, which clean and fix-perms both need.
+ */
+export declare function profileOf(args: ParsedArgs, defaults: ProjectDefaults): string;

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

@@ -1,6 +1,7 @@
 import type { GameConfig, ModEntry, ProfileConfig, ProjectDefaults, RootConfig, Settings } from '../types';
 import type { GamePlugin } from '../plugin';
-export declare function defaultConfigPath(): string;
+export declare function globalConfigDir(): string;
+export declare function findGlobalConfig(): Promise<string | undefined>;
 export declare function findProjectConfig(start?: string): Promise<string | undefined>;
 export declare function loadProjectDefaults(start?: string): Promise<ProjectDefaults>;
 export interface LoadedConfig {
@@ -8,10 +9,10 @@ export interface LoadedConfig {
     plugins: Map<string, GamePlugin>;
 }
 /**
- * Reads profiles.json, loads the plugins it lists, then merges the user's blocks over each
+ * Reads the global config, loads the plugins it lists, then merges the user's blocks over each
  * plugin's defaults. A missing file means no games, which every non-launch subcommand survives.
  */
-export declare function loadConfig(path?: string): Promise<LoadedConfig>;
+export declare function loadConfig(path?: string, project?: ProjectDefaults): Promise<LoadedConfig>;
 /** defaults -> games.<game> -> profile -> instance -> CLI. Scalars replace, arrays concatenate. */
 export declare function resolveSettings(root: RootConfig, game: GameConfig, profile: ProfileConfig, ...overrides: (Partial<Settings> | undefined)[]): Settings;
 /**
@@ -34,6 +35,7 @@ export declare function profileDataDir(root: RootConfig, game: string, profile:
  * verbatim: a directory name is already a path, and canonicalizing it skips odd-cased ones.
  */
 export declare function profileDirs(root: RootConfig, game: string, profile?: string): Promise<string[]>;
+export declare function profileKey(game: GameConfig, name: string): string | undefined;
 /** Removes entries whose id matches an exclusion. Dynamic entries are filtered after expansion. */
 export declare function subtract(mods: ModEntry[], exclude: string[]): ModEntry[];
 export declare function globToRegExp(pattern: string): RegExp;

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

@@ -0,0 +1,11 @@
+/** Probe order. yaml first: it is what `config edit` writes and what the docs show. */
+export declare const CONFIG_SUFFIXES: readonly [".yml", ".yaml", ".json", ".jsonc"];
+export declare function readConfigText(text: string, path: string): unknown;
+/** Undefined when the file is not there; every other read error propagates. */
+export declare function readConfigFile(path: string): Promise<unknown>;
+/**
+ * Source order of the keys under one top-level object. Object.keys sorts all-integer keys
+ * to the front, and NAME_PATTERN lets a profile be called 2024, so the syntax tree is the
+ * only honest answer to "which profile was written first".
+ */
+export declare function orderedKeys(text: string, path: string, key: string): string[];

package/dist/types/docker/run.d.ts

@@ -2,7 +2,7 @@ import type { ChildProcess, StdioOptions } from 'node:child_process';
 import type { Readable } from 'node:stream';
 import type { DockerRunSpec } from '../types';
 /** argv as one array, the way every caller here has it. */
-export declare function spawnArgv(argv: string[], stdio: StdioOptions): ChildProcess;
+export declare function spawnArgv(argv: string[], stdio: StdioOptions, detached?: boolean): ChildProcess;
 /** Rejects when the spawn itself fails, so a missing binary lands where a bad exit code would. */
 export declare function exited(proc: ChildProcess): Promise<number>;
 export declare function collect(stream: Readable): Promise<string>;
@@ -28,6 +28,8 @@ export interface RunOptions {
  * `exec docker run | tee` returns tee's code, which is why the old scripts always reported 0.
  */
 export declare function runContainer(spec: DockerRunSpec, opts: RunOptions): Promise<number>;
+/** Grace docker gives the game before SIGKILL, and the budget every teardown is measured against. */
+export declare const STOP_TIMEOUT_SECONDS = 10;
 export declare function stopContainer(name: string, timeoutSeconds: number): Promise<void>;
 /**
  * Host-side marker watch. Watches container stdout AND the game's own log file: RimWorld

package/dist/types/docker/window.d.ts

@@ -1,6 +1,34 @@
 export interface WindowWatch {
     stop: () => void;
 }
+export interface Toplevel {
+    id: string;
+    wmClass: string;
+}
+/** Every window that appeared since the snapshot and belongs to this game, in wmctrl's order. */
+export declare function newMatches(now: Toplevel[], seen: Set<string>, executable: string): Toplevel[];
+export declare function parseWindowPid(stdout: string): number | undefined;
+/**
+ * Another supervisor's window. Our own claim, or a dead or non-gamecrate pid, is not.
+ * Deliberately not `isRunning`: the cmdline read already throws for a dead pid, and it stays
+ * readable for a supervisor owned by another user, where a signal check is denied and would
+ * have us steal that run's window.
+ *
+ * Matched on each argument's own basename rather than anywhere in the raw cmdline, so a
+ * gamecrate log path or data directory in an unrelated process's arguments is not a peer. An
+ * editor opened on a directory literally named gamecrate still is; nothing in /proc separates
+ * those two.
+ *
+ * It also stops matching `bun run src/index.ts`, where the old substring match caught the repo
+ * directory in the script path. Installed users are unaffected, the bin and gamecrate.js both
+ * match; it costs peer detection between two concurrent from-source dev runs.
+ *
+ * Residual: before adoption `_NET_WM_PID` is the container's pid namespace, so this looks a
+ * container-local number up in the host's `/proc`. A false hit makes the run skip its own
+ * window for the whole wait. Container game pids are small and low host pids are kernel
+ * threads with an empty cmdline, so in practice the read returns nothing and no match happens.
+ */
+export declare function isPeerClaim(pid: number, self: number): boolean;
 export interface AdoptOptions {
     executable: string;
     title: string;
@@ -14,7 +42,8 @@ export interface AdoptOptions {
  * the screen first and takes the first window that was not there: an X client inside a
  * container reports a container-local _NET_WM_PID and hostname, so neither of those identifies
  * the run from out here. The WM_CLASS comes from the executable, which narrows it to this game
- * rather than any window that opened.
+ * rather than any window that opened. Once adopted, _NET_WM_PID holds our pid, so a second run
+ * starting at the same time can see the window is already spoken for and keep waiting for its own.
  */
 export declare function adoptNewWindow(opts: AdoptOptions): Promise<WindowWatch>;
 /** `WM_PROTOCOLS(ATOM): protocols  WM_DELETE_WINDOW, WM_TAKE_FOCUS`, or `:  not found.` */

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

@@ -29,13 +29,56 @@ export declare function buildLocalMods(plan: LaunchPlan, policy: BuildPolicy): P
 export interface ProfileLock {
     release: () => Promise<void>;
 }
+/**
+ * Refuses when this profile and instance are already up, and clears a lock whose holder is
+ * gone. Detach runs this before it forks, so a stale lock cannot strand the child.
+ */
+export declare function clearLock(plan: LaunchPlan): Promise<void>;
+/** The parent wrote this lock with the child's pid, so the child only has to drop it. */
+export declare function heldLock(plan: LaunchPlan): ProfileLock;
 export declare function takeLock(plan: LaunchPlan): Promise<ProfileLock>;
+/** Everything ps, stop, attach and wait need about a run, without reopening the container. */
+export interface LockRecord {
+    pid: number;
+    container: string;
+    game: string;
+    profile: string;
+    instance?: string;
+    detached: boolean;
+    mode?: string;
+    startedAt: string;
+}
+export declare function lockPath(plan: LaunchPlan): string;
+export declare function readLock(path: string): Promise<LockRecord | undefined>;
+/** wx fails rather than truncating, which is what makes this a lock and not a note. */
+export declare function writeLock(plan: LaunchPlan, record: Omit<LockRecord, 'startedAt'>): Promise<void>;
 /**
- * `--replace`: stops the container for this profile and instance only, so a parallel worktree
- * run is untouched. Waits for the holder to release before forcing, because its own release
- * would otherwise unlink the lock we are about to take.
+ * A signalled supervisor cannot finish before its own `docker stop --timeout` does, so the
+ * budget is derived from that rather than guessed alongside it.
+ */
+export declare const STOP_RELEASE_WAIT_MS: number;
+/**
+ * What stopRun did, because "the supervisor took the signal" and "the lock was stale anyway"
+ * are not the same answer and the caller has to say which one it is.
+ */
+export type StopOutcome = 'signalled' | 'orphaned' | 'held';
+/**
+ * Signals the supervisor, not the container. runContainer turns SIGTERM into a docker stop and
+ * returns 130, so the run records itself as stopped rather than crashed. Only a run whose
+ * supervisor is already gone gets the container stopped out from under it.
+ */
+export declare function stopRun(record: LockRecord, lockFile: string): Promise<StopOutcome>;
+/**
+ * `--replace`: ends the run for this profile and instance only, so a parallel worktree run is
+ * untouched. Goes through stopRun so the replaced run reports `stopped`; a raw docker stop
+ * would land as 137 instead.
  */
 export declare function replacePrevious(plan: LaunchPlan): Promise<void>;
+/**
+ * A pid alone is not proof. Detach leaves a long-lived process per run, so a recycled number
+ * would refuse every future launch and give ps a ghost with an invented uptime.
+ */
+export declare function isRunning(pid: number, startedAt?: string): boolean;
 /**
  * Grabs one frame from inside the running container. The run dir is already bind-mounted at
  * CONTAINER_LOG_DIR, so the png lands next to that run's logs with no extra mount.

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

@@ -0,0 +1,48 @@
+import type { NoticeSchedule } from '../cli/output';
+import type { LockRecord } from './prepare';
+import type { ExitReason, LaunchPlan, LaunchResult } from '../types';
+/**
+ * Written once, after the spawn, with the child's pid: a take-then-rewrite would leave a dead
+ * pid over a live child, and the next launcher would unlink it and race the same stage tree.
+ * Writing first is not open either, since a placeholder pid reads as "no lock" everywhere.
+ *
+ * So the child is killed when the write loses the `wx` race, because a supervisor with no lock
+ * runs unguarded and its release would drop the winner's lock.
+ *
+ * Residual: a parent killed between the spawn and the write leaves that child unguarded, with
+ * nothing left to kill it. That window spans a fork and an exec, so milliseconds.
+ */
+export declare function forkSupervisor(plan: LaunchPlan, argv: string[]): Promise<number>;
+export declare function recordExit(plan: LaunchPlan, result: LaunchResult): Promise<void>;
+/**
+ * The supervisor has no terminal and its stdio is discarded, so the exit record is the only way
+ * a caller ever learns it died. The lock goes only once that record is on disk, so a failed
+ * write leaves it: clearLock takes a dead holder on the next launch, while a cleared lock with
+ * no record makes wait answer "no run recorded" for a run that really failed.
+ */
+export declare function supervisorFailed(dir: string, code: number): Promise<number>;
+export interface ExitRecord {
+    at: string;
+    code: number;
+    reason: ExitReason;
+    container?: string;
+    runDir?: string;
+}
+/** The other half of writeExit. Missing or corrupt reads as "no exit recorded", never a throw. */
+export declare function lastExit(instanceDir: string): Promise<ExitRecord | undefined>;
+/**
+ * Blocks while a live holder has the lock. `orphaned` is a holder that died without recording
+ * anything, which is reachable with SIGKILL; `absent` is a run that never happened. Neither
+ * can ever produce an exit code, so neither may keep waiting for one.
+ *
+ * Once a lock has been seen, the pid outranks the file: the lock can vanish because someone
+ * else cleared it, but a live pid still owes us a record.
+ */
+export declare function awaitExit(instanceDir: string, poll?: number): Promise<ExitRecord | 'orphaned' | 'absent'>;
+/**
+ * The lock is written right after the spawn, but the supervisor only opens its run log after
+ * preflight, staging and the image, so `current` can point at the previous run for as long as
+ * a pull takes. tail follows a descriptor, so starting there would watch a finished run and
+ * never catch up. Waiting is bounded by the holder: if it dies first, there is nothing coming.
+ */
+export declare function awaitRunLog(instanceDir: string, lock: LockRecord, poll?: number, notice?: NoticeSchedule): Promise<boolean>;

package/dist/types/run/registry.d.ts

@@ -0,0 +1,22 @@
+import type { LockRecord } from '../launch/prepare';
+export interface RunRecord {
+    game: string;
+    profile: string;
+    instance?: string;
+    container: string;
+    pid?: number;
+    mode?: string;
+    startedAt?: string;
+    uptime?: string;
+    status: 'running' | 'starting' | 'orphaned';
+}
+export declare function parseDockerRuns(stdout: string): RunRecord[];
+/** <dataRoot>/<game>/<profile>/.gamecrate/lock, plus one level of instances under each. */
+export declare function walkLocks(dataRoot: string): Promise<LockRecord[]>;
+type Docker = () => Promise<string>;
+/**
+ * Docker answers for anything with a container. The lock walk covers the phase before one
+ * exists (pull, build, stage) and a lock whose container is already gone.
+ */
+export declare function listRuns(dataRoot: string, docker?: Docker): Promise<RunRecord[]>;
+export {};

package/dist/types/types.d.ts

@@ -18,6 +18,15 @@ export declare const Exit: {
     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;
@@ -26,7 +35,7 @@ export declare class GamecrateError extends Error {
 }
 /** 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. */
+    /** 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. */
@@ -138,6 +147,12 @@ export interface ProfileConfig {
     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;
@@ -381,9 +396,28 @@ export interface ParsedArgs {
     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'>>;
+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;

package/package.json

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