modwright 0.1.0

package/dist/core/process.js

@@ -0,0 +1,49 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export async function findRunningProcesses(names) {
+    const wanted = new Map(names.map((name) => [name.toLowerCase(), name]));
+    try {
+        if (process.platform === "win32") {
+            const { stdout } = await execFileAsync("tasklist", ["/FO", "CSV", "/NH"], {
+                windowsHide: true,
+                timeout: 10_000,
+            });
+            const running = [];
+            for (const line of stdout.split(/\r?\n/)) {
+                const match = line.match(/^"([^"]+)","(\d+)"/);
+                if (!match)
+                    continue;
+                const name = wanted.get(match[1].toLowerCase());
+                if (name)
+                    running.push({ name, pid: Number(match[2]) });
+            }
+            return { checked: true, running };
+        }
+        const { stdout } = await execFileAsync("ps", ["-A", "-o", "pid=,args="], { timeout: 10_000 });
+        const running = matchPsArgs(stdout, names);
+        return { checked: true, running };
+    }
+    catch {
+        return { checked: false, running: [] };
+    }
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function matchPsArgs(stdout, names) {
+    const patterns = names.map((name) => {
+        const bare = name.replace(/\.exe$/i, "");
+        return { name, re: new RegExp(`(?:^|[/\\\\])${escapeRegExp(bare)}(?:\\.exe)?(?:\\s|$)`, "i") };
+    });
+    const running = [];
+    for (const line of stdout.split("\n")) {
+        const match = line.trim().match(/^(\d+)\s+(.+)$/);
+        if (!match)
+            continue;
+        const hit = patterns.find((p) => p.re.test(match[2]));
+        if (hit)
+            running.push({ name: hit.name, pid: Number(match[1]) });
+    }
+    return running;
+}

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

@@ -0,0 +1,83 @@
+function basenameOf(p) {
+    const parts = p.replace(/\\/g, "/").split("/").filter((part) => part.length > 0);
+    return parts[parts.length - 1] ?? p;
+}
+export function defaultArtifactName(project) {
+    const archiveSource = project.sources.find((s) => s.kind === "archive-staging");
+    if (archiveSource)
+        return basenameOf(archiveSource.path);
+    return project.name.replace(/[^A-Za-z0-9]+/g, "");
+}
+function defaultForTypedStepName(step, project) {
+    const name = defaultArtifactName(project);
+    switch (step) {
+        case "stage":
+            return { step: "stage", sources: project.sources.map((s) => s.id) };
+        case "assert-absent":
+            return { step: "assert-absent", patterns: [] };
+        case "assert-present":
+            return { step: "assert-present", paths: [] };
+        case "zip":
+            return { step: "zip", from: "${stage}", name: `${name}-\${version}.zip` };
+        case "wolvenkit-pack":
+            return { step: "wolvenkit-pack", from: "${stage}", out: `${name}.archive`, verbosity: "Minimal" };
+        case "divine-lsx-to-lsf":
+            return { step: "divine-lsx-to-lsf", in: "${stage}", glob: "**/*.lsx", deleteSource: false };
+        case "divine-loca":
+            return { step: "divine-loca", in: "${stage}", glob: "**/*.xml" };
+        case "divine-create-package":
+            return { step: "divine-create-package", from: "${stage}", out: `${name}.pak` };
+        case "blender-export":
+        case "wolvenkit-import":
+        case "verify-listing":
+        case "exec":
+            throw new Error(`build step "${step}" has no default parameters (it names a specific file or command this project's ` +
+                `file must supply) — write it out as a typed step object instead of a bare string.`);
+        default:
+            throw new Error(`Unknown build step "${step}". Known bare-string shorthands: "wolvenkit-pack", ` +
+                `"stage-mods-public-generated", "pack-pak", or any typed step's own name.`);
+    }
+}
+export function expandBareString(entry, project) {
+    const name = defaultArtifactName(project);
+    switch (entry) {
+        case "wolvenkit-pack":
+            return [
+                { step: "stage", id: "stage", sources: project.sources.map((s) => s.id) },
+                { step: "wolvenkit-pack", from: "${stage}", out: `${name}.archive`, verbosity: "Minimal" },
+            ];
+        case "pack-pak":
+            return [{ step: "divine-create-package", from: "${stage}", out: `${name}.pak` }];
+        case "stage-mods-public-generated":
+            return [{ step: "stage", id: "stage", sources: ["mods", "public", "generated"] }];
+        default:
+            return [defaultForTypedStepName(entry, project)];
+    }
+}
+function withStepDefaults(step) {
+    switch (step.step) {
+        case "wolvenkit-pack":
+            return { ...step, verbosity: step.verbosity ?? "Minimal" };
+        case "divine-lsx-to-lsf":
+            return { ...step, glob: step.glob ?? "**/*.lsx", deleteSource: step.deleteSource ?? false };
+        case "divine-loca":
+            return { ...step, glob: step.glob ?? "**/*.xml" };
+        case "exec":
+            return { ...step, args: step.args ?? [], expectOutputs: step.expectOutputs ?? [] };
+        default:
+            return step;
+    }
+}
+export function normalizeBuildSteps(project) {
+    const steps = project.build?.steps ?? [];
+    const out = [];
+    for (const entry of steps) {
+        if (typeof entry === "string") {
+            out.push(...expandBareString(entry, project));
+        }
+        else {
+            out.push(withStepDefaults(entry));
+        }
+    }
+    return out;
+}

