modwright 0.1.0

package/dist/core/deploy/plan.js

@@ -0,0 +1,696 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { pathExists, walk } from "../fsutil.js";
+import { globToRegExp, isExcludedByGlobs } from "../validate/index.js";
+import { findRunningProcesses } from "../process.js";
+import { executePlan, isIdenticalFile, planCopy, planDelete, planJunction, planMkdir, planUnlink, sha256File } from "../safety/index.js";
+import { classifyReload } from "./reload.js";
+import { runReloadApply } from "./reload-apply.js";
+import { computePrune, defaultLocked, duplicateModuleUuidBlock, inspectJunctions, moduleShortDescReport, normalizeForCompare, staleArtifactBlock, waitForGameExit, } from "./guards.js";
+import { artifactSources, buildSourceGraph } from "./sources.js";
+const BUILD_MANIFEST_FILE = ".modwright-build-manifest.json";
+const LOCKED_COPY_BACKOFF_MS = [200, 400, 800, 1600];
+function execCommandLine(extras) {
+    const { command, args } = (extras ?? {});
+    if (typeof command !== "string")
+        return undefined;
+    const argv = Array.isArray(args) ? args.filter((a) => typeof a === "string") : [];
+    return [command, ...argv].join(" ");
+}
+async function readBuildManifest(outDir) {
+    const byOutput = new Map();
+    const outputEntries = new Map();
+    const recordedByOutput = new Map();
+    if (!outDir)
+        return { byOutput, outputEntries, recordedByOutput };
+    const file = path.join(outDir, BUILD_MANIFEST_FILE);
+    let manifest;
+    try {
+        manifest = JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return { byOutput, outputEntries, recordedByOutput };
+    }
+    for (const step of manifest.steps ?? []) {
+        const provenance = {
+            step: step.step,
+            id: step.id,
+            verified: step.verified,
+            command: step.verified ? undefined : execCommandLine(step.extras),
+        };
+        const recorded = { step: step.step, id: step.id, inputs: (step.inputs ?? []).map((i) => i.path) };
+        for (const output of step.outputs ?? []) {
+            byOutput.set(normalizeForCompare(output.path), provenance);
+            outputEntries.set(normalizeForCompare(output.path), output);
+            recordedByOutput.set(normalizeForCompare(output.path), recorded);
+        }
+    }
+    return { file, manifest, byOutput, outputEntries, recordedByOutput };
+}
+async function builtArtifactPath(target, project, outDir) {
+    const source = project.sources.find((s) => s.id === target.from);
+    if (source)
+        return { path: source.absPath, source: source.absPath };
+    if (path.isAbsolute(target.from))
+        return { path: target.from };
+    const candidates = [...(outDir ? [path.join(outDir, target.from)] : []), path.join(project.root, target.from)];
+    for (const candidate of candidates) {
+        if (await pathExists(candidate))
+            return { path: candidate };
+    }
+    return { path: candidates[0] };
+}
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+async function expandTarget(fromAbs, toAbs, isDirectory, excludeGlobs, projectRoot) {
+    const patterns = excludeGlobs.map(globToRegExp);
+    const matches = (rel, abs) => isExcludedByGlobs(patterns, rel, projectRoot ? toPosix(path.relative(projectRoot, abs)) : undefined);
+    if (!isDirectory) {
+        return matches(path.basename(fromAbs), fromAbs)
+            ? { copies: [], excluded: [fromAbs], links: [] }
+            : { copies: [{ from: fromAbs, to: toAbs }], excluded: [], links: [] };
+    }
+    const copies = [];
+    const excluded = [];
+    const walked = await walk(fromAbs, { limit: 200_000, skipDirs: [".modwright"], stat: false });
+    if (walked.truncated) {
+        throw new Error(`deploy: ${fromAbs} holds more than 200000 files; the listing was cut short, so nothing was planned`);
+    }
+    for (const rel of walked.files) {
+        const from = path.join(fromAbs, rel);
+        if (matches(toPosix(rel), from)) {
+            excluded.push(from);
+            continue;
+        }
+        copies.push({ from, to: path.join(toAbs, rel) });
+    }
+    return { copies, excluded, links: (walked.links ?? []).map((rel) => path.join(fromAbs, rel)) };
+}
+function deferTargets(lockedTargets, running, waitMinutes, waitedMs) {
+    const holders = running.map((p) => `${p.name}${p.pid ? ` (pid ${p.pid})` : ""}`).join(", ");
+    return lockedTargets.map((t) => ({
+        rootId: t.rootId,
+        from: t.target.from,
+        to: t.toAbs,
+        processes: running,
+        message: `${holders} is running and holds ${t.toAbs}. ` +
+            (waitMinutes > 0
+                ? `Waited ${Math.round(waitedMs / 1000)}s (the ${waitMinutes} minute bound) for it to exit. `
+                : `No wait was requested (waitMinutes: 0). `) +
+            `This target was deferred; everything else in the plan was deployed.`,
+    }));
+}
+function deferralInstruction(deferred) {
+    const holders = [...new Set(deferred.flatMap((d) => d.processes.map((p) => p.name)))].join(", ");
+    return `Close ${holders || "the game"} and run deploy again for: ${deferred.map((d) => d.to).join(", ")}.`;
+}
+function clampWaitMinutes(value) {
+    if (value === undefined)
+        return 0;
+    return Math.min(30, Math.max(0, Math.trunc(value)));
+}
+export async function planDeploy(inputs) {
+    const { project, surface } = inputs;
+    const mode = inputs.mode ?? "dry-run";
+    const deployMode = inputs.deployMode ?? "pak";
+    const backupRoot = path.join(project.root, ".modwright", "backups");
+    const blocked = [];
+    const warnings = [];
+    const assumptions = [];
+    const verifiedBy = [];
+    const targets = [];
+    const skipped = [];
+    const skippedDestDirs = [];
+    const noteSkippedDir = (target) => {
+        if (!target.into)
+            return;
+        const skRoot = roots?.find((r) => r.id === target.rootId);
+        if (skRoot)
+            skippedDestDirs.push(path.join(skRoot.path, target.into));
+    };
+    const notDeployedLocked = [];
+    const excluded = [];
+    const deferred = [];
+    const variantExcludedTargets = new Set();
+    const deploy = project.project.deploy;
+    const waitMinutes = clampWaitMinutes(inputs.waitMinutes ?? deploy?.waitMinutes);
+    const emptyProcessCheck = { checked: false, running: [], lockedPaths: [], waitMinutes };
+    if (!deploy || deploy.targets.length === 0) {
+        return {
+            blocked: [
+                {
+                    code: "no-deploy-config",
+                    message: `${project.project.name}: modwright.json declares no deploy targets — there is nothing to deploy.`,
+                },
+            ],
+            confidence: { level: "high", assumptions: [], verifiedBy: ["modwright.json"] },
+            targets: [],
+            skipped: [],
+            deferred: [],
+            junctions: [],
+            pruned: [],
+            skippedDestDirs: [],
+            excluded: [],
+            warnings,
+            writtenPaths: [],
+            processCheck: emptyProcessCheck,
+            backupRoot,
+        };
+    }
+    const roots = inputs.roots ?? (inputs.install ? surface.modRoots(inputs.install) : undefined);
+    if (!roots) {
+        return {
+            blocked: [
+                {
+                    code: "no-install",
+                    message: `No ${surface.name} install was located, so deploy cannot resolve any root id. Pass an install path.`,
+                },
+            ],
+            confidence: { level: "high", assumptions: [], verifiedBy: [] },
+            targets: [],
+            skipped: [],
+            deferred: [],
+            junctions: [],
+            pruned: [],
+            skippedDestDirs: [],
+            excluded: [],
+            warnings,
+            writtenPaths: [],
+            processCheck: emptyProcessCheck,
+            backupRoot,
+        };
+    }
+    const outDir = inputs.outDir ?? project.build?.absOutDir;
+    const manifestIndex = await readBuildManifest(outDir);
+    if (manifestIndex.file) {
+        verifiedBy.push(`build manifest at ${manifestIndex.file}`);
+    }
+    else if (outDir) {
+        assumptions.push(`no build manifest at ${path.join(outDir, BUILD_MANIFEST_FILE)}: deployed artifacts were matched by file existence alone, not against what a build recorded producing.`);
+    }
+    for (const target of deploy.targets) {
+        if (target.variant && target.variant !== inputs.variant) {
+            skipped.push({
+                rootId: target.rootId,
+                from: target.from,
+                reason: `only deploys under build variant "${target.variant}"${inputs.variant ? `, not "${inputs.variant}"` : " (no variant requested)"}`,
+            });
+            noteSkippedDir(target);
+            variantExcludedTargets.add(target);
+            continue;
+        }
+        if (target.mode && target.mode !== deployMode) {
+            skipped.push({ rootId: target.rootId, from: target.from, reason: `target is mode "${target.mode}", this deploy is mode "${deployMode}"` });
+            const skippedRoot = roots.find((r) => r.id === target.rootId);
+            if (skippedRoot && (target.locked ?? defaultLocked(target.rootId))) {
+                notDeployedLocked.push({ target, rootPath: skippedRoot.path });
+            }
+            noteSkippedDir(target);
+            continue;
+        }
+        const root = roots.find((r) => r.id === target.rootId);
+        if (!root) {
+            blocked.push({
+                code: "unknown-root",
+                message: `deploy target "${target.from}" names root "${target.rootId}", which ${surface.name} does not have. Known roots: ${roots.map((r) => r.id).join(", ")}`,
+                detail: { from: target.from, rootId: target.rootId },
+            });
+            continue;
+        }
+        const source = project.sources.find((s) => s.id === target.from);
+        const candidates = source
+            ? [source.absPath]
+            : path.isAbsolute(target.from)
+                ? [target.from]
+                : [...(outDir ? [path.join(outDir, target.from)] : []), path.join(project.root, target.from)];
+        let fromAbs;
+        let stat;
+        for (const candidate of candidates) {
+            try {
+                stat = await fs.stat(candidate);
+                fromAbs = candidate;
+                break;
+            }
+            catch {
+            }
+        }
+        if (!fromAbs || !stat) {
+            blocked.push({
+                code: "missing-artifact",
+                message: `deploy target "${target.from}" does not exist (looked at ${candidates.join(", ")}) — this build did not produce it. ` +
+                    `Deploying an artifact the build did not produce is the stale-deploy bug; run build first.`,
+                detail: { from: target.from, rootId: target.rootId, lookedAt: candidates },
+            });
+            continue;
+        }
+        const provenance = manifestIndex.byOutput.get(normalizeForCompare(fromAbs));
+        const recorded = manifestIndex.outputEntries.get(normalizeForCompare(fromAbs));
+        if (provenance && recorded && !recorded.files && stat.isFile()) {
+            const current = stat.size === recorded.sizeBytes ? (await sha256File(fromAbs)).sha256 : undefined;
+            if (current !== recorded.sha256) {
+                blocked.push({
+                    code: "artifact-changed",
+                    message: `${fromAbs} is not the file the last successful build recorded producing (${current === undefined ? `size ${stat.size} bytes, recorded ${recorded.sizeBytes}` : "sha256 differs"}). A build that failed after writing it, or a hand edit, left it there; run build again and deploy what it verifies.`,
+                    detail: { from: target.from, path: fromAbs, recordedSha256: recorded.sha256, recordedSizeBytes: recorded.sizeBytes, sizeBytes: stat.size },
+                });
+                continue;
+            }
+            verifiedBy.push(`sha256 of ${path.basename(fromAbs)} matches the build manifest`);
+        }
+        if (manifestIndex.file && !provenance && !source) {
+            assumptions.push(`${target.from} exists under the build outDir but is not an output of any step in the recorded build (a hand-authored sidecar, or a leftover); it is deployed on file existence alone.`);
+        }
+        if (provenance && !provenance.verified) {
+            assumptions.push(`${target.from} was produced by an unverified ${provenance.step} step${provenance.command ? `: ${provenance.command}` : ""} — ModWright checked only that it exited 0 and wrote its declared outputs.`);
+        }
+        const locked = target.locked ?? defaultLocked(target.rootId);
+        if (target.waitForGameExit !== undefined && target.waitForGameExit !== locked) {
+            warnings.push(`deploy target "${target.from}" sets waitForGameExit: ${target.waitForGameExit} but its lock class is ${locked} ` +
+                `(root "${target.rootId}"${target.locked === undefined ? ", by default" : ", set explicitly"}). The lock class is what deploy acts on; set "locked" to say otherwise.`);
+        }
+        const toAbs = target.into ? path.join(root.path, target.into) : path.join(root.path, path.basename(fromAbs));
+        const isDirectory = stat.isDirectory();
+        const excludeGlobs = [...(project.project.build?.exclude ?? []), ...(target.exclude ?? [])];
+        const { copies, excluded: targetExcluded, links } = await expandTarget(fromAbs, toAbs, isDirectory, excludeGlobs, project.root);
+        if (links.length > 0) {
+            warnings.push(`deploy target "${target.from}": ${links.length} symbolic link(s)/junction(s) under it are not followed and not deployed: ${links.slice(0, 10).join(", ")}${links.length > 10 ? ", ..." : ""}.`);
+        }
+        if (targetExcluded.length > 0) {
+            excluded.push(...targetExcluded);
+        }
+        if (copies.length === 0) {
+            const reason = targetExcluded.length > 0
+                ? `nothing left to copy: every file under it matches an exclude glob [${excludeGlobs.join(", ")}]`
+                : isDirectory
+                    ? "the source directory is empty"
+                    : "the source file is excluded";
+            skipped.push({ rootId: target.rootId, from: target.from, reason });
+            warnings.push(`deploy target "${target.from}" skipped: ${reason}.`);
+            continue;
+        }
+        const writes = copies.map((c) => c.to);
+        targets.push({ target, rootId: target.rootId, rootPath: root.path, fromAbs, toAbs, locked, isDirectory, copies, excluded: targetExcluded, writes, provenance, fromSource: Boolean(source) });
+    }
+    if (deployMode === "pak") {
+        for (const t of targets) {
+            const dupBlock = await duplicateModuleUuidBlock(surface, t, project.project.identity);
+            if (dupBlock)
+                blocked.push(dupBlock);
+        }
+    }
+    const sourceGraph = await buildSourceGraph(project, outDir);
+    const lockedTargets = targets.filter((t) => t.locked);
+    const LOOSE_CONTEXT = "A packed mod of the same identity wins over a junctioned loose copy, so this pak would shadow the loose files.";
+    const recordedFor = (built) => manifestIndex.recordedByOutput.get(normalizeForCompare(built));
+    const stalePairs = lockedTargets.map((t) => {
+        const sources = artifactSources(sourceGraph, t.fromAbs, {
+            fromSourcePath: t.fromSource ? t.fromAbs : undefined,
+            recorded: recordedFor(t.fromAbs),
+        });
+        return deployMode === "loose"
+            ? { artifact: t.toAbs, context: LOOSE_CONTEXT, kind: "installed", sources }
+            : { artifact: t.fromAbs, context: "Deploying it would put older content live.", kind: "built", sources };
+    });
+    if (deployMode === "loose") {
+        for (const { target, rootPath } of notDeployedLocked) {
+            const built = await builtArtifactPath(target, project, outDir);
+            stalePairs.push({
+                artifact: path.join(rootPath, target.into ?? path.basename(target.from)),
+                context: LOOSE_CONTEXT,
+                kind: "installed",
+                sources: artifactSources(sourceGraph, built.path, { fromSourcePath: built.source, recorded: recordedFor(built.path) }),
+            });
+        }
+    }
+    let compared = 0;
+    for (const pair of stalePairs) {
+        if (!pair.sources.known) {
+            assumptions.push(`stale-artifact guard: ${pair.artifact} was not compared — ${pair.sources.via}. ` +
+                `Give the step that builds it an "inputs" list (exec) to have it checked.`);
+            continue;
+        }
+        compared++;
+        const block = await staleArtifactBlock(pair.artifact, pair.sources.paths, pair.context, pair.kind, pair.sources.via);
+        if (block)
+            blocked.push(block);
+    }
+    if (compared > 0) {
+        verifiedBy.push(`stale-artifact guard over ${compared} locked artifact(s), each against the sources of the build step that produces it`);
+    }
+    const { statuses: junctions, blocks: junctionBlocks } = await inspectJunctions(project.project, project.root, roots);
+    blocked.push(...junctionBlocks);
+    const unlinkOps = [];
+    const junctionOps = [];
+    let moduleShortDesc;
+    if (junctions.length > 0) {
+        verifiedBy.push(`lstat of ${junctions.length} configured junction path(s)`);
+        if (deployMode === "pak") {
+            const live = junctions.filter((j) => j.before === "link");
+            if (live.length > 0 && !inputs.unlink) {
+                blocked.push({
+                    code: "junction-coexistence",
+                    message: `--mode pak refuses to run while a junction to this project exists: ${live.map((j) => j.linkPath).join(", ")}. ` +
+                        `A pak and a junction of the same identity both present means the pak silently wins over your loose edits. ` +
+                        `Re-run with unlink: true to remove the link(s) first (the link is removed, never what it points at).`,
+                    detail: { links: live.map((j) => ({ linkPath: j.linkPath, pointsAt: j.linkTargetBefore })) },
+                });
+            }
+            else if (live.length > 0) {
+                for (const j of live) {
+                    unlinkOps.push(planUnlink(j.linkPath));
+                    j.action = "unlink";
+                    j.after = "absent";
+                }
+            }
+        }
+        else {
+            for (const j of junctions) {
+                if (j.before === "directory" || j.before === "file") {
+                    warnings.push(`${j.linkPath} is a real ${j.before}, not a link. It will be backed up and replaced by a link to ${j.target}.`);
+                }
+                unlinkOps.push(planUnlink(j.linkPath));
+                junctionOps.push(planJunction(j.linkPath, j.target));
+                j.action = "relink";
+                j.after = "link";
+            }
+        }
+    }
+    if (deployMode === "loose" && surface.loadOrderFile) {
+        moduleShortDesc = await moduleShortDescReport(project.project, surface, inputs.install, targets);
+        if (moduleShortDesc.managerWarning)
+            warnings.push(moduleShortDesc.managerWarning);
+    }
+    const processNames = surface.processNames ?? [];
+    const unchangedLocked = new Set();
+    for (const t of lockedTargets) {
+        if (t.copies.length === 0)
+            continue;
+        let same = true;
+        for (const c of t.copies) {
+            if (!(await isIdenticalFile(c.from, c.to))) {
+                same = false;
+                break;
+            }
+        }
+        if (same)
+            unchangedLocked.add(t);
+    }
+    const changedLocked = lockedTargets.filter((t) => !unchangedLocked.has(t));
+    const lockedPaths = changedLocked.map((t) => t.toAbs);
+    const processCheck = { checked: false, running: [], lockedPaths, waitMinutes };
+    if (processNames.length === 0) {
+        warnings.push(`${surface.name} declares no processNames, so deploy cannot tell whether the game is running.`);
+    }
+    else if (mode === "dry-run") {
+        const probe = await (inputs.findProcesses ?? findRunningProcesses)(processNames);
+        processCheck.checked = probe.checked;
+        processCheck.running = probe.running;
+        if (!probe.checked) {
+            warnings.push("could not check whether the game is running; a failed probe is not proof that it is stopped.");
+        }
+        else if (probe.running.length > 0 && lockedPaths.length > 0) {
+            processCheck.wouldWaitFor = `${probe.running.map((p) => `${p.name}${p.pid ? ` (pid ${p.pid})` : ""}`).join(", ")} holding ${lockedPaths.join(", ")}`;
+            warnings.push(`the game is running (${processCheck.wouldWaitFor}); an apply would wait up to ${waitMinutes} minute(s) for it to exit, then deploy everything else and defer the locked target(s).`);
+            deferred.push(...deferTargets(changedLocked, probe.running, waitMinutes, 0));
+        }
+        verifiedBy.push(`process check for [${processNames.join(", ")}]`);
+    }
+    else if (lockedPaths.length === 0) {
+        const probe = await (inputs.findProcesses ?? findRunningProcesses)(processNames);
+        processCheck.checked = probe.checked;
+        processCheck.running = probe.running;
+        if (probe.running.length > 0) {
+            warnings.push(`the game is running (${probe.running.map((p) => p.name).join(", ")}), but no target in this deploy is in a locked class, so the copies proceed. Deployed content still needs the reload step below to take effect.`);
+        }
+    }
+    else {
+        const wait = await waitForGameExit(processNames, waitMinutes, inputs);
+        processCheck.checked = wait.checked;
+        processCheck.running = wait.running;
+        processCheck.waitedMs = wait.waitedMs;
+        if (!wait.checked) {
+            warnings.push("could not check whether the game is running; a failed probe is not proof that it is stopped, so the locked copies below may fail.");
+        }
+        else if (!wait.cleared) {
+            deferred.push(...deferTargets(changedLocked, wait.running, waitMinutes, wait.waitedMs));
+            warnings.push(deferralInstruction(deferred));
+        }
+        verifiedBy.push(`process check for [${processNames.join(", ")}]`);
+    }
+    const writeSet = new Set(targets.flatMap((t) => t.writes).map(normalizeForCompare));
+    const pruned = [];
+    for (const target of deploy.targets) {
+        if (!target.prune || target.prune.length === 0)
+            continue;
+        if (variantExcludedTargets.has(target))
+            continue;
+        const root = roots.find((r) => r.id === target.rootId);
+        if (!root || !(await pathExists(root.path)))
+            continue;
+        for (const leftover of await computePrune(root.path, target.prune, writeSet)) {
+            if (!pruned.includes(leftover))
+                pruned.push(leftover);
+        }
+    }
+    const deferredDests = new Set(deferred.map((d) => normalizeForCompare(d.to)));
+    const toWrite = targets.filter((t) => !deferredDests.has(normalizeForCompare(t.toAbs)));
+    const mkdirs = new Set();
+    for (const t of toWrite) {
+        for (const copy of t.copies)
+            mkdirs.add(path.dirname(copy.to));
+    }
+    const operations = [
+        ...unlinkOps,
+        ...junctionOps,
+        ...pruned.map((p) => planDelete(p)),
+        ...[...mkdirs].map((d) => planMkdir(d)),
+        ...toWrite.filter((t) => !t.locked).flatMap((t) => t.copies.map((c) => planCopy(c.from, c.to))),
+        ...toWrite.filter((t) => t.locked).flatMap((t) => t.copies.map((c) => planCopy(c.from, c.to))),
+    ];
+    const confidence = {
+        level: assumptions.length > 0 ? "medium" : "high",
+        assumptions,
+        verifiedBy,
+    };
+    const plan = blocked.length > 0
+        ? undefined
+        : { purpose: `deploy ${project.project.name} (${deployMode})`, operations, backupRoot };
+    return {
+        plan,
+        blocked,
+        confidence,
+        targets,
+        skipped,
+        deferred,
+        junctions,
+        pruned,
+        skippedDestDirs,
+        excluded,
+        warnings,
+        writtenPaths: toWrite.flatMap((t) => t.writes),
+        moduleShortDesc,
+        processCheck,
+        outDir,
+        backupRoot,
+    };
+}
+function copyKey(from, to) {
+    return `${normalizeForCompare(from)}\0${normalizeForCompare(to)}`;
+}
+async function observeJunctions(planned) {
+    const out = [];
+    for (const j of planned) {
+        let after = "absent";
+        try {
+            const lst = await fs.lstat(j.linkPath);
+            after = lst.isSymbolicLink() ? "link" : lst.isDirectory() ? "directory" : "file";
+        }
+        catch {
+            after = "absent";
+        }
+        out.push({ ...j, after });
+    }
+    return out;
+}
+export async function runDeploy(inputs) {
+    const mode = inputs.mode ?? "dry-run";
+    const deployMode = inputs.deployMode ?? "pak";
+    const planned = await planDeploy(inputs);
+    const baseSummary = {
+        project: inputs.project.project.name,
+        game: inputs.surface.id,
+        mode,
+        deployMode,
+        variant: inputs.variant,
+        outDir: planned.outDir,
+        skipped: planned.skipped,
+        deferred: planned.deferred,
+        partial: planned.deferred.length > 0,
+        excluded: planned.excluded,
+        junctions: planned.junctions,
+        moduleShortDesc: planned.moduleShortDesc,
+        processCheck: planned.processCheck,
+    };
+    if (!planned.plan) {
+        const summary = {
+            ...baseSummary,
+            written: [],
+            pruned: [],
+            cleanedEmptyDirs: [],
+            warnings: planned.warnings,
+            blocked: planned.blocked,
+            reload: classifyReload(inputs.surface.id, inputs.project.project, [], { compat: inputs.compat, redHotTools: inputs.redHotTools, scriptDiffs: inputs.scriptDiffs }),
+            next: `Refused before anything was touched: ${planned.blocked.map((b) => b.message).join(" ")}`,
+        };
+        return { applied: false, partial: false, blocked: planned.blocked, confidence: planned.confidence, summary };
+    }
+    const deferredDests = new Set(planned.deferred.map((d) => normalizeForCompare(d.to)));
+    const lockedDests = new Set(planned.targets.filter((t) => t.locked).flatMap((t) => t.copies.map((c) => normalizeForCompare(c.to))));
+    const warnings = [...planned.warnings];
+    const report = await executePlan(planned.plan, {
+        mode,
+        confidence: planned.confidence,
+        now: inputs.now,
+        retry: {
+            shouldRetry: (op) => op.kind === "copy" && lockedDests.has(normalizeForCompare(op.to)),
+            delaysMs: LOCKED_COPY_BACKOFF_MS,
+            sleep: inputs.sleep,
+            onRetry: (op, attempt, error) => {
+                warnings.push(`locked copy to ${op.kind === "copy" ? op.to : ""} failed (${error instanceof Error ? error.message : String(error)}); retry ${attempt} of ${LOCKED_COPY_BACKOFF_MS.length}.`);
+            },
+        },
+        deferOnLock: (op) => op.kind === "delete",
+    });
+    const deferredPrune = report.operations.filter((r) => r.op.kind === "delete" && r.status === "deferred");
+    if (deferredPrune.length > 0) {
+        warnings.push(`${deferredPrune.length} prune target(s) were left in place because something holds them open (the game, ` +
+            `if it is running): ${deferredPrune.map((r) => r.op.path).join(", ")}. These are runtime state, not stale ` +
+            `content, so the rest of the deploy still ran; run deploy again once the holder is closed to clear them.`);
+    }
+    const copyStatus = new Map();
+    for (const r of report.operations) {
+        if (r.op.kind === "copy")
+            copyStatus.set(copyKey(r.op.from, r.op.to), r.status);
+    }
+    const statusesOf = (t) => t.copies.map((c) => copyStatus.get(copyKey(c.from, c.to)) ?? "skipped");
+    const statusOf = (t) => {
+        const statuses = statusesOf(t);
+        if (statuses.length === 0)
+            return "skipped";
+        if (statuses.some((st) => st === "failed"))
+            return "failed";
+        if (statuses.every((st) => st === "planned"))
+            return "planned";
+        if (statuses.every((st) => st === "applied" || st === "skipped") && statuses.some((st) => st === "applied"))
+            return "applied";
+        return "skipped";
+    };
+    const written = planned.targets.map((t) => ({
+        rootId: t.rootId,
+        from: t.target.from,
+        to: t.toAbs,
+        locked: t.locked,
+        status: deferredDests.has(normalizeForCompare(t.toAbs)) ? "deferred" : statusOf(t),
+    }));
+    const blocked = [...planned.blocked];
+    const failedLocked = planned.targets.filter((t) => t.locked && statusOf(t) === "failed");
+    if (failedLocked.length > 0) {
+        const probe = await (inputs.findProcesses ?? findRunningProcesses)(inputs.surface.processNames ?? []);
+        const holders = probe.running.map((p) => `${p.name}${p.pid ? ` (pid ${p.pid})` : ""}`).join(", ");
+        blocked.push({
+            code: "locked-copy-failed",
+            message: `${failedLocked.map((t) => t.toAbs).join(", ")} could not be written after ${LOCKED_COPY_BACKOFF_MS.length + 1} attempts. ` +
+                (probe.checked
+                    ? holders
+                        ? `${holders} is running and is the likely holder.`
+                        : `No game process is running, so something else holds the file (antivirus, an indexer, an open editor).`
+                    : `The process check could not run, so the holder is unknown.`),
+            detail: { paths: failedLocked.map((t) => t.toAbs), processes: probe.running, processCheckWorked: probe.checked },
+        });
+    }
+    const appliedWrites = mode === "apply" ? written.filter((w) => w.status === "applied") : written;
+    const writtenPaths = mode === "apply"
+        ? planned.targets.flatMap((t) => t.copies.filter((c) => copyStatus.get(copyKey(c.from, c.to)) === "applied").map((c) => c.to))
+        : planned.writtenPaths;
+    const appliedDeletes = new Set(report.operations.filter((r) => r.op.kind === "delete" && r.status === "applied").map((r) => normalizeForCompare(r.op.path)));
+    const prunedApplied = mode === "apply" ? planned.pruned.filter((p) => appliedDeletes.has(normalizeForCompare(p))) : planned.pruned;
+    const junctions = mode === "apply" ? await observeJunctions(planned.junctions) : planned.junctions;
+    const reload = classifyReload(inputs.surface.id, inputs.project.project, writtenPaths, {
+        compat: inputs.compat,
+        redHotTools: inputs.redHotTools,
+        scriptDiffs: inputs.scriptDiffs,
+    });
+    let reloadApply;
+    if (inputs.reloadApply && inputs.install && inputs.surface.id === "cyberpunk2077") {
+        const reloadTargets = planned.targets.flatMap((t) => t.copies
+            .filter((c) => deferredDests.has(normalizeForCompare(t.toAbs)) || copyStatus.get(copyKey(c.from, c.to)) !== "skipped")
+            .map((c) => ({ from: c.from, to: c.to })));
+        reloadApply = await runReloadApply({
+            game: inputs.surface.id,
+            install: inputs.install,
+            targets: reloadTargets,
+            grant: inputs.reloadApply.grant,
+            allowMutate: inputs.reloadApply.allowMutate,
+            meshArchives: inputs.reloadApply.meshArchives,
+            devModule: inputs.reloadApply.devModule,
+            hotAvailable: inputs.redHotTools?.hotAvailable,
+            surface: inputs.surface,
+            projectRoot: inputs.project.root,
+            mode,
+            now: inputs.now,
+            sleep: inputs.sleep,
+        });
+    }
+    const cleanedEmptyDirs = [];
+    for (const dir of planned.skippedDestDirs) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        if (mode === "apply") {
+            if (entries.length === 0) {
+                try {
+                    await fs.rmdir(dir);
+                    cleanedEmptyDirs.push(dir);
+                }
+                catch {
+                }
+            }
+        }
+        else {
+            const remaining = entries
+                .map((e) => path.join(dir, e))
+                .filter((p) => !planned.pruned.some((pr) => normalizeForCompare(pr) === normalizeForCompare(p)));
+            if (remaining.length === 0)
+                cleanedEmptyDirs.push(dir);
+        }
+    }
+    const partial = planned.deferred.length > 0 || deferredPrune.length > 0;
+    const deferralNote = planned.deferred.length > 0 ? ` ${deferralInstruction(planned.deferred)}` : "";
+    const next = mode === "dry-run"
+        ? `Nothing was changed. Re-run with { mode: "apply" } to write these changes; any overwrite or delete is backed up first.${deferralNote}`
+        : blocked.length > 0
+            ? `Deploy did not complete. ${blocked.map((b) => b.message).join(" ")}${report.backupDir ? ` Undo what did apply with restoreBackup("${report.backupDir}", { mode: "apply" }).` : ""}`
+            : `Deployed ${appliedWrites.length} target(s)` +
+                (planned.deferred.length > 0 ? `, deferred ${planned.deferred.length}` : "") +
+                (deferredPrune.length > 0 ? `, left ${deferredPrune.length} held-open prune target(s) in place` : "") +
+                `. Reload recommendation: ${reload.overall}.${deferralNote}`;
+    const summary = {
+        ...baseSummary,
+        partial,
+        junctions,
+        written,
+        pruned: prunedApplied,
+        cleanedEmptyDirs,
+        warnings,
+        blocked,
+        reload,
+        ...(reloadApply ? { reloadApply } : {}),
+        next,
+    };
+    return { applied: report.applied && blocked.length === 0, partial, blocked, plan: planned.plan, report, confidence: planned.confidence, summary };
+}