modwright 0.1.0

package/dist/core/prompts.js

@@ -0,0 +1,72 @@
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { findProjectFile, loadProject } from "./project/index.js";
+import { claudeAssetsRoot, interpolateTemplate, modwrightVersion } from "./scaffold/claude-assets.js";
+export const SKILL_PROMPTS = [
+    { name: "mw-validate", templatePath: "skills/mw-validate.md" },
+    { name: "mw-scaffold", templatePath: "skills/mw-scaffold.md" },
+    { name: "mw-new-spell", templatePath: "skills/mw-new-spell.md", games: ["baldursgate3"] },
+    { name: "mw-new-item", templatePath: "skills/mw-new-item.md", games: ["cyberpunk2077"] },
+    { name: "mw-verify", templatePath: "skills/mw-verify.md" },
+    { name: "mw-ship", templatePath: "skills/mw-ship.md" },
+    { name: "mw-author", templatePath: "skills/mw-author.md" },
+];
+export function parseSkillTemplate(content) {
+    const text = content.replace(/\r\n/g, "\n");
+    const frontmatter = {};
+    let body = text;
+    const match = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    if (match) {
+        for (const line of match[1].split("\n")) {
+            const colon = line.indexOf(":");
+            if (colon <= 0)
+                continue;
+            frontmatter[line.slice(0, colon).trim()] = line.slice(colon + 1).trim();
+        }
+        body = text.slice(match[0].length);
+    }
+    body = body.replace(/^<!--\s*modwright:asset[^>]*-->\n?/m, "").replace(/^\n+/, "");
+    return { frontmatter, body };
+}
+export function loadSkillPromptCatalog() {
+    return SKILL_PROMPTS.map((spec) => {
+        const file = path.join(claudeAssetsRoot(), spec.templatePath);
+        const template = parseSkillTemplate(readFileSync(file, "utf8"));
+        const hint = template.frontmatter["argument-hint"];
+        const scope = spec.games ? ` (${spec.games.join(", ")} only)` : "";
+        const description = `${template.frontmatter.description ?? spec.name}${scope}${hint ? ` Arguments: ${hint}.` : ""}`;
+        return { ...spec, title: spec.name, description, template };
+    });
+}
+export async function renderSkillPrompt(entry, start) {
+    const from = start ?? process.cwd();
+    const version = modwrightVersion();
+    try {
+        const file = from.toLowerCase().endsWith(".json") ? from : await findProjectFile(from);
+        if (!file)
+            throw new Error(`no modwright.json at or above ${from}`);
+        const resolved = await loadProject(file);
+        const { name, game } = resolved.project;
+        if (entry.games && !entry.games.includes(game)) {
+            return {
+                name: entry.name,
+                text: `${entry.name} is a ${entry.games.join("/")} skill; ${name} is a ${game} project. Use \`scaffold\` with \`action: "list"\` and \`game: "${game}"\` to see what applies here.`,
+                project: { name, game, file },
+                note: "game mismatch",
+            };
+        }
+        return {
+            name: entry.name,
+            text: interpolateTemplate(entry.template.body, { version, game, project: name }),
+            project: { name, game, file },
+        };
+    }
+    catch (error) {
+        const note = `No project was loaded (${error.message}); \`<project>\` and \`<game>\` below are placeholders — call \`project_info\` first and read them from its result.`;
+        return {
+            name: entry.name,
+            text: `${note}\n\n${interpolateTemplate(entry.template.body, { version, game: "<game>", project: "<project>" })}`,
+            note,
+        };
+    }
+}

package/dist/core/registry.js

