skill/modules/dependency-chain.md

dependency-chain

Protect the dependency chain when deploying: track bundled dependencies (hard vs soft), never let one mod break another's, ask about conflicts once.

Why this matters

"Latest" is not automatically right. A mod can be the newest release yet bundle, or need, an exact version of a dependency (a library, framework or shared mod) that is not the newest. Variants differ too: a free and a paid edition of the same mod can both be "the latest you can get", and the paid one may have hard dependencies that cannot simply be copied in. If mod B then ships its own different copy of that dependency and overwrites it, mod A breaks.

What counts as a dependency / shared mod

Anything several mods rely on: frameworks, loaders, libraries and shared base mods (examples: ModuleManager, Harmony, Kopernicus, EVE, Scatterer, Parallax in KSP; BepInEx and plugin libraries; Fabric API or Forge libraries in Minecraft; script extenders and master files in Bethesda games; library mods named in info.json for Factorio). A folder or file that appears in more than one mod's download is a strong hint.

Hard vs soft

HARD = needs this exact version (or a narrow range). Signs: the page says "requires exactly" or "must use version X"; a version file with min/max bounds; package-manager metadata with version constraints; release notes "built against X"; the mod ships its own patched copy; the paid or special edition bundles its own dependencies. SOFT = works with other versions (for example "any 4.x", an optional dependency, or a version-agnostic library). Find out by reading the mod page, readme, release notes and forum thread (web_fetch). If you cannot tell, say so and treat it as hard. Record it: tracker_dep(name, version, folder, provided_by, hard_for, soft_for) for the chain, and tracker_mod(..., bundles="EVE 5.0.0 hard; ModuleManager 4.2.3 soft") for what a mod packages.

Procedure, for every mod

1. Before choosing versions, research the WHOLE list first and build the chain: for each mod, which dependencies and which versions it needs (hard or soft). Pick versions that satisfy everyone, not simply the highest number.
2. After extracting, look at the staged mod's top-level folders and files. Anything that is a dependency or already exists in the game is a bundled copy.
3. Run deps_check(staged, installed) (use granularity="file" for loose-file games such as Bethesda Data/). It lists items that are new, identical (skipped) and DIFFERENT.
4. For each DIFFERENT item decide:
   • Incoming copy is SOFT (works with the installed version): keep installed, do not copy the bundled one (exclude=).
   • Incoming is HARD, and every installed mod that uses the dependency is SOFT or has a confirmed compatible version: replacing may be fine; confirm with the sources, then ask the user as part of the single question below.
   • Both sides HARD on different versions: look for a compatibility patch or workaround (mod page, forum, package manager, a patch mod, a config change, an older/newer release of one mod). If one exists, apply it and record it. If not, it is a CONFLICT.
   • The mod needs a variant whose hard dependencies cannot be copied in (for example a paid edition): say so; it is blocked until the user decides.
5. Never merge two versions of the same dependency folder file by file. Keep one whole folder, or swap the whole folder (copy_tree replace= does this and backs up the old one).
6. Record every dependency (tracker_dep), every conflict (tracker_note kind conflict), then continue with the mods that do not conflict.
7. copy_tree already refuses to overwrite a differing installed folder and reports it as an open conflict: that is the safety net, not a replacement for steps 1 to 4.

Ask about conflicts ONCE, generally

Collect all open conflicts, then send ONE message, not one question per file or per conflict:

Dependency conflicts (N):
1. EVE: installed 3.2.2 (hard for: VolumetricAwareMod) vs ModA bundles 5.0.0 (hard). Workaround found: none.
2. ...
How should I handle them?
 a) Keep the installed versions and skip the conflicting bundled copies (safest)
 b) Keep the installed versions and skip the conflicting mods entirely
 c) Prefer the incoming versions for all (whole folders replaced, old ones backed up)
 d) Decide each: tell me the numbers and what to do

Apply the answer to every file in that conflict (exclude= or replace= with the unit names), then tracker_note kind conflict_resolved with the resolution. Do not ask again per file.

Never

Never pick "newer" automatically. Never delete an installed dependency without a backup. Never overwrite or mix a dependency because a mod bundled a copy of it.

Game notes (verify exact details with web_search)

• KSP (GameData): units are the folders directly inside GameData; version info is often in a .version file. Kopernicus-family mods (for example Outer Planets Mod) have many interdependencies; EVE exists as a free edition and a paid volumetric-clouds edition with its own hard dependencies, and some volumetric-aware mods need a specific EVE version. Always check each mod's stated requirement.
• Loose-file games such as Bethesda Data/: use granularity="file", or a manager such as Mod Organizer 2 or Vortex that keeps mods separate; master files (.esm) a plugin needs are hard dependencies.
• Minecraft: loader (Fabric/Forge/NeoForge/Quilt) and library mods (Fabric API etc.) must match the game version.
• Factorio: dependencies are in info.json; prefixes mean ! incompatible, ? optional, (?) hidden optional, ~ no load-order effect; operators such as >= and = set the version range.
• BepInEx games: the BepInEx build (Mono vs IL2CPP) and each plugin's declared dependencies.