modwright 0.1.0

package/dist/core/safety/restore.js

@@ -0,0 +1,172 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { copyFilePreservingMtime, readManifest, sha256File } from "./backup.js";
+import { isDirectory } from "../fsutil.js";
+export async function listBackups(backupRoot) {
+    let entries;
+    try {
+        entries = await fs.readdir(backupRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(backupRoot, entry.name);
+        try {
+            const manifest = await readManifest(dir);
+            const links = manifest.entries.filter((e) => "kind" in e);
+            const sizeBytes = manifest.entries.reduce((sum, e) => sum + ("kind" in e ? 0 : e.sizeBytes), 0);
+            out.push({
+                id: entry.name,
+                path: dir,
+                purpose: manifest.purpose,
+                time: manifest.time,
+                entryCount: manifest.entries.length,
+                linkEntryCount: links.length,
+                sizeBytes,
+            });
+        }
+        catch (err) {
+            out.push({ id: entry.name, path: dir, entryCount: 0, linkEntryCount: 0, sizeBytes: 0, error: errorMessage(err) });
+        }
+    }
+    return out.sort((a, b) => (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function restoreLinkEntry(entry) {
+    let existing;
+    try {
+        existing = await fs.lstat(entry.originalPath);
+    }
+    catch {
+        existing = undefined;
+    }
+    if (existing?.isSymbolicLink()) {
+        await fs.rm(entry.originalPath, { recursive: true, force: true });
+    }
+    else if (existing) {
+        throw new Error(`${entry.originalPath} is now a real ${existing.isDirectory() ? "directory" : "file"}, not a link; ` +
+            "refusing to replace it with the backed-up link. Move it aside and restore again.");
+    }
+    await fs.mkdir(path.dirname(entry.originalPath), { recursive: true });
+    const targetIsDir = await isDirectory(entry.linkTarget);
+    await fs.symlink(entry.linkTarget, entry.originalPath, process.platform === "win32" && targetIsDir ? "junction" : undefined);
+}
+export function isLockError(err) {
+    const code = err?.code;
+    return code === "EPERM" || code === "EBUSY" || code === "EACCES";
+}
+function backupFileFor(backupDir, backupPath) {
+    const src = path.resolve(backupDir, ...backupPath.split("/"));
+    const rel = path.relative(backupDir, src);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        throw new Error(`manifest entry names ${JSON.stringify(backupPath)}, which is not inside the backup directory ${backupDir}; refusing to restore from it`);
+    }
+    return src;
+}
+function restoreConfidence(backupDir) {
+    return {
+        level: "high",
+        assumptions: [`manifest.json under ${backupDir} has not been hand-edited since it was written`],
+        verifiedBy: ["manifest.json", "sha256 of each backed-up file, re-checked immediately before restoring it"],
+    };
+}
+export async function restoreBackup(backupDir, options = {}) {
+    const mode = options.mode ?? "dry-run";
+    if (!path.isAbsolute(backupDir)) {
+        throw new Error(`safety: backupDir must be an absolute path, got "${backupDir}"`);
+    }
+    const manifest = await readManifest(backupDir);
+    for (const entry of manifest.entries) {
+        if (!("kind" in entry))
+            backupFileFor(backupDir, entry.backupPath);
+    }
+    if (mode === "dry-run") {
+        const operations = [];
+        for (const entry of manifest.entries) {
+            if ("kind" in entry) {
+                const op = { kind: "junction", path: entry.originalPath, target: entry.linkTarget };
+                operations.push({ op, status: "planned" });
+                continue;
+            }
+            const op = { kind: "overwrite", path: entry.originalPath, content: new Uint8Array(0) };
+            operations.push({ op, status: "planned", sizeBytes: entry.sizeBytes, sha256: entry.sha256 });
+        }
+        return {
+            mode,
+            purpose: `restore: ${manifest.purpose}`,
+            applied: false,
+            operations,
+            confidence: restoreConfidence(backupDir),
+            next: `Nothing was changed. Re-run restoreBackup(backupDir, { mode: "apply" }) to write ` +
+                `these ${manifest.entries.length} file(s) back to their original locations.`,
+        };
+    }
+    const results = [];
+    const locked = [];
+    let stopped = false;
+    for (const entry of manifest.entries) {
+        if ("kind" in entry) {
+            const op = { kind: "junction", path: entry.originalPath, target: entry.linkTarget };
+            if (stopped) {
+                results.push({ op, status: "skipped" });
+                continue;
+            }
+            try {
+                await restoreLinkEntry(entry);
+                results.push({ op, status: "applied" });
+            }
+            catch (err) {
+                if (isLockError(err))
+                    locked.push(entry.originalPath);
+                else
+                    stopped = true;
+                results.push({ op, status: "failed", error: errorMessage(err) });
+            }
+            continue;
+        }
+        const op = { kind: "overwrite", path: entry.originalPath, content: new Uint8Array(0) };
+        if (stopped) {
+            results.push({ op, status: "skipped" });
+            continue;
+        }
+        try {
+            const src = backupFileFor(backupDir, entry.backupPath);
+            const { sha256 } = await sha256File(src);
+            if (sha256 !== entry.sha256) {
+                throw new Error(`backup of ${entry.originalPath} is corrupted: manifest says sha256 ${entry.sha256}, file on disk hashes to ${sha256}`);
+            }
+            await copyFilePreservingMtime(src, entry.originalPath);
+            results.push({ op, status: "applied" });
+        }
+        catch (err) {
+            if (isLockError(err))
+                locked.push(entry.originalPath);
+            else
+                stopped = true;
+            results.push({ op, status: "failed", error: errorMessage(err) });
+        }
+    }
+    const applied = results.every((r) => r.status === "applied" || r.status === "skipped");
+    const next = locked.length > 0
+        ? `${locked.length} file(s) could not be written because something holds them (the game, if it is running): ` +
+            `${locked.join(", ")}. Everything else was restored. Close the holder and run the same restore again; ` +
+            `entries already restored are rewritten with identical content.`
+        : undefined;
+    return {
+        mode,
+        purpose: `restore: ${manifest.purpose}`,
+        applied,
+        operations: results,
+        confidence: restoreConfidence(backupDir),
+        next: next ??
+            (applied
+                ? undefined
+                : "An integrity check failed before that file was restored; the backup itself is untouched, so fix the problem and retry."),
+    };
+}

package/dist/core/safety/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/scaffold/bootstrap.js

@@ -0,0 +1,7 @@
+import * as path from "node:path";
+import { PROJECT_FILE } from "../project/types.js";
+export function bootstrapProject(dir, game, name) {
+    const root = path.resolve(dir);
+    const project = { schemaVersion: 2, name, game, sources: [] };
+    return { file: path.join(root, PROJECT_FILE), root, project, sources: [], warnings: [] };
+}

package/dist/core/scaffold/catalog.js

@@ -0,0 +1,28 @@
+export function summarize(loaded) {
+    return loaded.map(({ definition }) => ({
+        id: definition.id,
+        game: definition.game,
+        title: definition.title,
+        summary: definition.summary,
+        modTypes: definition.modTypes,
+        sandbox: !definition.needs.install && definition.needs.toolchain.length === 0,
+    }));
+}
+export function describe(loaded) {
+    const { definition } = loaded;
+    const filesWritten = [...new Set(definition.emits.filter((e) => "path" in e).map((e) => e.path))];
+    return {
+        id: definition.id,
+        game: definition.game,
+        title: definition.title,
+        summary: definition.summary,
+        modTypes: definition.modTypes,
+        needs: definition.needs,
+        inputs: definition.inputs,
+        ids: definition.ids,
+        satisfies: definition.satisfies,
+        filesWritten,
+        manual: definition.manual,
+        evidence: definition.evidence,
+    };
+}

package/dist/core/scaffold/claude-assets.js

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, promises as fs } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readTextIfExists } from "../fsutil.js";
+import { planFile, planMkdir } from "../safety/plan.js";
+import { executePlan } from "../safety/execute.js";
+import { loadKnowledge } from "../knowledge/facts.js";
+const ASSETS = [
+    { path: "skills/mw-validate.md", templateId: "modwright-validate" },
+    { path: "skills/mw-scaffold.md", templateId: "modwright-scaffold" },
+    { path: "skills/mw-new-spell.md", templateId: "modwright-new-spell", games: ["baldursgate3"] },
+    { path: "skills/mw-new-item.md", templateId: "modwright-new-item", games: ["cyberpunk2077"] },
+    { path: "skills/mw-verify.md", templateId: "modwright-verify" },
+    { path: "skills/mw-ship.md", templateId: "modwright-ship" },
+    { path: "skills/mw-author.md", templateId: "modwright-author" },
+    { path: "agents/mw-explore.md", templateId: "modwright-explore" },
+    { path: "agents/mw-rule-author.md", templateId: "modwright-rule-author" },
+    { path: "agents/mw-scaffold-author.md", templateId: "modwright-scaffold-author" },
+    { path: "agents/mw-fixture.md", templateId: "modwright-fixture" },
+];
+const SETTINGS_PATH = "settings.json";
+const SETTINGS_TEMPLATE_ID = "modwright-settings";
+const MANIFEST_FILE = "ASSETS.json";
+const SETTINGS_BASELINE = { model: "sonnet", effortLevel: "high" };
+function findPackageRoot(startDir) {
+    let dir = startDir;
+    for (;;) {
+        if (existsSync(path.join(dir, "package.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error(`claude-assets: could not find package.json above ${startDir}`);
+        dir = parent;
+    }
+}
+function packageRoot() {
+    return findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+}
+export function claudeAssetsRoot() {
+    return path.join(packageRoot(), "assets", "claude");
+}
+let cachedVersion;
+export function modwrightVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        const raw = JSON.parse(readFileSync(path.join(packageRoot(), "package.json"), "utf8"));
+        cachedVersion = typeof raw.version === "string" ? raw.version : "0.0.0";
+    }
+    catch {
+        cachedVersion = "0.0.0";
+    }
+    return cachedVersion;
+}
+function sha256Hash(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+export function lineDiff(shipped, local, limit = 20) {
+    const a = shipped.split("\n");
+    const b = local.split("\n");
+    const width = b.length + 1;
+    const lcs = new Uint32Array((a.length + 1) * width);
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            lcs[i * width + j] =
+                a[i] === b[j]
+                    ? (lcs[(i + 1) * width + (j + 1)] ?? 0) + 1
+                    : Math.max(lcs[(i + 1) * width + j] ?? 0, lcs[i * width + (j + 1)] ?? 0);
+        }
+    }
+    const rows = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            i++;
+            j++;
+        }
+        else if ((lcs[(i + 1) * width + j] ?? 0) >= (lcs[i * width + (j + 1)] ?? 0)) {
+            rows.push({ kind: "removed", lineNumber: i + 1, text: a[i] ?? "" });
+            i++;
+        }
+        else {
+            rows.push({ kind: "added", lineNumber: j + 1, text: b[j] ?? "" });
+            j++;
+        }
+    }
+    for (; i < a.length; i++)
+        rows.push({ kind: "removed", lineNumber: i + 1, text: a[i] ?? "" });
+    for (; j < b.length; j++)
+        rows.push({ kind: "added", lineNumber: j + 1, text: b[j] ?? "" });
+    return rows.slice(0, limit);
+}
+export function interpolateTemplate(content, values) {
+    return content
+        .replace(/\$\{version\}/g, values.version)
+        .replace(/\$\{game\}/g, values.game)
+        .replace(/\$\{project\}/g, values.project);
+}
+function normalizeForCompare(text) {
+    return text.toLowerCase().replace(/\s+/g, " ").trim();
+}
+export function quotedFactIds(body, facts) {
+    const haystack = normalizeForCompare(body);
+    return facts
+        .filter((fact) => {
+        const claim = normalizeForCompare(fact.claim);
+        return claim.length >= 60 && haystack.includes(claim);
+    })
+        .map((fact) => fact.id);
+}
+async function loadTemplate(relPath) {
+    const filePath = path.join(claudeAssetsRoot(), relPath);
+    const content = await readTextIfExists(filePath);
+    if (content === undefined) {
+        throw new Error(`claude-assets: template not found: ${relPath} (looked in ${filePath})`);
+    }
+    return content.replace(/\r\n/g, "\n");
+}
+export async function generateClaudeAssets(options) {
+    const { project, mode = "dry-run", force = false, includeSettings = false, skipFactCheck = false } = options;
+    const version = modwrightVersion();
+    const claudeDir = path.join(project.root, ".claude");
+    const scope = { version, game: project.project.game, project: project.project.name };
+    let facts = [];
+    if (!skipFactCheck) {
+        try {
+            facts = (await loadKnowledge()).facts.map((fact) => ({ id: fact.id, claim: fact.claim }));
+        }
+        catch {
+            facts = [];
+        }
+    }
+    const files = [];
+    const plan = { purpose: `generate Claude Code assets for ${project.project.name}`, operations: [] };
+    plan.operations.push(planMkdir(claudeDir));
+    plan.operations.push(planMkdir(path.join(claudeDir, "skills")));
+    plan.operations.push(planMkdir(path.join(claudeDir, "agents")));
+    const manifestPath = path.join(claudeDir, MANIFEST_FILE);
+    let previous;
+    const previousText = await readTextIfExists(manifestPath);
+    if (previousText) {
+        try {
+            const parsed = JSON.parse(previousText);
+            if (parsed && typeof parsed === "object" && parsed.entries)
+                previous = parsed;
+        }
+        catch {
+        }
+    }
+    const entries = {};
+    const planAsset = async (relPath, templateId, generated) => {
+        const contentHash = sha256Hash(generated);
+        const absPath = path.join(claudeDir, relPath);
+        const recorded = previous?.entries[relPath]?.sha256;
+        const existing = await readTextIfExists(absPath);
+        let status;
+        let diff;
+        if (existing === undefined) {
+            status = "created";
+        }
+        else if (sha256Hash(existing) === contentHash) {
+            status = "unchanged";
+        }
+        else if (recorded !== undefined && sha256Hash(existing) === recorded) {
+            status = "updated";
+        }
+        else if (force) {
+            status = "overwritten";
+        }
+        else {
+            status = "diverged";
+            diff = lineDiff(generated, existing);
+        }
+        if (status === "diverged") {
+            const keep = previous?.entries[relPath];
+            if (keep)
+                entries[relPath] = keep;
+        }
+        else {
+            entries[relPath] = { template: templateId, version, sha256: contentHash };
+            if (status !== "unchanged")
+                plan.operations.push(planFile(absPath, generated));
+        }
+        files.push({ path: relPath, template: templateId, status, sha256: contentHash, diff });
+    };
+    for (const asset of ASSETS) {
+        if (asset.games && !asset.games.includes(project.project.game))
+            continue;
+        const raw = await loadTemplate(asset.path);
+        const generated = interpolateTemplate(raw, scope);
+        const quoted = quotedFactIds(generated, facts);
+        if (quoted.length > 0) {
+            throw new Error(`claude-assets: template ${asset.path} restates knowledge fact(s) ${quoted.join(", ")} verbatim. ` +
+                `A skill body cites the fact id and calls lookup instead.`);
+        }
+        await planAsset(asset.path, asset.templateId, generated);
+    }
+    if (includeSettings) {
+        await planAsset(SETTINGS_PATH, SETTINGS_TEMPLATE_ID, `${JSON.stringify(SETTINGS_BASELINE, null, 2)}\n`);
+    }
+    const shipped = new Set([...ASSETS.map((a) => a.path), SETTINGS_PATH]);
+    const orphans = [];
+    for (const [relPath, entry] of Object.entries(previous?.entries ?? {})) {
+        if (shipped.has(relPath))
+            continue;
+        entries[relPath] = entry;
+        orphans.push({
+            path: relPath,
+            template: entry.template,
+            version: entry.version,
+            onDisk: await pathOnDisk(path.join(claudeDir, relPath)),
+            note: `ModWright ${version} no longer ships this template. Left in place — delete it yourself if it is no longer wanted.`,
+        });
+    }
+    for (const [relPath, entry] of Object.entries(previous?.entries ?? {})) {
+        if (!entries[relPath])
+            entries[relPath] = entry;
+    }
+    const manifest = { schemaVersion: 1, entries };
+    plan.operations.push(planFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`));
+    const divergedCount = files.filter((file) => file.status === "diverged").length;
+    const confidence = {
+        level: "high",
+        assumptions: [
+            includeSettings
+                ? ".claude/settings.json is wanted: it sets Claude Code's model and effort baseline for the whole repo."
+                : "The repo's own .claude/settings.json (if any) is left alone; each skill and agent pins its own model and effort.",
+            "A file whose sha256 no longer matches ASSETS.json was edited on purpose.",
+        ],
+        verifiedBy: [
+            "every generated file hashed and compared against .claude/ASSETS.json",
+            "templates checked against knowledge/ for restated facts",
+        ],
+    };
+    let writeReport;
+    let applied = false;
+    if (mode === "apply") {
+        plan.backupRoot = path.join(project.root, ".modwright", "backups");
+        writeReport = await executePlan(plan, { mode: "apply", confidence });
+        applied = writeReport.applied;
+    }
+    const next = divergedCount > 0
+        ? `${divergedCount} file(s) were edited locally and were left untouched. Review each diff, then re-run with force: true to take ModWright's version (the old file is backed up first).`
+        : mode === "dry-run"
+            ? 'Re-run with mode: "apply" to write these files.'
+            : undefined;
+    return {
+        mode,
+        version,
+        files,
+        orphans,
+        manifest,
+        settingsIncluded: includeSettings,
+        plan,
+        writeReport,
+        applied,
+        confidence,
+        next,
+    };
+}
+async function pathOnDisk(absPath) {
+    try {
+        await fs.stat(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/scaffold/collisions.js

@@ -0,0 +1,64 @@
+import * as path from "node:path";
+import { walk } from "../fsutil.js";
+async function projectFilesText(project) {
+    const { promises: fs } = await import("node:fs");
+    const out = [];
+    for (const source of project.sources) {
+        if (!source.exists)
+            continue;
+        const { files } = await walk(source.absPath, { limit: 20_000 });
+        for (const rel of files) {
+            const abs = path.join(source.absPath, rel);
+            try {
+                out.push({ file: abs, text: await fs.readFile(abs, "utf8") });
+            }
+            catch {
+            }
+        }
+    }
+    return out;
+}
+function collisionProjectDefault(idSpec) {
+    return idSpec.collision.project ?? true;
+}
+export async function checkCollision(input) {
+    const { idSpec, value, project, store, install, lookup } = input;
+    const hits = [];
+    const skipped = [];
+    if (collisionProjectDefault(idSpec)) {
+        for (const { file, text } of await projectFilesText(project)) {
+            if (text.includes(value)) {
+                hits.push({ check: "project", source: file, detail: `"${value}" already appears in this project file.` });
+            }
+        }
+    }
+    if (idSpec.collision.index) {
+        if (!store) {
+            skipped.push({ check: "index", reason: `no vanilla index built for ${project.project.game} — run build_index` });
+        }
+        else {
+            const { kind, param } = idSpec.collision.index;
+            const res = await lookup(kind, { [param]: value });
+            if (res.count > 0) {
+                hits.push({
+                    check: "index",
+                    source: `vanilla index (${kind})`,
+                    detail: `"${value}" already resolves in the vanilla index (${res.count} row(s)).`,
+                });
+            }
+        }
+    }
+    if (idSpec.collision.loadOrder) {
+        if (!install || !input.surface.loadOrder) {
+            skipped.push({ check: "loadOrder", reason: !install ? `no ${project.project.game} install located` : "this surface has no load-order reader" });
+        }
+        else {
+            const entries = await input.surface.loadOrder(install);
+            const match = entries.find((e) => e.uuid?.toLowerCase() === value.toLowerCase());
+            if (match) {
+                hits.push({ check: "loadOrder", source: match.name, detail: `"${value}" already appears in the load order as "${match.name}".` });
+            }
+        }
+    }
+    return { idName: idSpec.name, value, hits, skipped };
+}