@@ -0,0 +1,35 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const defaultRunner = async (args) => {
+    const { stdout } = await execFileAsync("reg", args, { timeout: 10_000, windowsHide: true });
+    return stdout;
+};
+export function parseRegQueryValue(stdout, valueName) {
+    const wanted = valueName.toLowerCase();
+    for (const raw of stdout.split(/\r?\n/)) {
+        const line = raw.trim();
+        const m = /^(?<name>.+?)\s{2,}(?<type>REG_[A-Z_]+)\s{2,}(?<data>.*)$/.exec(line) ?? /^(?<name>.+?)\t+(?<type>REG_[A-Z_]+)\t+(?<data>.*)$/.exec(line);
+        if (!m?.groups)
+            continue;
+        if (m.groups.name.trim().toLowerCase() !== wanted)
+            continue;
+        return m.groups.data.trim();
+    }
+    return undefined;
+}
+export async function readRegistryValue(keys, valueName, runner = defaultRunner) {
+    if (process.platform !== "win32" && runner === defaultRunner)
+        return undefined;
+    for (const key of keys) {
+        try {
+            const stdout = await runner(["query", key, "/v", valueName]);
+            const value = parseRegQueryValue(stdout, valueName);
+            if (value !== undefined && value.length > 0)
+                return { key, value };
+        }
+        catch {
+        }
+    }
+    return undefined;
+}

package/dist/core/safety/backup.js

