modwright 0.1.0

package/dist/core/build/run.js

@@ -0,0 +1,342 @@
+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 { locateTool as coreLocateTool, TOOL_SPECS } from "../toolchain/index.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";
+import { runDivineCreatePackageStep, runDivineLocaStep, runDivineLsxToLsfStep, runVerifyPackageListingStep, } from "./steps/bg3.js";
+import { resolveOutDirPath, resolveSourceOrStagePath, stageStepOutputDir } from "./paths.js";
+import { runStageStep } from "./stage.js";
+import { BuildStepError } from "./types.js";
+function buildStamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+function defaultLocateTool(project, mode) {
+    const overrides = project.project.toolchain;
+    return async (id) => {
+        const spec = TOOL_SPECS.find((s) => s.id === id);
+        if (!spec) {
+            return {
+                id,
+                label: id,
+                found: false,
+                usedBy: [],
+                hint: `"${id}" is not a known tool id in ModWright's toolchain catalog (see core/toolchain/specs.ts).`,
+            };
+        }
+        return coreLocateTool(spec, { projectOverrides: overrides, probe: mode === "apply" ? "all" : "none" });
+    };
+}
+async function buildSourceMap(project) {
+    const map = new Map();
+    for (const s of project.sources) {
+        let exists = false;
+        let isFile = false;
+        try {
+            isFile = (await fs.stat(s.absPath)).isFile();
+            exists = true;
+        }
+        catch {
+            exists = false;
+        }
+        map.set(s.id, { id: s.id, kind: s.kind, path: s.path, absPath: s.absPath, exists, isFile });
+    }
+    return map;
+}
+function resolveVariant(project, variantName) {
+    if (!variantName)
+        return undefined;
+    const variant = project.project.build?.variants?.[variantName];
+    if (!variant) {
+        const known = Object.keys(project.project.build?.variants ?? {});
+        throw new Error(`Unknown build variant "${variantName}". Known: ${known.length > 0 ? known.join(", ") : "(none declared)"}`);
+    }
+    return variant;
+}
+function applyVariant(steps, variant) {
+    if (!variant)
+        return steps;
+    const withAddedSources = steps.map((step) => {
+        if (step.step !== "stage" || !variant.addSources || variant.addSources.length === 0)
+            return step;
+        return { ...step, sources: [...step.sources, ...variant.addSources] };
+    });
+    return [...withAddedSources, ...(variant.addSteps ?? [])];
+}
+function stepName({ step, stepIndex }) {
+    return step.id ?? `${step.step}-${stepIndex}`;
+}
+function gateByVariant(steps, variantName) {
+    const withIndex = steps.map((step, stepIndex) => ({ step, stepIndex }));
+    const runsHere = ({ step }) => !step.variant || step.variant === variantName;
+    return { active: withIndex.filter(runsHere), gatedOut: withIndex.filter((s) => !runsHere(s)) };
+}
+function selectSteps(withIndex, only) {
+    if (only && only.length > 0) {
+        const onlySet = new Set(only);
+        const selected = withIndex.filter(({ step }) => step.id !== undefined && onlySet.has(step.id));
+        return { selected, skippedOptional: [] };
+    }
+    const selected = withIndex.filter(({ step }) => !step.optional);
+    const skippedOptional = withIndex.filter(({ step }) => step.optional).map(stepName);
+    return { selected, skippedOptional };
+}
+async function runOneStep(step, ctx) {
+    switch (step.step) {
+        case "stage":
+            return runStageStep(step, ctx);
+        case "assert-absent":
+            return runAssertAbsentStep(step, ctx);
+        case "assert-present":
+            return runAssertPresentStep(step, ctx);
+        case "zip":
+            return runZipStep(step, ctx);
+        case "exec":
+            return runExecStep(step, ctx);
+        case "blender-export":
+            return runBlenderExportStep(step, ctx);
+        case "wolvenkit-import":
+            return runWolvenkitImportStep(step, ctx);
+        case "wolvenkit-pack":
+            return runWolvenkitPackStep(step, ctx);
+        case "divine-lsx-to-lsf":
+            return runDivineLsxToLsfStep(step, ctx);
+        case "divine-loca":
+            return runDivineLocaStep(step, ctx);
+        case "divine-create-package":
+            return runDivineCreatePackageStep(step, ctx);
+        case "verify-listing": {
+            const of = resolveOutDirPath(step.of, ctx);
+            return of.toLowerCase().endsWith(".pak")
+                ? runVerifyPackageListingStep(step, ctx, of)
+                : runVerifyArchiveListingStep(step, ctx, of);
+        }
+        default: {
+            const exhaustive = step;
+            throw new Error(`build: unhandled step kind "${exhaustive.step}"`);
+        }
+    }
+}
+function declaredOutputs(step, ctx) {
+    switch (step.step) {
+        case "stage":
+            return [stageStepOutputDir(ctx.stageRoot, step.id ?? `stage-${ctx.stepIndex}`, step.into)];
+        case "wolvenkit-pack":
+        case "divine-create-package":
+            return [resolveOutDirPath(step.out, ctx)];
+        case "zip":
+            return [resolveOutDirPath(step.name, ctx)];
+        case "blender-export":
+            return [resolveSourceOrStagePath(step.out, ctx)];
+        case "exec":
+            return step.expectOutputs.map((p) => resolveSourceOrStagePath(p, ctx));
+        default:
+            return [];
+    }
+}
+function stepLabel(step, stepIndex) {
+    return step.id ? `${step.step} (${step.id})` : `${step.step}#${stepIndex}`;
+}
+const EQUIVALENCE_BY_SURFACE = {
+    cyberpunk2077: "listing-plus-content",
+    baldursgate3: "byte-identical",
+};
+export async function runBuild(project, surface, options) {
+    if (!project.build) {
+        throw new Error(`${project.project.name}: project has no "build" configuration — nothing to build.`);
+    }
+    const startedAt = new Date().toISOString();
+    const variant = resolveVariant(project, options.variant);
+    const baseSteps = normalizeBuildSteps(project.project);
+    const steps = applyVariant(baseSteps, variant);
+    const { active, gatedOut } = gateByVariant(steps, options.variant);
+    if (options.only && options.only.length > 0) {
+        const activeIds = new Set(active.map(({ step }) => step.id).filter(Boolean));
+        const gatedOnly = options.only.filter((id) => !activeIds.has(id) && gatedOut.some(({ step }) => step.id === id));
+        if (gatedOnly.length > 0) {
+            const needs = gatedOnly.map((id) => {
+                const gates = [...new Set(gatedOut.filter(({ step }) => step.id === id).map(({ step }) => step.variant))];
+                return `"${id}" runs only under variant ${gates.map((g) => `"${g}"`).join(" or ")}`;
+            });
+            throw new Error(`--only named step(s) the ${options.variant ? `"${options.variant}" variant` : "plain build (no variant)"} gates out: ${needs.join("; ")}. Pass that variant to run them.`);
+        }
+    }
+    const { selected, skippedOptional } = selectSteps(active, options.only);
+    if (options.only && options.only.length > 0 && selected.length === 0) {
+        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 version = options.version ?? project.project.version ?? "0.0.0";
+    const stagingDir = project.build.staging
+        ? path.resolve(project.root, project.build.staging)
+        : path.join(project.root, ".modwright", "cache", "build");
+    const stageRoot = path.join(stagingDir, buildStamp());
+    const outDirAbs = project.build.absOutDir;
+    const locateTool = options.locateTool ?? defaultLocateTool(project, options.mode);
+    const projectExclude = project.build.exclude ?? [];
+    const dropSet = new Set(variant?.dropExclude ?? []);
+    const defaultExclude = projectExclude.filter((g) => !dropSet.has(g));
+    if (options.mode === "apply") {
+        await fs.mkdir(outDirAbs, { recursive: true });
+    }
+    const producedOutputs = [];
+    const plannedExecOutputs = [];
+    const manifestSteps = [];
+    const dryRunPlan = [];
+    let cheapGateRan = false;
+    let validated = false;
+    let failed = false;
+    let failureReason;
+    let failedStep;
+    const runCheapGate = async () => {
+        cheapGateRan = true;
+        if (options.noValidate || !options.validatorRegistry)
+            return undefined;
+        const stagedFiles = (await pathExists(stageRoot))
+            ? (await walk(stageRoot, { limit: 200_000 })).files.map((f) => path.join(stageRoot, f))
+            : [];
+        const vctx = buildContext({
+            project,
+            surface,
+            install: options.install,
+            store: options.store,
+            listFilesOverride: stagedFiles,
+        });
+        const report = await runValidators(options.validatorRegistry, vctx, { cheapOnly: true });
+        if (report.blocking) {
+            const blockers = report.findings.filter((f) => f.severity === "block" && !f.suppressedBy);
+            return `cheap-validate gate refused the build: ${blockers.map((f) => `${f.message}`).join("; ")}`;
+        }
+        validated = true;
+        return undefined;
+    };
+    for (const { step, stepIndex } of selected) {
+        const sources = await buildSourceMap(project);
+        const ctx = {
+            mode: options.mode,
+            projectRoot: project.root,
+            stageRoot,
+            outDirAbs,
+            version,
+            sources,
+            defaultExclude,
+            variant: options.variant,
+            producedOutputs,
+            ...(options.mode === "dry-run" ? { plannedExecOutputs } : {}),
+            locateTool,
+            stepIndex,
+        };
+        const isPackagingStep = step.step === "wolvenkit-pack" || step.step === "divine-create-package" || step.step === "zip";
+        if (options.mode === "apply" && isPackagingStep && !cheapGateRan) {
+            const refusal = await runCheapGate();
+            if (refusal) {
+                failed = true;
+                failureReason = refusal;
+                break;
+            }
+        }
+        const t0 = Date.now();
+        let result;
+        try {
+            result = await runOneStep(step, ctx);
+        }
+        catch (err) {
+            failed = true;
+            failureReason =
+                err instanceof BuildStepError
+                    ? `${stepLabel(step, stepIndex)}: ${err.message}`
+                    : `${stepLabel(step, stepIndex)}: ${err.message}`;
+            failedStep = {
+                step: step.step,
+                id: step.id,
+                label: stepLabel(step, stepIndex),
+                ...(err instanceof BuildStepError && err.output ? { output: err.output } : {}),
+            };
+            break;
+        }
+        const durationMs = Date.now() - t0;
+        producedOutputs.push(...(result.outputs.length > 0 ? result.outputs.map((o) => o.path) : declaredOutputs(step, ctx)));
+        if (options.mode === "dry-run") {
+            if (step.step === "exec")
+                plannedExecOutputs.push(...declaredOutputs(step, ctx));
+            dryRunPlan.push({ step: step.step, id: step.id, optional: step.optional, description: result.plan ?? "(no plan produced)" });
+        }
+        else {
+            manifestSteps.push({
+                step: step.step,
+                id: step.id,
+                tool: result.tool,
+                toolVersion: result.toolVersion,
+                inputs: result.inputs,
+                outputs: result.outputs,
+                durationMs,
+                verified: result.verified,
+                optional: step.optional,
+                extras: result.extras,
+                warnings: result.warnings,
+            });
+        }
+    }
+    if (!failed && options.mode === "apply" && !cheapGateRan) {
+        const refusal = await runCheapGate();
+        if (refusal) {
+            failed = true;
+            failureReason = refusal;
+        }
+    }
+    if (failed) {
+        return {
+            mode: options.mode,
+            project: project.project.name,
+            variant: options.variant,
+            stageRoot,
+            failed: true,
+            failureReason,
+            ...(failedStep ? { failedStep } : {}),
+            skippedOptional,
+            ...(options.mode === "dry-run" ? { skippedVariant } : {}),
+            outDirAbs,
+        };
+    }
+    if (options.mode === "dry-run") {
+        return {
+            mode: "dry-run",
+            project: project.project.name,
+            variant: options.variant,
+            stageRoot,
+            plan: dryRunPlan,
+            failed: false,
+            skippedOptional,
+            skippedVariant,
+            outDirAbs,
+        };
+    }
+    const manifest = {
+        project: project.project.name,
+        stageRoot,
+        variant: options.variant,
+        validated,
+        equivalence: EQUIVALENCE_BY_SURFACE[surface.id] ?? null,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        steps: manifestSteps,
+    };
+    const manifestPath = path.join(outDirAbs, ".modwright-build-manifest.json");
+    await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    if (!options.keepStage) {
+        await fs.rm(stageRoot, { recursive: true, force: true });
+    }
+    return {
+        mode: "apply",
+        project: project.project.name,
+        variant: options.variant,
+        stageRoot,
+        manifest,
+        manifestPath,
+        failed: false,
+        skippedOptional,
+        outDirAbs,
+    };
+}

package/dist/core/build/stage.js

@@ -0,0 +1,265 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { isDirectory, walk } from "../fsutil.js";
+import { globToRegExp, isExcludedByGlobs } from "../validate/context.js";
+import { directoryEntry } from "./manifest.js";
+import { resolveOutDirPath, stageStepOutputDir } from "./paths.js";
+import { BuildStepError } from "./types.js";
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+function isWithin(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!(rel === ".." || rel.startsWith(`..${path.sep}`)) && !path.isAbsolute(rel));
+}
+function isUnderModwright(abs, projectRoot) {
+    return isWithin(path.join(projectRoot, ".modwright"), abs);
+}
+function stagingGuardDir(ctx) {
+    const stagingDir = path.dirname(ctx.stageRoot);
+    const proper = stagingDir !== ctx.projectRoot && isWithin(ctx.projectRoot, stagingDir);
+    return proper ? stagingDir : ctx.stageRoot;
+}
+export function isGuardedPath(abs, projectRoot, outDirAbs) {
+    return isUnderModwright(abs, projectRoot) || isWithin(outDirAbs, abs);
+}
+function asEntry(raw) {
+    return typeof raw === "string" ? { source: raw } : raw;
+}
+function describeEntry(entry) {
+    return entry.output !== undefined ? `output "${entry.output}"` : `source "${entry.source}"`;
+}
+function normalizePrefix(raw) {
+    return toPosix(raw)
+        .split("/")
+        .filter((segment) => segment.length > 0 && segment !== ".")
+        .join("/");
+}
+function defaultPrefixForSource(source, ctx) {
+    const declared = source.path && !path.isAbsolute(source.path) ? source.path : path.relative(ctx.projectRoot, source.absPath);
+    const rel = normalizePrefix(declared);
+    if (rel === "" || rel.startsWith("../") || rel === ".." || path.isAbsolute(rel)) {
+        return source.isFile ? "" : path.basename(source.absPath);
+    }
+    return source.isFile ? normalizePrefix(path.posix.dirname(rel)) : rel;
+}
+function joinDest(prefix, rel) {
+    return prefix === "" ? rel : `${prefix}/${rel}`;
+}
+function resolveOutputEntry(entry, step, ctx) {
+    const abs = resolveOutDirPath(entry.output, ctx);
+    const known = ctx.producedOutputs.some((p) => path.resolve(p) === path.resolve(abs));
+    if (!known) {
+        throw new BuildStepError(`stage step's output "${entry.output}" was not produced by any earlier step in this build ` +
+            `(produced so far: ${ctx.producedOutputs.length > 0 ? ctx.producedOutputs.map((p) => path.basename(p)).join(", ") : "nothing"}). ` +
+            `An "output" entry may only name an artifact an earlier step of the same run wrote.`, step.id, step.step);
+    }
+    return abs;
+}
+function plannedFilesUnder(source, ctx) {
+    if (ctx.mode !== "dry-run" || source.exists)
+        return [];
+    return (ctx.plannedExecOutputs ?? []).filter((p) => isWithin(source.absPath, p));
+}
+async function planFiles(step, ctx) {
+    const files = [];
+    const plannedSources = [];
+    const skippedLinks = [];
+    const walkAll = async (dir) => {
+        const walked = await walk(dir, { limit: 200_000, skipDirs: [".modwright"], stat: false });
+        if (walked.truncated) {
+            throw new BuildStepError(`stage: ${dir} holds more than 200000 files; the listing was cut short, so nothing was staged`, step.id, step.step);
+        }
+        skippedLinks.push(...(walked.links ?? []).map((rel) => path.join(dir, rel)));
+        return walked;
+    };
+    const claimed = new Map();
+    let excludedCount = 0;
+    const matchedGlobs = new Set();
+    for (const raw of step.sources) {
+        const entry = asEntry(raw);
+        if (entry.variant && entry.variant !== ctx.variant)
+            continue;
+        const excludeGlobs = [...ctx.defaultExclude, ...(step.exclude ?? []), ...(entry.exclude ?? [])];
+        const excludeRes = excludeGlobs.map(globToRegExp);
+        const includeRes = (entry.include ?? []).map(globToRegExp);
+        const origin = describeEntry(entry);
+        const isExcluded = (relSource, abs) => {
+            const relProject = abs ? toPosix(path.relative(ctx.projectRoot, abs)) : undefined;
+            for (let i = 0; i < excludeRes.length; i++) {
+                if (isExcludedByGlobs([excludeRes[i]], relSource, relProject)) {
+                    matchedGlobs.add(excludeGlobs[i]);
+                    return true;
+                }
+            }
+            return false;
+        };
+        const isIncluded = (relForMatch) => includeRes.length === 0 || includeRes.some((re) => re.test(relForMatch));
+        const add = (abs, relDest) => {
+            const existing = claimed.get(relDest);
+            if (existing !== undefined && existing !== origin) {
+                throw new BuildStepError(`stage: ${existing} and ${origin} both write "${relDest}" — one would silently overlay the other. ` +
+                    `Give one of them its own "into" prefix.`, step.id, step.step);
+            }
+            claimed.set(relDest, origin);
+            files.push({ abs, relDest, origin });
+        };
+        if (entry.output !== undefined) {
+            const abs = resolveOutputEntry(entry, step, ctx);
+            const prefix = normalizePrefix(entry.into ?? "");
+            let stat;
+            try {
+                stat = await fs.stat(abs);
+            }
+            catch {
+                stat = undefined;
+            }
+            if (!stat) {
+                if (ctx.mode === "dry-run") {
+                    add(abs, joinDest(prefix, path.basename(abs)));
+                    continue;
+                }
+                throw new BuildStepError(`stage step's output "${entry.output}" is missing on disk (${abs})`, step.id, step.step);
+            }
+            if (stat.isDirectory()) {
+                const walked = await walkAll(abs);
+                for (const rel of walked.files) {
+                    const relPosix = toPosix(rel);
+                    if (!isIncluded(relPosix))
+                        continue;
+                    if (isExcluded(relPosix, path.join(abs, rel))) {
+                        excludedCount++;
+                        continue;
+                    }
+                    add(path.join(abs, rel), joinDest(prefix, relPosix));
+                }
+            }
+            else {
+                const base = path.basename(abs);
+                if (isIncluded(base) && !isExcluded(base, abs))
+                    add(abs, joinDest(prefix, base));
+                else
+                    excludedCount += isIncluded(base) ? 1 : 0;
+            }
+            continue;
+        }
+        const source = ctx.sources.get(entry.source);
+        if (!source)
+            continue;
+        if (isUnderModwright(source.absPath, ctx.projectRoot) || source.absPath === ctx.outDirAbs)
+            continue;
+        if (isWithin(stagingGuardDir(ctx), source.absPath))
+            continue;
+        if (!source.exists) {
+            const planned = plannedFilesUnder(source, ctx);
+            if (planned.length === 0)
+                continue;
+            plannedSources.push(entry.source);
+            const prefix = normalizePrefix(entry.into ?? (step.into ? "" : defaultPrefixForSource(source, ctx)));
+            for (const abs of planned) {
+                const relPosix = abs === source.absPath ? path.basename(abs) : toPosix(path.relative(source.absPath, abs));
+                if (!isIncluded(relPosix))
+                    continue;
+                if (isExcluded(relPosix, abs)) {
+                    excludedCount++;
+                    continue;
+                }
+                add(abs, joinDest(prefix, relPosix));
+            }
+            continue;
+        }
+        const prefix = normalizePrefix(entry.into ?? (step.into ? "" : defaultPrefixForSource(source, ctx)));
+        const outDirIsInsideThisSource = isWithin(source.absPath, ctx.outDirAbs);
+        if (source.isFile) {
+            const rel = path.basename(source.absPath);
+            if (!isIncluded(rel))
+                continue;
+            if (isExcluded(rel, source.absPath)) {
+                excludedCount++;
+                continue;
+            }
+            add(source.absPath, joinDest(prefix, rel));
+            continue;
+        }
+        const walked = await walkAll(source.absPath);
+        for (const rel of walked.files) {
+            const abs = path.join(source.absPath, rel);
+            if (isUnderModwright(abs, ctx.projectRoot) || isWithin(stagingGuardDir(ctx), abs))
+                continue;
+            if (outDirIsInsideThisSource && isWithin(ctx.outDirAbs, abs))
+                continue;
+            const relPosix = toPosix(rel);
+            if (!isIncluded(relPosix))
+                continue;
+            if (isExcluded(relPosix, abs)) {
+                excludedCount++;
+                continue;
+            }
+            add(abs, joinDest(prefix, relPosix));
+        }
+    }
+    return { files, excludedCount, matchedGlobs, skippedLinks, plannedSources };
+}
+export async function runStageStep(step, ctx) {
+    const warnings = [];
+    const entries = step.sources.map(asEntry).filter((entry) => !entry.variant || entry.variant === ctx.variant);
+    const sourceIds = entries.filter((entry) => entry.source !== undefined).map((entry) => entry.source);
+    for (const id of sourceIds) {
+        if (!ctx.sources.has(id)) {
+            throw new BuildStepError(`stage step references unknown source id "${id}"`, step.id, step.step);
+        }
+    }
+    for (const id of sourceIds) {
+        const source = ctx.sources.get(id);
+        if (!source.exists && plannedFilesUnder(source, ctx).length === 0) {
+            throw new BuildStepError(`stage step's source "${id}" does not exist on disk (${source.absPath})`, step.id, step.step);
+        }
+    }
+    const { files, excludedCount, matchedGlobs, skippedLinks, plannedSources } = await planFiles(step, ctx);
+    if (skippedLinks.length > 0) {
+        warnings.push(`${skippedLinks.length} symbolic link(s)/junction(s) under the staged sources were not followed and not staged: ${skippedLinks.slice(0, 10).join(", ")}${skippedLinks.length > 10 ? ", ..." : ""}. Copy the real files in if they must ship.`);
+    }
+    const declaredGlobs = [
+        ...ctx.defaultExclude,
+        ...(step.exclude ?? []),
+        ...entries.flatMap((entry) => entry.exclude ?? []),
+    ];
+    for (const glob of new Set(declaredGlobs)) {
+        if (!matchedGlobs.has(glob)) {
+            warnings.push(`exclude glob "${glob}" matched nothing — a stale exclusion is how a dev file returns`);
+        }
+    }
+    const id = step.id ?? `stage-${ctx.stepIndex}`;
+    const destRoot = stageStepOutputDir(ctx.stageRoot, id, step.into);
+    const label = entries.map((entry) => entry.output ?? entry.source).join(", ");
+    if (files.length === 0) {
+        throw new BuildStepError(`stage step staged zero files from [${label}] — check excludes and source paths`, step.id, step.step);
+    }
+    if (ctx.mode === "dry-run") {
+        return {
+            inputs: [],
+            outputs: [],
+            verified: true,
+            warnings,
+            extras: { stageRoot: destRoot, fileCount: files.length, excludedCount, excluded: [...matchedGlobs] },
+            plan: `stage ${files.length} file(s) from [${label}] into ${destRoot}` +
+                (plannedSources.length > 0
+                    ? `; ${plannedSources.map((id) => `"${id}"`).join(", ")} not on disk yet: planned from the files an earlier exec step declares in expectOutputs (the full tree is known once it runs)`
+                    : ""),
+        };
+    }
+    await fs.mkdir(destRoot, { recursive: true });
+    for (const file of files) {
+        const dest = path.join(destRoot, ...file.relDest.split("/"));
+        await fs.mkdir(path.dirname(dest), { recursive: true });
+        await fs.copyFile(file.abs, dest);
+    }
+    const outputEntry = (await isDirectory(destRoot)) ? await directoryEntry(destRoot) : undefined;
+    return {
+        inputs: [],
+        outputs: outputEntry ? [outputEntry] : [],
+        verified: true,
+        warnings,
+        extras: { stageRoot: destRoot, fileCount: files.length, excludedCount, excluded: [...matchedGlobs] },
+    };
+}