wowdump 0.0.0 → 0.2.1

package/dist/observability.js

@@ -0,0 +1,41 @@
+export const OBSERVATION_TIERS = [
+    "error_text",
+    "source_location",
+    "stack_trace",
+    "vm_metadata"
+];
+export const OBSERVATION_TIER_DEFINITIONS = Object.freeze([
+    Object.freeze({
+        tier: "error_text",
+        capability: "errorMessage",
+        description: "Read the existing error text at a verified error boundary"
+    }),
+    Object.freeze({
+        tier: "source_location",
+        capability: "sourceLocation",
+        description: "Read source and line metadata when its layout is proven"
+    }),
+    Object.freeze({
+        tier: "stack_trace",
+        capability: "stackTrace",
+        description: "Read an existing stack representation with bounded traversal"
+    }),
+    Object.freeze({
+        tier: "vm_metadata",
+        capability: "vmMetadata",
+        description: "Read build-specific VM metadata only after an exact proof"
+    })
+]);
+export function getObservationTiers(adapter) {
+    if (!adapter)
+        return Object.freeze([]);
+    return Object.freeze(OBSERVATION_TIER_DEFINITIONS
+        .filter(definition => adapter.capabilities[definition.capability])
+        .map(definition => definition.tier));
+}
+export function createObservationPolicy(adapter) {
+    return Object.freeze({
+        semanticReadOnly: true,
+        tiers: getObservationTiers(adapter)
+    });
+}

package/dist/process-log-lock.js