@@ -0,0 +1,206 @@
+import { createReadStream, promises as fs } from "node:fs";
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import { z } from "zod";
+import { isDirectory, readLinkTarget } from "../fsutil.js";
+export const backupManifestFileEntrySchema = z
+    .object({
+    originalPath: z.string().min(1),
+    backupPath: z.string().min(1),
+    sizeBytes: z.number().int().nonnegative(),
+    sha256: z.string().length(64),
+})
+    .strict();
+export const backupManifestLinkEntrySchema = z
+    .object({
+    originalPath: z.string().min(1),
+    kind: z.literal("link"),
+    linkTarget: z.string().min(1),
+})
+    .strict();
+export const backupManifestEntrySchema = z.union([
+    backupManifestFileEntrySchema,
+    backupManifestLinkEntrySchema,
+]);
+export const backupManifestSchema = z
+    .object({
+    purpose: z.string(),
+    time: z.string(),
+    entries: z.array(backupManifestEntrySchema),
+})
+    .strict();
+export const MANIFEST_FILE = "manifest.json";
+export function sanitizeForBackup(absPath) {
+    let p = absPath.replace(/\\/g, "/");
+    const drive = /^([A-Za-z]):\//.exec(p);
+    if (drive) {
+        p = p.slice(drive[0].length);
+        return [drive[1], ...p.split("/").filter(Boolean)];
+    }
+    const unc = /^\/\/([^/]+)\/(.*)$/.exec(p);
+    if (unc) {
+        return ["unc", unc[1], ...unc[2].split("/").filter(Boolean)];
+    }
+    return p.split("/").filter(Boolean);
+}
+export function backupDestFor(backupDir, originalAbsPath) {
+    return path.join(backupDir, "data", ...sanitizeForBackup(originalAbsPath));
+}
+export async function sha256File(p) {
+    const hash = crypto.createHash("sha256");
+    let sizeBytes = 0;
+    for await (const chunk of createReadStream(p)) {
+        sizeBytes += chunk.length;
+        hash.update(chunk);
+    }
+    return { sha256: hash.digest("hex"), sizeBytes };
+}
+export function tempSiblingPath(target) {
+    const dir = path.dirname(target);
+    const base = path.basename(target);
+    return path.join(dir, `.${base}.mwtmp-${crypto.randomBytes(6).toString("hex")}`);
+}
+export async function writeFileAtomic(target, content) {
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    const tmp = tempSiblingPath(target);
+    try {
+        await fs.writeFile(tmp, content);
+        await fs.rename(tmp, target);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        throw err;
+    }
+}
+export async function copyFilePreservingMtime(src, dest) {
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    const tmp = tempSiblingPath(dest);
+    try {
+        await fs.copyFile(src, tmp);
+        const stat = await fs.stat(src);
+        await fs.utimes(tmp, stat.atime, stat.mtime).catch(() => {
+        });
+        await fs.rename(tmp, dest);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        throw err;
+    }
+}
+export async function copyTreePreservingMtime(src, dest) {
+    if (await isDirectory(src)) {
+        await fs.mkdir(dest, { recursive: true });
+        const entries = await fs.readdir(src, { withFileTypes: true });
+        for (const entry of entries) {
+            await copyTreePreservingMtime(path.join(src, entry.name), path.join(dest, entry.name));
+        }
+    }
+    else {
+        await copyFilePreservingMtime(src, dest);
+    }
+}
+export class ManifestWriter {
+    backupDir;
+    purpose;
+    entries = [];
+    constructor(backupDir, purpose) {
+        this.backupDir = backupDir;
+        this.purpose = purpose;
+    }
+    get hasEntries() {
+        return this.entries.length > 0;
+    }
+    async addFile(originalAbsPath) {
+        const dest = backupDestFor(this.backupDir, originalAbsPath);
+        await copyFilePreservingMtime(originalAbsPath, dest);
+        const { sha256, sizeBytes } = await sha256File(originalAbsPath);
+        const backupPath = path.relative(this.backupDir, dest).split(path.sep).join("/");
+        this.entries.push({ originalPath: originalAbsPath, backupPath, sizeBytes, sha256 });
+    }
+    async addLink(originalAbsPath) {
+        const linkTarget = await readLinkTarget(originalAbsPath);
+        this.entries.push({ originalPath: originalAbsPath, kind: "link", linkTarget });
+        return this.backupDir;
+    }
+    async addTree(originalAbsDir) {
+        const entries = await fs.readdir(originalAbsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const child = path.join(originalAbsDir, entry.name);
+            if (entry.isSymbolicLink()) {
+                await this.addLink(child);
+            }
+            else if (entry.isDirectory()) {
+                await this.addTree(child);
+            }
+            else if (entry.isFile()) {
+                await this.addFile(child);
+            }
+        }
+    }
+    async addPath(originalAbsPath) {
+        const before = this.entries.length;
+        let lst;
+        try {
+            lst = await fs.lstat(originalAbsPath);
+        }
+        catch {
+            return undefined;
+        }
+        if (lst.isSymbolicLink()) {
+            return this.addLink(originalAbsPath);
+        }
+        if (lst.isDirectory()) {
+            await this.addTree(originalAbsPath);
+        }
+        else {
+            await this.addFile(originalAbsPath);
+        }
+        return this.entries.length > before ? backupDestFor(this.backupDir, originalAbsPath) : undefined;
+    }
+    async flush(now) {
+        const manifest = { purpose: this.purpose, time: now.toISOString(), entries: this.entries };
+        await fs.writeFile(path.join(this.backupDir, MANIFEST_FILE), JSON.stringify(manifest, null, 2), "utf8");
+    }
+}
+export async function readManifest(backupDir) {
+    const manifestPath = path.join(backupDir, MANIFEST_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(manifestPath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`safety: no ${MANIFEST_FILE} found at ${backupDir}: ${err.message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`safety: ${manifestPath} is not valid JSON: ${err.message}`);
+    }
+    const result = backupManifestSchema.safeParse(json);
+    if (!result.success) {
+        const lines = result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`);
+        throw new Error(`safety: ${manifestPath} is invalid:\n${lines.join("\n")}`);
+    }
+    return result.data;
+}
+export function backupTimestamp(now) {
+    const pad = (n, width = 2) => String(n).padStart(width, "0");
+    return (`${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}` +
+        `-${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}`);
+}
+export async function uniqueBackupDir(backupRoot, timestamp) {
+    await fs.mkdir(backupRoot, { recursive: true });
+    for (let n = 1;; n += 1) {
+        const candidate = n === 1 ? path.join(backupRoot, timestamp) : path.join(backupRoot, `${timestamp}-${n}`);
+        try {
+            await fs.mkdir(candidate);
+            return candidate;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+    }
+}

package/dist/core/safety/execute.js

@@ -0,0 +1,188 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { pathExists } from "../fsutil.js";
+import { userDataDir } from "../home.js";
+import { normalizePlan } from "./plan.js";
+import { isLockError } from "./restore.js";
+import { ManifestWriter, backupTimestamp, copyTreePreservingMtime, uniqueBackupDir, writeFileAtomic, } from "./backup.js";
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function lstatExists(p) {
+    try {
+        await fs.lstat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function applyOp(nop, ensureBackup) {
+    const op = nop.op;
+    switch (op.kind) {
+        case "mkdir": {
+            if (nop.skipEligible)
+                return { op, status: "skipped" };
+            await fs.mkdir(op.path, { recursive: true });
+            return { op, status: "applied" };
+        }
+        case "create":
+        case "overwrite": {
+            if (nop.skipEligible)
+                return { op, status: "skipped" };
+            let backedUpTo;
+            if (op.kind === "overwrite") {
+                backedUpTo = await (await ensureBackup()).addPath(op.path);
+            }
+            await writeFileAtomic(op.path, op.content);
+            return { op, status: "applied", backedUpTo };
+        }
+        case "copy": {
+            if (nop.skipEligible)
+                return { op, status: "skipped" };
+            let backedUpTo;
+            if (await pathExists(op.to)) {
+                backedUpTo = await (await ensureBackup()).addPath(op.to);
+            }
+            await copyTreePreservingMtime(op.from, op.to);
+            return { op, status: "applied", backedUpTo };
+        }
+        case "delete": {
+            if (nop.skipEligible)
+                return { op, status: "skipped" };
+            const backedUpTo = await (await ensureBackup()).addPath(op.path);
+            await fs.rm(op.path, { recursive: true, force: true });
+            return { op, status: "applied", backedUpTo };
+        }
+        case "unlink": {
+            if (nop.skipEligible)
+                return { op, status: "skipped" };
+            const backedUpTo = await (await ensureBackup()).addLink(op.path);
+            await fs.rm(op.path, { recursive: true, force: true });
+            return { op, status: "applied", backedUpTo };
+        }
+        case "junction": {
+            let backedUpTo;
+            if (await lstatExists(op.path)) {
+                backedUpTo = await (await ensureBackup()).addPath(op.path);
+                await fs.rm(op.path, { recursive: true, force: true });
+            }
+            await fs.mkdir(path.dirname(op.path), { recursive: true });
+            const linkType = process.platform === "win32" ? "junction" : "symlink";
+            await fs.symlink(op.target, op.path, process.platform === "win32" ? "junction" : undefined);
+            const result = { op, status: "applied", backedUpTo, linkType };
+            return result;
+        }
+    }
+}
+async function applyWithRetry(nop, ensureBackup, retry) {
+    const done = new Map();
+    const once = (kind, p, run) => {
+        const key = `${kind}:${p}`;
+        let pending = done.get(key);
+        if (!pending) {
+            pending = run();
+            done.set(key, pending);
+            pending.catch(() => done.delete(key));
+        }
+        return pending;
+    };
+    const backupOnce = async () => {
+        const writer = await ensureBackup();
+        return {
+            addPath: (p) => once("path", p, () => writer.addPath(p)),
+            addLink: (p) => once("link", p, () => writer.addLink(p)),
+        };
+    };
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await applyOp(nop, backupOnce);
+        }
+        catch (err) {
+            const delay = retry?.shouldRetry(nop.op, err) ? retry.delaysMs[attempt] : undefined;
+            if (delay === undefined)
+                throw err;
+            retry.onRetry?.(nop.op, attempt + 1, err);
+            await (retry.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(delay);
+        }
+    }
+}
+export async function executePlan(plan, options) {
+    const mode = options.mode ?? "dry-run";
+    const now = options.now ?? (() => new Date());
+    const normalized = await normalizePlan(plan);
+    if (mode === "dry-run") {
+        const operations = normalized.operations.map((nop) => ({
+            op: nop.op,
+            status: "planned",
+        }));
+        return {
+            mode,
+            purpose: plan.purpose,
+            applied: false,
+            operations,
+            confidence: options.confidence,
+            next: 'Nothing was changed. Re-run with { mode: "apply" } to write these changes; any overwrite or delete is backed up first.',
+        };
+    }
+    const backupRoot = plan.backupRoot ?? path.join(userDataDir(), "backups");
+    const timestamp = backupTimestamp(now());
+    let manifestWriter;
+    let backupDir;
+    const ensureBackup = async () => {
+        if (!manifestWriter) {
+            backupDir = await uniqueBackupDir(backupRoot, timestamp);
+            manifestWriter = new ManifestWriter(backupDir, plan.purpose);
+        }
+        return manifestWriter;
+    };
+    const results = [];
+    let stopped = false;
+    for (const nop of normalized.operations) {
+        if (stopped) {
+            results.push({ op: nop.op, status: "skipped" });
+            continue;
+        }
+        try {
+            results.push(await applyWithRetry(nop, ensureBackup, options.retry));
+        }
+        catch (err) {
+            const op = nop.op;
+            const deferrable = (op.kind === "delete" || op.kind === "overwrite") && options.deferOnLock?.(op) && isLockError(err);
+            if (deferrable) {
+                results.push({ op, status: "deferred", error: errorMessage(err) });
+                continue;
+            }
+            stopped = true;
+            results.push({ op, status: "failed", error: errorMessage(err) });
+        }
+    }
+    if (manifestWriter?.hasEntries) {
+        await manifestWriter.flush(now());
+    }
+    else if (backupDir) {
+        await fs.rm(backupDir, { recursive: true, force: true }).catch(() => { });
+        backupDir = undefined;
+    }
+    const deferredPaths = results.flatMap((r) => r.status === "deferred" && (r.op.kind === "delete" || r.op.kind === "overwrite") ? [r.op.path] : []);
+    const applied = results.every((r) => r.status === "applied" || r.status === "skipped" || r.status === "deferred");
+    const next = !applied
+        ? backupDir
+            ? `An operation failed; later operations were skipped rather than run against a partially-applied plan. ` +
+                `To undo what did apply, call restoreBackup("${backupDir}", { mode: "apply" }), then fix the problem and retry.`
+            : "An operation failed before anything needed backing up; later operations were skipped. Fix the problem and retry."
+        : deferredPaths.length > 0
+            ? `${deferredPaths.length} operation(s) could not be written because something holds them open (the game, if it is running): ` +
+                `${deferredPaths.join(", ")}. ` +
+                `Everything else in the plan still ran; re-run once the holder is closed to retry them.`
+            : undefined;
+    return {
+        mode,
+        purpose: plan.purpose,
+        applied,
+        operations: results,
+        backupDir,
+        confidence: options.confidence,
+        next,
+    };
+}

package/dist/core/safety/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { planFile, planMkdir, planCopy, planDelete, planJunction, planUnlink, normalizePlan, isIdenticalFile } from "./plan.js";
+export { executePlan } from "./execute.js";
+export { restoreBackup, listBackups, isLockError } from "./restore.js";
+export { MANIFEST_FILE, backupManifestSchema, backupManifestEntrySchema, backupManifestFileEntrySchema, backupManifestLinkEntrySchema, readManifest, sha256File, } from "./backup.js";

package/dist/core/safety/plan.js

@@ -0,0 +1,122 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { isDirectory, pathExists } from "../fsutil.js";
+import { sha256File } from "./backup.js";
+export function planFile(absPath, content) {
+    return { kind: "create", path: absPath, content };
+}
+export function planMkdir(absPath) {
+    return { kind: "mkdir", path: absPath };
+}
+export function planCopy(fromAbsPath, toAbsPath) {
+    return { kind: "copy", from: fromAbsPath, to: toAbsPath };
+}
+export function planDelete(absPath) {
+    return { kind: "delete", path: absPath };
+}
+export function planJunction(absPath, targetAbsPath) {
+    return { kind: "junction", path: absPath, target: targetAbsPath };
+}
+export function planUnlink(absPath) {
+    return { kind: "unlink", path: absPath };
+}
+function opPaths(op) {
+    switch (op.kind) {
+        case "copy":
+            return [op.from, op.to];
+        case "junction":
+            return [op.path, op.target];
+        default:
+            return [op.path];
+    }
+}
+function assertAbsolute(label, p) {
+    if (!path.isAbsolute(p)) {
+        throw new Error(`safety: ${label} must be an absolute path, got "${p}"`);
+    }
+}
+async function hasIdenticalContent(filePath, content) {
+    const incoming = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
+    let existing;
+    try {
+        const stat = await fs.stat(filePath);
+        if (!stat.isFile() || stat.size !== incoming.length)
+            return false;
+        existing = await fs.readFile(filePath);
+    }
+    catch {
+        return false;
+    }
+    return existing.equals(incoming);
+}
+export async function isIdenticalFile(from, to) {
+    try {
+        const [a, b] = await Promise.all([fs.stat(from), fs.lstat(to)]);
+        if (!a.isFile() || !b.isFile() || a.size !== b.size)
+            return false;
+        const [ha, hb] = await Promise.all([sha256File(from), sha256File(to)]);
+        return ha.sha256 === hb.sha256;
+    }
+    catch {
+        return false;
+    }
+}
+async function normalizeOp(op) {
+    for (const p of opPaths(op))
+        assertAbsolute(`${op.kind} path`, p);
+    switch (op.kind) {
+        case "create":
+        case "overwrite": {
+            const exists = await pathExists(op.path);
+            if (!exists) {
+                return { op: { ...op, kind: "create" }, skipEligible: false };
+            }
+            const identical = await hasIdenticalContent(op.path, op.content);
+            return {
+                op: { ...op, kind: "overwrite" },
+                skipEligible: identical,
+                skipReason: identical ? "target already has identical content" : undefined,
+            };
+        }
+        case "mkdir": {
+            const exists = await isDirectory(op.path);
+            return { op, skipEligible: exists, skipReason: exists ? "directory already exists" : undefined };
+        }
+        case "delete": {
+            const exists = await pathExists(op.path);
+            return { op, skipEligible: !exists, skipReason: exists ? undefined : "path does not exist" };
+        }
+        case "unlink": {
+            let lst;
+            try {
+                lst = await fs.lstat(op.path);
+            }
+            catch {
+                return { op, skipEligible: true, skipReason: "path does not exist" };
+            }
+            if (!lst.isSymbolicLink()) {
+                return {
+                    op,
+                    skipEligible: true,
+                    skipReason: "path is not a symbolic link or junction; unlink refuses to delete a real file or directory",
+                };
+            }
+            return { op, skipEligible: false };
+        }
+        case "copy": {
+            const identical = await isIdenticalFile(op.from, op.to);
+            return { op, skipEligible: identical, skipReason: identical ? "target already has identical content" : undefined };
+        }
+        case "junction":
+            return { op, skipEligible: false };
+    }
+}
+export async function normalizePlan(plan) {
+    if (plan.backupRoot !== undefined)
+        assertAbsolute("backupRoot", plan.backupRoot);
+    const operations = [];
+    for (const op of plan.operations) {
+        operations.push(await normalizeOp(op));
+    }
+    return { purpose: plan.purpose, backupRoot: plan.backupRoot, operations };
+}