package/dist/core/project/describe.js

@@ -0,0 +1,74 @@
+import { getSurface } from "../../surfaces/index.js";
+import { normalizeBuildSteps } from "./build-steps.js";
+export function describeProject(resolved) {
+    const { project } = resolved;
+    const warnings = [...resolved.warnings];
+    const surface = getSurface(project.game);
+    const game = surface ? { id: surface.id, name: surface.name } : { id: project.game, name: project.game };
+    const rootLabels = new Map();
+    if (surface) {
+        const placeholder = { gameId: surface.id, root: "<install>", source: "manual" };
+        for (const root of surface.modRoots(placeholder)) {
+            rootLabels.set(root.id, root.label);
+        }
+    }
+    const deploy = project.deploy
+        ? {
+            targets: project.deploy.targets.map((target) => {
+                const rootLabel = rootLabels.get(target.rootId);
+                if (surface && !rootLabel) {
+                    warnings.push(`deploy target rootId "${target.rootId}" is not a known ModRoot on surface "${surface.id}"`);
+                }
+                return {
+                    rootId: target.rootId,
+                    rootLabel,
+                    from: target.from,
+                    into: target.into,
+                    waitForGameExit: target.waitForGameExit,
+                    backup: target.backup,
+                    locked: target.locked,
+                    mode: target.mode,
+                    prune: target.prune,
+                    variant: target.variant,
+                };
+            }),
+            junctions: project.deploy.junctions,
+            waitMinutes: project.deploy.waitMinutes,
+        }
+        : undefined;
+    let normalizedSteps;
+    try {
+        normalizedSteps = project.build?.steps ? normalizeBuildSteps(project).map((s) => `${s.id ?? s.step}${s.variant ? ` [variant: ${s.variant}]` : ""}`) : undefined;
+    }
+    catch {
+        normalizedSteps = undefined;
+    }
+    return {
+        name: project.name,
+        game,
+        version: project.version,
+        authors: project.authors,
+        identity: project.identity,
+        sources: resolved.sources,
+        build: resolved.build
+            ? {
+                staging: resolved.build.staging,
+                absStaging: resolved.build.absStaging,
+                outDir: resolved.build.outDir,
+                absOutDir: resolved.build.absOutDir,
+                outDirExists: resolved.build.outDirExists,
+                steps: resolved.build.steps,
+                normalizedSteps,
+                exclude: resolved.build.exclude,
+                variantNames: resolved.build.variants ? Object.keys(resolved.build.variants) : undefined,
+            }
+            : undefined,
+        deploy,
+        dependencies: project.dependencies,
+        publish: project.publish,
+        toolchain: project.toolchain,
+        testProfile: project.testProfile,
+        reload: project.reload,
+        warnings,
+    };
+}

package/dist/core/project/index.js

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

package/dist/core/project/load.js

