Add mod installer adaptor contract

[halgari]

Summary

Introduces IGameInstallerService, the adaptor contract that decides where each file in a mod archive should be deployed. Adaptors can implement install() directly or declare glob-based StopPattern rules routed by resolveStopPatterns(). Cyberpunk 2077 ships with a concrete implementation covering the canonical mod layouts from the community redux extension.

To feed the contract, the main process now assembles a StorePathSnapshot (host OS, game OS, resolved bases per platform) at game discovery and hands it to the adaptor via adaptors:build-snapshot. The renderer bridge caches the snapshot plus the resolved GamePaths per game, and exposes a private installer registry through getAdaptorInstaller(gameId) for future InstallManager integration.

Adds scripts/test-adaptor.ts, a CLI that pulls a mod's file list from Nexus and runs it through a chosen adaptor's installer, rendering the source/anchor/destination mapping as a table.

Example run: Cyber Engine Tweaks

$ npx tsx scripts/test-adaptor.ts https://www.nexusmods.com/cyberpunk2077/mods/107

Mod:     CET 1.37.1 - Scripting fixes (cyberpunk2077 / 107)
Adaptor: cyberpunk2077 -> game:cyberpunk2077
File:    CET 1.37.1 - Scripting fixes-107-1-37-1-1759193708.zip (MAIN)

Archive: 19 files, 16 mapped, 3 unmapped
By anchor: game=16

Mapped (representative, full paths):
  bin/x64/global.ini                                                -> game/bin/x64/global.ini
  bin/x64/plugins/cyber_engine_tweaks/ThirdParty_LICENSES           -> game/bin/x64/plugins/cyber_engine_tweaks/ThirdParty_LICENSES
  bin/x64/plugins/cyber_engine_tweaks/fonts/NotoSans-Regular.ttf    -> game/bin/x64/plugins/cyber_engine_tweaks/fonts/NotoSans-Regular.ttf
  bin/x64/plugins/cyber_engine_tweaks/scripts/IconGlyphs/init.lua   -> game/bin/x64/plugins/cyber_engine_tweaks/scripts/IconGlyphs/init.lua
  bin/x64/plugins/cyber_engine_tweaks/tweakdb/tweakdb.str           -> game/bin/x64/plugins/cyber_engine_tweaks/tweakdb/tweakdb.str
  ...

Unmapped (3):
  bin/x64/LICENSE
  bin/x64/plugins/cyber_engine_tweaks.asi
  bin/x64/version.dll

The unmapped files are the CET ASI loader itself (cyber_engine_tweaks.asi, version.dll) plus a bare LICENSE. The current stop-pattern set does not yet route bootstrap DLLs/ASI files at bin/x64/, which is a known gap to address in a follow-up.

[erri120]

IGamePathService should take StorePathProvider, not StorePathSnapshot — and GamePaths needs a different shape

The snapshot is an IPC transport detail, not an API

StorePathSnapshot is how the framework gets pre-resolved paths into the adaptor Worker without a second round-trip. That's a sound implementation decision. But it shouldn't be the adaptor's API surface — StorePathSnapshot is now @public and every adaptor author has to know to call createStorePathProvider(snapshot) at the top of paths() before doing anything useful. That's boilerplate the framework should own.

The fix is a one-layer separation: the bridge wraps the snapshot before calling the adaptor, so adaptors always receive a StorePathProvider:

// bridge — adaptor never sees the seam
const snapshot = await window.api.adaptors.buildSnapshot(store, gamePath);
const provider  = createStorePathProvider(snapshot);  // framework's responsibility
cachedPaths     = await callAdaptor(name, pathsUri, "paths", [provider]);

// clean adaptor-facing contract
interface IGamePathService<T extends string = never> {
  paths(provider: StorePathProvider): Promise<GamePaths<"game" | T>>;
}

StorePathSnapshot, createStorePathProvider, and rehydrateGamePaths all become internal. If the IPC transport changes — snapshot batched into the load call, live-RPC proxy for some bases, test mock — no adaptor code changes.

The same applies to IGameInstallerService.install: the context: StorePathSnapshot parameter should be provider: StorePathProvider, reconstructed by the bridge from cachedSnapshot before dispatch.

---

GamePaths<T> is the wrong shape

Map<T | Base, QualifiedPath> has two problems:

1. Map.get() always returns QualifiedPath | undefined. The framework can never read the game path without a null check and a throw, even though the contract says it's always present.

2. T | Base is too wide. Base values like AppData and XdgData are inputs the adaptor consumes from the provider — they don't belong in the output map. Including them in the key type implies something that isn't true.

The right shape is a plain mapped type:

type GamePaths<T extends string> = {
  [K in T]: QualifiedPath;
};

Adaptors declare all their keys, including "game", in T:

type MyGamePaths = "game" | "saves";

class GamePathService implements IGamePathService<"saves"> {
  async paths(provider: StorePathProvider): Promise<GamePaths<MyGamePaths>> {
    const game = await provider.fromBase("game");
    let saves: QualifiedPath;
    if (provider.isWindows) {
      const documents = await provider.fromBase("documents");
      saves = documents.join("My Game", "saves");
    } else {
      saves = game.join("saves");
    }
    return { game, saves };
  }
}

paths.game is always QualifiedPath — no .get(), no null check. The framework reads it directly. Base.Game === "game" so adaptors can use either the constant or the literal.

The "game" key is enforced at the interface level, not inside GamePaths:

interface IGamePathService<T extends string = never> {
  paths(provider: StorePathProvider): Promise<GamePaths<"game" | T>>;
}

An adaptor implementing IGamePathService<"saves"> must return both game and saves — the compiler rejects a return missing either. GamePaths itself stays a simple mapped type with no intersection, no mandatory fields baked in, no Map overhead.

---

StorePathProvider needs isWindows narrowing restored

The example above uses provider.isWindows — this matters beyond ergonomics. The old StorePathProviderBase<TBase, TStore, IsWindows extends boolean> encoded available bases in the type: SteamLinuxPathProvider had IsWindows = false, making fromBase("documents") a compile error. After an if (provider.isWindows) check, TypeScript narrowed to a type where "documents" was in TBase and the call became valid.

The new StorePathProvider.fromBase(base: Base) accepts any Base regardless of OS. fromBase(Base.AppData) on a Linux-native snapshot is a runtime PathProviderError where a compile error was possible. The gameOS === OS.Windows check gives the same runtime behaviour but loses the narrowing entirely.

Restoring this — a StorePathProvider union with an isWindows discriminant that narrows the fromBase overload — is the right long-term shape. The current flat Base enum is already the right vocabulary; it just needs the narrowing layer on top.

[halgari]

I much prefer raw data over classes, but I get that approach doesn't line up with the rest of the new code design. Made the changes described.