wowdump 0.3.1 → 0.3.2

package/dist/toolchain.js

@@ -1,117 +1,55 @@
 import { createHash } from "node:crypto";
-import { execFile as execFileCallback } from "node:child_process";
-import { constants, createReadStream, createWriteStream, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { access, cp, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { createReadStream, readdirSync, statSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { pipeline } from "node:stream/promises";
-import { promisify } from "node:util";
-const execFile = promisify(execFileCallback);
-export const WOWDUMP_HOME_DIRECTORIES = [
-    "profiles",
-    "logs",
-    "runtime",
-    "cache",
-    "skills",
-    "monitors",
-    "toolchains"
-];
-export const PINNED_TOOLCHAINS = {
-    java: {
-        name: "Temurin JDK",
-        version: "21.0.8+9",
-        directory: "temurin-21.0.8+9",
-        windowsUrl: "https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.8%2B9/OpenJDK21U-jdk_x64_windows_hotspot_21.0.8_9.zip"
-    },
-    ghidra: {
-        name: "Ghidra",
-        version: "11.3.2",
-        directory: "ghidra-11.3.2",
-        windowsUrl: "https://github.com/NationalSecurityAgency/ghidra/releases/download/Ghidra_11.3.2_build/ghidra_11.3.2_PUBLIC_20250415.zip"
-    }
-};
-export const DEFAULT_WOWDUMP_SKILL = `---
-name: wowdump
-description: 使用 wowdump CLI 进行 WoW 原生内存分析和静态取证。
----
-
-# wowdump
-
-使用唯一入口 \`wowdump\` 按依赖顺序完成：静态发现候选 RVA；经确认后用 Frida 导出运行时基址和字节验证；验证通过后落盘为 \`reader_ready\` profile，后续只用 reader。
-
-所有结论都要保留 build、文件哈希、模块基址、RVA、命令和证据来源。详细命令、参数和输出字段见同目录的 \`commands.md\`。
+export const WOWDUMP_HOME_DIRECTORIES = ["profiles", "logs", "runtime", "cache", "skills", "monitors", "toolchains"];
+export const DEFAULT_WOWDUMP_SKILL = `---
+name: wowdump
+description: 使用 Frida 运行时证据和 IDA/iced-x86 定位 WoW 字段，生成 Reader 可用 profile。
+---
+
+# wowdump
+
+查字段时先读取 targets，再用显式 GumJS 导出运行时线索。静态定位优先交给可用的 IDA Pro MCP；没有时运行 \`wowdump analyze disassemble\`，由 Agent 根据 iced-x86 输出分析并补齐字段定义。两条路径都必须最终生成 \`wowdump.profile.v1\`，且只有地址、类型和证据齐全时才标记 \`reader_ready\`。详情见 references/workflow.md、references/dynamic.md、references/disassemble.md 和 references/profiles.md。
 `;
-export const DEFAULT_WOWDUMP_COMMANDS = `# wowdump 命令参考
-
-## 初始化和工具链
-
-\`wowdump init\` 初始化运行目录并探测 JDK/Ghidra。缺少默认依赖时，npm 安装阶段会下载到 \`WOWDUMP_HOME/toolchains\`；也可以用 \`--skip-toolchain-download\` 只探测本机安装。
-
-默认目录：运行数据为 \`~/.wowdump\`，Skill 为 \`~/.agents/skills/wowdump\`。可用 \`WOWDUMP_HOME\` 和 \`WOWDUMP_SKILL_HOME\` 覆盖。
-
-## 1. 静态发现
-
-命令：wowdump analyze static --exe "C:\\path\\Wow.exe" --build "retail@VERSION"
-
-输出候选 profile，包含模块 imageBase、段范围、函数/字符串/交叉引用和候选 RVA；结果 confidence 为 candidate。
-
-## 2. Frida 运行时导出
-
-命令：wowdump analyze runtime-export --pid 1234 --build "retail@VERSION" --static-profile .wowdump\\profiles\\static.json --kind providers --confirm
-
-Frida 只负责一次性验证 moduleBase 和静态 profile 指定 RVA 的现场字节/事件，并记录 runtimeAddress = moduleBase + rva；完成后卸载脚本并断开。
-
-## 3. 验证并落盘
-
-命令：wowdump analyze verify --static-profile .wowdump\\profiles\\static.json --runtime-export .wowdump\\runtime\\export.json --output .wowdump\\profiles\\verified.json
-
-只有检查通过的记录才可标为 reader_ready；不匹配项原样保留。
-
-## 4. 后续只读 reader
-
-命令：wowdump target；wowdump profiles；wowdump memory read --pid 1234 --profile reader-ready；wowdump memory watch start --pid 1234 --profile reader-ready；wowdump memory watch poll --id WATCH_ID；wowdump memory watch stop --id WATCH_ID
-
-Windows 首次读取会由 Node 自动请求 UAC 并启动 broker；后续调用复用 broker、句柄和监控状态。broker 仅监听本机 loopback，20 分钟无请求后退出。
-
-Frida 导出必须绑定 PID、build、目标、限制和清理期限，并显式传 \`--confirm\`。写操作和失败结果都以结构化 JSON 返回；candidate/unverified 不能当作已确认偏移。
+export const DEFAULT_WOWDUMP_COMMANDS = `# wowdump 命令参考
+
+1. \`wowdump targets\`
+2. \`wowdump analyze runtime --pid <pid> --build <buildKey> --kind text --confirm\`
+3. \`wowdump analyze dynamic --pid <pid> --build <buildKey> --script <GumJS> --export collect --confirm\`
+4. \`wowdump analyze disassemble --exe <Wow.exe> --build <buildKey> --runtime-export <runtime.json> --output <profile.json>\`
+5. \`wowdump memory read --pid <pid> --build <buildKey> --profile <profile.json> --field <name>\`
+
+若 Agent 能调用 IDA Pro MCP，先用 MCP 分析 runtime text，再把结果保存为 JSON 并通过 \`--ida-evidence\` 交给 disassemble 命令。未确认的候选 profile 放在 runtime 目录；确认后才复制到当前 build 的 profile 目录。
 `;
-function normalizePath(value) {
-    return resolve(value.trim().replace(/^"|"$/g, ""));
-}
-function pathExists(value) {
-    try {
-        return statSync(value).isFile();
-    }
-    catch {
-        return false;
-    }
-}
-function directoryExists(value) {
-    try {
-        return statSync(value).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-export function resolveWowdumpHome(env = process.env, userHome = homedir()) {
-    return normalizePath(env.WOWDUMP_HOME || join(userHome, ".wowdump"));
-}
-export function resolveWowdumpSkillHome(env = process.env, userHome = homedir()) {
-    return normalizePath(env.WOWDUMP_SKILL_HOME || join(userHome, ".agents", "skills"));
-}
-async function createFileIfMissing(file, contents, created, preserved) {
-    try {
-        await writeFile(file, contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
-        created.push(file);
-    }
-    catch (error) {
-        if (error.code !== "EEXIST")
-            throw error;
+function normalizePath(value) { return resolve(value.trim().replace(/^"|"$/g, "")); }
+function directoryExists(value) { try {
+    return statSync(value).isDirectory();
+}
+catch {
+    return false;
+} }
+function fileExists(value) { try {
+    return statSync(value).isFile();
+}
+catch {
+    return false;
+} }
+async function createFileIfMissing(file, contents, created, preserved) { try {
+    await writeFile(file, contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    created.push(file);
+}
+catch (error) {
+    if (error.code === "EEXIST")
         preserved.push(file);
-    }
-}
+    else
+        throw error;
+} }
+export function resolveWowdumpHome(env = process.env, userHome = homedir()) { return normalizePath(env.WOWDUMP_HOME || join(userHome, ".wowdump")); }
+export function resolveWowdumpSkillHome(env = process.env, userHome = homedir()) { return normalizePath(env.WOWDUMP_SKILL_HOME || join(userHome, ".agents", "skills")); }
 export async function initializeWowdumpHome(options = {}) {
     const env = options.env ?? process.env;
     const home = normalizePath(options.home ?? resolveWowdumpHome(env, options.userHome));
@@ -119,476 +57,67 @@ export async function initializeWowdumpHome(options = {}) {
     const preserved = [];
     await mkdir(home, { recursive: true });
     for (const name of WOWDUMP_HOME_DIRECTORIES) {
-        const directory = join(home, name);
-        if (directoryExists(directory))
-            preserved.push(directory);
+        const dir = join(home, name);
+        if (directoryExists(dir))
+            preserved.push(dir);
         else {
-            await mkdir(directory, { recursive: true });
-            created.push(directory);
+            await mkdir(dir, { recursive: true });
+            created.push(dir);
         }
     }
     const configFile = join(home, "config.json");
-    await createFileIfMissing(configFile, `${JSON.stringify({ schema: "wowdump.config.v1", toolchains: {} }, null, 2)}\n`, created, preserved);
-    const skillRoot = normalizePath(options.skillHome ?? resolveWowdumpSkillHome(env, options.userHome));
-    const skillDirectory = join(skillRoot, "wowdump");
-    if (!directoryExists(skillDirectory)) {
+    await createFileIfMissing(configFile, `${JSON.stringify({ schema: "wowdump.config.v1" }, null, 2)}\n`, created, preserved);
+    const skillDirectory = join(normalizePath(options.skillHome ?? resolveWowdumpSkillHome(env, options.userHome)), "wowdump");
+    if (directoryExists(skillDirectory))
+        preserved.push(skillDirectory);
+    else {
         await mkdir(skillDirectory, { recursive: true });
         created.push(skillDirectory);
     }
-    else
-        preserved.push(skillDirectory);
+    const bundledSkill = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", "wowdump", "SKILL.md");
+    const skillSource = options.skillSource ? normalizePath(options.skillSource) : fileExists(bundledSkill) ? bundledSkill : undefined;
     const skillFile = join(skillDirectory, "SKILL.md");
-    const skill = options.skillSource
-        ? await readFile(normalizePath(options.skillSource), "utf8")
-        : DEFAULT_WOWDUMP_SKILL;
-    await createFileIfMissing(skillFile, skill.endsWith("\n") ? skill : `${skill}\n`, created, preserved);
-    const commandsFile = join(skillDirectory, "commands.md");
-    const commands = options.commandsSource
-        ? await readFile(normalizePath(options.commandsSource), "utf8")
-        : DEFAULT_WOWDUMP_COMMANDS;
-    await createFileIfMissing(commandsFile, commands.endsWith("\n") ? commands : `${commands}\n`, created, preserved);
-    return { home, created, preserved, configFile, skillFile, commandsFile };
-}
-function readConfig(file) {
-    try {
-        const value = JSON.parse(readFileSync(file, "utf8"));
-        return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-    }
-    catch {
-        return {};
-    }
-}
-function configuredTool(config, name) {
-    const toolchains = config.toolchains;
-    if (!toolchains || typeof toolchains !== "object" || Array.isArray(toolchains))
-        return undefined;
-    const value = toolchains[name];
-    if (typeof value === "string" && value.trim())
-        return value;
-    if (value && typeof value === "object" && !Array.isArray(value)) {
-        const path = value.path;
-        return typeof path === "string" && path.trim() ? path : undefined;
-    }
-    return undefined;
-}
-function executableNames(base, platform) {
-    if (platform !== "win32")
-        return [base];
-    return [base, `${base}.exe`, `${base}.cmd`, `${base}.bat`];
-}
-function pathCandidates(name, pathValue, platform) {
-    if (!pathValue)
-        return [];
-    const separator = platform === "win32" ? ";" : ":";
-    return pathValue.split(separator).filter(Boolean).flatMap(directory => executableNames(name, platform).map(executable => join(directory.replace(/^"|"$/g, ""), executable)));
-}
-function childDirectories(parent, prefix) {
-    try {
-        return readdirSync(parent, { withFileTypes: true })
-            .filter(entry => entry.isDirectory() && prefix.test(entry.name))
-            .map(entry => join(parent, entry.name))
-            .sort((left, right) => right.localeCompare(left, undefined, { numeric: true }));
-    }
-    catch {
-        return [];
-    }
-}
-function javaExecutable(input, platform) {
-    const value = normalizePath(input);
-    if (pathExists(value))
-        return value;
-    for (const name of executableNames("java", platform)) {
-        const candidate = join(value, "bin", name);
-        if (pathExists(candidate))
-            return candidate;
-    }
-    return undefined;
-}
-function ghidraExecutable(input, platform) {
-    const value = normalizePath(input);
-    if (pathExists(value) && /^analyzeHeadless(?:\.(?:bat|cmd|sh))?$/i.test(basename(value)))
-        return value;
-    const names = platform === "win32"
-        ? ["analyzeHeadless.bat", "analyzeHeadless.cmd", "analyzeHeadless.exe", "analyzeHeadless"]
-        : executableNames("analyzeHeadless", platform);
-    for (const name of names) {
-        for (const candidate of [join(value, "support", name), join(value, name)]) {
-            if (pathExists(candidate))
-                return candidate;
-        }
-        for (const child of childDirectories(value, /^ghidra[_-]/i)) {
-            const candidate = join(child, "support", name);
-            if (pathExists(candidate))
-                return candidate;
-        }
-    }
-    return undefined;
-}
-function unique(values) {
-    const seen = new Set();
-    const result = [];
-    for (const item of values) {
-        if (!item?.trim())
-            continue;
-        const value = normalizePath(item);
-        const key = process.platform === "win32" ? value.toLowerCase() : value;
-        if (!seen.has(key)) {
-            seen.add(key);
-            result.push(value);
-        }
-    }
-    return result;
-}
-function resolvedTool(candidates, resolver) {
-    const searched = [];
-    for (const candidate of candidates) {
-        if (!candidate.value?.trim())
-            continue;
-        const normalized = normalizePath(candidate.value);
-        searched.push(normalized);
-        const executable = resolver(normalized);
-        if (executable) {
-            const root = basename(dirname(executable)).toLowerCase() === "bin" || basename(dirname(executable)).toLowerCase() === "support"
-                ? dirname(dirname(executable))
-                : dirname(executable);
-            return { tool: { executable, root, source: candidate.source }, searched: unique(searched) };
-        }
-    }
-    return { tool: null, searched: unique(searched) };
-}
-function windowsRoots(env) {
-    const user = env.USERPROFILE || homedir();
-    const programFiles = [env.ProgramFiles, env["ProgramFiles(x86)"], env.LOCALAPPDATA && join(env.LOCALAPPDATA, "Programs")].filter((value) => Boolean(value));
-    return {
-        java: programFiles.flatMap(root => [
-            ...childDirectories(join(root, "Eclipse Adoptium"), /^(?:jdk|temurin)/i),
-            ...childDirectories(join(root, "Java"), /^jdk/i),
-            ...childDirectories(join(root, "Microsoft"), /^jdk/i)
-        ]),
-        ghidra: [
-            ...programFiles.flatMap(root => childDirectories(root, /^ghidra/i)),
-            ...childDirectories(user, /^ghidra/i),
-            ...childDirectories(join(user, "tools"), /^ghidra/i)
-        ]
-    };
-}
-export function resolveToolchain(options = {}) {
-    const env = options.env ?? process.env;
-    const platform = options.platform ?? process.platform;
-    const home = normalizePath(options.home ?? resolveWowdumpHome(env, options.userHome));
-    const config = readConfig(normalizePath(options.configFile ?? join(home, "config.json")));
-    const managedRoot = join(home, "toolchains");
-    const standard = platform === "win32"
-        ? windowsRoots(env)
-        : {
-            java: ["/usr/lib/jvm/default-java", "/usr/lib/jvm/java-21-openjdk", "/opt/java"],
-            ghidra: ["/opt/ghidra", "/usr/local/ghidra", join(options.userHome ?? homedir(), "ghidra")]
-        };
-    const javaPathMatches = pathCandidates("java", options.path ?? env.PATH, platform);
-    const ghidraPathMatches = pathCandidates("analyzeHeadless", options.path ?? env.PATH, platform);
-    const javaCandidates = [
-        { value: options.java ?? env.WOWDUMP_JAVA, source: "explicit" },
-        { value: configuredTool(config, "java"), source: "config" },
-        { value: env.JAVA_HOME, source: "system" },
-        ...javaPathMatches.map(value => ({ value, source: "system" })),
-        ...standard.java.map(value => ({ value, source: "system" })),
-        ...childDirectories(managedRoot, /^(?:temurin|jdk|java)/i).map(value => ({ value, source: "managed" }))
-    ];
-    const ghidraCandidates = [
-        { value: options.ghidra ?? env.WOWDUMP_GHIDRA, source: "explicit" },
-        { value: configuredTool(config, "ghidra"), source: "config" },
-        { value: env.GHIDRA_HOME ?? env.GHIDRA_INSTALL_DIR, source: "system" },
-        ...ghidraPathMatches.map(value => ({ value, source: "system" })),
-        ...standard.ghidra.map(value => ({ value, source: "system" })),
-        ...childDirectories(managedRoot, /^ghidra/i).map(value => ({ value, source: "managed" }))
-    ];
-    const java = resolvedTool(javaCandidates, value => javaExecutable(value, platform));
-    const ghidra = resolvedTool(ghidraCandidates, value => ghidraExecutable(value, platform));
-    const missing = [];
-    if (!java.tool)
-        missing.push("java");
-    if (!ghidra.tool)
-        missing.push("ghidra");
-    return {
-        home,
-        ready: missing.length === 0,
-        java: java.tool,
-        ghidra: ghidra.tool,
-        missing,
-        searched: { java: java.searched, ghidra: ghidra.searched }
-    };
-}
-async function download(url, file) {
-    const response = await fetch(url, { redirect: "follow" });
-    if (!response.ok || !response.body)
-        throw new Error(`download failed with HTTP ${response.status}: ${url}`);
-    await pipeline(response.body, createWriteStream(file, { flags: "wx", mode: 0o600 }));
-}
-async function extractZip(archive, directory) {
-    if (process.platform === "win32") {
-        await execFile("powershell.exe", [
-            "-NoProfile",
-            "-NonInteractive",
-            "-Command",
-            "Expand-Archive -LiteralPath $args[0] -DestinationPath $args[1] -Force",
-            archive,
-            directory
-        ], { windowsHide: true, maxBuffer: 4 * 1024 * 1024 });
-        return;
-    }
-    await execFile("unzip", ["-q", archive, "-d", directory], { maxBuffer: 4 * 1024 * 1024 });
-}
-function firstDirectory(directory) {
-    const entries = readdirSync(directory, { withFileTypes: true }).filter(entry => entry.isDirectory());
-    return entries.length === 1 ? join(directory, entries[0].name) : directory;
-}
-export const defaultToolchainInstaller = async (input) => {
-    if (process.platform !== "win32") {
-        throw new Error(`managed ${input.component} installation currently requires Windows; configure an existing installation`);
-    }
-    if (directoryExists(input.destination))
-        return;
-    await mkdir(dirname(input.destination), { recursive: true });
-    const staging = await mkdtemp(join(tmpdir(), `wowdump-${input.component}-`));
-    const archive = join(staging, `${input.component}.zip`);
-    const extracted = join(staging, "extracted");
-    try {
-        await download(input.url, archive);
-        await mkdir(extracted, { recursive: true });
-        await extractZip(archive, extracted);
-        const source = firstDirectory(extracted);
-        try {
-            await rename(source, input.destination);
-        }
-        catch (error) {
-            if (error.code === "EXDEV")
-                await cp(source, input.destination, { recursive: true, errorOnExist: true });
-            else if (error.code !== "EEXIST")
-                throw error;
-        }
-        const manifest = join(input.destination, ".wowdump-toolchain.json");
-        if (!existsSync(manifest)) {
-            await writeFile(manifest, `${JSON.stringify({
-                schema: "wowdump.toolchain.v1",
-                component: input.component,
-                version: input.version,
-                source: input.url,
-                installedAt: new Date().toISOString()
-            }, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
-        }
-    }
-    finally {
-        await rm(staging, { recursive: true, force: true });
-    }
-};
-export async function bootstrapToolchain(options = {}) {
-    const initialized = await initializeWowdumpHome(options);
-    let toolchain = resolveToolchain({ ...options, home: initialized.home });
-    const installed = [];
-    if (options.installMissing === true && toolchain.missing.length > 0) {
-        const installer = options.installer ?? defaultToolchainInstaller;
-        for (const component of toolchain.missing) {
-            const pinned = PINNED_TOOLCHAINS[component];
-            const destination = join(initialized.home, "toolchains", pinned.directory);
-            await installer({ component, destination, url: pinned.windowsUrl, version: pinned.version });
-            installed.push(component);
-        }
-        toolchain = resolveToolchain({ ...options, home: initialized.home });
-    }
-    return { ...initialized, toolchain, installed };
-}
-export function ghidraHeadlessArguments(options) {
-    const args = [
-        normalizePath(options.projectDirectory),
-        options.projectName,
-        "-import",
-        normalizePath(options.executable),
-        "-analysisTimeoutPerFile",
-        String(options.timeoutSeconds ?? 1800)
-    ];
-    if (options.overwrite !== false)
-        args.push("-overwrite");
-    if (options.scriptDirectory)
-        args.push("-scriptPath", normalizePath(options.scriptDirectory));
-    if (options.exporterScript) {
-        args.push("-postScript", options.exporterScript);
-        if (options.evidenceFile)
-            args.push(normalizePath(options.evidenceFile));
-        if (options.buildKey)
-            args.push(options.buildKey);
-    }
-    return args;
-}
-export const defaultExternalCommandRunner = async (command) => {
-    try {
-        const result = await execFile(command.file, command.args, {
-            cwd: command.cwd,
-            env: command.env,
-            windowsHide: true,
-            maxBuffer: 64 * 1024 * 1024
-        });
-        return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
-    }
-    catch (error) {
-        const failure = error;
-        return {
-            exitCode: typeof failure.code === "number" ? failure.code : 1,
-            stdout: failure.stdout ?? "",
-            stderr: failure.stderr ?? failure.message
-        };
-    }
-};
-export async function sha256File(file) {
-    const hash = createHash("sha256");
-    await pipeline(createReadStream(file), hash);
-    return hash.digest("hex");
-}
-function hex(value) {
-    return `0x${BigInt(value).toString(16)}`;
-}
-export function inspectPeSections(buffer) {
-    if (buffer.length < 0x40 || buffer.toString("ascii", 0, 2) !== "MZ")
-        return [];
-    const peOffset = buffer.readUInt32LE(0x3c);
-    if (peOffset + 24 > buffer.length || buffer.toString("ascii", peOffset, peOffset + 4) !== "PE\0\0")
-        return [];
-    const sectionCount = buffer.readUInt16LE(peOffset + 6);
-    const optionalSize = buffer.readUInt16LE(peOffset + 20);
-    const table = peOffset + 24 + optionalSize;
-    const sections = [];
-    for (let index = 0; index < sectionCount; index += 1) {
-        const offset = table + index * 40;
-        if (offset + 40 > buffer.length)
-            break;
-        const name = buffer.subarray(offset, offset + 8).toString("ascii").replace(/\0+$/, "");
-        sections.push({
-            name,
-            virtualSize: hex(buffer.readUInt32LE(offset + 8)),
-            rva: hex(buffer.readUInt32LE(offset + 12)),
-            rawSize: hex(buffer.readUInt32LE(offset + 16)),
-            rawOffset: hex(buffer.readUInt32LE(offset + 20)),
-            characteristics: hex(buffer.readUInt32LE(offset + 36))
-        });
-    }
-    return sections;
-}
-function safeBuildName(buildKey) {
-    const value = buildKey.trim().replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
-    if (!value)
-        throw new Error("buildKey must contain a filesystem-safe character");
-    return value;
-}
-function record(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function evidenceArray(evidence, ...keys) {
-    for (const key of keys)
-        if (Array.isArray(evidence[key]))
-            return evidence[key];
-    return [];
-}
-export async function runGhidraStaticAnalysis(options) {
-    const executable = normalizePath(options.executable);
-    await access(executable, constants.R_OK);
-    if (!options.buildKey.trim())
-        throw new Error("buildKey is required");
-    const toolchain = resolveToolchain(options);
-    if (!toolchain.ghidra || !toolchain.java) {
-        throw new Error(`Ghidra toolchain is incomplete: missing ${toolchain.missing.join(", ")}; run npm install or configure --java/--ghidra`);
-    }
-    const suffix = safeBuildName(options.buildKey);
-    const outputDirectory = normalizePath(options.outputDirectory ?? join(toolchain.home, "profiles", suffix));
-    const projectDirectory = normalizePath(options.projectDirectory ?? join(toolchain.home, "cache", "ghidra", suffix));
-    const projectName = options.projectName ?? `wowdump-${suffix}`;
-    const evidenceFile = normalizePath(options.evidenceFile ?? join(outputDirectory, "ghidra-evidence.json"));
-    const outputFile = join(outputDirectory, "profile.json");
-    await mkdir(outputDirectory, { recursive: true });
-    await mkdir(projectDirectory, { recursive: true });
-    const args = ghidraHeadlessArguments({
-        projectDirectory,
-        projectName,
-        executable,
-        timeoutSeconds: options.timeoutSeconds,
-        overwrite: options.overwrite,
-        scriptDirectory: options.scriptDirectory,
-        exporterScript: options.exporterScript,
-        evidenceFile,
-        buildKey: options.buildKey
-    });
-    const command = {
-        file: toolchain.ghidra.executable,
-        args,
-        cwd: outputDirectory,
-        env: { ...process.env, JAVA_HOME: toolchain.java.root }
-    };
-    let processResult;
-    if (!options.dryRun) {
-        processResult = await (options.runner ?? defaultExternalCommandRunner)(command);
-        if (processResult.exitCode !== 0) {
-            throw new Error(`Ghidra Headless exited with ${processResult.exitCode}: ${processResult.stderr.trim() || "no diagnostic"}`);
-        }
-    }
-    let evidence = {};
-    if (!options.dryRun && existsSync(evidenceFile))
-        evidence = record(JSON.parse(await readFile(evidenceFile, "utf8")));
-    const executableSha256 = await sha256File(executable);
-    const sections = evidenceArray(evidence, "sections").length > 0
-        ? evidenceArray(evidence, "sections")
-        : inspectPeSections(await readFile(executable));
-    const profile = {
-        schema: "wowdump.profile.v1",
-        buildKey: options.buildKey,
-        executable: { path: executable, sha256: executableSha256, module: basename(executable) },
-        sections,
-        functions: evidenceArray(evidence, "functions"),
-        strings: evidenceArray(evidence, "strings"),
-        xrefs: evidenceArray(evidence, "xrefs", "crossReferences"),
-        providers: evidenceArray(evidence, "providers", "providerMatches"),
-        signatures: evidenceArray(evidence, "signatures", "signatureMatches"),
-        analysis: {
-            engine: "ghidra-headless",
-            engineVersion: evidence.ghidraVersion ?? PINNED_TOOLCHAINS.ghidra.version,
-            javaVersion: evidence.javaVersion ?? PINNED_TOOLCHAINS.java.version,
-            generatedAt: new Date().toISOString(),
-            command: { file: command.file, args: command.args },
-            evidenceFile
-        },
-        confidence: "candidate"
-    };
-    if (!options.dryRun)
-        await writeFile(outputFile, `${JSON.stringify(profile, null, 2)}\n`, "utf8");
-    return {
-        ok: true,
-        command: "analyze.static",
-        dryRun: options.dryRun === true,
-        buildKey: options.buildKey,
-        executable,
-        executableSha256,
-        outputFile,
-        commandLine: { file: command.file, args: command.args, cwd: outputDirectory },
-        toolchain,
-        profile,
-        ...(processResult ? { process: processResult } : {})
-    };
-}
-async function postinstall() {
-    const installMissing = process.env.WOWDUMP_SKIP_TOOLCHAIN_DOWNLOAD !== "1";
-    try {
-        const result = await bootstrapToolchain({ installMissing });
-        process.stdout.write(`${JSON.stringify({
-            ok: result.toolchain.ready,
-            command: "postinstall",
-            home: result.home,
-            installed: result.installed,
-            missing: result.toolchain.missing,
-            skillFile: result.skillFile
-        })}\n`);
-    }
-    catch (error) {
-        process.stderr.write(`wowdump postinstall: ${error instanceof Error ? error.message : String(error)}\n`);
-        process.stderr.write("Set WOWDUMP_SKIP_TOOLCHAIN_DOWNLOAD=1 to initialize without downloading, then configure WOWDUMP_JAVA and WOWDUMP_GHIDRA.\n");
-    }
-}
+    await createFileIfMissing(skillFile, `${(skillSource ? await readFile(skillSource, "utf8") : DEFAULT_WOWDUMP_SKILL).replace(/\n?$/, "\n")}`, created, preserved);
+    const referencesDirectory = join(skillDirectory, "references");
+    if (directoryExists(referencesDirectory))
+        preserved.push(referencesDirectory);
+    else {
+        await mkdir(referencesDirectory, { recursive: true });
+        created.push(referencesDirectory);
+    }
+    const commandsFile = join(referencesDirectory, "commands.md");
+    await createFileIfMissing(commandsFile, `${(options.commandsSource ? await readFile(normalizePath(options.commandsSource), "utf8") : DEFAULT_WOWDUMP_COMMANDS).replace(/\n?$/, "\n")}`, created, preserved);
+    const bundledReferences = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", "wowdump", "references");
+    if (directoryExists(bundledReferences))
+        for (const entry of readdirSync(bundledReferences, { withFileTypes: true }))
+            if (entry.isFile() && extname(entry.name).toLowerCase() === ".md")
+                await createFileIfMissing(join(referencesDirectory, entry.name), await readFile(join(bundledReferences, entry.name), "utf8"), created, preserved);
+    const scriptsDirectory = join(skillDirectory, "scripts");
+    if (directoryExists(scriptsDirectory))
+        preserved.push(scriptsDirectory);
+    else {
+        await mkdir(scriptsDirectory, { recursive: true });
+        created.push(scriptsDirectory);
+    }
+    const bundledScripts = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", "wowdump", "scripts");
+    if (directoryExists(bundledScripts))
+        for (const entry of readdirSync(bundledScripts, { withFileTypes: true }))
+            if (entry.isFile() && extname(entry.name).toLowerCase() === ".js")
+                await createFileIfMissing(join(scriptsDirectory, entry.name), await readFile(join(bundledScripts, entry.name), "utf8"), created, preserved);
+    return { home, created, preserved, configFile, skillFile, commandsFile, scriptsDirectory };
+}
+export async function bootstrapToolchain(options = {}) { const home = await initializeWowdumpHome(options); return { ...home, toolchain: { ready: true, disassembler: "iced-x86" }, installed: [] }; }
+export function resolveToolchain(options = {}) { return { home: normalizePath(options.home ?? resolveWowdumpHome(options.env ?? process.env, options.userHome)), ready: true, disassembler: "iced-x86" }; }
+export async function sha256File(file) { const hash = createHash("sha256"); await pipeline(createReadStream(file), hash); return hash.digest("hex"); }
+export function inspectPeSections(buffer) { if (buffer.length < 0x40 || buffer.toString("ascii", 0, 2) !== "MZ")
+    return []; const pe = buffer.readUInt32LE(0x3c); if (pe + 24 > buffer.length || buffer.toString("ascii", pe, pe + 4) !== "PE\0\0")
+    return []; const count = buffer.readUInt16LE(pe + 6); const optional = buffer.readUInt16LE(pe + 20); const table = pe + 24 + optional; const out = []; for (let i = 0; i < count; i++) {
+    const off = table + i * 40;
+    if (off + 40 > buffer.length)
+        break;
+    out.push({ name: buffer.subarray(off, off + 8).toString("ascii").replace(/\0+$/, ""), virtualSize: `0x${buffer.readUInt32LE(off + 8).toString(16)}`, rva: `0x${buffer.readUInt32LE(off + 12).toString(16)}`, rawSize: `0x${buffer.readUInt32LE(off + 16).toString(16)}`, rawOffset: `0x${buffer.readUInt32LE(off + 20).toString(16)}` });
+} return out; }
 const invokedFile = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : "";
-if (invokedFile === import.meta.url && process.argv.includes("--postinstall"))
-    await postinstall();
+if (invokedFile === import.meta.url && process.argv.includes("--postinstall")) {
+    await bootstrapToolchain();
+}