@@ -0,0 +1,146 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { isDirectory, pathExists } from "../fsutil.js";
+import { getSurface, surfaceIds } from "../../surfaces/index.js";
+import { parseProject } from "./schema.js";
+import { PROJECT_FILE } from "./types.js";
+export async function findProjectFile(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(dir, PROJECT_FILE);
+        if (await pathExists(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        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));
+}
+async function resolveProjectFile(fileOrDir) {
+    const abs = path.resolve(fileOrDir);
+    if (await isDirectory(abs)) {
+        const found = await findProjectFile(abs);
+        if (!found) {
+            throw new Error(`No ${PROJECT_FILE} found in ${abs} or any parent directory`);
+        }
+        return found;
+    }
+    if (!(await pathExists(abs))) {
+        throw new Error(`Project file not found: ${abs}`);
+    }
+    return abs;
+}
+export async function loadProject(fileOrDir) {
+    const file = await resolveProjectFile(fileOrDir);
+    const root = path.dirname(file);
+    const text = await fs.readFile(file, "utf8");
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`${file}: invalid JSON: ${err.message}`);
+    }
+    const project = parseProject(raw);
+    const surface = getSurface(project.game);
+    if (!surface) {
+        throw new Error(`Unknown game "${project.game}" in ${file}. Known: ${surfaceIds().join(", ")}`);
+    }
+    const warnings = [];
+    const resolveFromRoot = (p) => (path.isAbsolute(p) ? p : path.join(root, p));
+    const seenSourceIds = new Set();
+    const sources = await Promise.all(project.sources.map(async (source) => {
+        if (seenSourceIds.has(source.id)) {
+            warnings.push(`duplicate source id "${source.id}"`);
+        }
+        seenSourceIds.add(source.id);
+        if (looksAbsolute(source.path)) {
+            warnings.push(`source "${source.id}" uses an absolute path (${source.path}); portable projects should use paths relative to ${PROJECT_FILE}`);
+        }
+        const absPath = resolveFromRoot(source.path);
+        const exists = await pathExists(absPath);
+        if (!exists) {
+            warnings.push(`source "${source.id}" does not exist: ${absPath}`);
+        }
+        return { ...source, absPath, exists };
+    }));
+    let build;
+    if (project.build) {
+        if (looksAbsolute(project.build.outDir)) {
+            warnings.push(`build.outDir is an absolute path (${project.build.outDir}); portable projects should use a path relative to ${PROJECT_FILE}`);
+        }
+        if (project.build.staging && looksAbsolute(project.build.staging)) {
+            warnings.push(`build.staging is an absolute path (${project.build.staging}); portable projects should use a path relative to ${PROJECT_FILE}`);
+        }
+        const absOutDir = resolveFromRoot(project.build.outDir);
+        const outDirExists = await pathExists(absOutDir);
+        const absStaging = project.build.staging ? resolveFromRoot(project.build.staging) : undefined;
+        build = { ...project.build, absOutDir, outDirExists, absStaging };
+        for (const source of sources) {
+            if (isWithin(source.absPath, absOutDir)) {
+                warnings.push(`build.outDir (${absOutDir}) is inside source "${source.id}" (${source.absPath})`);
+            }
+        }
+        if (absStaging) {
+            if (absStaging === root) {
+                warnings.push(`build.staging is the project root — packing from there would sweep up the whole repository (the "never pack the repo root" trap)`);
+            }
+            for (const source of sources) {
+                if (absStaging === source.absPath) {
+                    warnings.push(`build.staging equals source "${source.id}"'s path (${absStaging}) — packing from there would sweep up the whole source tree instead of a clean staged copy`);
+                }
+            }
+        }
+    }
+    if (project.deploy) {
+        const sourceIdSet = new Set(sources.map((s) => s.id));
+        for (const target of project.deploy.targets) {
+            const isSourceId = sourceIdSet.has(target.from);
+            let isUnderOutDir = false;
+            if (build) {
+                const absFrom = path.isAbsolute(target.from) ? target.from : path.join(build.absOutDir, target.from);
+                isUnderOutDir = isWithin(build.absOutDir, absFrom);
+            }
+            const isModWrightOwned = !looksAbsolute(target.from) && /^\.modwright[\\/]/.test(target.from);
+            if (!isSourceId && !isUnderOutDir && !isModWrightOwned) {
+                warnings.push(`deploy target for root "${target.rootId}": from "${target.from}" is neither a source id nor a path under build.outDir` +
+                    (build ? "" : " (project has no build.outDir configured)"));
+            }
+        }
+    }
+    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 "..")`);
+        }
+    }
+    const toolchain = project.toolchain
+        ? Object.fromEntries(Object.entries(project.toolchain).map(([id, p]) => [id, looksAbsolute(p) ? p : resolveFromRoot(p)]))
+        : undefined;
+    return { file, root, project: toolchain ? { ...project, toolchain } : project, sources, build, warnings };
+}

package/dist/core/project/schema.js

@@ -0,0 +1,264 @@
+import { z } from "zod";
+import { SUPPORTED_PROJECT_SCHEMA_VERSIONS } from "./types.js";
+import { bridgeTierSchema } from "../bridge/types.js";
+const projectSourceSchema = z
+    .object({
+    id: z.string().min(1),
+    path: z.string().min(1),
+    kind: z.string().min(1),
+    notes: z.string().optional(),
+})
+    .strict();
+const dependencyKindSchema = z.enum(["loader", "framework", "tool", "mod"]);
+const projectDependencySchema = z
+    .object({
+    id: z.string().min(1),
+    kind: dependencyKindSchema,
+    minVersion: z.string().optional(),
+    url: z.string().optional(),
+    notes: z.string().optional(),
+})
+    .strict();
+const stepBase = {
+    id: z.string().min(1).optional(),
+    label: z.string().optional(),
+    optional: z.boolean().optional(),
+    variant: z.string().min(1).optional(),
+};
+const stageSourceEntrySchema = z
+    .object({
+    source: z.string().min(1).optional(),
+    output: z.string().min(1).optional(),
+    into: z.string().optional(),
+    include: z.array(z.string().min(1)).optional(),
+    exclude: z.array(z.string().min(1)).optional(),
+    variant: z.string().optional(),
+})
+    .strict()
+    .refine((entry) => (entry.source === undefined) !== (entry.output === undefined), {
+    message: 'a stage source entry needs exactly one of "source" (a project source id) or "output" (an earlier step\'s artifact)',
+});
+const buildStepSchema = z.discriminatedUnion("step", [
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("stage"),
+        sources: z.array(z.union([z.string().min(1), stageSourceEntrySchema])),
+        into: z.string().optional(),
+        exclude: z.array(z.string().min(1)).optional(),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("assert-absent"),
+        in: z.string().optional(),
+        patterns: z.array(z.string().min(1)),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("assert-present"),
+        in: z.string().optional(),
+        paths: z.array(z.string().min(1)),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("zip"),
+        from: z.string(),
+        name: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("blender-export"),
+        blend: z.string(),
+        script: z.string(),
+        out: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("wolvenkit-import"),
+        glb: z.string(),
+        base: z.string(),
+        outDir: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("wolvenkit-pack"),
+        from: z.string(),
+        out: z.string(),
+        verbosity: z.enum(["Minimal", "Normal", "Diagnostic"]).default("Minimal"),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("divine-lsx-to-lsf"),
+        in: z.string(),
+        glob: z.string().default("**/*.lsx"),
+        deleteSource: z.boolean().default(false),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("divine-loca"),
+        in: z.string(),
+        glob: z.string().default("**/*.xml"),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("divine-create-package"),
+        from: z.string(),
+        out: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("verify-listing"),
+        of: z.string(),
+        forbid: z.array(z.string()).optional(),
+        require: z.array(z.string()).optional(),
+    })
+        .strict(),
+    z
+        .object({
+        ...stepBase,
+        step: z.literal("exec"),
+        command: z.string(),
+        args: z.array(z.string()).default([]),
+        cwd: z.string().optional(),
+        expectOutputs: z.array(z.string()).default([]),
+        timeoutMs: z.number().int().positive().optional(),
+        inputs: z.array(z.string().min(1)).optional(),
+    })
+        .strict(),
+]);
+const buildVariantSchema = z
+    .object({
+    addSources: z.array(z.string().min(1)).optional(),
+    addSteps: z.array(buildStepSchema).optional(),
+    dropExclude: z.array(z.string().min(1)).optional(),
+})
+    .strict();
+const projectBuildSchema = z
+    .object({
+    staging: z.string().min(1).optional(),
+    outDir: z.string().min(1),
+    steps: z.array(z.union([z.string().min(1), buildStepSchema])).optional(),
+    exclude: z.array(z.string().min(1)).optional(),
+    variants: z.record(buildVariantSchema).optional(),
+})
+    .strict();
+const deployTargetSchema = z
+    .object({
+    rootId: z.string().min(1),
+    from: z.string().min(1),
+    into: z.string().optional(),
+    waitForGameExit: z.boolean().optional(),
+    backup: z.boolean().optional(),
+    locked: z.boolean().optional(),
+    mode: z.enum(["pak", "loose"]).optional(),
+    prune: z.array(z.string().min(1)).optional(),
+    variant: z.string().optional(),
+    exclude: z.array(z.string().min(1)).optional(),
+})
+    .strict();
+const junctionSchema = z
+    .object({
+    linkPath: z.string().min(1),
+    rootId: z.string().min(1),
+    target: z.string().min(1),
+})
+    .strict();
+const deploySchema = z
+    .object({
+    targets: z.array(deployTargetSchema),
+    junctions: z.array(junctionSchema).optional(),
+    waitMinutes: z.number().int().min(0).max(30).optional(),
+})
+    .strict();
+const reloadRuleSchema = z
+    .object({
+    match: z.string().min(1),
+    action: z.enum(["hot", "hot-degraded", "save-reload", "restart", "unknown"]),
+    via: z.string().optional(),
+    caveat: z.string().optional(),
+})
+    .strict();
+const reloadSchema = z.object({ rules: z.array(reloadRuleSchema) }).strict();
+const bridgePolicySchema = z
+    .object({
+    mode: z.enum(["verify", "workbench"]),
+    grant: z.array(bridgeTierSchema).optional(),
+})
+    .strict();
+const projectBridgeSchema = z.object({ policy: bridgePolicySchema.optional() }).strict();
+const publishTargetSchema = z
+    .object({
+    target: z.enum(["nexus", "modio", "github", "zip"]),
+    id: z.string().optional(),
+    include: z.array(z.string().min(1)).optional(),
+    notes: z.string().optional(),
+})
+    .strict();
+const testProfileSchema = z
+    .object({
+    saveName: z.string().optional(),
+    notes: z.string().optional(),
+})
+    .strict();
+export const modProjectSchema = z
+    .object({
+    schemaVersion: z.union(SUPPORTED_PROJECT_SCHEMA_VERSIONS.map((v) => z.literal(v))),
+    name: z.string().min(1),
+    game: z.string().min(1),
+    version: z.string().optional(),
+    authors: z.array(z.string().min(1)).optional(),
+    identity: z.record(z.string()).optional(),
+    sources: z.array(projectSourceSchema),
+    build: projectBuildSchema.optional(),
+    deploy: deploySchema.optional(),
+    dependencies: z.array(projectDependencySchema).optional(),
+    toolchain: z.record(z.string()).optional(),
+    publish: z.array(publishTargetSchema).optional(),
+    testProfile: testProfileSchema.optional(),
+    reload: reloadSchema.optional(),
+    bridge: projectBridgeSchema.optional(),
+    testPlans: z.array(z.string().min(1)).optional(),
+})
+    .strict();
+function formatPath(segments) {
+    if (segments.length === 0)
+        return "(root)";
+    let out = "";
+    for (const segment of segments) {
+        if (typeof segment === "number") {
+            out += `[${segment}]`;
+        }
+        else {
+            out += out ? `.${segment}` : segment;
+        }
+    }
+    return out;
+}
+export function parseProject(json) {
+    const result = modProjectSchema.safeParse(json);
+    if (!result.success) {
+        const lines = result.error.issues.map((issue) => `${formatPath(issue.path)}: ${issue.message}`);
+        throw new Error(`Invalid modwright.json:\n${lines.join("\n")}`);
+    }
+    return result.data;
+}

package/dist/core/project/types.js

@@ -0,0 +1,3 @@
+export const PROJECT_FILE = "modwright.json";
+export const PROJECT_SCHEMA_VERSION = 2;
+export const SUPPORTED_PROJECT_SCHEMA_VERSIONS = [1, 2];