modwright 0.1.0

package/dist/core/text/xml.js

@@ -0,0 +1,58 @@
+const TAG_RE = /<([a-zA-Z][\w:-]*)((?:\s+[\w:-]+\s*=\s*"[^"]*")*)\s*(\/?)>|<\/([a-zA-Z][\w:-]*)\s*>/g;
+const ATTR_RE = /([\w:-]+)\s*=\s*"([^"]*)"/g;
+function decodeEntities(s) {
+    return s
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+function parseAttrs(raw) {
+    const attrs = {};
+    let m;
+    ATTR_RE.lastIndex = 0;
+    while ((m = ATTR_RE.exec(raw))) {
+        attrs[m[1]] = decodeEntities(m[2]);
+    }
+    return attrs;
+}
+export function parseXml(xml) {
+    const cleaned = xml
+        .replace(/^/, "")
+        .replace(/<\?xml[^?]*\?>/, "")
+        .replace(/<!--[\s\S]*?-->/g, "");
+    const root = { tag: "#document", attrs: {}, children: [], text: "" };
+    const stack = [root];
+    let lastIndex = 0;
+    let m;
+    TAG_RE.lastIndex = 0;
+    while ((m = TAG_RE.exec(cleaned))) {
+        const between = cleaned.slice(lastIndex, m.index);
+        if (between.trim().length > 0) {
+            stack[stack.length - 1].text += decodeEntities(between);
+        }
+        lastIndex = TAG_RE.lastIndex;
+        const [, openTag, attrRaw, selfClose, closeTag] = m;
+        if (closeTag) {
+            if (stack.length > 1)
+                stack.pop();
+            continue;
+        }
+        const el = { tag: openTag, attrs: parseAttrs(attrRaw ?? ""), children: [], text: "" };
+        stack[stack.length - 1].children.push(el);
+        if (!selfClose)
+            stack.push(el);
+    }
+    return root.children[0] ?? root;
+}
+export function findAll(root, tag) {
+    const out = [];
+    (function walk(el) {
+        if (el.tag === tag)
+            out.push(el);
+        for (const child of el.children)
+            walk(child);
+    })(root);
+    return out;
+}

package/dist/core/toolchain/datafetch.js

@@ -0,0 +1,151 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { executePlan } from "../safety/index.js";
+import { userDataDir } from "../home.js";
+import { planDataMemory } from "./remember.js";
+export function defaultDataFolder(id) {
+    return path.join(userDataDir(), "data", id);
+}
+export function planDataFetch(dataId, known, destination) {
+    const need = known.find((k) => k.id === dataId);
+    if (!need)
+        return { ok: false, error: `Unknown data folder "${dataId}". Known: ${known.map((k) => k.id).join(", ") || "none"}.` };
+    if (!need.fetch) {
+        return { ok: false, error: `ModWright cannot fetch ${need.id} (${need.what}); point at it once with check_toolchain action=remember data=${need.id} dataPath=<folder>.` };
+    }
+    if (destination !== undefined && !path.isAbsolute(destination)) {
+        return { ok: false, error: `dataPath must be absolute ("${destination}" is relative).` };
+    }
+    const spec = need.fetch;
+    const origins = [...new Set(spec.files.map((f) => new URL(f.url).origin))];
+    return {
+        ok: true,
+        plan: {
+            data: need.id,
+            destination: destination ?? defaultDataFolder(need.id),
+            source: spec.source,
+            license: spec.license,
+            delayMs: spec.delayMs,
+            userAgent: spec.userAgent,
+            robotsToken: spec.robotsToken,
+            files: spec.files,
+            robots: origins.map((o) => `${o}/robots.txt`),
+            estimatedSeconds: Math.ceil((spec.files.length * (spec.delayMs + 500)) / 1000),
+        },
+    };
+}
+export function robotsRules(text, token) {
+    const groups = [];
+    let current;
+    let lastWasAgent = false;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.replace(/#.*/, "").trim();
+        const m = /^([A-Za-z-]+)\s*:\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const key = (m[1] ?? "").toLowerCase();
+        const value = (m[2] ?? "").trim();
+        if (key === "user-agent") {
+            if (!current || !lastWasAgent) {
+                current = { agents: [], rules: [] };
+                groups.push(current);
+            }
+            current.agents.push(value.toLowerCase());
+            lastWasAgent = true;
+            continue;
+        }
+        lastWasAgent = false;
+        if (!current)
+            continue;
+        if ((key === "allow" || key === "disallow") && value !== "")
+            current.rules.push({ allow: key === "allow", pattern: value });
+    }
+    const t = token.toLowerCase();
+    const named = groups.filter((g) => g.agents.some((a) => a !== "*" && t.includes(a)));
+    const chosen = named.length > 0 ? named : groups.filter((g) => g.agents.includes("*"));
+    return chosen.flatMap((g) => g.rules);
+}
+function patternMatches(pattern, target) {
+    const anchored = pattern.endsWith("$");
+    const body = anchored ? pattern.slice(0, -1) : pattern;
+    const re = new RegExp("^" + body.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + (anchored ? "$" : ""));
+    return re.test(target);
+}
+export function robotsAllows(rules, pathAndQuery) {
+    let best;
+    for (const rule of rules) {
+        if (!patternMatches(rule.pattern, pathAndQuery))
+            continue;
+        if (!best || rule.pattern.length > best.pattern.length || (rule.pattern.length === best.pattern.length && rule.allow))
+            best = rule;
+    }
+    return best ? best.allow : true;
+}
+export async function applyDataFetch(plan, ctx = {}) {
+    const fetchImpl = ctx.fetchImpl ?? fetch;
+    const delayMs = ctx.delayMs ?? plan.delayMs;
+    const headers = { "User-Agent": plan.userAgent };
+    const rulesByOrigin = new Map();
+    for (const robotsUrl of plan.robots) {
+        const origin = new URL(robotsUrl).origin;
+        try {
+            const res = await fetchImpl(robotsUrl, { headers });
+            if (res.status === 404)
+                rulesByOrigin.set(origin, []);
+            else if (!res.ok)
+                rulesByOrigin.set(origin, undefined);
+            else
+                rulesByOrigin.set(origin, robotsRules(await res.text(), plan.robotsToken));
+        }
+        catch {
+            rulesByOrigin.set(origin, undefined);
+        }
+    }
+    await fs.mkdir(plan.destination, { recursive: true });
+    const saved = [];
+    const failed = [];
+    const refused = [];
+    let first = true;
+    for (const { url, file } of plan.files) {
+        const u = new URL(url);
+        const rules = rulesByOrigin.get(u.origin);
+        if (rules === undefined) {
+            refused.push(`${file}: ${u.origin}/robots.txt could not be read`);
+            continue;
+        }
+        if (!robotsAllows(rules, u.pathname + u.search)) {
+            refused.push(`${file}: disallowed by ${u.origin}/robots.txt`);
+            continue;
+        }
+        if (!first && delayMs > 0)
+            await new Promise((r) => setTimeout(r, delayMs));
+        first = false;
+        try {
+            const res = await fetchImpl(url, { headers: { ...headers, Accept: "text/html" }, redirect: "follow" });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const body = await res.text();
+            const target = path.join(plan.destination, file);
+            const temp = `${target}.part`;
+            await fs.writeFile(temp, body, "utf8");
+            await fs.rename(temp, target);
+            saved.push(file);
+        }
+        catch (error) {
+            failed.push({ file, error: error.message });
+        }
+    }
+    let remembered = false;
+    if (saved.length > 0) {
+        const known = ctx.known ?? [{ id: plan.data, envVar: "", what: plan.source }];
+        const memory = await planDataMemory("remember", plan.data, plan.destination, known, { file: ctx.configFile });
+        if (memory.ok) {
+            const report = await executePlan(memory.plan, {
+                mode: "apply",
+                confidence: { level: "high", assumptions: ["The per-user config is ModWright's own file."] },
+            });
+            remembered = report.applied;
+        }
+    }
+    return { ok: true, destination: plan.destination, saved, failed, refused, remembered };
+}

package/dist/core/toolchain/env.js

@@ -0,0 +1,63 @@
+import * as os from "node:os";
+import * as path from "node:path";
+function lookup(env, name) {
+    const wanted = name.toLowerCase();
+    for (const [key, value] of Object.entries(env)) {
+        if (key.toLowerCase() === wanted && value !== undefined && value !== "")
+            return value;
+    }
+    return undefined;
+}
+function defaultHost() {
+    const arch = os.arch();
+    return {
+        is64Bit: arch === "x64" || arch === "arm64" || Boolean(process.env.PROCESSOR_ARCHITEW6432),
+        cpuCount: os.cpus().length,
+        hostname: os.hostname(),
+    };
+}
+export function missingWindowsEnv(env, host = defaultHost()) {
+    const win = path.win32;
+    const systemRootRaw = lookup(env, "SystemRoot") ?? lookup(env, "windir");
+    const systemDrive = lookup(env, "SystemDrive") ?? (systemRootRaw ? systemRootRaw.slice(0, 2) : "C:");
+    const systemRoot = systemRootRaw ?? win.join(`${systemDrive}\\`, "Windows");
+    const programFiles = lookup(env, "ProgramW6432") ?? lookup(env, "ProgramFiles") ?? win.join(`${systemDrive}\\`, "Program Files");
+    const programFilesX86 = win.join(`${systemDrive}\\`, "Program Files (x86)");
+    const programData = win.join(`${systemDrive}\\`, "ProgramData");
+    const wanted = [
+        ["SystemDrive", systemDrive],
+        ["SystemRoot", systemRoot],
+        ["windir", systemRoot],
+        ["ComSpec", win.join(systemRoot, "System32", "cmd.exe")],
+        ["PATHEXT", ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC"],
+        ["OS", "Windows_NT"],
+        ["ProgramFiles", programFiles],
+        ["CommonProgramFiles", win.join(programFiles, "Common Files")],
+        ["ProgramFiles(x86)", host.is64Bit ? programFilesX86 : undefined],
+        ["CommonProgramFiles(x86)", host.is64Bit ? win.join(programFilesX86, "Common Files") : undefined],
+        ["ProgramW6432", host.is64Bit ? programFiles : undefined],
+        ["CommonProgramW6432", host.is64Bit ? win.join(programFiles, "Common Files") : undefined],
+        ["ProgramData", programData],
+        ["ALLUSERSPROFILE", programData],
+        ["PUBLIC", win.join(`${systemDrive}\\`, "Users", "Public")],
+        ["TMP", lookup(env, "TEMP")],
+        ["NUMBER_OF_PROCESSORS", host.cpuCount > 0 ? String(host.cpuCount) : undefined],
+        ["COMPUTERNAME", host.hostname ? host.hostname.toUpperCase() : undefined],
+    ];
+    const out = {};
+    for (const [name, value] of wanted) {
+        if (value === undefined)
+            continue;
+        if (lookup(env, name) !== undefined)
+            continue;
+        out[name] = value;
+    }
+    return out;
+}
+export function toolEnvironment(extra, base = process.env, platform = process.platform, host) {
+    const merged = { ...base, ...(extra ?? {}) };
+    if (platform !== "win32")
+        return { env: merged, filled: [] };
+    const missing = missingWindowsEnv(merged, host);
+    return { env: { ...merged, ...missing }, filled: Object.keys(missing) };
+}

package/dist/core/toolchain/features.js

@@ -0,0 +1,170 @@
+import { normalizeBuildSteps } from "../project/build-steps.js";
+import { TOOL_SPECS } from "./specs.js";
+export function toolsForStep(step) {
+    switch (step.step) {
+        case "blender-export":
+            return ["blender"];
+        case "wolvenkit-import":
+        case "wolvenkit-pack":
+            return ["wolvenkit-cli"];
+        case "divine-lsx-to-lsf":
+        case "divine-loca":
+        case "divine-create-package":
+            return ["divine"];
+        case "verify-listing":
+            return [step.of.toLowerCase().endsWith(".pak") ? "divine" : "wolvenkit-cli"];
+        case "exec":
+            return TOOL_SPECS.some((s) => s.id === step.command) ? [step.command] : [];
+        default:
+            return [];
+    }
+}
+export function toolsToLocate(surface, options = {}) {
+    const ids = new Set();
+    for (const spec of TOOL_SPECS)
+        if (spec.usedBy.includes(surface.id))
+            ids.add(spec.id);
+    for (const need of surface.toolNeeds ?? [])
+        for (const t of need.tools ?? [])
+            ids.add(t);
+    for (const v of surface.validators ?? [])
+        for (const t of v.needs?.toolchain ?? [])
+            ids.add(t);
+    if (options.project)
+        for (const step of normalizeBuildSteps(options.project))
+            for (const t of toolsForStep(step))
+                ids.add(t);
+    return [...ids];
+}
+function stateOf(tools, data = []) {
+    if (tools.some((t) => !t.found && !t.optional) || data.some((d) => !d.set))
+        return "blocked";
+    if (tools.some((t) => !t.found))
+        return "degraded";
+    return "ready";
+}
+export function featureReadiness(surface, locations, options = {}) {
+    const env = options.env ?? process.env;
+    const byId = new Map(locations.map((l) => [l.id, l]));
+    const tool = (id, optional) => {
+        const l = byId.get(id);
+        return {
+            id,
+            found: l?.found ?? false,
+            optional,
+            ...(l?.path ? { path: l.path } : {}),
+            ...(l?.source ? { source: l.source } : {}),
+            ...(l && !l.found && l.hint ? { hint: l.hint } : {}),
+            ...(!(l?.found ?? false) && TOOL_SPECS.find((s) => s.id === id)?.managed ? { installable: true } : {}),
+        };
+    };
+    const fromNeed = (need) => {
+        const tools = (need.tools ?? []).map((id) => tool(id, need.optional ?? false));
+        const data = (need.data ?? []).map(({ fetch: fetchSpec, ...d }) => {
+            const base = { ...d, ...(fetchSpec ? { fetchable: true } : {}) };
+            const fromEnv = env[d.envVar];
+            const remembered = options.userData?.[d.id]?.path;
+            if (fromEnv)
+                return { ...base, set: true, source: "env", path: fromEnv };
+            if (remembered)
+                return { ...base, set: true, source: "user", path: remembered };
+            return { ...base, set: false };
+        });
+        return { feature: need.feature, state: stateOf(tools, data), tools, ...(data.length > 0 ? { data } : {}), note: need.note };
+    };
+    const declared = (feature) => (surface.toolNeeds ?? []).filter((n) => n.feature === feature);
+    const merge = (feature, needs, fallbackNote) => {
+        if (needs.length === 0)
+            return { feature, state: "ready", tools: [], note: fallbackNote };
+        const parts = needs.map(fromNeed);
+        const tools = parts.flatMap((p) => p.tools);
+        const data = parts.flatMap((p) => p.data ?? []);
+        return { feature, state: stateOf(tools, data), tools, ...(data.length > 0 ? { data } : {}), note: parts.map((p) => p.note).join(" ") };
+    };
+    const rows = [];
+    const covered = new Set();
+    const cover = (r) => {
+        for (const t of r.tools)
+            covered.add(t.id);
+        rows.push(r);
+    };
+    if (surface.logs)
+        cover({ feature: "logs", state: "ready", tools: [], note: "triage_logs and read_log need no external tool." });
+    if (surface.compat)
+        cover({ feature: "compat", state: "ready", tools: [], note: "check_compat reads the install directly; no external tool." });
+    if (surface.index)
+        cover(merge("index", declared("index"), "build_index needs no external tool for this game."));
+    const validators = surface.validators ?? [];
+    if (validators.length > 0) {
+        const perTool = new Map();
+        let indexRules = 0;
+        for (const v of validators) {
+            for (const t of v.needs?.toolchain ?? [])
+                perTool.set(t, (perTool.get(t) ?? 0) + 1);
+            if (v.needs?.index)
+                indexRules++;
+        }
+        const tools = [...perTool.keys()].map((id) => tool(id, true));
+        const missingTools = tools.filter((t) => !t.found);
+        const indexMissing = indexRules > 0 && options.indexBuilt === false;
+        const skipped = missingTools.map((t) => `${perTool.get(t.id)} need ${t.id}`);
+        if (indexMissing)
+            skipped.push(`${indexRules} need the vanilla index (build_index)`);
+        cover({
+            feature: "validate",
+            state: missingTools.length > 0 || indexMissing ? "degraded" : "ready",
+            tools,
+            note: `${validators.length} rules.` +
+                (skipped.length > 0 ? ` Skipped until available: ${skipped.join("; ")}; the rest run now.` : indexRules > 0 && options.indexBuilt === undefined ? ` ${indexRules} of them need the vanilla index.` : " All of them can run."),
+        });
+    }
+    if (options.project) {
+        const steps = normalizeBuildSteps(options.project);
+        const ids = [...new Set(steps.flatMap(toolsForStep))];
+        const tools = ids.map((id) => tool(id, false));
+        const kinds = [...new Set(steps.map((s) => s.step))];
+        cover({
+            feature: "build",
+            state: steps.length === 0 ? "ready" : stateOf(tools),
+            tools,
+            note: steps.length === 0 ? `${options.project.name} declares no build steps.` : `${options.project.name}'s ${steps.length} build steps (${kinds.join(", ")}).`,
+        });
+    }
+    else if (declared("build").length > 0) {
+        const row = merge("build", declared("build"), "");
+        cover({ ...row, note: `${row.note} With a project (projectPath), its own build steps decide this row exactly.` });
+    }
+    for (const need of surface.toolNeeds ?? []) {
+        if (need.feature === "index" || need.feature === "build")
+            continue;
+        cover(fromNeed(need));
+    }
+    const rest = TOOL_SPECS.filter((s) => s.usedBy.includes(surface.id) && !covered.has(s.id)).map((s) => tool(s.id, true));
+    if (rest.length > 0) {
+        rows.push({
+            feature: "exec-steps",
+            state: "optional",
+            tools: rest,
+            note: "Run only by exec build steps a project declares (or by hand); none is needed until a project names one.",
+        });
+    }
+    return rows;
+}
+export function readinessSummary(rows) {
+    const ready = rows.filter((r) => r.state === "ready").map((r) => r.feature);
+    const waiting = rows
+        .filter((r) => r.state === "blocked" || r.state === "degraded")
+        .map((r) => {
+        const missing = [...r.tools.filter((t) => !t.found).map((t) => t.id), ...(r.data ?? []).filter((d) => !d.set).map((d) => d.what)];
+        return `${r.feature} ${r.state === "blocked" ? "needs" : "works without"} ${missing.length > 0 ? missing.join(", ") : "the index"}`;
+    });
+    const installable = [...new Set(rows.filter((r) => r.state === "blocked" || r.state === "degraded").flatMap((r) => r.tools.filter((t) => t.installable).map((t) => t.id)))];
+    const unsetData = rows.flatMap((r) => (r.data ?? []).filter((d) => !d.set));
+    const offer = (installable.length > 0 ? ` ModWright can install ${installable.join(" and ")} itself: check_toolchain action=install tool=<id>.` : "") +
+        unsetData
+            .map((d) => d.fetchable
+            ? ` ModWright can fetch ${d.id} itself: check_toolchain action=install data=${d.id}.`
+            : ` Remember that folder once: check_toolchain action=remember data=${d.id} dataPath=<folder>.`)
+            .join("");
+    return `Ready now: ${ready.length > 0 ? ready.join(", ") : "nothing"}.${waiting.length > 0 ? ` ${waiting.join("; ")}.${offer}` : " Nothing else to install."}`;
+}

package/dist/core/toolchain/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./specs.js";
+export * from "./locate.js";
+export * from "./run.js";
+export { planDataMemory, planToolMemory } from "./remember.js";
+export { featureReadiness, readinessSummary, toolsForStep, toolsToLocate } from "./features.js";
+export { applyManagedInstall, findBasePython, planManagedInstall } from "./install.js";
+export { applyDataFetch, defaultDataFolder, planDataFetch, robotsAllows, robotsRules } from "./datafetch.js";

package/dist/core/toolchain/install.js

@@ -0,0 +1,191 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, promises as fs } from "node:fs";
+import * as path from "node:path";
+import { userDataDir } from "../home.js";
+import { executePlan, planFile, planMkdir } from "../safety/index.js";
+import { loadUserConfig, userConfigFile, userConfigWritePlan } from "../userconfig.js";
+import { runTool } from "./run.js";
+import { TOOL_SPECS } from "./specs.js";
+const CONFIDENCE = { level: "high", assumptions: ["Writes only under ModWright's own per-user directories."] };
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+async function fileSha256(file) {
+    try {
+        return sha256Hex(await fs.readFile(file));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function findBasePython(min) {
+    const candidates = process.platform === "win32" ? [["py", ["-3"]], ["python", []], ["python3", []]] : [["python3", []], ["python", []]];
+    for (const [command, args] of candidates) {
+        const r = spawnSync(command, [...args, "-c", "import sys; print(sys.version_info[0], sys.version_info[1], sys.executable)"], { encoding: "utf8", timeout: 15_000, windowsHide: true });
+        const m = /^(\d+) (\d+) (.+)$/m.exec(r.stdout ?? "");
+        if (r.status !== 0 || !m)
+            continue;
+        const version = [Number(m[1]), Number(m[2])];
+        if (version[0] > min[0] || (version[0] === min[0] && version[1] >= min[1]))
+            return { command, args, version, executable: m[3].trim() };
+    }
+    return undefined;
+}
+function pickAsset(assets, platform, arch) {
+    return assets.find((a) => a.platform === platform && a.arch === arch);
+}
+function venvPython(dir, platform) {
+    return platform === "win32" ? path.join(dir, "Scripts", "python.exe") : path.join(dir, "bin", "python");
+}
+export async function planManagedInstall(toolId, ctx = {}) {
+    const specs = ctx.specs ?? TOOL_SPECS;
+    const spec = specs.find((s) => s.id === toolId);
+    if (!spec)
+        return { ok: false, error: `Unknown tool "${toolId}". Known: ${specs.map((s) => s.id).join(", ")}.` };
+    const managed = spec.managed;
+    if (!managed) {
+        const installable = specs.filter((s) => s.managed).map((s) => s.id);
+        return { ok: false, error: `ModWright does not install ${spec.label}: install it yourself${spec.homepage ? ` (${spec.homepage})` : ""}, then check_toolchain action=remember. Installable today: ${installable.join(", ")}.` };
+    }
+    const platform = ctx.platform ?? process.platform;
+    const arch = ctx.arch ?? process.arch;
+    const configFile = ctx.configFile ?? userConfigFile();
+    const loaded = await loadUserConfig(configFile);
+    if (loaded.problems.length > 0)
+        return { ok: false, error: `${loaded.problems.join(" ")} Fix or remove ${configFile} first; an install records itself there.` };
+    const targetDir = path.join(ctx.dataDir ?? userDataDir(), "tools", spec.id, managed.version);
+    const now = (ctx.now ?? (() => new Date()))().toISOString();
+    if (managed.kind === "download") {
+        const asset = pickAsset(managed.assets, platform, arch);
+        if (!asset) {
+            return { ok: false, error: `${spec.label} ${managed.version} has no pinned release for ${platform}/${arch}. Pinned: ${managed.assets.map((a) => `${a.platform}/${a.arch}`).join(", ")}.` };
+        }
+        const executable = path.join(targetDir, platform === "win32" ? managed.fileName.win32 : managed.fileName.other);
+        const alreadyInstalled = (await fileSha256(executable)) === asset.sha256;
+        const steps = alreadyInstalled
+            ? []
+            : [{ kind: "download", url: asset.url, sizeBytes: asset.sizeBytes, sha256: asset.sha256, to: executable }];
+        return {
+            ok: true,
+            plan: {
+                tool: spec.id,
+                label: spec.label,
+                version: managed.version,
+                license: managed.license,
+                kind: "download",
+                targetDir,
+                executable,
+                steps,
+                download: alreadyInstalled ? 0 : asset.sizeBytes,
+                alreadyInstalled,
+                configFile,
+                configEntry: { path: executable, installedBy: "modwright", version: managed.version, sha256: asset.sha256, source: asset.url, rememberedAt: now },
+                notes: alreadyInstalled
+                    ? [`The pinned ${spec.label} is already at ${executable} (sha256 matches); only the config entry is written.`]
+                    : [`The file is checked against the pinned size and sha256 before anything is written; a mismatch leaves the disk untouched.`],
+            },
+        };
+    }
+    const base = await (ctx.findPython ?? (() => findBasePython(managed.pythonMin)))();
+    if (!base) {
+        const install = platform === "win32" ? "winget install Python.Python.3.12" : platform === "darwin" ? "brew install python" : "your distribution's python3 and python3-venv packages";
+        return { ok: false, error: `${spec.label} is built from a Python you already have, and none ${managed.pythonMin.join(".")}+ was found on PATH. Install one (${install}; ModWright does not install Python itself), then repeat.` };
+    }
+    const executable = venvPython(targetDir, platform);
+    const constraints = path.join(targetDir, "modwright-constraints.txt");
+    const pipArgs = ["-m", "pip", "install", "--disable-pip-version-check", "--no-input", "--index-url", managed.index, "-c", constraints, ...managed.packages];
+    return {
+        ok: true,
+        plan: {
+            tool: spec.id,
+            label: spec.label,
+            version: managed.version,
+            license: managed.license,
+            kind: "python-venv",
+            targetDir,
+            executable,
+            steps: [
+                { kind: "run", what: `create a virtual environment from your Python ${base.version.join(".")} (${base.executable})`, command: base.executable, args: ["-m", "venv", targetDir] },
+                { kind: "write", what: `pin the dependency closure (${managed.constraints.length} packages)`, path: constraints },
+                { kind: "run", what: `install ${managed.packages.join(" and ")} from PyPI`, command: executable, args: pipArgs },
+                { kind: "run", what: "check the packages import and report their version", command: executable, args: ["-c", "import UnityPy, TypeTreeGeneratorAPI; print('UnityPy', UnityPy.__version__)"] },
+            ],
+            download: `decided by pip from ${managed.index} (about 10 MB of wheels on Windows); pip checks each file against the index's sha256`,
+            alreadyInstalled: false,
+            configFile,
+            configEntry: { path: executable, installedBy: "modwright", version: managed.version, source: `${managed.index} (${managed.packages.join(", ")}; dependencies pinned by version)`, rememberedAt: now },
+            notes: [
+                "Top-level packages and their dependencies are pinned by version; they are not hash-locked.",
+                ...(existsSync(targetDir) ? [`${targetDir} exists already; the venv is updated in place.`] : []),
+            ],
+        },
+    };
+}
+async function recordInConfig(plan) {
+    const loaded = await loadUserConfig(plan.configFile);
+    if (loaded.problems.length > 0)
+        return loaded.problems.join(" ");
+    const config = { ...loaded.config, tools: { ...loaded.config.tools, [plan.tool]: plan.configEntry } };
+    const report = await executePlan(userConfigWritePlan(config, `record the managed ${plan.label} in the per-user config`, plan.configFile), { mode: "apply", confidence: CONFIDENCE });
+    return report.applied ? undefined : "the config write did not apply";
+}
+export async function applyManagedInstall(plan, ctx = {}) {
+    const spec = (ctx.specs ?? TOOL_SPECS).find((s) => s.id === plan.tool);
+    const backupRoot = path.join(ctx.dataDir ?? userDataDir(), "backups");
+    const verified = [];
+    const fetchImpl = ctx.fetchImpl ?? fetch;
+    const pythonAt = ctx.pythonLocation ?? ((p) => ({ id: plan.tool, label: plan.label, found: true, path: p, usedBy: spec.usedBy }));
+    for (const step of plan.steps) {
+        if (step.kind === "download") {
+            let bytes;
+            try {
+                const response = await fetchImpl(step.url, { redirect: "follow" });
+                if (!response.ok)
+                    return { ok: false, error: `Download failed: ${step.url} answered ${response.status} ${response.statusText}. Nothing was written.` };
+                bytes = new Uint8Array(await response.arrayBuffer());
+            }
+            catch (error) {
+                return { ok: false, error: `Download failed: ${step.url}: ${error.message}. Nothing was written.` };
+            }
+            if (bytes.byteLength !== step.sizeBytes)
+                return { ok: false, error: `Size mismatch for ${step.url}: got ${bytes.byteLength} bytes, pinned ${step.sizeBytes}. Nothing was written.` };
+            const hash = sha256Hex(bytes);
+            if (hash !== step.sha256)
+                return { ok: false, error: `sha256 mismatch for ${step.url}: got ${hash}, pinned ${step.sha256}. Nothing was written.` };
+            const written = await executePlan({ purpose: `install ${plan.label} ${plan.version}`, operations: [planMkdir(path.dirname(step.to)), planFile(step.to, bytes)], backupRoot }, { mode: "apply", confidence: CONFIDENCE });
+            if (!written.applied)
+                return { ok: false, error: `Writing ${step.to} did not apply.` };
+            if ((ctx.platform ?? process.platform) !== "win32")
+                await fs.chmod(step.to, 0o755);
+            verified.push(`${path.basename(step.to)}: ${bytes.byteLength} bytes, sha256 ${hash} (matches the pin)`);
+        }
+        else if (step.kind === "write") {
+            const managed = spec.managed;
+            if (managed?.kind !== "python-venv")
+                return { ok: false, error: `Plan step "${step.what}" does not fit ${plan.tool}.` };
+            const written = await executePlan({ purpose: step.what, operations: [planMkdir(path.dirname(step.path)), planFile(step.path, managed.constraints.join("\n") + "\n")], backupRoot }, { mode: "apply", confidence: CONFIDENCE });
+            if (!written.applied)
+                return { ok: false, error: `Writing ${step.path} did not apply.` };
+        }
+        else {
+            const location = pythonAt(step.command);
+            const result = await runTool(location, { args: step.args, timeoutMs: 20 * 60_000, maxCaptureBytes: 4_000_000 });
+            if (!result.ok)
+                return { ok: false, error: `${step.what} failed: ${result.error?.message ?? `exit ${result.exitCode}`}\n${(result.stderr || result.stdout).slice(-2000)}` };
+            if (step.args.includes("import UnityPy, TypeTreeGeneratorAPI; print('UnityPy', UnityPy.__version__)")) {
+                const m = spec.versionPattern?.exec(result.stdout);
+                if (!m || m[1] !== plan.version)
+                    return { ok: false, error: `The check after install read "${result.stdout.trim()}", not UnityPy ${plan.version}. The config was not changed.` };
+                verified.push(`import check: ${result.stdout.trim()}`);
+            }
+        }
+    }
+    if (!existsSync(plan.executable))
+        return { ok: false, error: `${plan.executable} is missing after the install; the config was not changed.` };
+    const configProblem = await recordInConfig(plan);
+    if (configProblem)
+        return { ok: false, error: `Installed, but the config was not updated: ${configProblem}` };
+    verified.push(`recorded in ${plan.configFile}`);
+    return { ok: true, executable: plan.executable, verified };
+}