modwright 0.1.0

package/dist/surfaces/cyberpunk2077/index/queries.js

@@ -0,0 +1,504 @@
+import { overlayFlats } from "./model.js";
+const DEFAULT_LIMIT = 50;
+const MAX_CHAIN_DEPTH = 25;
+const MAX_CHILDREN_DEPTH = 25;
+function str(v) {
+    if (v === undefined)
+        return undefined;
+    const s = String(v).trim();
+    return s.length > 0 ? s : undefined;
+}
+function limitOf(params) {
+    const n = Number(params.limit);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_LIMIT;
+}
+function truthy(v) {
+    const s = str(v);
+    return s === "1" || s?.toLowerCase() === "true";
+}
+function page(rows, limit) {
+    if (rows.length > limit)
+        return { rows: rows.slice(0, limit), truncated: true };
+    return { rows, truncated: false };
+}
+function result(kind, params, rows, truncated, note) {
+    return { kind, params, count: rows.length, truncated, rows, note };
+}
+function parseValueJson(raw) {
+    try {
+        return JSON.parse(String(raw));
+    }
+    catch {
+        return raw;
+    }
+}
+function rawOccurrencesFor(store, name) {
+    const rows = store.all(`SELECT id, base, type, source_id, file, line FROM record WHERE name = ? ORDER BY id`, [name]);
+    return rows.map((r) => {
+        const flatRows = store.all(`SELECT name, kind, value_json, op FROM flat WHERE record_id = ? ORDER BY id`, [r.id ?? null]);
+        return {
+            id: Number(r.id),
+            file: String(r.file),
+            line: Number(r.line),
+            base: r.base === null || r.base === undefined ? null : String(r.base),
+            type: r.type === null || r.type === undefined ? null : String(r.type),
+            sourceId: r.source_id,
+            flats: flatRows.map((f) => ({
+                name: String(f.name),
+                kind: String(f.kind),
+                value: parseValueJson(f.value_json),
+                op: f.op,
+            })),
+        };
+    });
+}
+function latestPointer(store, name, column) {
+    const row = store.get(`SELECT ${column} AS v FROM record WHERE name = ? AND ${column} IS NOT NULL ORDER BY id DESC LIMIT 1`, [
+        name,
+    ]);
+    return row?.v === undefined || row.v === null ? undefined : String(row.v);
+}
+function effectiveOwnFlats(name, occs) {
+    return overlayFlats(occs.map((o) => ({ recordLabel: name, flats: o.flats })));
+}
+function queryRecord(store, params) {
+    const name = str(params.name);
+    const prefix = str(params.prefix);
+    if (!name && !prefix) {
+        return result("record", params, [], false, "No 'name' or 'prefix' given; nothing searched.");
+    }
+    const limit = limitOf(params);
+    let names;
+    if (name) {
+        names = store.get(`SELECT 1 FROM record WHERE name = ? LIMIT 1`, [name]) ? [name] : [];
+    }
+    else {
+        const rows = store.all(`SELECT DISTINCT name FROM record WHERE name LIKE ? ORDER BY name LIMIT ?`, [
+            `${prefix}%`,
+            limit + 1,
+        ]);
+        names = rows.map((r) => String(r.name));
+    }
+    const { rows: pageNames, truncated } = page(names, limit);
+    const mapped = pageNames.map((n) => {
+        const occs = rawOccurrencesFor(store, n);
+        const effective = effectiveOwnFlats(n, occs);
+        return {
+            name: n,
+            base: latestPointer(store, n, "base") ?? null,
+            type: latestPointer(store, n, "type") ?? null,
+            occurrences: occs.map((o) => ({ file: o.file, line: o.line })),
+            flats: [...effective.values()].map((f) => ({ name: f.name, value: f.value, kind: f.kind })),
+        };
+    });
+    const how = name ? `exact name '${name}'` : `name prefix '${prefix}'`;
+    const note = `Searched TweakDB records by ${how}; each record's flats are merged across every occurrence that touched it.`;
+    return result("record", params, mapped, truncated, note);
+}
+function queryChain(store, params) {
+    const name = str(params.name);
+    if (!name)
+        return result("chain", params, [], false, "No 'name' given; nothing searched.");
+    if (!store.get(`SELECT 1 FROM record WHERE name = ? LIMIT 1`, [name])) {
+        return result("chain", params, [], false, `No record named '${name}' found.`);
+    }
+    const ancestors = [];
+    const seen = new Set([name]);
+    let current = latestPointer(store, name, "base");
+    let hitCap = false;
+    while (current && !seen.has(current)) {
+        ancestors.push(current);
+        seen.add(current);
+        if (ancestors.length >= MAX_CHAIN_DEPTH) {
+            hitCap = latestPointer(store, current, "base") !== undefined;
+            break;
+        }
+        current = latestPointer(store, current, "base");
+    }
+    const cyclic = current !== undefined && seen.has(current) && !hitCap && ancestors[ancestors.length - 1] !== current;
+    const rootToLeaf = [...ancestors].reverse();
+    rootToLeaf.push(name);
+    const rawOccs = rootToLeaf.flatMap((n) => rawOccurrencesFor(store, n).map((o) => ({ recordLabel: n, flats: o.flats })));
+    const effective = overlayFlats(rawOccs);
+    const type = [name, ...ancestors].map((n) => latestPointer(store, n, "type")).find((t) => t !== undefined);
+    const flats = [...effective.values()]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((f) => ({ name: f.name, value: f.value, kind: f.kind, from: f.from, contributors: f.contributors }));
+    const row = {
+        name,
+        base: latestPointer(store, name, "base") ?? null,
+        type: type ?? null,
+        chain: ancestors.map((n) => ({ name: n, type: latestPointer(store, n, "type") ?? null })),
+        flats,
+    };
+    const notes = [`Resolved the $base chain for '${name}' (${ancestors.length} ancestor(s)).`];
+    if (hitCap)
+        notes.push(`Chain walk stopped at ${MAX_CHAIN_DEPTH} ancestors; the true root may be further up.`);
+    if (cyclic)
+        notes.push(`A cycle was detected in the $base chain and the walk stopped early.`);
+    return result("chain", params, [row], false, notes.join(" "));
+}
+function queryFlat(store, params) {
+    const name = str(params.name);
+    if (!name)
+        return result("flat", params, [], false, "No flat 'name' given; nothing searched.");
+    const valueFilterRaw = str(params.value);
+    const limit = limitOf(params);
+    const candidateRows = store.all(`SELECT DISTINCT r.name AS name FROM flat f JOIN record r ON r.id = f.record_id WHERE f.name = ? ORDER BY r.name`, [
+        name,
+    ]);
+    const totalCandidates = candidateRows.length;
+    let valueFilter;
+    let hasValueFilter = false;
+    if (valueFilterRaw !== undefined) {
+        hasValueFilter = true;
+        try {
+            valueFilter = JSON.parse(valueFilterRaw);
+        }
+        catch {
+            valueFilter = valueFilterRaw;
+        }
+    }
+    const matched = [];
+    for (const row of candidateRows) {
+        if (matched.length > limit)
+            break;
+        const recName = String(row.name);
+        const occs = rawOccurrencesFor(store, recName);
+        const effective = effectiveOwnFlats(recName, occs);
+        const flat = effective.get(name);
+        if (!flat)
+            continue;
+        if (hasValueFilter && JSON.stringify(flat.value) !== JSON.stringify(valueFilter))
+            continue;
+        matched.push({ record: recName, value: flat.value, kind: flat.kind, from: flat.from, contributors: flat.contributors });
+    }
+    const { rows: pageRows, truncated } = page(matched, limit);
+    const note = hasValueFilter
+        ? `Records whose flat '${name}' equals the given value (${totalCandidates} record(s) declare '${name}' at all).`
+        : `Records that declare flat '${name}' (${totalCandidates} total).`;
+    return result("flat", params, pageRows, truncated, note);
+}
+function queryReverse(store, params) {
+    const token = str(params.token);
+    if (!token)
+        return result("reverse", params, [], false, "No 'token' given; nothing searched.");
+    const flatName = str(params.flat);
+    const limit = limitOf(params);
+    let sql = `SELECT r.name AS record, f.name AS flat, f.value_json AS value_json, f.kind AS kind, f.op AS op, r.file AS file, r.line AS line
+             FROM flat f JOIN record r ON r.id = f.record_id
+             WHERE f.value_json LIKE ?`;
+    const args = [`%${token}%`];
+    if (flatName) {
+        sql += ` AND f.name = ?`;
+        args.push(flatName);
+    }
+    sql += ` ORDER BY r.name, f.name LIMIT ?`;
+    args.push(limit + 1);
+    const rows = store.all(sql, args);
+    const { rows: pageRows, truncated } = page(rows, limit);
+    const mapped = pageRows.map((row) => ({
+        record: row.record,
+        flat: row.flat,
+        value: parseValueJson(row.value_json),
+        kind: row.kind,
+        op: row.op,
+        file: row.file,
+        line: row.line,
+    }));
+    const note = `Records whose flat value contains '${token}'${flatName ? ` (restricted to flat '${flatName}')` : ""}, via substring LIKE on the indexed value_json column.`;
+    return result("reverse", params, mapped, truncated, note);
+}
+function queryChildren(store, params) {
+    const base = str(params.base);
+    if (!base)
+        return result("children", params, [], false, "No 'base' given; nothing searched.");
+    const directOnly = truthy(params.direct);
+    const limit = limitOf(params);
+    const out = [];
+    const visited = new Set([base]);
+    let frontier = [base];
+    let depth = 0;
+    let hitDepthCap = false;
+    while (frontier.length > 0 && out.length <= limit && depth < MAX_CHILDREN_DEPTH) {
+        depth++;
+        const nextFrontier = [];
+        for (const parent of frontier) {
+            const rows = store.all(`SELECT DISTINCT name FROM record WHERE base = ? ORDER BY name`, [parent]);
+            for (const row of rows) {
+                const childName = String(row.name);
+                if (visited.has(childName))
+                    continue;
+                visited.add(childName);
+                out.push({ name: childName, base: parent, depth });
+                nextFrontier.push(childName);
+                if (out.length > limit)
+                    break;
+            }
+            if (out.length > limit)
+                break;
+        }
+        if (!directOnly)
+            frontier = nextFrontier;
+        else
+            break;
+        if (frontier.length > 0 && depth >= MAX_CHILDREN_DEPTH)
+            hitDepthCap = true;
+    }
+    const { rows: pageRows, truncated } = page(out, limit);
+    const notes = [
+        `${directOnly ? "Direct" : "Direct and transitive"} derivations of '${base}' (records whose $base chain passes through it).`,
+    ];
+    if (hitDepthCap)
+        notes.push(`Depth capped at ${MAX_CHILDREN_DEPTH} levels.`);
+    return result("children", params, pageRows, truncated, notes.join(" "));
+}
+function queryType(store, params) {
+    const type = str(params.type);
+    if (!type)
+        return result("type", params, [], false, "No 'type' given; nothing searched.");
+    const limit = limitOf(params);
+    const bare = type.replace(/^gamedata/, "").replace(/_Record$/, "");
+    const forms = [type, bare, `gamedata${bare}_Record`];
+    const rows = store.all(`SELECT COALESCE(package, '(none)') AS package, COUNT(*) AS n
+     FROM record WHERE type IN (?, ?, ?)
+     GROUP BY package ORDER BY n DESC, package LIMIT ?`, [...forms, limit + 1]);
+    const { rows: pageRows, truncated } = page(rows, limit);
+    const mapped = pageRows.map((row) => ({ package: row.package, count: Number(row.n) }));
+    const total = store.get(`SELECT COUNT(*) AS n FROM record WHERE type IN (?, ?, ?)`, forms)?.n ?? 0;
+    const note = `Records of $type '${type}' (also matched as '${bare}' / 'gamedata${bare}_Record'): ${Number(total)} total, broken out by package.`;
+    return result("type", params, mapped, truncated, note);
+}
+function queryResource(store, params) {
+    const exactPath = str(params.path);
+    const prefix = str(params.prefix);
+    const ext = str(params.ext);
+    if (!exactPath && !prefix) {
+        return result("resource", params, [], false, "No 'path' or 'prefix' given; nothing searched.");
+    }
+    const limit = limitOf(params);
+    const extSuffix = ext ? (ext.startsWith(".") ? ext : `.${ext}`) : undefined;
+    if (exactPath) {
+        let sql = `SELECT path, archive, sizeBytes FROM resource WHERE path = ?`;
+        const args = [exactPath];
+        if (extSuffix) {
+            sql += ` AND path LIKE ?`;
+            args.push(`%${extSuffix}`);
+        }
+        sql += ` ORDER BY archive LIMIT ?`;
+        args.push(limit + 1);
+        const rows = store.all(sql, args);
+        const { rows: pageRows, truncated } = page(rows, limit);
+        const mapped = pageRows.map((row) => ({ path: row.path, archive: row.archive, sizeBytes: row.sizeBytes }));
+        const note = `Searched the archive resource listing by exact depot path '${exactPath}'${ext ? ` filtered to extension '${ext}'` : ""} ` +
+            `(COLLATE NOCASE): one row per archive that lists it; count > 0 means the path exists in at least one archive. ` +
+            `'sizeBytes' is always null — 'archive <path> -l' prints no per-entry size (resource.ts's own note) — not "size unknown for this row".`;
+        return result("resource", params, mapped, truncated, note);
+    }
+    let sql = `SELECT path, COUNT(*) AS archiveCount FROM resource WHERE path LIKE ?`;
+    const args = [`${prefix}%`];
+    if (extSuffix) {
+        sql += ` AND path LIKE ?`;
+        args.push(`%${extSuffix}`);
+    }
+    sql += ` GROUP BY path ORDER BY path LIMIT ?`;
+    args.push(limit + 1);
+    const rows = store.all(sql, args);
+    const { rows: pageRows, truncated } = page(rows, limit);
+    const mapped = pageRows.map((row) => ({ path: row.path, archiveCount: Number(row.archiveCount) }));
+    const note = `Searched the archive resource listing by depot path prefix '${prefix}'${ext ? ` filtered to extension '${ext}'` : ""} (COLLATE NOCASE), deduped by path with the count of archives carrying each.`;
+    return result("resource", params, mapped, truncated, note);
+}
+const BLUEPRINT_MAX_DEPTH = 8;
+const INLINE_RECORD_NAME_RE = /_inline\d+$/;
+function renderBlueprintElement(element, pad) {
+    const lines = [];
+    if (element.slot !== undefined)
+        lines.push(`${pad}slot: ${element.slot}`);
+    if (element.childElements.length > 0) {
+        lines.push(`${pad}childElements:`);
+        for (const child of element.childElements) {
+            if (typeof child === "string") {
+                lines.push(`${pad}  - ${child}`);
+                continue;
+            }
+            const sub = renderBlueprintElement(child, `${pad}    `);
+            if (sub.length === 0) {
+                lines.push(`${pad}  - {}`);
+                continue;
+            }
+            lines.push(`${pad}  - ${sub[0].trimStart()}`);
+            lines.push(...sub.slice(1));
+        }
+    }
+    return lines;
+}
+function queryBlueprintRoot(store, params) {
+    const name = str(params.name);
+    if (!name)
+        return result("blueprint-root", params, [], false, "No 'name' given; nothing searched.");
+    if (!store.get(`SELECT 1 FROM record WHERE name = ? LIMIT 1`, [name])) {
+        return result("blueprint-root", params, [], false, `No record named '${name}' found.`);
+    }
+    const indentRaw = Number(params.indent ?? 0);
+    const indent = Number.isFinite(indentRaw) && indentRaw > 0 ? Math.floor(indentRaw) : 0;
+    const prepend = (str(params.prepend) ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    const chain = queryChain(store, { name });
+    const flats = (chain.rows[0]?.flats ?? []);
+    const flatValue = (flatName) => flats.find((f) => f.name === flatName)?.value;
+    const notes = [];
+    const expanding = new Set();
+    let hitDepthCap = false;
+    function elementOf(value, depth, forceExpand) {
+        if (depth > BLUEPRINT_MAX_DEPTH) {
+            hitDepthCap = true;
+            return undefined;
+        }
+        if (typeof value === "string") {
+            const occs = rawOccurrencesFor(store, value);
+            if (occs.length === 0)
+                return value;
+            const hasIdentity = latestPointer(store, value, "type") !== undefined || latestPointer(store, value, "base") !== undefined;
+            const inlineNamed = INLINE_RECORD_NAME_RE.test(value);
+            if (hasIdentity && !inlineNamed && !forceExpand)
+                return value;
+            if (expanding.has(value))
+                return value;
+            expanding.add(value);
+            const own = [...effectiveOwnFlats(value, occs).values()];
+            const ownValue = (flatName) => own.find((f) => f.name === flatName)?.value;
+            const element = elementFromFields(ownValue("slot"), ownValue("childElements"), depth);
+            expanding.delete(value);
+            return element;
+        }
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            const o = value;
+            return elementFromFields(o.slot, o.childElements, depth);
+        }
+        return undefined;
+    }
+    function elementFromFields(slot, children, depth) {
+        const element = { childElements: [] };
+        if (typeof slot === "string")
+            element.slot = slot;
+        if (Array.isArray(children)) {
+            for (const child of children) {
+                const resolved = elementOf(child, depth + 1, false);
+                if (resolved !== undefined)
+                    element.childElements.push(resolved);
+            }
+        }
+        return element;
+    }
+    const rootRaw = flatValue("rootElement");
+    let root;
+    let rootSource;
+    if (rootRaw !== undefined) {
+        const resolved = elementOf(rootRaw, 0, true);
+        if (resolved !== undefined && typeof resolved !== "string") {
+            root = resolved;
+            rootSource = "rootElement";
+        }
+    }
+    if (!root) {
+        const children = flatValue("childElements");
+        const slot = flatValue("slot");
+        if (Array.isArray(children) || typeof slot === "string") {
+            root = elementFromFields(slot, children, 0);
+            rootSource = "record-flats";
+        }
+    }
+    if (!root || !rootSource) {
+        const why = rootRaw === undefined
+            ? "has no rootElement and no slot/childElements flats along its $base chain"
+            : typeof rootRaw === "string"
+                ? `names its rootElement '${rootRaw}', which this index does not hold, and has no slot/childElements flats along its $base chain to fall back on`
+                : "has a rootElement that is neither a record name nor a slot/childElements mapping, and no slot/childElements flats along its $base chain to fall back on";
+        return result("blueprint-root", params, [], false, `'${name}' ${why}; nothing to restate.`);
+    }
+    const present = new Set(root.childElements.filter((c) => typeof c === "string"));
+    const prepended = prepend.filter((p) => !present.has(p));
+    root.childElements = [...prepended, ...root.childElements];
+    const pad = " ".repeat(indent);
+    const row = {
+        name,
+        rootSource,
+        slot: root.slot ?? null,
+        root,
+        prepended,
+        rootYaml: renderBlueprintElement(root, pad).join("\n"),
+    };
+    if (hitDepthCap)
+        notes.push(`Stopped expanding inline elements at depth ${BLUEPRINT_MAX_DEPTH}; a deeper branch was dropped.`);
+    notes.unshift(`Restated the root element of '${name}' from its ${rootSource === "rootElement" ? "rootElement" : "own slot/childElements flats"} (${root.childElements.length} child element(s), ${prepended.length} prepended).`);
+    return result("blueprint-root", params, [row], false, notes.join(" "));
+}
+export function queryKinds() {
+    return [
+        {
+            kind: "record",
+            description: "A TweakDB record by exact or prefix name: its $base, $type, and own flats merged across every occurrence that touched it.",
+            params: ["name", "prefix", "limit"],
+        },
+        {
+            kind: "chain",
+            description: "The $base inheritance chain for a record up to the root, with effective flats overlaid parent-to-child (append ops concatenate arrays), each flat marked with the record that contributed it.",
+            params: ["name"],
+        },
+        {
+            kind: "flat",
+            description: "Records that declare a given flat name, with its effective value; optionally filtered to a specific value.",
+            params: ["name", "value", "limit"],
+        },
+        {
+            kind: "reverse",
+            description: "Records whose any flat value contains a token — e.g. who references 'Items.Preset_Ashura_Default' — via substring search, optionally restricted to one flat name.",
+            params: ["token", "flat", "limit"],
+        },
+        {
+            kind: "children",
+            description: "Records that derive (directly, or transitively unless 'direct' is set) from a base record via $base.",
+            params: ["base", "direct", "limit"],
+        },
+        {
+            kind: "type",
+            description: "Records of a given $type, counted by package.",
+            params: ["type", "limit"],
+        },
+        {
+            kind: "blueprint-root",
+            description: "An item blueprint's root element restated for a derived blueprint: the root's slot and every child, named elements by name and inline elements as nested slot/childElements mappings, rendered as YAML lines ('rootYaml', padded by 'indent') with any 'prepend' names put first.",
+            params: ["name", "indent", "prepend"],
+        },
+        {
+            kind: "resource",
+            description: "Depot paths listed out of the install's .archive files: an exact 'path' answers existence with one row per archive holding it (a path can be listed by more than one archive), a 'prefix' lists matches deduped by path with an archiveCount, optionally filtered by file extension.",
+            params: ["path", "prefix", "ext", "limit"],
+        },
+    ];
+}
+export async function query(store, kind, params) {
+    switch (kind) {
+        case "record":
+            return queryRecord(store, params);
+        case "chain":
+            return queryChain(store, params);
+        case "flat":
+            return queryFlat(store, params);
+        case "reverse":
+            return queryReverse(store, params);
+        case "children":
+            return queryChildren(store, params);
+        case "type":
+            return queryType(store, params);
+        case "resource":
+            return queryResource(store, params);
+        case "blueprint-root":
+            return queryBlueprintRoot(store, params);
+        default:
+            throw new Error(`Unknown CP2077 index query kind: '${kind}'. See queryKinds() for the supported set.`);
+    }
+}

