modwright 0.1.0

package/dist/core/deploy/guards.js

@@ -0,0 +1,292 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { readLinkTarget, readTextIfExists, walk } from "../fsutil.js";
+import { parseMetaLsxModuleInfo } from "../lsx.js";
+import { findRunningProcesses } from "../process.js";
+import { globToRegExp } from "../validate/index.js";
+import { scanPaksIdentities } from "../../surfaces/baldursgate3/identity.js";
+const LOCKED_ROOT_IDS = new Set(["archive", "paks", "red4ext"]);
+export function defaultLocked(rootId) {
+    return LOCKED_ROOT_IDS.has(rootId);
+}
+export async function duplicateModuleUuidBlock(surface, target, identity) {
+    if (surface.id !== "baldursgate3" || target.rootId !== "paks")
+        return undefined;
+    const uuid = identity?.uuid;
+    if (!uuid)
+        return undefined;
+    const { copies } = await scanPaksIdentities(target.rootPath);
+    const own = normalizeForCompare(target.toAbs);
+    const ownFolder = identity?.folder;
+    const duplicates = copies.filter((copy) => {
+        if (copy.uuid?.toLowerCase() !== uuid.toLowerCase())
+            return false;
+        if (normalizeForCompare(copy.path) === own)
+            return false;
+        if (ownFolder && copy.folder === ownFolder)
+            return false;
+        return true;
+    });
+    if (duplicates.length === 0)
+        return undefined;
+    return {
+        code: "duplicate-module-uuid",
+        message: `${duplicates.length} other installed pak(s) already carry this project's module UUID (${uuid}) under a ` +
+            `different path: ${duplicates.map((d) => d.path).join(", ")}. Which of several same-UUID copies BG3 loads is ` +
+            `not predictable from outside (observed in game), so deploying here risks landing content the game never actually loads. ` +
+            `Rename or remove the duplicate pak(s) first — the game only scans files with a .pak extension, so renaming ` +
+            `one to .pak.bak (the same convention already used in the profile folder for retired copies) or deleting it ` +
+            `takes it out of consideration. A copy that came from a mod.io subscription can simply be deleted; mod.io ` +
+            `will re-download it if you resubscribe.`,
+        detail: {
+            uuid,
+            ownFolder,
+            duplicates: duplicates.map((d) => ({ path: d.path, folder: d.folder, modifiedAt: d.modifiedAt })),
+        },
+    };
+}
+export async function newestChange(paths) {
+    let when = new Date(0);
+    let from;
+    for (const p of paths) {
+        let stat;
+        try {
+            stat = await fs.stat(p);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            const walked = await walk(p, { limit: 200_000, skipDirs: [".modwright"] });
+            if (walked.modifiedAt > when) {
+                when = walked.modifiedAt;
+                from = p;
+            }
+        }
+        else if (stat.mtime > when) {
+            when = stat.mtime;
+            from = p;
+        }
+    }
+    return { when, path: from };
+}
+const STALE_FIX = {
+    built: {
+        action: "build",
+        advice: (artifactPath) => `Run "build" to refresh ${path.basename(artifactPath)}, then deploy.`,
+    },
+    installed: {
+        action: 'deploy --deployMode pak',
+        advice: (artifactPath) => `Rebuilding does NOT clear this: "build" only refreshes the artifact under the project's build output, and this ` +
+            `guard is comparing the copy already installed at ${artifactPath}. Run "deploy" with deployMode "pak" to refresh ` +
+            `the installed copy, then re-run this deploy.`,
+    },
+};
+export async function staleArtifactBlock(artifactPath, sourcePaths, context, kind, via) {
+    let artifactMtime;
+    try {
+        artifactMtime = (await fs.stat(artifactPath)).mtime;
+    }
+    catch {
+        return undefined;
+    }
+    const newest = await newestChange(sourcePaths);
+    if (newest.when <= artifactMtime)
+        return undefined;
+    const fix = STALE_FIX[kind];
+    return {
+        code: "stale-artifact",
+        message: `${path.basename(artifactPath)} (modified ${artifactMtime.toISOString()}) is older than its contributing sources ` +
+            `(newest change ${newest.when.toISOString()}${newest.path ? ` under ${newest.path}` : ""}). ` +
+            `${context} ${fix.advice(artifactPath)}`,
+        detail: {
+            artifact: artifactPath,
+            artifactKind: kind,
+            fix: fix.action,
+            artifactModifiedAt: artifactMtime.toISOString(),
+            sourcesNewestChangeAt: newest.when.toISOString(),
+            newestSource: newest.path,
+            contributingSources: sourcePaths,
+            ...(via ? { contributingSourcesVia: via } : {}),
+        },
+    };
+}
+async function linkState(absPath) {
+    let lst;
+    try {
+        lst = await fs.lstat(absPath);
+    }
+    catch {
+        return { state: "absent" };
+    }
+    if (lst.isSymbolicLink()) {
+        const linkTarget = await readLinkTarget(absPath).catch(() => undefined);
+        return { state: "link", linkTarget };
+    }
+    return { state: lst.isDirectory() ? "directory" : "file" };
+}
+export async function inspectJunctions(project, projectRoot, roots) {
+    const statuses = [];
+    const blocks = [];
+    for (const declared of project.deploy?.junctions ?? []) {
+        const root = roots.find((r) => r.id === declared.rootId);
+        if (!root) {
+            blocks.push({
+                code: "unknown-root",
+                message: `deploy.junctions entry "${declared.linkPath}" names root "${declared.rootId}", which this surface does not have. Known roots: ${roots.map((r) => r.id).join(", ")}`,
+                detail: { linkPath: declared.linkPath, rootId: declared.rootId },
+            });
+            continue;
+        }
+        const linkPath = path.join(root.path, declared.linkPath);
+        const target = path.isAbsolute(declared.target) ? declared.target : path.join(projectRoot, declared.target);
+        const { state, linkTarget } = await linkState(linkPath);
+        statuses.push({ declared, linkPath, target, before: state, after: state, action: "none", linkTargetBefore: linkTarget });
+    }
+    return { statuses, blocks };
+}
+const MANAGER_MARKERS = [
+    { pattern: /bg3modmanager|laughingleader/i, label: "BG3 Mod Manager" },
+    { pattern: /vortex/i, label: "Vortex" },
+    { pattern: /<node\s+id="ModOrder"/i, label: "a ModOrder node (written by BG3 Mod Manager)" },
+];
+export async function moduleShortDescReport(project, surface, install, targets = []) {
+    const file = install && surface.loadOrderFile ? surface.loadOrderFile(install) : undefined;
+    let managerWarning;
+    if (file) {
+        const text = await readTextIfExists(file);
+        if (text) {
+            const hits = MANAGER_MARKERS.filter((m) => m.pattern.test(text)).map((m) => m.label);
+            if (hits.length > 0) {
+                managerWarning =
+                    `${file} contains ${hits.join(" and ")} — a mod manager appears to own this file. ` +
+                        `Add the entry through the manager instead; a hand edit will be overwritten.`;
+            }
+        }
+    }
+    const uuid = project.identity?.uuid;
+    const folder = project.identity?.folder ?? project.name;
+    const name = project.identity?.name ?? folder;
+    const own = {
+        source: "project",
+        folder,
+        name,
+        ...(uuid ? { uuid } : {}),
+        ...(project.identity?.version64 ? { version64: project.identity.version64 } : {}),
+    };
+    own.xml = moduleShortDescXml(own);
+    if (!own.xml) {
+        own.note =
+            `This project's identity has no "uuid", so its ModuleShortDesc entry cannot be written out. ` +
+                `Copy Folder, Name, UUID and Version64 from the module's own meta.lsx into ${file ?? "modsettings.lsx"}'s Mods list.`;
+    }
+    const staged = await stagedModules(targets, own);
+    const modules = [own, ...staged];
+    const writable = modules.filter((m) => m.xml);
+    const note = own.xml
+        ? `Add ${writable.length === 1 ? "this node" : `these ${writable.length} nodes`} to the Mods children list in ` +
+            `${file ?? "modsettings.lsx"}. ModWright reports them and never edits the file.` +
+            (own.version64 ? "" : ` Version64 is absent from this project's identity — copy it from the module's meta.lsx rather than guessing it.`) +
+            (staged.length > 0
+                ? ` ${staged.length === 1 ? "One module" : `${staged.length} modules`} staged by this deploy ship their own meta.lsx ` +
+                    `(${staged.map((m) => m.folder).join(", ")}); their values come from those files, not from this project's identity.`
+                : "")
+        : `${own.note} ModWright never edits that file.` +
+            (staged.length > 0 ? ` The ${staged.length} module(s) staged with their own meta.lsx are reported in "modules".` : "");
+    return {
+        file,
+        managerWarning,
+        ...(own.xml ? { xml: own.xml } : {}),
+        note,
+        modules,
+    };
+}
+function escapeXmlAttr(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function moduleShortDescXml(entry) {
+    if (!entry.uuid)
+        return undefined;
+    const v = (value) => (entry.source === "project" ? escapeXmlAttr(value) : value);
+    const attributes = [
+        `    <attribute id="Folder" type="LSString" value="${v(entry.folder)}"/>`,
+        `    <attribute id="MD5" type="LSString" value=""/>`,
+        `    <attribute id="Name" type="LSString" value="${v(entry.name)}"/>`,
+        ...(entry.version64 ? [`    <attribute id="Version64" type="int64" value="${v(entry.version64)}"/>`] : []),
+        `    <attribute id="UUID" type="guid" value="${v(entry.uuid)}"/>`,
+    ];
+    return `  <node id="ModuleShortDesc">\n${attributes.join("\n")}\n  </node>`;
+}
+export { parseMetaLsxModuleInfo } from "../lsx.js";
+async function stagedModules(targets, own) {
+    const found = [];
+    const seen = new Set(own.uuid ? [own.uuid.toLowerCase()] : []);
+    for (const target of targets) {
+        for (const copy of target.copies) {
+            if (path.basename(copy.to).toLowerCase() !== "meta.lsx")
+                continue;
+            const text = await readTextIfExists(copy.from);
+            if (!text)
+                continue;
+            const info = parseMetaLsxModuleInfo(text);
+            if (!info)
+                continue;
+            const folder = info.folder ?? info.name;
+            if (!folder)
+                continue;
+            const key = (info.uuid ?? folder).toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const entry = {
+                source: "meta.lsx",
+                folder,
+                name: info.name ?? folder,
+                ...(info.uuid ? { uuid: info.uuid } : {}),
+                ...(info.version64 ? { version64: info.version64 } : {}),
+                file: copy.from,
+            };
+            entry.xml = moduleShortDescXml(entry);
+            if (!entry.xml) {
+                entry.note = `${copy.from} carries no UUID, so no ModuleShortDesc entry can be written for it.`;
+            }
+            found.push(entry);
+        }
+    }
+    return found;
+}
+export async function waitForGameExit(processNames, waitMinutes, deps = {}) {
+    const find = deps.findProcesses ?? findRunningProcesses;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const budgetMs = Math.min(30, Math.max(0, waitMinutes)) * 60_000;
+    let waitedMs = 0;
+    for (;;) {
+        const probe = await find(processNames);
+        if (!probe.checked)
+            return { checked: false, running: [], cleared: false, waitedMs };
+        if (probe.running.length === 0)
+            return { checked: true, running: [], cleared: true, waitedMs };
+        if (waitedMs >= budgetMs)
+            return { checked: true, running: probe.running, cleared: false, waitedMs };
+        await sleep(2_000);
+        waitedMs += 2_000;
+    }
+}
+export async function computePrune(rootPath, globs, writes) {
+    const patterns = globs.map(globToRegExp);
+    const walked = await walk(rootPath, { limit: 200_000, stat: false });
+    const leftovers = [];
+    for (const rel of walked.files) {
+        if (!patterns.some((re) => re.test(rel)))
+            continue;
+        const abs = path.join(rootPath, rel);
+        if (writes.has(normalizeForCompare(abs)))
+            continue;
+        leftovers.push(abs);
+    }
+    return leftovers;
+}
+export function normalizeForCompare(p) {
+    const resolved = path.resolve(p);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}

package/dist/core/deploy/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { planDeploy, runDeploy } from "./plan.js";
+export { classifyReload, detectRedHotTools, redHotToolsDir, redscriptChangeAction, ARCHIVE_WATCHER_LINE } from "./reload.js";
+export { planReloadApply, runReloadApply } from "./reload-apply.js";
+export { defaultLocked, waitForGameExit } from "./guards.js";