modwright 0.1.0 → 0.1.2

package/README.md

@@ -15,8 +15,9 @@ The core is generic. Each game is a **surface**: one module that declares
 where things live and what the rules are, so every tool works for every
 supported game.
 
-**Status:** 0.x. The tools are exercised against real installs and real mod
-projects, but the API is not stable yet.
+**Status:** 0.x, and the API is not stable yet. How far each game is tested
+differs a lot; "Supported games" says which surfaces have been used against
+a real install and which are built from documentation alone.
 
 ## Why
 
@@ -65,16 +66,26 @@ pointed at once.
 
 ## Supported games
 
-| Surface | Game | Mod systems modeled |
-|---|---|---|
-| `cyberpunk2077` | Cyberpunk 2077 | legacy archives, REDmod, redscript, TweakXL, ArchiveXL, RED4ext, CET; the TweakDB vanilla index; garment, vehicle, tweak and packaging validators; the CET bridge |
-| `baldursgate3` | Baldur's Gate 3 | `.pak` mods, loose overrides, Script Extender, the native mod loader; the stats, GUID and handle vanilla index; stats, story, progression and visual-bank validators; the Script Extender bridge |
-| `skyrimse` | Skyrim Special Edition | plugins, BSA archives, SKSE plugins, loose files |
-| `eldenring` | Elden Ring | me3 profiles, Mod Engine 2 overlay and DLLs, UXM loose files; paramdef-typed param exports, the `.me3` profile, package-layout and DCX rules |
-| `valheim` | Valheim | BepInEx plugins, patchers, config, MonoMod, the Doorstop loader; Thunderstore packaging, plugin-source and config rules; the vanilla index from Jötunn's dumps |
-| `stardewvalley` | Stardew Valley | SMAPI mods and Content Patcher packs, the load-order override lists, SMAPI's log; the manifest and `content.json` rules; the wiki schema index, built from the wiki's data pages, which `check_toolchain` fetches for you |
-| `subnautica2` | Subnautica 2 | `~mods` paks, LogicMods, UE4SS mods, DLC-style plugins; triplet, mount-point, TOC and UE4SS-shape rules |
-| `nivalisnights` | Nivalis Nights | BepInEx 6 IL2CPP plugins, patchers, config, generated interop, MelonLoader mods; the vanilla index (items, recipes, vendors, venues, NPCs, by GUID) built from your install with Cpp2IL and UnityPy |
+| Surface | Game | Tested | Mod systems modeled |
+|---|---|---|---|
+| `cyberpunk2077` | Cyberpunk 2077 | field-tested | legacy archives, REDmod, redscript, TweakXL, ArchiveXL, RED4ext, CET; the TweakDB vanilla index; garment, vehicle, tweak and packaging validators; the CET bridge |
+| `baldursgate3` | Baldur's Gate 3 | field-tested | `.pak` mods, loose overrides, Script Extender, the native mod loader; the stats, GUID and handle vanilla index; stats, story, progression and visual-bank validators; the Script Extender bridge |
+| `skyrimse` | Skyrim Special Edition | research only | plugins, BSA archives, SKSE plugins, loose files |
+| `eldenring` | Elden Ring | research only | me3 profiles, Mod Engine 2 overlay and DLLs, UXM loose files; paramdef-typed param exports, the `.me3` profile, package-layout and DCX rules |
+| `valheim` | Valheim | research only | BepInEx plugins, patchers, config, MonoMod, the Doorstop loader; Thunderstore packaging, plugin-source and config rules; the vanilla index from Jötunn's dumps |
+| `stardewvalley` | Stardew Valley | research only | SMAPI mods and Content Patcher packs, the load-order override lists, SMAPI's log; the manifest and `content.json` rules; the wiki schema index, built from the wiki's data pages, which `check_toolchain` fetches for you |
+| `subnautica2` | Subnautica 2 | research only | `~mods` paks, LogicMods, UE4SS mods, DLC-style plugins; triplet, mount-point, TOC and UE4SS-shape rules |
+| `nivalisnights` | Nivalis Nights | checked on an install | BepInEx 6 IL2CPP plugins, patchers, config, generated interop, MelonLoader mods; the vanilla index (items, recipes, vendors, venues, NPCs, by GUID) built from your install with Cpp2IL and UnityPy |
+
+- **Field-tested:** used against real installs, real mod projects and the
+  running game, through the in-game bridge, over many field runs.
+- **Checked on an install:** detection, logs, compatibility and the vanilla
+  index were checked against an installed copy of the game. No mod project
+  has been built or deployed through it yet, and it has no bridge.
+- **Research only:** written from the game's modding documentation, its
+  community tools' sources and their published file formats, and tested
+  against fixtures. No install was behind it. Expect gaps, and please report
+  them.
 
 Installs are auto-detected from Steam (every library folder), plus GOG and
 Epic paths where they apply. Override with `installPath` on any tool, or set