@@ -0,0 +1,195 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+const DEFAULT_RETRY_DELAY_MS = 20;
+const DEFAULT_STALE_AFTER_MS = 2_000;
+const DEFAULT_TRANSIENT_RETRIES = 50;
+const defaultFileSystem = { mkdir, readFile, readdir, rename, rm, stat, utimes, writeFile };
+export async function acquireProcessLogLock(file, options = {}) {
+    const fileSystem = { ...defaultFileSystem, ...options.fileSystem };
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+    const staleAfterMs = Math.max(options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS, 2_000);
+    const transientRetries = options.transientRetries ?? DEFAULT_TRANSIENT_RETRIES;
+    const operationTimeoutMs = options.timeoutMs ?? 10_000;
+    const platform = options.platform ?? process.platform;
+    const ownerPid = options.ownerPid ?? process.pid;
+    const token = (options.tokenFactory ?? randomUUID)();
+    const tokenHash = createHash("sha256").update(token).digest("hex");
+    const ownerName = `owner.${tokenHash}.json`;
+    const ownerPath = `${file}/${ownerName}`;
+    const candidate = `${file}.candidate-${ownerPid}-${tokenHash}`;
+    const deadline = now() + operationTimeoutMs;
+    const isProcessAlive = options.isProcessAlive ?? processIsAlive;
+    while (now() <= deadline) {
+        if (await publishCandidate(file, candidate, ownerName, ownerPid, token, fileSystem, now, platform)) {
+            const heartbeat = setInterval(() => { void touch(ownerPath, fileSystem, now); }, Math.max(1_000, Math.floor(staleAfterMs / 2)));
+            heartbeat.unref?.();
+            let released = false;
+            return async () => {
+                if (released)
+                    return;
+                released = true;
+                clearInterval(heartbeat);
+                const claimName = `claim.${tokenHash}.json`;
+                const releaseDeadline = now() + operationTimeoutMs;
+                try {
+                    await renameWithTransientWindowsRetry(ownerPath, `${file}/${claimName}`, fileSystem, platform, retryDelayMs, transientRetries, releaseDeadline, now, sleep);
+                }
+                catch (error) {
+                    if (errorCode(error) === "ENOENT")
+                        return;
+                    throw error;
+                }
+                await quarantineClaimed(file, ownerPid, tokenHash, "release", fileSystem, platform, retryDelayMs, transientRetries, releaseDeadline, now, sleep);
+            };
+        }
+        const state = await inspectState(file, fileSystem);
+        if (state === null)
+            continue;
+        if (state.kind === "legacy") {
+            const claimed = now() - state.mtimeMs >= staleAfterMs
+                && await claimLegacy(file, ownerPid, tokenHash, fileSystem);
+            if (claimed) {
+                await quarantineClaimed(file, ownerPid, tokenHash, "legacy", fileSystem, platform, retryDelayMs, transientRetries, deadline, now, sleep);
+                continue;
+            }
+        }
+        else {
+            const stale = now() - state.mtimeMs >= staleAfterMs;
+            const reclaimable = (state.kind === "owner" ? stale : true) && !isProcessAlive(state.pid);
+            if (reclaimable) {
+                const claimName = `claim.${tokenHash}.json`;
+                try {
+                    await renameWithTransientWindowsRetry(`${file}/${state.name}`, `${file}/${claimName}`, fileSystem, platform, retryDelayMs, transientRetries, deadline, now, sleep);
+                    await quarantineClaimed(file, ownerPid, tokenHash, "stale", fileSystem, platform, retryDelayMs, transientRetries, deadline, now, sleep);
+                    continue;
+                }
+                catch (error) {
+                    if (errorCode(error) !== "ENOENT")
+                        throw error;
+                }
+            }
+        }
+        await sleep(retryDelayMs);
+    }
+    throw new Error(`analysis process log lock timed out: ${file}`);
+}
+async function publishCandidate(file, candidate, ownerName, ownerPid, token, fileSystem, now, platform) {
+    await fileSystem.rm(candidate, { recursive: true, force: true });
+    await fileSystem.mkdir(candidate);
+    const ownerPath = `${candidate}/${ownerName}`;
+    try {
+        await fileSystem.writeFile(ownerPath, JSON.stringify({ kind: "owner", pid: ownerPid, token, acquiredAt: new Date(now()).toISOString() }), "utf8");
+        await touch(ownerPath, fileSystem, now);
+        await fileSystem.rename(candidate, file);
+        return true;
+    }
+    catch (error) {
+        await fileSystem.rm(candidate, { recursive: true, force: true });
+        const code = errorCode(error);
+        if (code === "EEXIST" || code === "ENOTEMPTY" || isTransientWindowsLockError(error, platform))
+            return false;
+        throw error;
+    }
+}
+async function inspectState(file, fileSystem) {
+    let names;
+    try {
+        names = await fileSystem.readdir(file);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+    const name = names.find(value => /^(owner|released|claim)\.[a-f0-9]{64}\.json$/.test(value)) ?? (names.includes("legacy-claim.json") ? "legacy-claim.json" : null);
+    if (!name)
+        return legacyState(file, fileSystem);
+    try {
+        const value = JSON.parse(await fileSystem.readFile(`${file}/${name}`, "utf8"));
+        const details = await fileSystem.stat(`${file}/${name}`);
+        if ((value.kind === "owner" || value.kind === "claim") && Number.isSafeInteger(value.pid)) {
+            return { name, kind: value.kind, pid: Number(value.pid), mtimeMs: details.mtimeMs };
+        }
+        return legacyState(file, fileSystem);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        if (error instanceof SyntaxError)
+            return legacyState(file, fileSystem);
+        throw error;
+    }
+}
+async function legacyState(file, fileSystem) {
+    try {
+        return { name: "legacy-claim.json", kind: "legacy", pid: 0, mtimeMs: (await fileSystem.stat(file)).mtimeMs };
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function claimLegacy(file, ownerPid, tokenHash, fileSystem) {
+    try {
+        await fileSystem.writeFile(`${file}/legacy-claim.json`, JSON.stringify({ kind: "claim", pid: ownerPid, tokenHash }), { encoding: "utf8", flag: "wx" });
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "EEXIST" || errorCode(error) === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function quarantineClaimed(file, ownerPid, tokenHash, reason, fileSystem, platform, retryDelayMs, transientRetries, deadline, now, sleep) {
+    const quarantine = `${file}.${reason}-${ownerPid}-${tokenHash}`;
+    try {
+        await renameWithTransientWindowsRetry(file, quarantine, fileSystem, platform, retryDelayMs, transientRetries, deadline, now, sleep);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return;
+        throw error;
+    }
+    await fileSystem.rm(quarantine, { recursive: true, force: true });
+}
+async function renameWithTransientWindowsRetry(oldPath, newPath, fileSystem, platform, retryDelayMs, transientRetries, deadline, now, sleep) {
+    let firstTransientError;
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await fileSystem.rename(oldPath, newPath);
+            return;
+        }
+        catch (error) {
+            if (!isTransientWindowsLockError(error, platform))
+                throw error;
+            firstTransientError ??= error;
+            if (attempt >= transientRetries || now() + retryDelayMs > deadline)
+                throw firstTransientError;
+            await sleep(retryDelayMs);
+        }
+    }
+}
+async function touch(path, fileSystem, now) {
+    const date = new Date(now());
+    await fileSystem.utimes(path, date, date).catch(error => { if (errorCode(error) !== "ENOENT")
+        throw error; });
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) !== "ESRCH";
+    }
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error ? String(error.code) : undefined;
+}
+export function isTransientWindowsLockError(error, platform = process.platform) {
+    const code = errorCode(error);
+    return platform === "win32" && (code === "EPERM" || code === "EACCES");
+}

package/dist/processes.js

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { basename, resolve } from "node:path";
+const execFileAsync = promisify(execFile);
+export function parseWowProcessRows(stdout, installs) {
+    if (!stdout.trim() || stdout.trim() === "null")
+        return [];
+    const decoded = JSON.parse(stdout);
+    const rows = (Array.isArray(decoded) ? decoded : [decoded]).filter((row) => typeof row === "object" && row !== null && !Array.isArray(row));
+    return rows.flatMap(row => {
+        const pid = Number(row.ProcessId);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            return [];
+        const observedExecutable = String(row.ExecutablePath ?? "");
+        let executable = observedExecutable;
+        let install;
+        if (observedExecutable) {
+            if (basename(observedExecutable).toLowerCase() !== "wow.exe")
+                return [];
+            install = installs.find(candidate => resolve(candidate.executable).toLowerCase() === resolve(observedExecutable).toLowerCase());
+        }
+        else if (row.Name === "Wow.exe" && installs.length === 1) {
+            install = installs[0];
+            executable = install.executable;
+        }
+        if (!install)
+            return [];
+        return [{
+                pid,
+                executable,
+                install,
+                commandLine: String(row.CommandLine ?? ""),
+                ...(typeof row.StartTime === "string" && row.StartTime.length > 0
+                    ? { startTime: row.StartTime }
+                    : {})
+            }];
+    });
+}
+export async function listWowProcesses(installs) {
+    const { stdout } = await execFileAsync("powershell.exe", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        "Get-CimInstance Win32_Process -Filter \"Name = 'Wow.exe'\" | Select-Object Name,ProcessId,ExecutablePath,CommandLine,@{Name='StartTime';Expression={$_.CreationDate.ToUniversalTime().ToString('o')}} | ConvertTo-Json -Compress"
+    ], { windowsHide: true });
+    return parseWowProcessRows(stdout, installs);
+}

