hoi4-agent-tools 2.3.0 → 2.3.3

package/dist/hoi4_agent_tools/mcp/tools/chaosx.js

@@ -0,0 +1,480 @@
+import path from 'node:path';
+import sharp from 'sharp';
+import { z } from 'zod/v4';
+import { publicArtifactLink } from '../../core/artifacts.js';
+import { compareCodeUnits, hashCanonical } from '../../core/canonical.js';
+import { emptyServiceResult } from '../../core/result.js';
+import { RenderBudget } from '../../core/render-budget.js';
+import { workspaceIdSchema } from '../../schemas/common.js';
+import { GuiAssetCatalog } from '../../gui/assets.js';
+import { ScriptedGuiStudio } from '../../gui/index.js';
+import { buildGuiSourceGraph } from '../../gui/source-graph.js';
+import { PACKAGE_VERSION } from '../../version.js';
+import { compactValidatedInputSchema } from '../server/context-schemas.js';
+import { nonNegativeIntegerSchema, sha256Schema } from '../server/output-schemas.js';
+import { progressReporter } from '../server/progress.js';
+import { errorResult, setInlineFilesScanned, strictOperationResultSchema, toolResult, } from '../server/result.js';
+const countryTagSchema = z
+    .string()
+    .regex(/^[A-Z0-9]{3}$/u)
+    .describe('Exact HOI4 country tag selected by ChaosX');
+const chaosxCountryAssetsInput = compactValidatedInputSchema(z
+    .object({
+    workspaceId: workspaceIdSchema,
+    countryTags: z.array(countryTagSchema).min(1).max(4),
+    eventId: z.number().int().min(0).max(999).optional(),
+    treeId: z.string().min(1).max(256).optional(),
+})
+    .strict(), 'ChaosX-only country tags and optional event/focus identity');
+const chaosxCountryAssetsOutput = strictOperationResultSchema(z
+    .object({
+    revision: sha256Schema,
+    countries: z
+        .array(z
+        .object({
+        tag: countryTagSchema,
+        flagArtifactName: z.string().max(128).optional(),
+        leaderPortraitArtifactName: z.string().max(128).optional(),
+        leaderSprite: z.string().max(256).optional(),
+    })
+        .strict())
+        .max(4),
+    artifactCount: nonNegativeIntegerSchema,
+})
+    .strict());
+const visualGuiSelectorSchema = z
+    .object({
+    windowName: z.string().min(1).max(256),
+    guiId: z.string().min(1).max(256),
+})
+    .strict();
+const chaosxVisualRevisionInput = compactValidatedInputSchema(z
+    .object({
+    workspaceId: workspaceIdSchema,
+    guiWindows: z.array(visualGuiSelectorSchema).min(1).max(3),
+})
+    .strict(), 'ChaosX-only scripted-GUI selectors for fast cache revision checks');
+const visualRevisionEntrySchema = z
+    .object({
+    windowName: z.string().min(1).max(256),
+    guiId: z.string().min(1).max(256),
+    revision: sha256Schema,
+})
+    .strict();
+const chaosxVisualRevisionOutput = strictOperationResultSchema(z
+    .object({
+    workspaceRevision: sha256Schema,
+    guiRevisions: z.array(visualRevisionEntrySchema).max(3),
+    dependencyFileCount: nonNegativeIntegerSchema,
+})
+    .strict());
+const artifactProducing = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+const readOnly = { ...artifactProducing, readOnlyHint: true };
+function activeFiles(snapshot) {
+    return snapshot.files.filter(({ shadowedBy }) => shadowedBy === undefined);
+}
+function historyFile(snapshot, tag) {
+    const prefix = `history/countries/${tag.toLowerCase()} `;
+    return activeFiles(snapshot)
+        .filter(({ relativePath }) => relativePath.toLowerCase().startsWith(prefix))
+        .sort((left, right) => {
+        const ownership = Number(right.rootKind === 'mod') - Number(left.rootKind === 'mod');
+        return (ownership ||
+            right.loadOrder - left.loadOrder ||
+            compareCodeUnits(left.displayPath, right.displayPath));
+    })[0];
+}
+function pictureFromText(file, tag, requireTagPrefix) {
+    const text = file.bytes.toString('utf8');
+    const pattern = requireTagPrefix
+        ? new RegExp(`\\bpicture\\s*=\\s*"?(GFX_portrait_${tag}_[A-Za-z0-9_.:-]+)"?`, 'u')
+        : /\bpicture\s*=\s*"?(GFX_[A-Za-z0-9_.:-]+)"?/u;
+    return pattern.exec(text)?.[1];
+}
+function eventPictureSource(snapshot, tag, eventId) {
+    const eventPrefix = eventId === undefined ? undefined : String(eventId).padStart(3, '0');
+    const candidates = activeFiles(snapshot)
+        .filter(({ relativePath, bytes }) => {
+        const normalized = relativePath.toLowerCase();
+        return (normalized.endsWith('.txt') &&
+            (normalized.startsWith('events/') || normalized.startsWith('common/scripted_effects/')) &&
+            bytes.includes(Buffer.from(`GFX_portrait_${tag}_`, 'utf8')));
+    })
+        .sort((left, right) => {
+        const leftPreferred = eventPrefix !== undefined && path.posix.basename(left.relativePath).startsWith(eventPrefix);
+        const rightPreferred = eventPrefix !== undefined &&
+            path.posix.basename(right.relativePath).startsWith(eventPrefix);
+        return (Number(rightPreferred) - Number(leftPreferred) ||
+            compareCodeUnits(left.displayPath, right.displayPath));
+    });
+    for (const file of candidates) {
+        const sprite = pictureFromText(file, tag, true);
+        if (sprite !== undefined)
+            return { sprite, path: file.displayPath };
+    }
+    return undefined;
+}
+function leaderSelection(snapshot, tag, eventId) {
+    const countryHistory = historyFile(snapshot, tag);
+    const historyPicture = countryHistory === undefined ? undefined : pictureFromText(countryHistory, tag, false);
+    const eventPicture = historyPicture === undefined ? eventPictureSource(snapshot, tag, eventId) : undefined;
+    const fallbackSprite = snapshot.index
+        .findAll('sprite')
+        .filter(({ overridden, id }) => !overridden && id.startsWith(`GFX_portrait_${tag}_`))
+        .sort((left, right) => compareCodeUnits(left.id, right.id))[0];
+    const leaderSprite = historyPicture ?? eventPicture?.sprite ?? fallbackSprite?.id;
+    if (leaderSprite === undefined)
+        return {};
+    const sprite = snapshot.index.find('sprite', leaderSprite);
+    const texture = typeof sprite?.metadata.texture === 'string' ? sprite.metadata.texture : undefined;
+    return {
+        leaderSprite,
+        ...(texture === undefined ? {} : { leaderTexturePath: texture }),
+        ...(countryHistory !== undefined
+            ? { discoverySourcePath: countryHistory.displayPath }
+            : eventPicture === undefined
+                ? {}
+                : { discoverySourcePath: eventPicture.path }),
+        ...(sprite === undefined ? {} : { spriteSourcePath: sprite.path }),
+    };
+}
+function flagCandidates(tag) {
+    return ['tga', 'dds', 'png'].flatMap((extension) => [
+        `gfx/flags/${tag}.${extension}`,
+        `gfx/flags/medium/${tag}.${extension}`,
+        `gfx/flags/small/${tag}.${extension}`,
+    ]);
+}
+async function rasterPng(catalog, assetPath) {
+    const raster = await catalog.loadRaster(assetPath);
+    if (!raster.supported || raster.width < 1 || raster.height < 1)
+        return undefined;
+    return sharp(raster.data, {
+        raw: { width: raster.width, height: raster.height, channels: 4 },
+    })
+        .png({ compressionLevel: 9, adaptiveFiltering: false, palette: false })
+        .toBuffer();
+}
+async function selectCountryAssets(engine, snapshot, workspaceId, tags, eventId, context, signal) {
+    const selections = tags.map((tag) => ({
+        tag,
+        ...leaderSelection(snapshot, tag, eventId),
+    }));
+    const patterns = [
+        ...new Set(selections.flatMap(({ tag, leaderTexturePath }) => [
+            ...flagCandidates(tag),
+            ...(leaderTexturePath === undefined ? [] : [leaderTexturePath]),
+        ])),
+    ].sort(compareCodeUnits);
+    const workspace = engine.resolver.get(workspaceId, context.principal);
+    const scannedAssets = patterns.length === 0
+        ? []
+        : await engine.scanner.scan(workspace, {
+            patterns,
+            ...(signal === undefined ? {} : { signal }),
+        });
+    const graph = buildGuiSourceGraph([], snapshot.index);
+    const catalog = new GuiAssetCatalog(graph, scannedAssets, new RenderBudget());
+    for (const selection of selections) {
+        const flagPath = flagCandidates(selection.tag).find((candidate) => catalog.resolveFile(candidate) !== undefined);
+        if (flagPath !== undefined)
+            selection.flagPath = flagPath;
+    }
+    return { selections, catalog };
+}
+function scannerPattern(displayPath) {
+    const separator = displayPath.indexOf(':');
+    return separator < 0 ? displayPath : displayPath.slice(separator + 1);
+}
+async function cachedGuiRevisionCurrent(engine, context, workspaceId, cached, signal) {
+    const expectedPaths = Object.keys(cached.sourceHashes);
+    if (expectedPaths.length === 0)
+        return true;
+    const workspace = engine.resolver.get(workspaceId, context.principal);
+    const expected = new Set(expectedPaths);
+    const scanned = await engine.scanner.scan(workspace, {
+        patterns: [...new Set(expectedPaths.map(scannerPattern))].sort(compareCodeUnits),
+        signal,
+    });
+    const current = Object.fromEntries(scanned
+        .filter(({ displayPath }) => expected.has(displayPath))
+        .map(({ displayPath, sha256 }) => [displayPath, sha256]));
+    return hashCanonical(current) === hashCanonical(cached.sourceHashes);
+}
+function collectNamedGuiAttributes(value, keys, output) {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectNamedGuiAttributes(entry, keys, output);
+        return;
+    }
+    if (typeof value !== 'object' || value === null)
+        return;
+    for (const [key, entry] of Object.entries(value)) {
+        if (keys.has(key) && typeof entry === 'string' && entry.length > 0)
+            output.add(entry);
+        collectNamedGuiAttributes(entry, keys, output);
+    }
+}
+function guiDependencySourceHashes(graph, selector) {
+    const window = [...graph.elements]
+        .sort((left, right) => left.definitionOrder - right.definitionOrder)
+        .find(({ name }) => name === selector.windowName);
+    if (window === undefined)
+        throw new Error(`GUI window not found: ${selector.windowName}`);
+    const scriptedGui = graph.scriptedGuis.find(({ name }) => name === selector.guiId);
+    if (scriptedGui === undefined)
+        throw new Error(`Scripted GUI not found: ${selector.guiId}`);
+    const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+    const elementById = new Map(graph.elements.map((element) => [element.id, element]));
+    const spriteByName = new Map(graph.sprites.map((sprite) => [sprite.name, sprite]));
+    const fontByName = new Map(graph.fonts.map((font) => [font.name, font]));
+    const localisationByKey = new Map();
+    for (const localisation of graph.localisation)
+        if (!localisationByKey.has(localisation.key))
+            localisationByKey.set(localisation.key, localisation);
+    const outgoing = new Map();
+    for (const edge of graph.edges) {
+        if (!edge.resolved)
+            continue;
+        const targets = outgoing.get(edge.from) ?? [];
+        targets.push(edge.to);
+        outgoing.set(edge.from, targets);
+    }
+    const pending = [window.id, scriptedGui.id];
+    const visited = new Set();
+    const sourcePaths = new Set([window.sourcePath, scriptedGui.sourcePath]);
+    while (pending.length > 0) {
+        const nodeId = pending.pop();
+        if (nodeId === undefined || visited.has(nodeId))
+            continue;
+        visited.add(nodeId);
+        const node = nodeById.get(nodeId);
+        if (node !== undefined && graph.sourceHashes[node.path] !== undefined)
+            sourcePaths.add(node.path);
+        const element = elementById.get(nodeId);
+        if (element !== undefined) {
+            const spriteNames = new Set();
+            const fontNames = new Set();
+            const localisationKeys = new Set();
+            collectNamedGuiAttributes(element.attributes, new Set(['spriteType', 'quadTextureSprite']), spriteNames);
+            collectNamedGuiAttributes(element.attributes, new Set(['font', 'buttonFont']), fontNames);
+            collectNamedGuiAttributes(element.attributes, new Set(['text', 'buttonText', 'pdx_tooltip', 'pdx_tooltip_delayed', 'hint_tag']), localisationKeys);
+            for (const spriteName of spriteNames) {
+                const sprite = spriteByName.get(spriteName);
+                if (sprite !== undefined)
+                    pending.push(sprite.id);
+            }
+            for (const fontName of fontNames) {
+                const font = fontByName.get(fontName);
+                if (font !== undefined)
+                    pending.push(font.id);
+            }
+            for (const localisationKey of localisationKeys) {
+                const localisation = localisationByKey.get(localisationKey);
+                if (localisation !== undefined)
+                    sourcePaths.add(localisation.sourcePath);
+            }
+        }
+        for (const target of outgoing.get(nodeId) ?? [])
+            pending.push(target);
+    }
+    return Object.fromEntries([...sourcePaths]
+        .filter((sourcePath) => graph.sourceHashes[sourcePath] !== undefined)
+        .sort(compareCodeUnits)
+        .map((sourcePath) => [sourcePath, graph.sourceHashes[sourcePath]]));
+}
+async function resolveGuiRevision(engine, context, studio, cache, workspaceId, selector, signal) {
+    const cacheKey = hashCanonical({ workspaceId, selector });
+    const cached = cache.get(cacheKey);
+    if (cached !== undefined &&
+        (await cachedGuiRevisionCurrent(engine, context, workspaceId, cached, signal))) {
+        return {
+            windowName: selector.windowName,
+            guiId: selector.guiId,
+            revision: cached.sourceRevision,
+            workspaceRevision: cached.workspaceRevision,
+            filesScanned: Object.keys(cached.sourceHashes).sort(compareCodeUnits),
+        };
+    }
+    const linted = await studio.lint({
+        workspaceId,
+        windowName: selector.windowName,
+        scenario: {
+            id: 'chaosx-visual-revision',
+            resolution: { width: 1920, height: 1080 },
+            state: 'active',
+            scriptedGui: { [selector.guiId]: true },
+            visibility: { [selector.windowName]: true, [selector.guiId]: true },
+        },
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        signal,
+    });
+    const sourceHashes = guiDependencySourceHashes(linted.graph, selector);
+    const sourceRevision = hashCanonical({ selector, sourceHashes });
+    const next = {
+        workspaceRevision: linted.scene.sourceRevision,
+        sourceRevision,
+        sourceHashes,
+    };
+    cache.set(cacheKey, next);
+    return {
+        windowName: selector.windowName,
+        guiId: selector.guiId,
+        revision: sourceRevision,
+        workspaceRevision: next.workspaceRevision,
+        filesScanned: Object.keys(sourceHashes).sort(compareCodeUnits),
+    };
+}
+export function registerChaosxTools(server, engine, context) {
+    const guiStudio = new ScriptedGuiStudio(engine);
+    const guiRevisionCache = new Map();
+    server.registerTool('chaosx.visual_revision', {
+        title: 'Check ChaosX visual revisions',
+        description: 'Private ChaosX cache-coherency endpoint. Computes exact scripted-GUI source revisions without rendering PNG artifacts.',
+        inputSchema: chaosxVisualRevisionInput,
+        outputSchema: chaosxVisualRevisionOutput,
+        annotations: readOnly,
+    }, async (input, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
+        try {
+            const progress = progressReporter(extra);
+            await progress.report(0, 2, 'Checking ChaosX scripted-GUI sources');
+            const resolvedGuiRevisions = [];
+            for (const selector of input.guiWindows)
+                resolvedGuiRevisions.push(await resolveGuiRevision(engine, context, guiStudio, guiRevisionCache, workspaceId, selector, progress.signal));
+            const filesScanned = new Set(resolvedGuiRevisions.flatMap(({ filesScanned }) => filesScanned));
+            const guiRevisions = resolvedGuiRevisions.map(({ windowName, guiId, revision }) => ({
+                windowName,
+                guiId,
+                revision,
+            }));
+            const workspaceRevision = hashCanonical(resolvedGuiRevisions.map(({ windowName, workspaceRevision: revision }) => ({
+                windowName,
+                revision,
+            })));
+            const result = emptyServiceResult(workspaceId, {
+                workspaceRevision,
+                guiRevisions,
+                dependencyFileCount: filesScanned.size,
+            });
+            result.code = 'CHAOSX_VISUAL_REVISION_CHECKED';
+            setInlineFilesScanned(result, [...filesScanned].sort(compareCodeUnits));
+            await progress.report(2, 2, 'ChaosX scripted-GUI revisions complete');
+            return toolResult(result);
+        }
+        catch (error) {
+            return errorResult(error, workspaceId);
+        }
+    });
+    server.registerTool('chaosx.focus_country_assets', {
+        title: 'Render ChaosX focus country assets',
+        description: 'Private ChaosX Discord integration endpoint. Returns country flags and leader portraits to accompany a focus-tree raster; it is not intended for coding-agent workflows.',
+        inputSchema: chaosxCountryAssetsInput,
+        outputSchema: chaosxCountryAssetsOutput,
+        annotations: artifactProducing,
+    }, async (input, extra) => {
+        const workspaceId = engine.resolver.resolveWorkspaceId(input.workspaceId, context.principal);
+        try {
+            const progress = progressReporter(extra);
+            await progress.report(0, 3, 'Resolving ChaosX country assets');
+            const snapshot = await engine.scan(workspaceId, {}, context.principal, progress.signal);
+            const tags = [...new Set(input.countryTags)];
+            const { selections, catalog } = await selectCountryAssets(engine, snapshot, workspaceId, tags, input.eventId, context, progress.signal);
+            await progress.report(1, 3, 'Rasterizing ChaosX country assets');
+            const writes = [];
+            const countries = [];
+            const filesScanned = new Set();
+            for (const selection of selections) {
+                const country = { tag: selection.tag };
+                const sourcePaths = [selection.discoverySourcePath, selection.spriteSourcePath].filter((value) => value !== undefined);
+                for (const sourcePath of sourcePaths)
+                    filesScanned.add(sourcePath);
+                if (selection.flagPath !== undefined) {
+                    const png = await rasterPng(catalog, selection.flagPath);
+                    const source = catalog.resolveFile(selection.flagPath);
+                    if (png !== undefined && source !== undefined) {
+                        filesScanned.add(source.displayPath);
+                        const name = `chaosx-${selection.tag}-flag.png`;
+                        country.flagArtifactName = name;
+                        writes.push({
+                            name,
+                            mimeType: 'image/png',
+                            content: png,
+                            provenance: {
+                                kind: 'chaosx-country-flag',
+                                toolVersion: PACKAGE_VERSION,
+                                schemaVersion: 'chaosx-country-assets.v1',
+                                sourceHashes: { [source.displayPath]: source.sha256 },
+                                metadata: {
+                                    tag: selection.tag,
+                                    eventId: input.eventId ?? null,
+                                    treeId: input.treeId ?? null,
+                                },
+                            },
+                            description: `ChaosX country flag for ${selection.tag}`,
+                        });
+                    }
+                }
+                if (selection.leaderTexturePath !== undefined) {
+                    const png = await rasterPng(catalog, selection.leaderTexturePath);
+                    const source = catalog.resolveFile(selection.leaderTexturePath);
+                    if (png !== undefined && source !== undefined) {
+                        filesScanned.add(source.displayPath);
+                        const name = `chaosx-${selection.tag}-leader.png`;
+                        country.leaderPortraitArtifactName = name;
+                        const leaderSprite = selection.leaderSprite;
+                        if (leaderSprite !== undefined)
+                            country.leaderSprite = leaderSprite;
+                        const sourceHashes = { [source.displayPath]: source.sha256 };
+                        for (const sourcePath of sourcePaths) {
+                            const file = snapshot.files.find(({ displayPath }) => displayPath === sourcePath);
+                            if (file !== undefined)
+                                sourceHashes[sourcePath] = file.sha256;
+                        }
+                        writes.push({
+                            name,
+                            mimeType: 'image/png',
+                            content: png,
+                            provenance: {
+                                kind: 'chaosx-leader-portrait',
+                                toolVersion: PACKAGE_VERSION,
+                                schemaVersion: 'chaosx-country-assets.v1',
+                                sourceHashes,
+                                metadata: {
+                                    tag: selection.tag,
+                                    leaderSprite: selection.leaderSprite ?? null,
+                                    eventId: input.eventId ?? null,
+                                    treeId: input.treeId ?? null,
+                                },
+                            },
+                            description: `ChaosX leader portrait for ${selection.tag}`,
+                        });
+                    }
+                }
+                countries.push(country);
+            }
+            const workspace = engine.resolver.get(workspaceId, context.principal);
+            const artifacts = writes.length === 0
+                ? []
+                : await engine.artifacts.withAtomicChunkedWrites(workspace, writes, (stored) => Promise.resolve([...stored]), progress.signal);
+            const result = emptyServiceResult(workspaceId, {
+                revision: snapshot.revision,
+                countries,
+                artifactCount: artifacts.length,
+            });
+            result.code = 'CHAOSX_COUNTRY_ASSETS_RENDERED';
+            setInlineFilesScanned(result, [...filesScanned].sort(compareCodeUnits));
+            result.artifacts = artifacts.map(publicArtifactLink);
+            await progress.report(3, 3, 'ChaosX country assets complete');
+            return toolResult(result);
+        }
+        catch (error) {
+            return errorResult(error, workspaceId);
+        }
+    });
+}