@@ -94,7 +105,7 @@ Epic paths where they apply. Override with `installPath` on any tool, or set
 | `read_log` | Tail a mod-related log (redscript, RED4ext, CET, SKSE, BG3SE, BepInEx, SMAPI and more). |
 | `triage_logs` | Read every mod log for the current run and classify lines against known failure signatures. It returns one verdict: which systems loaded, what failed first, and the usual fix. |
 | `check_compat` | Detect the game build, loaders, frameworks and tools, and check them against cited compatibility floors. |
-| `check_toolchain` | Locate the external tools (LSLib divine, WolvenKit CLI, Blender, Cpp2IL and others), report each one's path and version (never guessed), and say what each feature needs. It also remembers a tool or data folder you point it at, and installs the tools ModWright can install. |
+| `check_toolchain` | Locate the external tools (LSLib divine, WolvenKit CLI, Blender, Cpp2IL and others), report each one's path and version (never guessed), and say what each feature needs. It also remembers a tool or data folder you point it at, installs the tools ModWright can install, and trusts a project to run its own build commands. |
 | `project_info` | Load a `modwright.json` mod project: sources, build, deploy targets, dependencies and publish targets, with paths resolved and structural warnings. |
 | `lookup` | Search the knowledge base of game and toolchain facts (each with a status and a source), the validator catalogue, or the game's vanilla index you built locally. |
 | `build_index` | Extract and index the game's own data into a local SQLite file in ModWright's cache. Never redistributed. |
@@ -114,6 +125,23 @@ Epic paths where they apply. Override with `installPath` on any tool, or set
 Every tool that writes is **dry-run by default**: it describes the plan and
 writes nothing until you apply it.
 
+## How much to trust an answer
+
+Every fact `lookup` returns carries a status and a source:
+
+| Status | Means |
+|---|---|
+| `verified` | Someone observed it in the game; the fact says when. |
+| `community` | A wiki, README, issue or forum post states it, cited by URL, and it has not been re-checked here. |
+| `inferred` | Derived from reading code or from other facts. |
+| `unverified` | Written from documentation or reasoning, and never observed. |
+| `contradicted` | Once believed and later shown wrong. It is kept, pointing at what replaced it, so the mistake is not made again. |
+
+A validator that cannot run is reported as **skipped**, with the reason,
+never as passed. That happens when the vanilla index is not built, a tool is
+missing, or the project has nothing of the kind it checks. An in-game test
+whose probe is `unverified` can pass, but its result stays below `verified`.
+
 ## Workflow prompts
 
 Seven workflow prompts walk the authoring loop in any MCP client
@@ -173,6 +201,12 @@ project:
   `check_toolchain action=install tool=cpp2il` shows exactly what it would
   fetch (URL, size, sha256, destination); `mode=apply` installs it. Downloads
   are pinned and checked before anything is written.
+- **Trusted projects** are listed in `trusted-projects.json`, beside that
+  config. A project's `exec` build steps and `toolchain` overrides run only
+  after you trust it once: `check_toolchain action=trust projectPath=<mod>`
+  lists what it would allow, and `mode=apply` records it. Until then an
+  applied build, convert, template extract or index build that would run
+  them is refused. `MODWRIGHT_TRUST_ALL=1` trusts every project, for CI.
 - **Overrides:** `MODWRIGHT_CACHE_DIR` moves the cache; `MODWRIGHT_HOME`
   moves everything.
 - **Project state** stays in the project's own `.modwright/`.