package/dist/runtime-config.js

@@ -0,0 +1,399 @@
+import { accessSync, existsSync, readFileSync, statSync } from "node:fs";
+import { constants } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, delimiter, isAbsolute, join, normalize, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const STABLE_KEYS = new Set(["game_roots", "profile_root", "runtime_root", "log_level", "broker_idle_ms"]);
+const RUNTIME_STATE_KEYS = /^(?:pid|module_?base|build|build_?key|session_?id|hook|frida|attach(?:ment)?(?:_state)?)$/i;
+const DEFAULT_BROKER_IDLE_MS = 20 * 60 * 1000;
+const MAX_BATTLENET_PRODUCT_DB_BYTES = 16 * 1024 * 1024;
+const MAX_BATTLENET_STRING_BYTES = 32 * 1024;
+export function parseRuntimeArguments(argv) {
+    const result = { gameRoots: [] };
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--game-root" || argument === "--config") {
+            const value = argv[++index];
+            if (!value || value.startsWith("--"))
+                throw new Error(`${argument} requires a path`);
+            if (argument === "--game-root")
+                result.gameRoots.push(value);
+            else if (result.configPath)
+                throw new Error("--config may only be specified once");
+            else
+                result.configPath = value;
+            continue;
+        }
+        if (argument.startsWith("--game-root="))
+            result.gameRoots.push(requiredInlineValue(argument, "--game-root"));
+        else if (argument.startsWith("--config=")) {
+            if (result.configPath)
+                throw new Error("--config may only be specified once");
+            result.configPath = requiredInlineValue(argument, "--config");
+        }
+    }
+    return result;
+}
+export function parseRuntimeConfigToml(text, source = "config.toml") {
+    const result = {};
+    const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
+    let pending = "";
+    for (let lineNumber = 1; lineNumber <= lines.length; lineNumber += 1) {
+        pending = pending ? `${pending}\n${lines[lineNumber - 1]}` : lines[lineNumber - 1];
+        const line = stripTomlComment(pending).trim();
+        if (!line) {
+            pending = "";
+            continue;
+        }
+        if (line.startsWith("[") && !line.startsWith("[["))
+            throw new Error(`${source}:${lineNumber}: TOML tables are not supported`);
+        if (!isCompleteTomlValue(line))
+            continue;
+        pending = "";
+        const match = /^([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*([\s\S]+)$/.exec(line);
+        if (!match)
+            throw new Error(`${source}:${lineNumber}: invalid TOML assignment`);
+        const [, key, rawValue] = match;
+        if (!STABLE_KEYS.has(key)) {
+            const reason = RUNTIME_STATE_KEYS.test(key) ? "runtime state is not allowed" : "unknown setting";
+            throw new Error(`${source}:${lineNumber}: ${reason}: ${key}`);
+        }
+        if (key === "game_roots")
+            result.gameRoots = parseStringArray(rawValue, source, lineNumber);
+        else if (key === "profile_root")
+            result.profileRoot = parseTomlString(rawValue, source, lineNumber);
+        else if (key === "runtime_root")
+            result.runtimeRoot = parseTomlString(rawValue, source, lineNumber);
+        else if (key === "log_level")
+            result.logLevel = parseTomlString(rawValue, source, lineNumber);
+        else {
+            const value = Number(rawValue.replaceAll("_", ""));
+            if (!Number.isSafeInteger(value) || value < 0)
+                throw new Error(`${source}:${lineNumber}: broker_idle_ms must be a non-negative integer`);
+            result.brokerIdleMs = value;
+        }
+    }
+    if (pending.trim())
+        throw new Error(`${source}:${lines.length}: unterminated TOML value`);
+    return result;
+}
+export function resolveRuntimeConfig(options = {}) {
+    const argv = options.argv ?? process.argv.slice(2);
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    const packageRoot = resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), ".."));
+    const args = parseRuntimeArguments(argv);
+    const localAppData = resolve(env.LOCALAPPDATA || join(homedir(), "AppData", "Local"));
+    const userConfigPath = join(localAppData, "wowdump", "config.toml");
+    const diagnostics = [];
+    const explicitConfigPath = args.configPath ? normalizePath(args.configPath, cwd) : undefined;
+    const userConfig = readConfig(userConfigPath, false, diagnostics);
+    const explicitConfig = explicitConfigPath ? readConfig(explicitConfigPath, true, diagnostics) : undefined;
+    const profileSetting = explicitConfig?.profileRoot !== undefined
+        ? { value: explicitConfig.profileRoot, base: dirname(explicitConfigPath) }
+        : userConfig?.profileRoot !== undefined
+            ? { value: userConfig.profileRoot, base: dirname(userConfigPath) }
+            : undefined;
+    const runtimeSetting = explicitConfig?.runtimeRoot !== undefined
+        ? { value: explicitConfig.runtimeRoot, base: dirname(explicitConfigPath) }
+        : userConfig?.runtimeRoot !== undefined
+            ? { value: userConfig.runtimeRoot, base: dirname(userConfigPath) }
+            : undefined;
+    const candidates = [
+        { source: "cli", roots: args.gameRoots, base: cwd },
+        { source: "environment", roots: splitEnvironmentPaths(env.WOWDUMP_GAME_ROOTS), base: cwd },
+        { source: "explicit-config", roots: explicitConfig?.gameRoots ?? [], base: explicitConfigPath ? dirname(explicitConfigPath) : cwd },
+        { source: "user-config", roots: userConfig?.gameRoots ?? [], base: dirname(userConfigPath) },
+        { source: "deprecated-environment", roots: splitEnvironmentPaths(env.WOW_ROOT), base: cwd },
+        { source: "auto-detect", roots: (options.autoDetect ?? detectGameRoots)(env), base: cwd }
+    ];
+    const selected = candidates.find(candidate => candidate.roots.some(root => root.trim())) ?? { source: "none", roots: [], base: cwd };
+    if (selected.source === "deprecated-environment")
+        diagnostics.push({
+            level: "warning", code: "deprecated-wow-root", message: "WOW_ROOT is deprecated; use --game-root or WOWDUMP_GAME_ROOTS"
+        });
+    const gameRoots = normalizePaths(selected.roots, selected.base);
+    for (const path of gameRoots)
+        validateGameRoot(path, diagnostics);
+    return Object.freeze({
+        gameRoots: Object.freeze(gameRoots),
+        gameRootSource: selected.source,
+        configPath: explicitConfigPath,
+        userConfigPath,
+        profileRoot: profileSetting ? normalizePath(profileSetting.value, profileSetting.base) : join(packageRoot, "resources", "builds"),
+        runtimeRoot: runtimeSetting ? normalizePath(runtimeSetting.value, runtimeSetting.base) : join(localAppData, "wowdump"),
+        logLevel: explicitConfig?.logLevel ?? userConfig?.logLevel ?? "info",
+        brokerIdleMs: explicitConfig?.brokerIdleMs ?? userConfig?.brokerIdleMs ?? DEFAULT_BROKER_IDLE_MS,
+        diagnostics: Object.freeze(diagnostics)
+    });
+}
+export function detectGameRoots(env = process.env) {
+    const drives = [env.ProgramFiles, env["ProgramFiles(x86)"], env.PUBLIC && join(dirname(env.PUBLIC), "Program Files"), "C:/Program Files (x86)"]
+        .filter((value) => Boolean(value));
+    const candidates = drives.flatMap(root => [join(root, "World of Warcraft"), join(root, "World of Warcraft Beta")]);
+    const battleNetRoots = readBattleNetProductRoots(env).sort(comparePaths);
+    return normalizePaths([...battleNetRoots, ...candidates.filter(looksLikeGameRoot)], process.cwd());
+}
+function readBattleNetProductRoots(env) {
+    const programData = env.ProgramData || "C:/ProgramData";
+    const databasePath = join(programData, "Battle.net", "Agent", "product.db");
+    try {
+        const stat = statSync(databasePath);
+        if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_BATTLENET_PRODUCT_DB_BYTES)
+            return [];
+        const database = readFileSync(databasePath);
+        const records = protobufFields(database);
+        if (!records)
+            return [];
+        const roots = [];
+        for (const record of records) {
+            if (record.number !== 1 || record.wire !== 2)
+                continue;
+            const productFields = protobufFields(record.value);
+            if (!productFields)
+                return [];
+            const uid = protobufString(lengthDelimitedValue(productFields, 1));
+            if (!uid || !/^wow(?:_|$)/i.test(uid))
+                continue;
+            for (const installField of productFields) {
+                if (installField.number !== 3 || installField.wire !== 2)
+                    continue;
+                const installFields = protobufFields(installField.value);
+                if (!installFields)
+                    return [];
+                const root = protobufString(lengthDelimitedValue(installFields, 1));
+                if (root && isAbsolute(root) && looksLikeGameRoot(root))
+                    roots.push(root);
+            }
+        }
+        return roots;
+    }
+    catch {
+        return [];
+    }
+}
+function lengthDelimitedValue(fields, number) {
+    const field = fields.find(candidate => candidate.number === number && candidate.wire === 2);
+    return field?.wire === 2 ? field.value : undefined;
+}
+function protobufFields(buffer) {
+    const fields = [];
+    let offset = 0;
+    while (offset < buffer.length) {
+        const key = readProtobufVarint(buffer, offset);
+        if (!key || key.value === 0)
+            return undefined;
+        offset = key.next;
+        const number = Math.floor(key.value / 8);
+        const wire = key.value & 7;
+        if (number <= 0)
+            return undefined;
+        if (wire === 0) {
+            const value = readProtobufVarint(buffer, offset);
+            if (!value)
+                return undefined;
+            fields.push({ number, wire, value: value.value });
+            offset = value.next;
+        }
+        else if (wire === 1 || wire === 5) {
+            const length = wire === 1 ? 8 : 4;
+            if (offset + length > buffer.length)
+                return undefined;
+            fields.push({ number, wire, value: buffer.subarray(offset, offset + length) });
+            offset += length;
+        }
+        else if (wire === 2) {
+            const length = readProtobufVarint(buffer, offset);
+            if (!length || length.value > buffer.length - length.next)
+                return undefined;
+            offset = length.next;
+            fields.push({ number, wire, value: buffer.subarray(offset, offset + length.value) });
+            offset += length.value;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return fields;
+}
+function readProtobufVarint(buffer, offset) {
+    let value = 0n;
+    for (let index = 0; index < 10 && offset + index < buffer.length; index += 1) {
+        const byte = buffer[offset + index];
+        value |= BigInt(byte & 0x7f) << BigInt(index * 7);
+        if ((byte & 0x80) === 0) {
+            if (value > BigInt(Number.MAX_SAFE_INTEGER))
+                return undefined;
+            return { value: Number(value), next: offset + index + 1 };
+        }
+    }
+    return undefined;
+}
+function protobufString(value) {
+    if (!value || value.length === 0 || value.length > MAX_BATTLENET_STRING_BYTES)
+        return undefined;
+    try {
+        const decoded = new TextDecoder("utf-8", { fatal: true }).decode(value);
+        if (decoded.includes("\0"))
+            return undefined;
+        return decoded;
+    }
+    catch {
+        return undefined;
+    }
+}
+function comparePaths(left, right) {
+    return left.toLowerCase().localeCompare(right.toLowerCase(), "en") || left.localeCompare(right, "en");
+}
+function readConfig(path, required, diagnostics) {
+    try {
+        return parseRuntimeConfigToml(readFileSync(path, "utf8"), path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" && !required)
+            return undefined;
+        diagnostics.push({ level: "error", code: code === "ENOENT" ? "config-not-found" : "invalid-config", message: error instanceof Error ? error.message : String(error), path });
+        return undefined;
+    }
+}
+function validateGameRoot(path, diagnostics) {
+    try {
+        accessSync(path, constants.R_OK);
+        if (!statSync(path).isDirectory())
+            throw new Error("path is not a directory");
+        if (!looksLikeGameRoot(path))
+            diagnostics.push({ level: "warning", code: "unrecognized-game-root", message: `No .build.info or WoW installation was found at ${path}`, path });
+    }
+    catch (error) {
+        diagnostics.push({ level: "error", code: "unreadable-game-root", message: `Game root is not a readable directory: ${path} (${error instanceof Error ? error.message : String(error)})`, path });
+    }
+}
+function looksLikeGameRoot(path) {
+    if (!existsSync(path))
+        return false;
+    if (existsSync(join(path, ".build.info")))
+        return true;
+    for (const flavor of ["_retail_", "_classic_", "_classic_era_", "_beta_"])
+        if (existsSync(join(path, flavor, "Wow.exe")))
+            return true;
+    return false;
+}
+function splitEnvironmentPaths(value) {
+    if (!value?.trim())
+        return [];
+    const separator = value.includes(";") ? ";" : delimiter;
+    return value.split(separator).map(item => item.trim()).filter(Boolean);
+}
+function normalizePaths(paths, base) {
+    const seen = new Set();
+    const result = [];
+    for (const value of paths) {
+        if (!value.trim())
+            continue;
+        const path = normalizePath(value, base);
+        const key = process.platform === "win32" ? path.toLowerCase() : path;
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(path);
+        }
+    }
+    return result;
+}
+function normalizePath(value, base) {
+    const expanded = value === "~" ? homedir() : value.startsWith("~/") || value.startsWith("~\\") ? join(homedir(), value.slice(2)) : value;
+    return normalize(isAbsolute(expanded) ? resolve(expanded) : resolve(base, expanded));
+}
+function requiredInlineValue(argument, name) {
+    const value = argument.slice(name.length + 1);
+    if (!value)
+        throw new Error(`${name} requires a path`);
+    return value;
+}
+function stripTomlComment(line) {
+    let quoted = false;
+    let escaped = false;
+    for (let index = 0; index < line.length; index += 1) {
+        const char = line[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quoted) {
+            escaped = true;
+            continue;
+        }
+        if (char === '"')
+            quoted = !quoted;
+        if (char === "#" && !quoted)
+            return line.slice(0, index);
+    }
+    return line;
+}
+function isCompleteTomlValue(line) {
+    let quoted = false;
+    let escaped = false;
+    let brackets = 0;
+    for (const char of line) {
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quoted) {
+            escaped = true;
+            continue;
+        }
+        if (char === '"')
+            quoted = !quoted;
+        else if (!quoted && char === "[")
+            brackets += 1;
+        else if (!quoted && char === "]")
+            brackets -= 1;
+    }
+    return !quoted && brackets === 0;
+}
+function parseStringArray(raw, source, line) {
+    const value = raw.trim();
+    if (!value.startsWith("[") || !value.endsWith("]"))
+        throw new Error(`${source}:${line}: game_roots must be an array of strings`);
+    const inner = value.slice(1, -1).trim();
+    if (!inner)
+        return [];
+    const items = [];
+    let start = 0;
+    let quoted = false;
+    let escaped = false;
+    for (let index = 0; index <= inner.length; index += 1) {
+        const char = inner[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quoted) {
+            escaped = true;
+            continue;
+        }
+        if (char === '"')
+            quoted = !quoted;
+        if ((char === "," && !quoted) || index === inner.length) {
+            const item = inner.slice(start, index).trim();
+            if (item)
+                items.push(parseTomlString(item, source, line));
+            start = index + 1;
+        }
+    }
+    if (quoted)
+        throw new Error(`${source}:${line}: unterminated string`);
+    return items;
+}
+function parseTomlString(raw, source, line) {
+    const value = raw.trim();
+    if (!/^"(?:[^"\\]|\\.)*"$/.test(value))
+        throw new Error(`${source}:${line}: expected a basic TOML string`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${source}:${line}: invalid string escape`);
+    }
+}