package/dist/hoi4_agent_tools/mcp/tools/technology.js

@@ -162,6 +162,7 @@ const readOnly = {
 function graphHash(graph) {
     return hashCanonical({
         schemaVersion: graph.schemaVersion,
+        analysisMode: graph.analysisMode ?? 'full',
         workspaceIdentity: graph.workspaceIdentity,
         revision: graph.revision,
         statistics: graph.statistics,
@@ -192,7 +193,9 @@ function validation(graph) {
                 passed: graph.complete && blocking === 0,
                 message: graph.complete
                     ? `${blocking} blocking technology diagnostics; full evidence is linked`
-                    : `${graph.skippedSourceCount} source(s) were skipped; full evidence is linked`,
+                    : graph.analysisMode === 'focused'
+                        ? 'Helper projections were deferred for this large workspace; direct evidence is linked'
+                        : `${graph.skippedSourceCount} source(s) were skipped; full evidence is linked`,
             },
         ],
     };

package/dist/hoi4_agent_tools/runtime.js

@@ -1,4 +1,4 @@
-import { stat } from 'node:fs/promises';
+import { lstat, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { loadConfiguration, serverConfigurationSchema, } from './core/configuration.js';
@@ -39,15 +39,117 @@ async function isFile(candidate) {
         return false;
     }
 }
+/**
+ * Standard content directories that can be the only content in a valid local
+ * mod. Keep this list limited to HOI4 roots so an arbitrary project directory
+ * is not mistaken for a mod just because it contains a generic `common`
+ * folder.
+ */
+const MOD_CONTENT_DIRECTORIES = [
+    'events',
+    'gfx',
+    'history',
+    'interface',
+    'localisation',
+    'localisation_synced',
+    'map',
+    'music',
+    'portraits',
+    'sound',
+];
+const MOD_CONTENT_EXTENSIONS = {
+    events: ['.txt'],
+    gfx: ['.dds', '.gfx', '.png', '.tga'],
+    history: ['.txt'],
+    interface: ['.gfx', '.gui', '.txt'],
+    localisation: ['.yml', '.yaml'],
+    localisation_synced: ['.yml', '.yaml'],
+    map: ['.bmp', '.csv', '.map', '.txt'],
+    music: ['.asset', '.ogg', '.txt', '.wav'],
+    portraits: ['.dds', '.jpg', '.jpeg', '.png', '.tga'],
+    sound: ['.asset', '.ogg', '.txt', '.wav'],
+};
+const MOD_COMMON_DIRECTORIES = [
+    'abilities',
+    'ai_focuses',
+    'ai_strategy',
+    'ai_strategy_plans',
+    'bop',
+    'buildings',
+    'characters',
+    'continuous_focus',
+    'decisions',
+    'doctrines',
+    'ideas',
+    'mtth',
+    'national_focus',
+    'on_actions',
+    'operations',
+    'raids',
+    'resistance_compliance_modifiers',
+    'script_constants',
+    'scripted_effects',
+    'scripted_guis',
+    'scripted_triggers',
+    'special_projects',
+    'technology_sharing',
+    'technologies',
+    'technology_tags',
+    'units',
+    'unit_tags',
+];
+async function hasEntries(candidate, extensions) {
+    try {
+        const entries = await readdir(candidate, { withFileTypes: true });
+        return entries.some((entry) => entry.isFile() &&
+            (extensions === undefined ||
+                extensions.some((extension) => entry.name.toLowerCase().endsWith(extension))));
+    }
+    catch {
+        return false;
+    }
+}
+async function isRealDirectory(candidate) {
+    try {
+        const metadata = await lstat(candidate);
+        return metadata.isDirectory() && !metadata.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function isLikelyGameRoot(candidate) {
+    // Vanilla installations have an executable or launcher marker that a mod
+    // root should never contain. The marker check also protects a nested cwd
+    // such as `<game>/common` when the server is started from there.
+    return ((await isFile(path.join(candidate, 'hoi4.exe'))) ||
+        (await isFile(path.join(candidate, 'run_hoi4'))) ||
+        (await isFile(path.join(candidate, 'steam_appid.txt'))));
+}
+async function isLikelyModRoot(candidate) {
+    if (await isFile(path.join(candidate, 'descriptor.mod')))
+        return true;
+    if (await isLikelyGameRoot(candidate))
+        return false;
+    for (const directory of MOD_COMMON_DIRECTORIES) {
+        if (await isRealDirectory(path.join(candidate, 'common', directory)))
+            return true;
+    }
+    if (await isFile(path.join(candidate, 'common', 'combat_tactics.txt')))
+        return true;
+    for (const directory of MOD_CONTENT_DIRECTORIES) {
+        if ((await isRealDirectory(path.join(candidate, directory))) &&
+            (await hasEntries(path.join(candidate, directory), MOD_CONTENT_EXTENSIONS[directory])))
+            return true;
+    }
+    return false;
+}
 async function findCurrentModRoot(start = process.cwd()) {
     for (let cursor = path.resolve(start);;) {
-        if ((await isFile(path.join(cursor, 'descriptor.mod'))) ||
-            ((await isDirectory(path.join(cursor, 'common'))) &&
-                ((await isDirectory(path.join(cursor, 'history'))) ||
-                    (await isDirectory(path.join(cursor, 'interface'))) ||
-                    (await isDirectory(path.join(cursor, 'map')))))) {
+        if (await isLikelyGameRoot(cursor))
+            break;
+        if (await isLikelyModRoot(cursor))
             return cursor;
-        }
         const parent = path.dirname(cursor);
         if (parent === cursor)
             break;