modwright 0.1.0

package/dist/core/scaffold/ids.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+const DIGEST_PREFIX = "modwright.scaffold.v1";
+function digestBytes(projectIdentity, scaffoldId, slot) {
+    return createHash("sha256").update([DIGEST_PREFIX, projectIdentity, scaffoldId, slot].join("\0")).digest();
+}
+function bytesToV4Uuid(bytes) {
+    const b = Buffer.from(bytes.subarray(0, 16));
+    b[6] = (b[6] & 0x0f) | 0x40;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const hex = b.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function bytesToBg3Handle(bytes) {
+    const dashed = bytesToV4Uuid(bytes);
+    return `h${dashed.replace(/-/g, "g")};1`;
+}
+function bytesToBg3HandleBare(bytes) {
+    return bytesToBg3Handle(bytes).replace(/;1$/, "");
+}
+function bytesToDashedUuid(bytes) {
+    return bytesToV4Uuid(bytes);
+}
+function slugifyKeepCase(raw) {
+    return raw
+        .trim()
+        .replace(/[^A-Za-z0-9_.]+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+function slugifyLower(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+const FNV64_OFFSET = 0xcbf29ce484222325n;
+const FNV64_PRIME = 0x100000001b3n;
+const U64_MASK = 0xffffffffffffffffn;
+export function fnv1a64(text) {
+    let h = FNV64_OFFSET;
+    for (const byte of Buffer.from(text, "utf8")) {
+        h = ((h ^ BigInt(byte)) * FNV64_PRIME) & U64_MASK;
+    }
+    return h.toString();
+}
+export function fixedPointBits(slot, fractionBits) {
+    const n = Number(slot);
+    if (slot.trim() === "" || !Number.isFinite(n)) {
+        throw new Error(`scaffold: a fixed-point id needs a numeric slot, got "${slot}".`);
+    }
+    return String(Math.round(n * 2 ** fractionBits));
+}
+export function renderId(form, projectIdentity, scaffoldId, slot, fractionBits = 17) {
+    switch (form) {
+        case "uuid":
+            return bytesToV4Uuid(digestBytes(projectIdentity, scaffoldId, slot));
+        case "bg3-handle":
+            return bytesToBg3Handle(digestBytes(projectIdentity, scaffoldId, slot));
+        case "bg3-handle-bare":
+            return bytesToBg3HandleBare(digestBytes(projectIdentity, scaffoldId, slot));
+        case "dashed-uuid":
+            return bytesToDashedUuid(digestBytes(projectIdentity, scaffoldId, slot));
+        case "tweak-record":
+        case "map-key":
+            return slugifyKeepCase(slot);
+        case "slug":
+            return slugifyLower(slot);
+        case "fnv1a64":
+            return fnv1a64(slot);
+        case "fixed-point":
+            return fixedPointBits(slot, fractionBits);
+    }
+}
+export function collisionSlot(slot, attempt) {
+    return `${slot}#${attempt}`;
+}

package/dist/core/scaffold/index.js

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export { scaffoldsRoot, listScaffoldFiles, loadScaffoldFile, loadAllScaffolds, findScaffold, unknownSatisfiesIds } from "./load.js";
+export { summarize, describe } from "./catalog.js";
+export { runScaffold } from "./engine.js";
+export { renderId, collisionSlot } from "./ids.js";
+export { interpolate, interpolateDeep, emptyScope } from "./render.js";
+export { checkCollision } from "./collisions.js";
+export { bootstrapProject } from "./bootstrap.js";
+export { generateClaudeAssets, claudeAssetsRoot, modwrightVersion, interpolateTemplate, lineDiff, quotedFactIds } from "./claude-assets.js";
+export { checkSequence, findSequence, listSequenceFiles, loadAllSequences, loadSequenceFile, parseSequenceDefinition, planSequence, sequenceSchema, summarizeSequences, } from "./sequence.js";

package/dist/core/scaffold/jsonpath.js

@@ -0,0 +1,121 @@
+import { isJsonArray, isJsonObject } from "../text/json.js";
+function splitPath(path) {
+    const segments = [];
+    let i = 0;
+    while (i < path.length) {
+        if (path[i] === "'") {
+            const end = path.indexOf("'", i + 1);
+            if (end === -1)
+                throw new Error(`scaffold: unterminated quoted path segment in "${path}".`);
+            segments.push(path.slice(i + 1, end));
+            i = end + 1;
+            if (path[i] === ".")
+                i++;
+            continue;
+        }
+        const next = path.indexOf(".", i);
+        const end = next === -1 ? path.length : next;
+        const seg = path.slice(i, end);
+        if (seg.length > 0)
+            segments.push(seg);
+        i = end + 1;
+    }
+    return segments;
+}
+export function getAtPath(root, path) {
+    const segments = splitPath(path);
+    let node = root;
+    for (const seg of segments) {
+        if (isJsonArray(node)) {
+            const idx = Number(seg);
+            node = Number.isInteger(idx) ? node[idx] : undefined;
+        }
+        else if (isJsonObject(node)) {
+            node = node[seg];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return node;
+}
+export function setAtPath(root, path, value) {
+    const segments = splitPath(path);
+    if (segments.length === 0)
+        return value;
+    if (!isJsonObject(root) && !isJsonArray(root)) {
+        throw new Error(`scaffold: cannot set "${path}" on a non-object/array document root.`);
+    }
+    let node = root;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const seg = segments[i];
+        if (Array.isArray(node)) {
+            const idx = seg === "-" ? node.length : Number(seg);
+            if (!Number.isInteger(idx) || idx < 0 || idx >= node.length) {
+                throw new Error(`scaffold: path "${path}" indexes a missing array element at segment "${seg}".`);
+            }
+            const next = node[idx];
+            if (!isJsonObject(next) && !isJsonArray(next)) {
+                node[idx] = segments[i + 1] === "-" ? [] : {};
+                node = node[idx];
+            }
+            else {
+                node = next;
+            }
+        }
+        else {
+            const existing = node[seg];
+            if (!isJsonObject(existing) && !isJsonArray(existing)) {
+                node[seg] = segments[i + 1] === "-" ? [] : {};
+            }
+            node = node[seg];
+        }
+    }
+    const last = segments[segments.length - 1];
+    if (Array.isArray(node)) {
+        if (last === "-") {
+            node.push(value);
+        }
+        else {
+            const idx = Number(last);
+            if (!Number.isInteger(idx))
+                throw new Error(`scaffold: path "${path}" ends in a non-numeric array segment "${last}".`);
+            node[idx] = value;
+        }
+    }
+    else {
+        node[last] = value;
+    }
+    return root;
+}
+function getParentBySegments(root, segments) {
+    let node = root;
+    for (const seg of segments) {
+        if (isJsonArray(node)) {
+            const idx = Number(seg);
+            node = Number.isInteger(idx) ? node[idx] : undefined;
+        }
+        else if (isJsonObject(node)) {
+            node = node[seg];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return node;
+}
+export function deleteAtPath(root, path) {
+    const segments = splitPath(path);
+    if (segments.length === 0)
+        return;
+    const parent = getParentBySegments(root, segments.slice(0, -1));
+    const last = segments[segments.length - 1];
+    if (isJsonObject(parent)) {
+        delete parent[last];
+    }
+    else if (isJsonArray(parent)) {
+        const idx = Number(last);
+        if (Number.isInteger(idx) && idx >= 0 && idx < parent.length)
+            parent.splice(idx, 1);
+    }
+}

package/dist/core/scaffold/load.js

@@ -0,0 +1,81 @@
+import { existsSync, promises as fs } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { parseScaffoldDefinition } from "./types.js";
+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(`scaffold: could not find package.json above ${startDir}`);
+        dir = parent;
+    }
+}
+export function scaffoldsRoot() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.join(findPackageRoot(here), "scaffolds");
+}
+export function unknownSatisfiesIds(def, registry) {
+    return def.satisfies.filter((id) => !registry.get(id));
+}
+export async function loadScaffoldFile(filePath, registry) {
+    const text = await fs.readFile(filePath, "utf8");
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (err) {
+        throw new Error(`${filePath}: YAML parse error: ${err.message}`);
+    }
+    const def = parseScaffoldDefinition(raw, filePath);
+    const unknown = unknownSatisfiesIds(def, registry);
+    if (unknown.length > 0) {
+        throw new Error(`${filePath}: scaffold "${def.id}" names unknown rule id(s) in satisfies: ${unknown.join(", ")}. ` +
+            `Every entry must be a real, registered validator id.`);
+    }
+    return def;
+}
+export async function listScaffoldFiles(root = scaffoldsRoot()) {
+    const out = [];
+    let games;
+    try {
+        games = (await fs.readdir(root, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    for (const game of games) {
+        const gameDir = path.join(root, game);
+        let files;
+        try {
+            files = (await fs.readdir(gameDir)).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files.sort()) {
+            out.push({ file: path.join(gameDir, file), game, kind: path.basename(file).replace(/\.ya?ml$/, "") });
+        }
+    }
+    return out;
+}
+export async function loadAllScaffolds(registry, root = scaffoldsRoot()) {
+    const entries = await listScaffoldFiles(root);
+    const loaded = [];
+    const problems = [];
+    for (const entry of entries) {
+        try {
+            loaded.push({ file: entry.file, definition: await loadScaffoldFile(entry.file, registry) });
+        }
+        catch (err) {
+            problems.push(err.message);
+        }
+    }
+    return { loaded, problems };
+}
+export function findScaffold(loaded, id) {
+    return loaded.find((s) => s.definition.id === id);
+}

package/dist/core/scaffold/render.js

@@ -0,0 +1,85 @@
+const LONE_INPUT_TOKEN_RE = /^\$\{input\.([a-zA-Z0-9_]+)\}$/;
+const LONE_IDS_TOKEN_RE = /^\$\{ids\.([a-zA-Z0-9_]+)\}$/;
+export function listInputItems(raw) {
+    return raw
+        .split(/[\n;]/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function reindentBlock(raw, spaces) {
+    const lines = raw.split("\n");
+    const nonEmpty = lines.filter((l) => l.trim() !== "");
+    if (nonEmpty.length === 0)
+        return raw.trim() === "" ? "" : raw;
+    const min = Math.min(...nonEmpty.map((l) => l.match(/^ */)[0].length));
+    const pad = " ".repeat(spaces);
+    return lines.map((l) => (l.trim() === "" ? "" : pad + l.slice(min))).join("\n");
+}
+const TOKEN_RE = /\$\{(input|ids|project|template|each)\.([a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*)\}/g;
+export function emptyScope() {
+    return { input: {}, ids: {}, project: {}, template: {} };
+}
+export function interpolate(text, scope) {
+    return text.replace(TOKEN_RE, (whole, ns, key) => {
+        const bag = scope[ns];
+        if (!bag) {
+            throw new Error(`scaffold: "${whole}" is only valid inside a $each element's $item.`);
+        }
+        if (!(key in bag)) {
+            throw new Error(`scaffold: unresolved interpolation "${whole}" — no "${key}" in $${ns}.`);
+        }
+        return bag[key];
+    });
+}
+function isEach(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return false;
+    const keys = Object.keys(v);
+    return keys.length === 2 && keys.includes("$each") && keys.includes("$item") && typeof v.$each === "string";
+}
+function expandEach(v, scope) {
+    const lone = LONE_INPUT_TOKEN_RE.exec(v.$each);
+    if (!lone || !scope.listInputs?.has(lone[1])) {
+        throw new Error(`scaffold: $each "${v.$each}" must be exactly \${input.<name>} of a list input.`);
+    }
+    if (!(lone[1] in scope.input))
+        throw new Error(`scaffold: unresolved interpolation "${v.$each}" — no "${lone[1]}" in $input.`);
+    return listInputItems(scope.input[lone[1]]).map((item) => {
+        const each = { value: item };
+        item.split("|").forEach((field, i) => {
+            each[String(i)] = field.trim();
+        });
+        return interpolateDeep(v.$item, { ...scope, each });
+    });
+}
+export function interpolateDeep(value, scope) {
+    if (typeof value === "string") {
+        const lone = LONE_INPUT_TOKEN_RE.exec(value);
+        if (lone && scope.numberInputs?.has(lone[1])) {
+            if (!(lone[1] in scope.input))
+                throw new Error(`scaffold: unresolved interpolation "${value}" — no "${lone[1]}" in $input.`);
+            return Number(scope.input[lone[1]]);
+        }
+        if (lone && scope.listInputs?.has(lone[1])) {
+            if (!(lone[1] in scope.input))
+                throw new Error(`scaffold: unresolved interpolation "${value}" — no "${lone[1]}" in $input.`);
+            return listInputItems(scope.input[lone[1]]);
+        }
+        const loneId = LONE_IDS_TOKEN_RE.exec(value);
+        if (loneId && scope.numberIds?.has(loneId[1])) {
+            if (!(loneId[1] in scope.ids))
+                throw new Error(`scaffold: unresolved interpolation "${value}" — no "${loneId[1]}" in $ids.`);
+            return Number(scope.ids[loneId[1]]);
+        }
+        return interpolate(value, scope);
+    }
+    if (Array.isArray(value))
+        return value.flatMap((v) => (isEach(v) ? expandEach(v, scope) : [interpolateDeep(v, scope)]));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = interpolateDeep(v, scope);
+        return out;
+    }
+    return value;
+}