@@ -205,6 +239,50 @@ produce confident nonsense:
 - **Redistributing game data.** Indexes and templates are built from your
   own install, on your machine, and never shipped.
 
+## Security
+
+ModWright runs programs on your machine and writes into your game folders.
+What it runs, and where it writes:
+
+- **Tools it finds.** It runs the external tools it locates (LSLib divine,
+  WolvenKit CLI, Blender and the others `check_toolchain` lists). They come
+  from a `MODWRIGHT_TOOL_*` variable, your per-user config, its own managed
+  installs, PATH or common install locations. Managed installs are pinned
+  and their sha256 is checked before anything is written.
+- **A project's own commands.** A mod project's `exec` build steps and its
+  `toolchain` overrides are programs the project's author chose. They run
+  only after you trust that project on this machine:
+  `check_toolchain action=trust projectPath=<mod>` lists what it would allow,
+  and `mode=apply` records it. Read the project's `modwright.json` first,
+  above all for a mod you cloned from someone else. Trust belongs to the
+  folder, not to the file's content, so a trusted project that later gains
+  a step (after a `git pull`) is not asked again.
+- **Where it writes.** Every writer is dry-run until you apply it, and it
+  backs up what it replaces. A build writes under the project's
+  `build.outDir`, and a deploy writes under the game's mod roots. A project
+  path that is absolute or climbs out with `..` is refused unless that entry
+  sets `"allowOutsideRoot": true`. `rollback` restores only under the
+  project and the game's mod roots, unless you pass `allowOutsideRoots`.
+- **The in-game bridges.** While a verification bridge is deployed and the
+  game runs, anything that can write the bridge's request folder can run Lua
+  in the game. There is no token. Deploy a bridge only while you verify,
+  remove it afterwards, and never ship it (the release validators block a
+  build that contains it). The bridge READMEs under `bridges/` describe each
+  one's trust model.
+
+To report a security problem, use **Report a vulnerability** on
+[modwright-community's Security tab](https://github.com/jtrachtenberg/modwright-community/security),
+not a public issue.
+
+## Reporting a problem
+
+Bug reports, game and feature requests and questions go to
+[modwright-community](https://github.com/jtrachtenberg/modwright-community):
+[open an issue](https://github.com/jtrachtenberg/modwright-community/issues/new/choose),
+or ask in [Discussions](https://github.com/jtrachtenberg/modwright-community/discussions).
+Include `npx modwright --version`, the game, the tool call and what it
+returned. Release notes are in that repository's CHANGELOG.
+
 ## License
 
 MIT; see LICENSE. Files ModWright generates into your own projects are

package/bridges/bg3-se/README.md

@@ -82,6 +82,21 @@ No Lua parser is vendored. Syntax is checked with `luac -p` under Lua 5.1 and
 dispatch-table keys equal the catalogue's probe ids, that the `PROTOCOL_VERSION` literals
 agree, that `bridge.json` lists every shipped file, and that every `.lua` carries the banner.
 
+## Trust model
+
+While this bridge is deployed and the game is running, anything that can write a file into
+its request folder (`%LOCALAPPDATA%\Larian Studios\Baldur's Gate 3\Script Extender`) can run
+Lua inside the game. A request names its own probes and its own grants, and `bg3.lua.eval`
+runs whatever code a request carries once the request grants the `session` tier. There is no
+token. The nonce and the request's `armedUntil` expiry only stop a consumed or stale request
+from running again; they do not say who wrote it. So:
+
+- deploy the bridge only to a machine and a profile you control, and only while you are
+  verifying a mod;
+- remove `Mods/ModWrightBridge` from the profile when you are done, before playing normally
+  or sharing the profile;
+- never ship it. `bg3.history.bridge-never-ships` blocks a release build that contains it.
+
 ## What this bridge never does
 
 - No Osiris **action**, ever, and no forced cast: `Osi.UseSpell` was observed to re-cast,

package/bridges/cp2077-cet/README.md

@@ -155,6 +155,20 @@ The Lua is kept inside the 5.1-compatible subset shipped CET mods use, and check
 against both dialects — CET embeds a 5.4-era sol2, but nothing on disk pins which dialect
 features are available, so the intersection is the safe target.
 
+## Trust model
+
+While this bridge is deployed and the game is running, anything that can write a file into
+its write root (the folders listed under "The `io` write-root discovery") can run Lua inside
+the game, and so can anything that can type into the CET console. A request names its own
+probes and its own grants, and `cp2077.lua.eval` runs whatever code a request carries once
+the request grants the `session` tier. There is no token. The nonce and the request's expiry
+only stop a consumed or stale request from running again; they do not say who wrote it. So:
+
+- deploy the bridge only to an install you control, and only while you are verifying a mod;
+- remove `bin/x64/plugins/cyber_engine_tweaks/mods/ModWrightBridge` when you are done,
+  before playing normally;
+- never ship it. `cp2077.history.bridge-never-ships` blocks a release build that contains it.
+
 ## What this bridge never does
 
 * It never observes: no CET listener API is attested, so `effect: "observe"` is `unsupported`

package/dist/core/bridge/pending.js

@@ -51,7 +51,14 @@ export async function readPendingArm(projectRoot, id) {
     catch {
         return undefined;
     }
-    const parsed = pendingArmSchema.safeParse(JSON.parse(raw));
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = pendingArmSchema.safeParse(json);
     return parsed.success ? parsed.data : undefined;
 }
 export async function listPendingArms(projectRoot, game, opts) {

package/dist/core/bridge/stage.js

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { isDirectory, pathExists } from "../fsutil.js";
 import { parseProject } from "../project/schema.js";
 import { PROJECT_FILE } from "../project/types.js";
-import { executePlan, planCopy, planFile, planMkdir } from "../safety/index.js";
+import { executePlan, planCopy, planDelete, planFile, planMkdir } from "../safety/index.js";
 const BRIDGE_DIR_BY_GAME = {
     baldursgate3: "bg3-se",
     cyberpunk2077: "cp2077-cet",
@@ -77,7 +77,7 @@ export async function planStageBridge(projectRoot, game) {
     }
     const to = stagedBridgeDir(projectRoot, game);
     const registration = await planDeployTargetRegistration(projectRoot, game);
-    const operations = [planMkdir(path.dirname(to)), planCopy(from, to)];
+    const operations = [planMkdir(path.dirname(to)), ...(await pathExists(to) ? [planDelete(to)] : []), planCopy(from, to)];
     if (registration.op)
         operations.push(registration.op);
     return {

package/dist/core/build/run.js

@@ -2,7 +2,9 @@ import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import { pathExists, walk } from "../fsutil.js";
 import { normalizeBuildSteps } from "../project/build-steps.js";
+import { outsideRootPaths } from "../project/outside-root.js";
 import { locateTool as coreLocateTool, TOOL_SPECS } from "../toolchain/index.js";
+import { describeNeeds, isProjectTrusted, trustRefusal } from "../trust.js";
 import { buildContext, runValidators } from "../validate/index.js";
 import { runAssertAbsentStep, runAssertPresentStep, runExecStep, runZipStep } from "./steps/core.js";
 import { runBlenderExportStep, runVerifyArchiveListingStep, runWolvenkitImportStep, runWolvenkitPackStep, } from "./steps/cyberpunk.js";
@@ -168,6 +170,18 @@ export async function runBuild(project, surface, options) {
         throw new Error(`--only named no matching step id(s): ${options.only.join(", ")}. Known ids: ${active.map(({ step }) => step.id).filter(Boolean).join(", ") || "(none declared)"}`);
     }
     const skippedVariant = gatedOut.map(stepName);
+    const outside = outsideRootPaths(project.project, selected.map(({ step }) => step)).filter((e) => e.kind === "build-step" && !e.allowed);
+    if (outside.length > 0) {
+        throw new Error(`${project.project.name}: ${outside.map((e) => e.message).join("; ")}. A build writes only under build.outDir and runs only inside the project; ` +
+            `set "allowOutsideRoot": true on the step if this is intended.`);
+    }
+    if (options.mode === "apply") {
+        const exec = selected.flatMap(({ step, stepIndex }) => (step.step === "exec" ? [`"${stepName({ step, stepIndex })}" (${step.command})`] : []));
+        const what = describeNeeds({ toolchain: Object.keys(project.project.toolchain ?? {}), exec });
+        if (what && !(await (options.isTrusted ?? ((root) => isProjectTrusted(root)))(project.root))) {
+            throw new Error(trustRefusal(project.root, what));
+        }
+    }
     const version = options.version ?? project.project.version ?? "0.0.0";
     const stagingDir = project.build.staging
         ? path.resolve(project.root, project.build.staging)

package/dist/core/build/steps/core.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { isDirectory, walk } from "../../fsutil.js";
 import { globToRegExp } from "../../validate/context.js";
 import { runTool } from "../../toolchain/run.js";
+import { DEFAULT_TOOL_TIMEOUT_MS } from "../../toolchain/types.js";
 import { TOOL_SPECS } from "../../toolchain/specs.js";
 import { directoryEntry, pathEntries } from "../manifest.js";
 import { resolveOutDirPath, resolveSourceOrStagePath, resolveStageId } from "../paths.js";
@@ -86,9 +87,8 @@ export async function runZipStep(step, ctx) {
         .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     await fs.mkdir(path.dirname(out), { recursive: true });
     await writeZipFile(out, entries.map((entry) => ({ name: entry.name, read: () => fs.readFile(entry.abs) })));
-    const stat = await fs.stat(out);
-    if (stat.size === 0)
-        throw new BuildStepError(`zip: wrote an empty archive: ${out}`, step.id, step.step);
+    if (entries.length === 0)
+        throw new BuildStepError(`zip: nothing to archive under ${from}`, step.id, step.step);
     const outputs = await pathEntries([out]);
     return {
         inputs: [await directoryEntry(from)],
@@ -128,7 +128,7 @@ async function resolveCommandLocation(step, ctx) {
     }
     return { id: "exec", label, found: true, path: resolveSourceOrStagePath(step.command, ctx), usedBy: [] };
 }
-export const EXEC_DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+export const EXEC_DEFAULT_TIMEOUT_MS = DEFAULT_TOOL_TIMEOUT_MS;
 export async function runExecStep(step, ctx) {
     const location = await resolveCommandLocation(step, ctx);
     const command = location.path;

package/dist/core/deploy/plan.js

@@ -1,7 +1,8 @@
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
-import { pathExists, walk } from "../fsutil.js";
+import { isDirectory, pathExists, walk } from "../fsutil.js";
 import { globToRegExp, isExcludedByGlobs } from "../validate/index.js";
+import { outsideRootPaths } from "../project/outside-root.js";
 import { findRunningProcesses } from "../process.js";
 import { executePlan, isIdenticalFile, planCopy, planDelete, planJunction, planMkdir, planUnlink, sha256File } from "../safety/index.js";
 import { classifyReload } from "./reload.js";
@@ -158,6 +159,60 @@ export async function planDeploy(inputs) {
             backupRoot,
         };
     }
+    if (inputs.variant !== undefined) {
+        const named = new Set([
+            ...deploy.targets.flatMap((t) => (t.variant ? [t.variant] : [])),
+            ...Object.keys(project.project.build?.variants ?? {}),
+        ]);
+        if (!named.has(inputs.variant)) {
+            const known = [...named].sort();
+            return {
+                blocked: [
+                    {
+                        code: "unknown-variant",
+                        message: `${project.project.name}: variant "${inputs.variant}" is named by no deploy target and no build.variants entry` +
+                            (known.length > 0 ? ` (known: ${known.join(", ")})` : " (this project declares none)") +
+                            "; nothing was deployed rather than silently deploying only the ungated targets.",
+                        detail: { variant: inputs.variant, known },
+                    },
+                ],
+                confidence: { level: "high", assumptions: [], verifiedBy: ["modwright.json"] },
+                targets: [],
+                skipped: [],
+                deferred: [],
+                junctions: [],
+                pruned: [],
+                skippedDestDirs: [],
+                excluded: [],
+                warnings,
+                writtenPaths: [],
+                processCheck: emptyProcessCheck,
+                backupRoot,
+            };
+        }
+    }
+    const outside = outsideRootPaths(project.project).filter((e) => (e.kind === "deploy-target" || e.kind === "junction") && !e.allowed);
+    if (outside.length > 0) {
+        return {
+            blocked: outside.map((e) => ({
+                code: "outside-root",
+                message: `${e.message}; a deploy writes only under the game's mod roots. Set "allowOutsideRoot": true on that entry if this is intended.`,
+                detail: { kind: e.kind, value: e.value },
+            })),
+            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 {
@@ -202,6 +257,7 @@ export async function planDeploy(inputs) {
         }
         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}"` });
+            variantExcludedTargets.add(target);
             const skippedRoot = roots.find((r) => r.id === target.rootId);
             if (skippedRoot && (target.locked ?? defaultLocked(target.rootId))) {
                 notDeployedLocked.push({ target, rootPath: skippedRoot.path });
@@ -365,7 +421,18 @@ export async function planDeploy(inputs) {
             }
         }
         else {
+            const fold = (p) => (process.platform === "win32" ? path.resolve(p).toLowerCase() : path.resolve(p));
             for (const j of junctions) {
+                if (!(await isDirectory(j.target))) {
+                    blocked.push({
+                        code: "junction-target-missing",
+                        message: `deploy.junctions: ${j.linkPath} would point at ${j.target}, which is not a directory. Build or create it first, or fix the junction's target.`,
+                        detail: { linkPath: j.linkPath, target: j.target },
+                    });
+                    continue;
+                }
+                if (j.before === "link" && j.linkTargetBefore !== undefined && fold(j.linkTargetBefore) === fold(j.target))
+                    continue;
                 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}.`);
                 }

package/dist/core/deploy/reload.js

@@ -331,9 +331,11 @@ export function classifyReload(surfaceId, project, writtenPaths, options = {}) {
         .map((c) => RANK[c.action]);
     if (unclassified.length > 0)
         ranked.push(RANK.restart);
-    const overall = ranked.length === 0
-        ? "unknown"
-        : Object.keys(RANK).find((a) => RANK[a] === Math.max(...ranked));
+    const overall = writtenPaths.length === 0
+        ? "none"
+        : ranked.length === 0
+            ? "unknown"
+            : Object.keys(RANK).find((a) => RANK[a] === Math.max(...ranked));
     const notes = [];
     if (writtenPaths.length === 0) {
         notes.push("nothing was written, so there is nothing to reload");

package/dist/core/ledger/hooks.js

@@ -5,16 +5,33 @@ const NONE = { skipped: true, applied: [], refused: [] };
 function toPosix(p) {
     return p.split(path.sep).join("/");
 }
+function relPosix(projectRoot, f) {
+    return toPosix(path.isAbsolute(f) ? path.relative(projectRoot, f) : f);
+}
 function claimFileSet(claim, projectRoot) {
     const files = claim.scope?.files ?? [];
-    return new Set(files.map((f) => toPosix(path.isAbsolute(f) ? path.relative(projectRoot, f) : f)));
+    return new Set(files.map((f) => relPosix(projectRoot, f)));
+}
+function sameFile(a, b) {
+    if (a === b)
+        return true;
+    const lower = (x) => (process.platform === "win32" ? x.toLowerCase() : x);
+    const x = lower(a);
+    const y = lower(b);
+    return x.endsWith(`/${y}`) || y.endsWith(`/${x}`);
+}
+function anyMatch(files, f) {
+    for (const other of files)
+        if (sameFile(other, f))
+            return true;
+    return false;
 }
 export async function applyValidateLedgerHook(projectRoot, blockingFindingFiles, ranFiles, tool = "validate", options = {}) {
     const loaded = await loadClaims(projectRoot);
     if (!loaded.exists)
         return NONE;
-    const blocked = new Set(blockingFindingFiles.map(toPosix));
-    const ran = ranFiles ? new Set(ranFiles.map(toPosix)) : undefined;
+    const blocked = blockingFindingFiles.map((f) => relPosix(projectRoot, f));
+    const ran = ranFiles ? ranFiles.map((f) => relPosix(projectRoot, f)) : undefined;
     const by = options.by ?? "validate";
     let claims = loaded.claims;
     const applied = [];
@@ -25,10 +42,10 @@ export async function applyValidateLedgerHook(projectRoot, blockingFindingFiles,
         const files = claimFileSet(claim, projectRoot);
         if (files.size === 0)
             continue;
-        const allRan = !ran || [...files].every((f) => ran.has(f));
+        const allRan = !ran || [...files].every((f) => anyMatch(ran, f));
         if (!allRan)
             continue;
-        const anyBlocked = [...files].some((f) => blocked.has(f));
+        const anyBlocked = [...files].some((f) => anyMatch(blocked, f));
         if (anyBlocked)
             continue;
         const result = applyClaimTransition({ claims, id: claim.id, to: "checker-clean", tool, by, now: options.now });

package/dist/core/logs/scan.js

@@ -102,14 +102,30 @@ export async function scanSource(source, signatures, scope, ctx) {
     let text = "";
     const length = sizeBytes - startOffset;
     if (length > 0) {
-        const handle = await fs.open(source.path, "r");
         try {
-            const buffer = Buffer.alloc(length);
-            await handle.read(buffer, 0, length, startOffset);
-            text = buffer.toString("utf8");
+            const handle = await fs.open(source.path, "r");
+            try {
+                const buffer = Buffer.alloc(length);
+                await handle.read(buffer, 0, length, startOffset);
+                text = buffer.toString("utf8");
+            }
+            finally {
+                await handle.close();
+            }
         }
-        finally {
-            await handle.close();
+        catch (err) {
+            const status = {
+                source,
+                sizeBytes,
+                modifiedAt: modifiedAt.toISOString(),
+                zeroByte,
+                linesScanned: 0,
+                findingCount: 0,
+                unreadable: err.message,
+            };
+            if (stale !== undefined)
+                status.stale = stale;
+            return { status, findings: [] };
         }
     }
     if (startOffset === 0 && text.charCodeAt(0) === 0xfeff)

package/dist/core/project/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export { modProjectSchema, parseProject } from "./schema.js";
 export { findProjectFile, loadProject } from "./load.js";
+export { escapesRoot, outsideRootPaths } from "./outside-root.js";
 export { describeProject } from "./describe.js";
 export { defaultArtifactName, normalizeBuildSteps } from "./build-steps.js";

package/dist/core/project/load.js

@@ -4,6 +4,7 @@ import { isDirectory, pathExists } from "../fsutil.js";
 import { getSurface, surfaceIds } from "../../surfaces/index.js";
 import { parseProject } from "./schema.js";
 import { PROJECT_FILE } from "./types.js";
+import { looksAbsolute, outsideRootPaths } from "./outside-root.js";
 export async function findProjectFile(startDir) {
     let dir = path.resolve(startDir);
     for (;;) {
@@ -16,9 +17,6 @@ export async function findProjectFile(startDir) {
         dir = parent;
     }
 }
-function looksAbsolute(p) {
-    return path.isAbsolute(p) || /^[a-zA-Z]:[\\/]/.test(p) || p.startsWith("\\\\");
-}
 function isWithin(parent, child) {
     const rel = path.relative(parent, child);
     return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
@@ -115,29 +113,8 @@ export async function loadProject(fileOrDir) {
             }
         }
     }
-    const escapes = (p) => p !== undefined && (looksAbsolute(p) || p.split(/[\\/]/).includes(".."));
-    for (const target of project.deploy?.targets ?? []) {
-        if (escapes(target.into)) {
-            warnings.push(`deploy target "${target.from}": into "${target.into}" leaves the "${target.rootId}" root (absolute or "..")`);
-        }
-    }
-    for (const junction of project.deploy?.junctions ?? []) {
-        if (escapes(junction.linkPath)) {
-            warnings.push(`junction linkPath "${junction.linkPath}" leaves the "${junction.rootId}" root (absolute or "..")`);
-        }
-    }
-    for (const step of project.build?.steps ?? []) {
-        if (typeof step !== "object" || step === null)
-            continue;
-        const s = step;
-        if ((s.step === "wolvenkit-pack" || s.step === "divine-create-package") && escapes(s.out)) {
-            warnings.push(`build step ${s.step}: out "${s.out}" leaves build.outDir (absolute or "..")`);
-        }
-        if (s.step === "zip" && escapes(s.name))
-            warnings.push(`build step zip: name "${s.name}" leaves build.outDir (absolute or "..")`);
-        if (s.step === "exec" && s.cwd !== undefined && !s.cwd.includes("${stage}") && escapes(s.cwd)) {
-            warnings.push(`build step exec: cwd "${s.cwd}" leaves the project (absolute or "..")`);
-        }
+    for (const entry of outsideRootPaths(project)) {
+        warnings.push(entry.allowed ? `${entry.message} — allowed by allowOutsideRoot` : `${entry.message}; build and deploy refuse it unless the entry sets "allowOutsideRoot": true`);
     }
     const toolchain = project.toolchain
         ? Object.fromEntries(Object.entries(project.toolchain).map(([id, p]) => [id, looksAbsolute(p) ? p : resolveFromRoot(p)]))

package/dist/core/project/outside-root.js

@@ -0,0 +1,36 @@
+import * as path from "node:path";
+export function looksAbsolute(p) {
+    return path.isAbsolute(p) || /^[a-zA-Z]:[\\/]/.test(p) || p.startsWith("\\\\");
+}
+export function escapesRoot(p) {
+    return p !== undefined && (looksAbsolute(p) || p.split(/[\\/]/).includes(".."));
+}
+export function outsideRootPaths(project, steps = project.build?.steps) {
+    const found = [];
+    for (const target of project.deploy?.targets ?? []) {
+        if (escapesRoot(target.into)) {
+            found.push({ kind: "deploy-target", value: target.into, allowed: target.allowOutsideRoot === true, message: `deploy target "${target.from}": into "${target.into}" leaves the "${target.rootId}" root (absolute or "..")` });
+        }
+    }
+    for (const junction of project.deploy?.junctions ?? []) {
+        if (escapesRoot(junction.linkPath)) {
+            found.push({ kind: "junction", value: junction.linkPath, allowed: junction.allowOutsideRoot === true, message: `junction linkPath "${junction.linkPath}" leaves the "${junction.rootId}" root (absolute or "..")` });
+        }
+    }
+    for (const step of steps ?? []) {
+        if (typeof step !== "object" || step === null)
+            continue;
+        const s = step;
+        const label = `build step ${s.id ? `"${s.id}" (${s.step})` : s.step}`;
+        const allowed = s.allowOutsideRoot === true;
+        if ((s.step === "wolvenkit-pack" || s.step === "divine-create-package") && escapesRoot(s.out)) {
+            found.push({ kind: "build-step", value: s.out, allowed, message: `${label}: out "${s.out}" leaves build.outDir (absolute or "..")` });
+        }
+        if (s.step === "zip" && escapesRoot(s.name))
+            found.push({ kind: "build-step", value: s.name, allowed, message: `${label}: name "${s.name}" leaves build.outDir (absolute or "..")` });
+        if (s.step === "exec" && s.cwd !== undefined && !s.cwd.includes("${stage}") && escapesRoot(s.cwd)) {
+            found.push({ kind: "build-step", value: s.cwd, allowed, message: `${label}: cwd "${s.cwd}" leaves the project (absolute or "..")` });
+        }
+    }
+    return found;
+}