modwright 0.1.0

package/dist/core/fsutil.js

@@ -0,0 +1,191 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+const DEFAULT_SKIP = ["node_modules", ".git", ".svn", "__macosx"];
+const STAT_CONCURRENCY = 32;
+export async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readLinkTarget(p) {
+    const raw = await fs.readlink(p);
+    return /^[A-Za-z]:[\\/]$|^[\\/]$/.test(raw) ? raw : raw.replace(/[\\/]+$/, "");
+}
+export async function isDirectory(p) {
+    try {
+        return (await fs.stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function walk(dir, options = {}) {
+    const limit = options.limit ?? 5000;
+    const skip = new Set([...DEFAULT_SKIP, ...(options.skipDirs ?? [])]);
+    const files = [];
+    const links = [];
+    const toStat = [];
+    let sizeBytes = 0;
+    let modifiedAt = new Date(0);
+    let truncated = false;
+    async function recurse(current, prefix) {
+        if (truncated)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (truncated)
+                return;
+            const abs = path.join(current, entry.name);
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink()) {
+                links.push(rel);
+            }
+            else if (entry.isDirectory()) {
+                if (skip.has(entry.name.toLowerCase()))
+                    continue;
+                await recurse(abs, rel);
+            }
+            else if (entry.isFile()) {
+                if (files.length >= limit) {
+                    truncated = true;
+                    return;
+                }
+                files.push(rel);
+                if (options.stat !== false)
+                    toStat.push(abs);
+            }
+        }
+    }
+    await recurse(dir, "");
+    let next = 0;
+    const worker = async () => {
+        while (next < toStat.length) {
+            const abs = toStat[next++];
+            try {
+                const stat = await fs.stat(abs);
+                sizeBytes += stat.size;
+                if (stat.mtime > modifiedAt)
+                    modifiedAt = stat.mtime;
+            }
+            catch {
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(STAT_CONCURRENCY, toStat.length) }, worker));
+    return { files, sizeBytes, modifiedAt, truncated, links };
+}
+export async function statFile(p) {
+    const stat = await fs.stat(p);
+    return {
+        files: [path.basename(p)],
+        sizeBytes: stat.size,
+        modifiedAt: stat.mtime,
+        truncated: false,
+    };
+}
+export async function readTextIfExists(p) {
+    try {
+        return await fs.readFile(p, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function head(p, maxBytes = 65_536) {
+    const handle = await fs.open(p, "r");
+    try {
+        const { size } = await handle.stat();
+        const length = Math.min(Number(size), maxBytes);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, 0);
+        return buffer.toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function tail(p, lines, maxBytes = 512_000) {
+    const handle = await fs.open(p, "r");
+    try {
+        const { size } = await handle.stat();
+        const start = Math.max(0, size - maxBytes);
+        const length = size - start;
+        const buffer = Buffer.alloc(Number(length));
+        await handle.read(buffer, 0, Number(length), start);
+        const text = buffer.toString("utf8");
+        const split = text.split(/\r?\n/);
+        return split.slice(Math.max(0, split.length - lines)).join("\n");
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function firstExisting(candidates) {
+    for (const candidate of candidates) {
+        if (await pathExists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+export function homePath(...segments) {
+    const home = process.env.USERPROFILE ?? process.env.HOME ?? "";
+    return path.join(home, ...segments);
+}
+export function localAppData(...segments) {
+    const base = process.env.LOCALAPPDATA ?? homePath("AppData", "Local");
+    return path.join(base, ...segments);
+}
+export function appData(...segments) {
+    const base = process.env.APPDATA ?? homePath("AppData", "Roaming");
+    return path.join(base, ...segments);
+}
+export function documents(...segments) {
+    return homePath("Documents", ...segments);
+}
+export async function resolveCandidate(candidates) {
+    for (const candidate of candidates) {
+        const base = path.basename(candidate);
+        if (!base.includes("*")) {
+            if (await pathExists(candidate))
+                return { path: candidate, candidate };
+            continue;
+        }
+        const dir = path.dirname(candidate);
+        const regex = new RegExp("^" + base.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$", "i");
+        let entries;
+        try {
+            entries = await fs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        let best;
+        for (const entry of entries) {
+            if (!regex.test(entry))
+                continue;
+            const abs = path.join(dir, entry);
+            try {
+                const stat = await fs.stat(abs);
+                if (!stat.isFile())
+                    continue;
+                if (!best || stat.mtimeMs > best.mtime)
+                    best = { path: abs, mtime: stat.mtimeMs };
+            }
+            catch {
+            }
+        }
+        if (best)
+            return { path: best.path, candidate };
+    }
+    return undefined;
+}

package/dist/core/home.js

@@ -0,0 +1,70 @@
+import { existsSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+function resolve(kind, ctx) {
+    const env = ctx.env ?? process.env;
+    const platform = ctx.platform ?? process.platform;
+    const home = ctx.homedir ?? os.homedir();
+    if (env.MODWRIGHT_HOME) {
+        const root = path.resolve(env.MODWRIGHT_HOME);
+        return kind === "cache" ? path.join(root, "cache") : root;
+    }
+    if (platform === "win32") {
+        const w = path.win32;
+        const abs = (v, ...fallback) => (v && w.isAbsolute(v) ? v : w.join(home, ...fallback));
+        if (kind === "config")
+            return w.join(abs(env.APPDATA, "AppData", "Roaming"), "ModWright");
+        const local = w.join(abs(env.LOCALAPPDATA, "AppData", "Local"), "ModWright");
+        return kind === "cache" ? w.join(local, "cache") : local;
+    }
+    const p = path.posix;
+    if (platform === "darwin") {
+        return kind === "cache" ? p.join(home, "Library", "Caches", "ModWright") : p.join(home, "Library", "Application Support", "ModWright");
+    }
+    const xdg = (v, ...fallback) => (v && p.isAbsolute(v) ? v : p.join(home, ...fallback));
+    if (kind === "config")
+        return p.join(xdg(env.XDG_CONFIG_HOME, ".config"), "modwright");
+    if (kind === "cache")
+        return p.join(xdg(env.XDG_CACHE_HOME, ".cache"), "modwright");
+    return p.join(xdg(env.XDG_DATA_HOME, ".local", "share"), "modwright");
+}
+export function userConfigDir(ctx = {}) {
+    return resolve("config", ctx);
+}
+export function userCacheDir(ctx = {}) {
+    return resolve("cache", ctx);
+}
+export function userDataDir(ctx = {}) {
+    return resolve("data", ctx);
+}
+export function packageRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        if (existsSync(path.join(dir, "package.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            throw new Error("could not find ModWright's package.json above its own module");
+        dir = parent;
+    }
+}
+export function legacyCacheDirs(current, env = process.env, cwd = process.cwd()) {
+    if (env.MODWRIGHT_CACHE_DIR)
+        return [];
+    const candidates = [path.resolve(cwd, ".modwright-cache")];
+    try {
+        candidates.push(path.join(packageRoot(), ".modwright-cache"));
+    }
+    catch {
+    }
+    const seen = new Set();
+    const currentKey = path.resolve(current).toLowerCase();
+    return candidates.filter((dir) => {
+        const key = path.resolve(dir).toLowerCase();
+        if (seen.has(key) || key === currentKey)
+            return false;
+        seen.add(key);
+        return existsSync(dir);
+    });
+}

package/dist/core/knowledge/facts.js

@@ -0,0 +1,229 @@
+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 { z } from "zod";
+export const FACT_STATUSES = [
+    "verified",
+    "unverified",
+    "contradicted",
+    "community",
+    "inferred",
+];
+export const FACT_ID_PREFIXES = {
+    baldursgate3: "bg3.",
+    cyberpunk2077: "cp2077.",
+    skyrimse: "sse.",
+};
+export function idPrefixFor(game) {
+    return FACT_ID_PREFIXES[game] ?? `${game}.`;
+}
+const ID_PATTERN = /^[a-z0-9]+(\.[a-z0-9-]+)+$/;
+const TOPIC_PATTERN = /^[a-z0-9]+(\.[a-z0-9-]+)*$/;
+const KNOWN_FACT_KEYS = [
+    "id",
+    "claim",
+    "status",
+    "verified_on",
+    "verified_by",
+    "source",
+    "tags",
+    "detail",
+    "supersedes",
+    "related",
+];
+const factStatusSchema = z.enum(FACT_STATUSES);
+const optionalString = () => z
+    .string()
+    .nullish()
+    .transform((v) => v ?? undefined);
+const factSchema = z
+    .object({
+    id: z.string().regex(ID_PATTERN, "id must be dotted lowercase, hyphenated words (e.g. bg3.stats.example)"),
+    claim: z.string().refine((v) => v.trim().length >= 15, "claim missing or too short"),
+    status: factStatusSchema,
+    verified_on: optionalString(),
+    verified_by: optionalString(),
+    source: z.string().refine((v) => v.trim().length > 0, "source missing"),
+    tags: z
+        .array(z.string())
+        .refine((tags) => tags.every((t) => t === t.toLowerCase()), "tags must be lowercase strings")
+        .optional(),
+    detail: optionalString(),
+    supersedes: optionalString(),
+    related: z
+        .array(z.union([z.string().min(1), z.object({ id: z.string().min(1), detail: z.string().optional() }).strict()]))
+        .transform((entries) => entries.map((r) => (typeof r === "string" ? r : r.id)))
+        .optional(),
+})
+    .strict();
+function buildFactFileSchema(expectedGame) {
+    return z
+        .object({
+        game: z.string().min(1),
+        topic: z.string().regex(TOPIC_PATTERN, "topic must be dotted lowercase"),
+        title: z.string().min(1),
+        source_docs: z.array(z.string()).optional(),
+        facts: z.array(factSchema).min(1, "facts must be a non-empty list"),
+    })
+        .strict()
+        .superRefine((data, ctx) => {
+        if (expectedGame !== undefined && data.game !== expectedGame) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["game"], message: `game must be "${expectedGame}"` });
+        }
+        const prefix = idPrefixFor(expectedGame ?? data.game);
+        const seenAt = new Map();
+        data.facts.forEach((fact, i) => {
+            if (!fact.id.startsWith(prefix)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["facts", i, "id"],
+                    message: `id must start with "${prefix}" (got ${JSON.stringify(fact.id)})`,
+                });
+            }
+            const earlier = seenAt.get(fact.id);
+            if (earlier !== undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["facts", i, "id"],
+                    message: `duplicate id ${fact.id} (also facts[${earlier}] in this file)`,
+                });
+            }
+            else {
+                seenAt.set(fact.id, i);
+            }
+        });
+    });
+}
+function formatPath(segments) {
+    if (segments.length === 0)
+        return "(root)";
+    let out = "";
+    for (const segment of segments) {
+        out += typeof segment === "number" ? `[${segment}]` : out ? `.${segment}` : segment;
+    }
+    return out;
+}
+export async function loadFactFile(filePath, expectedGame) {
+    const where = filePath;
+    let text;
+    try {
+        text = await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        return { path: filePath, problems: [`${where}: cannot read file: ${error.message}`] };
+    }
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (error) {
+        return { path: filePath, problems: [`${where}: YAML parse error: ${error.message}`] };
+    }
+    const schema = buildFactFileSchema(expectedGame);
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+        const problems = result.error.issues.map((issue) => `${where} ${formatPath(issue.path)}: ${issue.message}`);
+        return { path: filePath, problems };
+    }
+    return { path: filePath, file: result.data, problems: [] };
+}
+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(`loadKnowledge: could not find package.json above ${startDir}`);
+        }
+        dir = parent;
+    }
+}
+export function defaultKnowledgeDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.join(findPackageRoot(here), "knowledge");
+}
+export async function loadKnowledge(rootDir, options = {}) {
+    const root = rootDir ?? defaultKnowledgeDir();
+    const problems = [];
+    let gameDirs;
+    try {
+        gameDirs = (await fs.readdir(root, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        problems.push(`${root}: cannot read knowledge directory: ${error.message}`);
+        return { files: [], facts: [], problems };
+    }
+    const wanted = options.games ? new Set(options.games) : undefined;
+    const loaded = [];
+    for (const game of gameDirs) {
+        if (wanted && !wanted.has(game))
+            continue;
+        const dir = path.join(root, game);
+        let names;
+        try {
+            names = (await fs.readdir(dir)).filter((n) => n.endsWith(".yaml") || n.endsWith(".yml")).sort();
+        }
+        catch (error) {
+            problems.push(`${dir}: cannot read: ${error.message}`);
+            continue;
+        }
+        for (const name of names) {
+            const filePath = path.join(dir, name);
+            const result = await loadFactFile(filePath, game);
+            if (result.problems.length > 0 || !result.file) {
+                problems.push(...result.problems);
+                continue;
+            }
+            loaded.push({ path: filePath, file: result.file });
+        }
+    }
+    const idOwner = new Map();
+    const uniqueFiles = [];
+    for (const entry of loaded) {
+        let collided = false;
+        for (const fact of entry.file.facts) {
+            const owner = idOwner.get(fact.id);
+            if (owner) {
+                problems.push(`${entry.path}: duplicate id ${fact.id} (also in ${owner})`);
+                collided = true;
+            }
+        }
+        if (collided)
+            continue;
+        for (const fact of entry.file.facts)
+            idOwner.set(fact.id, entry.path);
+        uniqueFiles.push(entry);
+    }
+    const allIds = new Set(idOwner.keys());
+    const finalFiles = [];
+    for (const entry of uniqueFiles) {
+        for (const fact of entry.file.facts) {
+            for (const rel of fact.related ?? []) {
+                if (!allIds.has(rel))
+                    problems.push(`${entry.path}: fact ${fact.id} relates to unknown id "${rel}"`);
+            }
+        }
+        const dangling = entry.file.facts.filter((fact) => fact.supersedes && !allIds.has(fact.supersedes));
+        if (dangling.length > 0) {
+            for (const fact of dangling) {
+                problems.push(`${entry.path}: fact ${fact.id} supersedes unknown id "${fact.supersedes}"`);
+            }
+            continue;
+        }
+        finalFiles.push(entry);
+    }
+    const files = [];
+    const facts = [];
+    for (const entry of finalFiles) {
+        files.push(entry.file);
+        for (const fact of entry.file.facts) {
+            facts.push({ ...fact, game: entry.file.game, topic: entry.file.topic, topicTitle: entry.file.title });
+        }
+    }
+    return { files, facts, problems };
+}

package/dist/core/knowledge/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export { IndexStore, indexFile, defaultCacheDir, findLegacyIndex, legacyIndexHint, resolveIndexFile } from "./store.js";
+export * from "./facts.js";
+export * from "./search.js";

package/dist/core/knowledge/search.js

@@ -0,0 +1,112 @@
+import { compareVersions, isDifferentVersionAxis, parseVersion } from "../compat/version.js";
+const STATUS_RANK = {
+    verified: 0,
+    community: 1,
+    inferred: 2,
+    unverified: 3,
+    contradicted: 4,
+};
+const WEIGHT = {
+    id: 6,
+    tag: 5,
+    claim: 3,
+    detail: 1,
+    topic: 2,
+    phrase: 4,
+};
+function tokenize(text) {
+    const lower = text.toLowerCase().trim();
+    if (!lower)
+        return [];
+    const whole = lower.split(/\s+/).filter(Boolean);
+    const split = lower.split(/[^a-z0-9]+/).filter(Boolean);
+    return Array.from(new Set([...whole, ...split]));
+}
+function matchesAllTags(fact, tags) {
+    const factTags = new Set(fact.tags ?? []);
+    return tags.every((t) => factTags.has(t.toLowerCase()));
+}
+function scoreFact(fact, tokens, phrase) {
+    if (tokens.length === 0)
+        return 0;
+    const id = fact.id.toLowerCase();
+    const claim = fact.claim.toLowerCase();
+    const detail = fact.detail?.toLowerCase() ?? "";
+    const tags = (fact.tags ?? []).map((t) => t.toLowerCase());
+    const topic = `${fact.topic} ${fact.topicTitle}`.toLowerCase();
+    let score = 0;
+    for (const token of tokens) {
+        if (id.includes(token))
+            score += WEIGHT.id;
+        for (const tag of tags) {
+            if (tag.includes(token) || token.includes(tag))
+                score += WEIGHT.tag;
+        }
+        if (claim.includes(token))
+            score += WEIGHT.claim;
+        if (detail && detail.includes(token))
+            score += WEIGHT.detail;
+        if (topic.includes(token))
+            score += WEIGHT.topic;
+    }
+    if (phrase && claim.includes(phrase))
+        score += WEIGHT.phrase;
+    return score;
+}
+export function computeStale(fact, installedVersion) {
+    if (!installedVersion || !fact.verified_on)
+        return undefined;
+    if (!parseVersion(installedVersion) || !parseVersion(fact.verified_on))
+        return undefined;
+    if (isDifferentVersionAxis(fact.verified_on, installedVersion))
+        return undefined;
+    return compareVersions(fact.verified_on, installedVersion) < 0;
+}
+export function searchFacts(entries, query) {
+    const limit = query.limit ?? 20;
+    const tokens = query.text ? tokenize(query.text) : [];
+    const phrase = query.text ? query.text.toLowerCase().trim() : "";
+    const hasText = tokens.length > 0;
+    const statusSet = query.status ? new Set(query.status) : undefined;
+    const tagList = query.tags?.length ? query.tags : undefined;
+    const filtered = entries.filter((fact) => {
+        if (query.game && fact.game !== query.game)
+            return false;
+        if (query.topic && fact.topic !== query.topic)
+            return false;
+        if (tagList && !matchesAllTags(fact, tagList))
+            return false;
+        if (statusSet && !statusSet.has(fact.status))
+            return false;
+        return true;
+    });
+    const scored = filtered
+        .map((fact) => ({ fact, score: scoreFact(fact, tokens, phrase) }))
+        .filter(({ score }) => !hasText || score > 0);
+    scored.sort((a, b) => {
+        if (a.score !== b.score)
+            return b.score - a.score;
+        const statusDiff = STATUS_RANK[a.fact.status] - STATUS_RANK[b.fact.status];
+        if (statusDiff !== 0)
+            return statusDiff;
+        return a.fact.id < b.fact.id ? -1 : a.fact.id > b.fact.id ? 1 : 0;
+    });
+    return scored.slice(0, limit).map(({ fact, score }) => {
+        const stale = computeStale(fact, query.installedVersion);
+        const axisMismatch = query.installedVersion !== undefined &&
+            fact.verified_on !== undefined &&
+            isDifferentVersionAxis(fact.verified_on, query.installedVersion);
+        return {
+            ...fact,
+            score,
+            ...(stale === undefined ? {} : { stale }),
+            ...(axisMismatch ? { staleUnknownAxis: true } : {}),
+        };
+    });
+}
+export function factById(entries, id) {
+    return entries.find((fact) => fact.id === id);
+}
+export function factsByTopic(entries, topic) {
+    return entries.filter((fact) => fact.topic === topic);
+}