package/dist/surfaces/cyberpunk2077/index/resource.js

@@ -0,0 +1,135 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { pathExists } from "../../../core/fsutil.js";
+import { locateTool, runTool, toNativePath, TOOL_SPECS } from "../../../core/toolchain/index.js";
+import { ensureResourceSchema } from "./schema.js";
+export const LISTING_CAPTURE_BYTES = 512 * 1024 * 1024;
+export function isDepotPathLine(line) {
+    if (line.length === 0)
+        return false;
+    if (line.startsWith("[") || line.startsWith("..."))
+        return false;
+    if (!/[\\/]/.test(line))
+        return false;
+    return /\.[A-Za-z0-9_]+$/.test(line);
+}
+const ARCHIVE_SUBDIRS = [path.join("archive", "pc", "content"), path.join("archive", "pc", "ep1")];
+async function listArchiveFiles(dir) {
+    if (!(await pathExists(dir)))
+        return [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.toLowerCase().endsWith(".archive"))
+        .map((e) => path.resolve(dir, e))
+        .sort();
+}
+async function defaultLocate(toolId, toolOverrides) {
+    const spec = TOOL_SPECS.find((s) => s.id === toolId);
+    if (!spec)
+        throw new Error(`No toolchain spec registered for '${toolId}'.`);
+    return locateTool(spec, { projectOverrides: toolOverrides });
+}
+export async function buildResourceListing(install, store, options = {}) {
+    ensureResourceSchema(store);
+    const progress = options.progress;
+    const notes = [];
+    const archivePaths = [];
+    const foldersScanned = [];
+    for (const sub of ARCHIVE_SUBDIRS) {
+        const dir = path.join(install.root, sub);
+        const found = await listArchiveFiles(dir);
+        foldersScanned.push({ dir, exists: await pathExists(dir), archives: found.length });
+        archivePaths.push(...found);
+    }
+    store.run("INSERT OR REPLACE INTO meta (key, value) VALUES ('resourceFoldersScanned', ?)", [JSON.stringify(foldersScanned)]);
+    const resourceCountNow = () => Number(store.get(`SELECT COUNT(*) AS n FROM resource`)?.n ?? 0);
+    if (archivePaths.length === 0) {
+        notes.push(`${ARCHIVE_SUBDIRS.map((s) => path.join(install.root, s)).join(", ")}: no .archive files found — ` +
+            "resource paths cannot be listed without at least one.");
+        return { archivesFound: 0, archivesListed: 0, archivesUnchanged: 0, resourceCount: resourceCountNow(), notes };
+    }
+    const locate = options.resourceToolLocator ?? ((id) => defaultLocate(id, options.toolOverrides));
+    let toolLocation;
+    let listed = 0;
+    let unchanged = 0;
+    const seenArchives = new Set();
+    for (const archivePath of archivePaths) {
+        seenArchives.add(archivePath);
+        let stat;
+        try {
+            stat = await fs.stat(archivePath);
+        }
+        catch {
+            continue;
+        }
+        const mtime = stat.mtime.toISOString();
+        const sizeBytes = stat.size;
+        const prior = store.get(`SELECT mtime, sizeBytes FROM resource_archive WHERE path = ?`, [archivePath]);
+        if (!options.force && prior && String(prior.mtime) === mtime && Number(prior.sizeBytes) === sizeBytes) {
+            unchanged++;
+            progress?.({ step: "resource-unchanged", note: archivePath });
+            continue;
+        }
+        if (!toolLocation) {
+            toolLocation = await locate("wolvenkit-cli");
+            if (!toolLocation.found || !toolLocation.path) {
+                notes.push(`wolvenkit-cli not found — resource listing skipped for ${archivePaths.length} archive(s): ` +
+                    `${toolLocation.hint ?? "WolvenKit CLI was not located."}`);
+                break;
+            }
+        }
+        progress?.({ step: "resource-list", note: archivePath });
+        const result = await runTool(toolLocation, {
+            args: ["archive", toNativePath(archivePath), "-l"],
+            maxCaptureBytes: LISTING_CAPTURE_BYTES,
+        });
+        if (!result.ok) {
+            notes.push(`archive -l failed for ${archivePath}: ${result.error?.message ?? "unknown error"}`);
+            continue;
+        }
+        if (result.stdoutTruncated) {
+            notes.push(`archive -l output for ${archivePath} exceeded the ${LISTING_CAPTURE_BYTES} byte capture cap and was not indexed; ` +
+                `raise LISTING_CAPTURE_BYTES in cyberpunk2077/index/resource.ts.`);
+            continue;
+        }
+        const depotPaths = result.stdout
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(isDepotPathLine);
+        const rows = depotPaths.map((depotPath) => [depotPath, archivePath, null]);
+        store.transaction(() => {
+            store.run(`DELETE FROM resource WHERE archive = ?`, [archivePath]);
+            if (rows.length > 0)
+                store.insertMany("resource", ["path", "archive", "sizeBytes"], rows);
+            store.run(`INSERT OR REPLACE INTO resource_archive (path, mtime, sizeBytes, listedAt) VALUES (?, ?, ?, ?)`, [
+                archivePath,
+                mtime,
+                sizeBytes,
+                new Date().toISOString(),
+            ]);
+        });
+        listed++;
+    }
+    const staleArchives = store
+        .all(`SELECT path FROM resource_archive`)
+        .map((r) => String(r.path))
+        .filter((p) => !seenArchives.has(p));
+    if (staleArchives.length > 0) {
+        store.transaction(() => {
+            for (const stale of staleArchives) {
+                store.run(`DELETE FROM resource WHERE archive = ?`, [stale]);
+                store.run(`DELETE FROM resource_archive WHERE path = ?`, [stale]);
+            }
+        });
+        notes.push(`${staleArchives.length} previously-listed archive(s) no longer found on disk; their resource rows were removed.`);
+    }
+    const totalNow = resourceCountNow();
+    notes.push(`Cyberpunk resource index: ${archivePaths.length} archive(s) found, ${listed} (re)listed, ${unchanged} unchanged and skipped, ${totalNow} resource path(s) total.`);
+    return { archivesFound: archivePaths.length, archivesListed: listed, archivesUnchanged: unchanged, resourceCount: totalNow, notes };
+}