wowdump 0.2.1 → 0.3.2

package/dist/reader/main.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { createServer } from "node:net";
+import { spawn } from "node:child_process";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { serveReaderBroker } from "./broker.js";
+import { createWindowsNativeReader } from "./windows.js";
+async function runElevatedFrida(request) {
+    const worker = resolve(request.worker);
+    if (!isAbsolute(request.worker) || worker !== request.worker && process.platform === "win32") {
+        throw new Error("Frida worker path must be absolute");
+    }
+    const timeoutMs = Math.max(1, Math.min(Number(request.timeoutMs ?? 120_000), 600_000));
+    return new Promise(resolveResult => {
+        const child = spawn(process.execPath, [worker], { windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (exitCode, timedOut = false) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolveResult({ exitCode, stdout, stderr, timedOut });
+        };
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", value => { stdout += value; });
+        child.stderr.on("data", value => { stderr += value; });
+        child.once("error", error => { stderr += error.message; finish(1); });
+        child.once("exit", code => finish(code ?? 1));
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(1, true);
+        }, timeoutMs);
+        child.stdin.end(request.input);
+    });
+}
+function argument(name) {
+    const index = process.argv.indexOf(name);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+const listen = argument("--listen");
+const port = Number(argument("--port") ?? "0");
+const token = argument("--token");
+const metadata = argument("--metadata");
+let server;
+const broker = serveReaderBroker({
+    attachStdio: !listen,
+    backend: process.env.WOWDUMP_USE_FAKE_READER === "1" ? undefined : createWindowsNativeReader(),
+    runFrida: runElevatedFrida,
+    onShutdown: async () => {
+        server?.close();
+        if (metadata)
+            await rm(metadata, { force: true }).catch(() => undefined);
+    }
+});
+if (listen) {
+    if (listen !== "127.0.0.1" || !token || !metadata || !Number.isSafeInteger(port) || port < 0 || port > 65535) {
+        throw new Error("--listen requires 127.0.0.1, a valid --port, --token and --metadata");
+    }
+    server = createServer(socket => {
+        socket.setEncoding("utf8");
+        let buffer = "";
+        let pending = Promise.resolve();
+        socket.on("data", chunk => {
+            buffer += chunk;
+            while (buffer.includes("\n")) {
+                const newline = buffer.indexOf("\n");
+                const line = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                pending = pending.then(async () => {
+                    try {
+                        const envelope = JSON.parse(line);
+                        if (envelope.token !== token || !envelope.request) {
+                            socket.write(`${JSON.stringify({ ok: false, command: "auth", timestamp: Date.now(), error: { code: "AUTH_FAILED", message: "invalid reader broker token" } })}\n`);
+                            return;
+                        }
+                        socket.write(`${JSON.stringify(await broker.handle(envelope.request))}\n`);
+                    }
+                    catch (error) {
+                        socket.write(`${JSON.stringify({ ok: false, command: "parse", timestamp: Date.now(), error: { code: "INVALID_JSON", message: error instanceof Error ? error.message : String(error) } })}\n`);
+                    }
+                });
+            }
+        });
+    });
+    server.listen(port, listen, async () => {
+        await mkdir(dirname(metadata), { recursive: true });
+        const address = server?.address();
+        if (!address || typeof address === "string")
+            throw new Error("reader broker did not acquire a TCP endpoint");
+        await writeFile(metadata, `${JSON.stringify({ schema: "wowdump.reader-broker.v1", host: listen, port: address.port, token, pid: process.pid })}\n`, { encoding: "utf8", mode: 0o600 });
+    });
+}
+const shutdown = () => {
+    void broker.shutdown("request").catch(() => process.exitCode = 1);
+};
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);

package/dist/reader/protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/reader/windows.js

@@ -0,0 +1,242 @@
+import koffi from "koffi";
+import { basename } from "node:path";
+const PROCESS_QUERY_INFORMATION = 0x0400;
+const PROCESS_VM_READ = 0x0010;
+const PROCESS_QUERY_LIMITED_INFORMATION = 0x1000;
+const HANDLE = koffi.pointer("WOWDUMP_HANDLE", koffi.opaque());
+const BYTE_POINTER = koffi.pointer("WOWDUMP_BYTE", koffi.opaque());
+const SIZE_T = process.arch === "x64" ? "uint64_t" : "uint32_t";
+const kernel32 = koffi.load("kernel32.dll");
+const shell32 = koffi.load("shell32.dll");
+const OpenProcess = kernel32.func("OpenProcess", HANDLE, ["uint32_t", "bool", "uint32_t"]);
+const ReadProcessMemory = kernel32.func("ReadProcessMemory", "bool", [HANDLE, "uint64_t", koffi.pointer("uint8_t"), SIZE_T, koffi.out(koffi.pointer(SIZE_T))]);
+const VirtualQueryEx = kernel32.func("VirtualQueryEx", SIZE_T, [HANDLE, "uint64_t", koffi.pointer("uint8_t"), SIZE_T]);
+const CloseHandle = kernel32.func("CloseHandle", "bool", [HANDLE]);
+const GetLastError = kernel32.func("GetLastError", "uint32_t", []);
+const QueryFullProcessImageNameW = kernel32.func("QueryFullProcessImageNameW", "bool", [HANDLE, "uint32_t", koffi.pointer("char16_t"), koffi.inout(koffi.pointer("uint32_t"))]);
+const IsUserAnAdmin = shell32.func("IsUserAnAdmin", "bool", []);
+const MODULEENTRY32W = koffi.struct("WOWDUMP_MODULEENTRY32W", {
+    dwSize: "uint32_t",
+    th32ModuleID: "uint32_t",
+    th32ProcessID: "uint32_t",
+    GlblcntUsage: "uint32_t",
+    ProccntUsage: "uint32_t",
+    modBaseAddr: BYTE_POINTER,
+    modBaseSize: "uint32_t",
+    hModule: HANDLE,
+    szModule: koffi.array("char16_t", 256, "String"),
+    szExePath: koffi.array("char16_t", 260, "String")
+});
+const PROCESSENTRY32W = koffi.struct("WOWDUMP_PROCESSENTRY32W", {
+    dwSize: "uint32_t",
+    cntUsage: "uint32_t",
+    th32ProcessID: "uint32_t",
+    th32DefaultHeapID: "uint64_t",
+    th32ModuleID: "uint32_t",
+    cntThreads: "uint32_t",
+    th32ParentProcessID: "uint32_t",
+    pcPriClassBase: "int32_t",
+    dwFlags: "uint32_t",
+    szExeFile: koffi.array("char16_t", 260, "String")
+});
+const CreateToolhelp32Snapshot = kernel32.func("CreateToolhelp32Snapshot", HANDLE, ["uint32_t", "uint32_t"]);
+const Module32FirstW = kernel32.func("Module32FirstW", "bool", [HANDLE, koffi.inout(koffi.pointer(MODULEENTRY32W))]);
+const Module32NextW = kernel32.func("Module32NextW", "bool", [HANDLE, koffi.inout(koffi.pointer(MODULEENTRY32W))]);
+const Process32FirstW = kernel32.func("Process32FirstW", "bool", [HANDLE, koffi.inout(koffi.pointer(PROCESSENTRY32W))]);
+const Process32NextW = kernel32.func("Process32NextW", "bool", [HANDLE, koffi.inout(koffi.pointer(PROCESSENTRY32W))]);
+const TH32CS_SNAPMODULE = 0x00000008;
+const TH32CS_SNAPMODULE32 = 0x00000010;
+const TH32CS_SNAPPROCESS = 0x00000002;
+function addressOf(handle) {
+    return `0x${koffi.address(handle).toString(16)}`;
+}
+function win32Error(operation) {
+    const win32 = Number(GetLastError());
+    const error = new Error(`${operation} failed with Win32 error ${win32}`);
+    error.code = "WIN32_ERROR";
+    error.win32 = win32;
+    return error;
+}
+class WindowsHandle {
+    raw;
+    pid;
+    id;
+    constructor(raw, pid) {
+        this.raw = raw;
+        this.pid = pid;
+        this.id = addressOf(raw);
+    }
+    close() {
+        if (this.raw !== null) {
+            CloseHandle(this.raw);
+            this.raw = null;
+        }
+    }
+}
+export class WindowsNativeReader {
+    async enumerateModules(pid) {
+        const snapshot = CreateToolhelp32Snapshot(TH32CS_SNAPMODULE | TH32CS_SNAPMODULE32, pid);
+        if (!snapshot)
+            throw win32Error(`CreateToolhelp32Snapshot(${pid})`);
+        const modules = [];
+        try {
+            const entry = {
+                dwSize: koffi.sizeof(MODULEENTRY32W),
+                th32ModuleID: 0,
+                th32ProcessID: 0,
+                GlblcntUsage: 0,
+                ProccntUsage: 0,
+                modBaseAddr: null,
+                modBaseSize: 0,
+                hModule: null,
+                szModule: "",
+                szExePath: ""
+            };
+            let first = Module32FirstW(snapshot, entry);
+            while (first) {
+                const base = entry.modBaseAddr ? `0x${koffi.address(entry.modBaseAddr).toString(16)}` : "0x0";
+                modules.push({ name: String(entry.szModule), base, size: Number(entry.modBaseSize), path: String(entry.szExePath) });
+                first = Module32NextW(snapshot, entry);
+            }
+            if (modules.some(module => module.name.length > 0 || Boolean(module.path)))
+                return modules;
+            const path = await this.queryProcessPath(pid);
+            if (path)
+                return [{ name: basename(path), base: "0x0", size: 0, path }];
+            throw win32Error(`QueryFullProcessImageNameW(${pid})`);
+        }
+        finally {
+            CloseHandle(snapshot);
+        }
+    }
+    async queryProcessPath(pid) {
+        const handle = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_QUERY_INFORMATION, false, pid);
+        if (!handle)
+            return undefined;
+        try {
+            const capacity = 32768;
+            const buffer = Buffer.alloc(capacity * 2);
+            const length = [capacity];
+            if (!QueryFullProcessImageNameW(handle, 0, buffer, length))
+                return undefined;
+            const count = Math.max(0, Math.min(Number(length[0]), capacity));
+            return buffer.toString("utf16le", 0, count * 2) || undefined;
+        }
+        finally {
+            CloseHandle(handle);
+        }
+    }
+    async openProcess(pid, rights) {
+        const requested = rights.reduce((mask, right) => {
+            if (right === "PROCESS_QUERY_INFORMATION")
+                return mask | PROCESS_QUERY_INFORMATION;
+            if (right === "PROCESS_VM_READ")
+                return mask | PROCESS_VM_READ;
+            return mask;
+        }, 0);
+        const handle = OpenProcess(requested || PROCESS_QUERY_INFORMATION | PROCESS_VM_READ, false, pid);
+        if (!handle)
+            throw win32Error(`OpenProcess(${pid})`);
+        return new WindowsHandle(handle, pid);
+    }
+    async readProcessMemory(handle, address, size) {
+        const native = handle;
+        const bytes = Buffer.allocUnsafe(size);
+        const read = [0n];
+        const ok = ReadProcessMemory(native.raw, address, bytes, size, read);
+        const bytesRead = Number(read[0]);
+        if (!ok && bytesRead === 0)
+            throw win32Error(`ReadProcessMemory(${native.id}, ${`0x${address.toString(16)}`})`);
+        return { bytes: bytes.subarray(0, bytesRead), bytesRead };
+    }
+    async virtualQueryEx(handle, address) {
+        const native = handle;
+        const buffer = Buffer.alloc(48);
+        const result = Number(VirtualQueryEx(native.raw, address, buffer, buffer.length));
+        if (result === 0)
+            throw win32Error(`VirtualQueryEx(${native.id})`);
+        return {
+            baseAddress: `0x${buffer.readBigUInt64LE(0).toString(16)}`,
+            allocationBase: `0x${buffer.readBigUInt64LE(8).toString(16)}`,
+            allocationProtect: buffer.readUInt32LE(16),
+            regionSize: buffer.readBigUInt64LE(24).toString(),
+            state: buffer.readUInt32LE(32),
+            protect: buffer.readUInt32LE(36),
+            type: buffer.readUInt32LE(40),
+            bytesReturned: result
+        };
+    }
+    async isProcessAlive(pid) {
+        try {
+            const handle = await this.openProcess(pid, ["PROCESS_QUERY_INFORMATION"]);
+            handle.close();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    elevationStatus() {
+        return {
+            elevated: Boolean(IsUserAnAdmin()),
+            processArchitecture: process.arch,
+            backend: "koffi/kernel32",
+            requestedRights: ["PROCESS_QUERY_INFORMATION", "PROCESS_VM_READ"]
+        };
+    }
+}
+/** Enumerate processes without spawning a shell or depending on Frida. */
+export function enumerateWindowsProcesses() {
+    if (process.platform !== "win32")
+        return [];
+    const snapshot = CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0);
+    if (!snapshot)
+        throw win32Error("CreateToolhelp32Snapshot(processes)");
+    const rows = [];
+    try {
+        const entry = {
+            dwSize: koffi.sizeof(PROCESSENTRY32W),
+            cntUsage: 0,
+            th32ProcessID: 0,
+            th32DefaultHeapID: 0n,
+            th32ModuleID: 0,
+            cntThreads: 0,
+            th32ParentProcessID: 0,
+            pcPriClassBase: 0,
+            dwFlags: 0,
+            szExeFile: ""
+        };
+        let found = Process32FirstW(snapshot, entry);
+        while (found) {
+            const pid = Number(entry.th32ProcessID);
+            const name = String(entry.szExeFile);
+            let path = null;
+            if (pid > 0) {
+                const handle = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_QUERY_INFORMATION, false, pid);
+                if (handle) {
+                    try {
+                        const capacity = 32768;
+                        const buffer = Buffer.alloc(capacity * 2);
+                        const length = [capacity];
+                        if (QueryFullProcessImageNameW(handle, 0, buffer, length)) {
+                            const count = Math.max(0, Math.min(Number(length[0]), capacity));
+                            path = buffer.toString("utf16le", 0, count * 2) || null;
+                        }
+                    }
+                    finally {
+                        CloseHandle(handle);
+                    }
+                }
+            }
+            rows.push({ pid, name, path });
+            found = Process32NextW(snapshot, entry);
+        }
+    }
+    finally {
+        CloseHandle(snapshot);
+    }
+    return rows;
+}
+export function createWindowsNativeReader() {
+    return new WindowsNativeReader();
+}

package/dist/reader-main.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./reader/main.js";

package/dist/toolchain.js

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+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";
+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 命令参考
+
+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 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));
+    const created = [];
+    const preserved = [];
+    await mkdir(home, { recursive: true });
+    for (const name of WOWDUMP_HOME_DIRECTORIES) {
+        const dir = join(home, name);
+        if (directoryExists(dir))
+            preserved.push(dir);
+        else {
+            await mkdir(dir, { recursive: true });
+            created.push(dir);
+        }
+    }
+    const configFile = join(home, "config.json");
+    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);
+    }
+    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");
+    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 bootstrapToolchain();
+}

package/package.json

@@ -1,64 +1,46 @@
 {
   "name": "wowdump",
-  "version": "0.2.1",
-  "description": "Build-aware World of Warcraft runtime analysis MCP server backed by Frida",
-  "type": "module",
-  "bin": {
-    "wowdump": "dist/mcp-main.js"
-  },
-  "files": [
-    "dist/**",
-    "!dist/main.js",
-    "resources/**",
-    "README.md",
-    "LICENSE"
-  ],
+  "version": "0.3.2",
+  "description": "WoW native memory analysis CLI with Frida evidence, IDA/iced-x86 disassembly, and an elevated reader broker",
   "license": "MIT",
-  "author": "Follenfang",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Follen/wowdump.git"
   },
-  "bugs": {
-    "url": "https://github.com/Follen/wowdump/issues"
-  },
-  "homepage": "https://github.com/Follen/wowdump#readme",
-  "keywords": [
-    "mcp",
-    "frida",
-    "world-of-warcraft",
-    "wow",
-    "runtime-analysis"
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
   ],
-  "publishConfig": {
-    "access": "public"
+  "type": "module",
+  "bin": {
+    "wowdump": "dist/cli.js"
   },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "npm run build:host && npm run build:agent",
+    "clean": "node scripts/clean-dist.mjs",
+    "build": "npm run clean && npm run build:host",
     "build:host": "tsc -p tsconfig.json",
-    "build:agent": "frida-compile agent/index.ts -o dist/agent.js",
-    "bundle:build": "node scripts/build-build-bundle.mjs --analysis-root analyze/vm --output-root resources/builds",
-    "bundle:verify": "node scripts/verify-build-bundle.mjs resources/builds/retail/12.0.7.68974",
+    "wowdump": "node dist/cli.js",
+    "postinstall": "node -e \"const fs=require('node:fs');if(fs.existsSync('dist/toolchain.js'))import('./dist/toolchain.js').then(m=>m.bootstrapToolchain())\"",
+    "prepack": "npm run build",
     "package:verify": "node scripts/verify-package.mjs",
     "release:verify": "node scripts/verify-release-workflow.mjs verify",
-    "mcp": "node dist/mcp-main.js",
-    "test": "npm run build:host && node --test tests/*.test.mjs && npm run release:verify",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "prepack": "npm run build && npm run bundle:verify"
+    "test": "npm run build:host && node --test tests/*.test.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0",
     "commander": "^13.1.0",
     "frida": "^17.2.0",
-    "pino": "^9.6.0",
+    "iced-x86": "^1.21.0",
+    "koffi": "^2.16.3",
     "zod": "^3.24.2"
   },
   "devDependencies": {
     "@types/node": "^22.13.4",
-    "frida-compile": "^16.4.2",
     "typescript": "^5.7.3"
   }
 }

package/skills/wowdump/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: wowdump
+description: 以 Frida 运行时探测为主，按证据需要交替使用 IDA Pro MCP 或 iced-x86，生成并验证 WoW 原生内存 Reader profile。
+---
+
+# wowdump
+
+用于读取角色属性、Buff/Debuff、技能冷却、附近单位等原生字段。优先从当前进程取得真实值；需要长期复用时，再把已验证的线索固化为带证据的 `wowdump.profile.v1`。
+
+## 默认策略
+
+1. 先运行 `wowdump targets`，确认 PID、Wow.exe 路径和 buildKey；多个目标时让用户选择。
+2. 在 `~/.wowdump/<buildKey>/runtime/<session>/` 保存临时证据，在 `~/.wowdump/<buildKey>/profile/` 只保存用户确认的持久化 profile。
+3. 默认编写并显式传入 GumJS，使用 `wowdump analyze dynamic --script <GumJS> --confirm` 做运行时发现、原生 Hook、快照或事件采集。
+4. 若已有 `reader_ready` profile，先用 reader 读取；若动态结果已足够回答问题，直接返回，不强行做静态分析。
+5. 动态结果需要函数 RVA、对象布局或字段类型时，再对相关样本调用 IDA Pro MCP；没有 IDA 时才用 `wowdump analyze disassemble` 的 iced-x86 输出。静态和动态可以交替执行，每轮只扩大当前字段所需的证据范围。
+6. 将确认的 RVA、指针链、类型、边界和证据写入候选 profile。字段证据不足时保持 `candidate`，回到 dynamic 补采样或回到 IDA/iced 缩小候选。
+7. 用 `wowdump memory read --profile <profile> --field <name>` 做 broker-backed 验证；只有地址、类型和实际读取都成功后才标记 `reader_ready`。经用户确认后再保存到该 build 的 `profile/`。
+
+不要把 dynamic、IDA 或 iced 固定成一次性线性流水线。选择下一步的依据是当前字段缺少什么证据：值用 dynamic，函数/布局用 IDA/iced，稳定读取用 reader。
+
+具体的交替决策见 [references/workflow.md](references/workflow.md)；动态 Hook 规则见 [references/dynamic.md](references/dynamic.md)；IDA/iced 的选择和交替策略见 [references/disassemble.md](references/disassemble.md)；请求字段和 profile 生命周期见 [references/request-schema.md](references/request-schema.md) 与 [references/profiles.md](references/profiles.md)。

package/skills/wowdump/references/commands.md

@@ -0,0 +1,63 @@
+# wowdump 命令参考
+
+Windows 下需要内存或 Frida 权限时，CLI 会连接同一个管理员 broker；首次建立 broker 才需要 UAC，默认空闲 20 分钟后退出。
+
+## 发现目标
+
+```powershell
+wowdump targets
+wowdump targets --pid 33976
+```
+
+使用输出里的 `pid`、`path` 和 `buildKey`。`buildKey` 来自目标安装目录的 `.build.info`；不要写 `SIM` 或手填版本。
+
+## 运行时动态分析
+
+```powershell
+wowdump analyze dynamic `
+  --pid 33976 `
+  --build "retail@12.1.0.69587" `
+  --script "C:\work\discover-state.js" `
+  --export collect `
+  --args '{"fields":["playerAuras","nearbyEnemies","cooldowns"]}' `
+  --duration-ms 5000 `
+  --confirm > $HOME\.wowdump\runtime\<session-id>\state.json
+```
+
+固定采样：
+
+```powershell
+wowdump analyze runtime `
+  --pid 33976 `
+  --build "retail@12.1.0.69587" `
+  --kind text `
+  --duration-ms 5000 `
+  --max-events 100 `
+  --confirm > $HOME\.wowdump\runtime\<session-id>\text.json
+```
+
+## 需要时做静态定位
+
+只有 dynamic 结果缺少函数 RVA、对象布局或字段类型时，才调用 IDA Pro MCP；没有 IDA 时使用 iced-x86 兜底：
+
+```powershell
+wowdump analyze disassemble `
+  --exe "D:\Game\World of Warcraft\_retail_\Wow.exe" `
+  --build "retail@12.1.0.69587" `
+  --runtime-export "$HOME\.wowdump\runtime\<session-id>\state.json" `
+  --output "$HOME\.wowdump\runtime\<session-id>\retail-12.1.0.69587.profile.json"
+```
+
+## 读取
+
+```powershell
+wowdump memory read `
+  --pid 33976 `
+  --build "retail@12.1.0.69587" `
+  --profile "$HOME\.wowdump\retail@12.1.0.69587\profile\player-state.json" `
+  --field playerAuras nearbyEnemies cooldowns
+```
+
+需要连续观察时使用 `memory watch start/poll/stop`。字段未定义、模块不匹配、指针为空或发生短读时，保留 JSON 证据并停止该字段，不改写 profile。
+
+静态分析完成后回到 `analyze dynamic` Hook 验证候选，再生成 profile。短时 Hook/事件采集可以复制 [scripts/dynamic-session.js](../scripts/dynamic-session.js) 后按请求修改；它不会被 CLI 自动执行。详细脚本规则见 [dynamic.md](dynamic.md) 和 [disassemble.md](disassemble.md)。字段请求格式见 [request-schema.md](request-schema.md)，profile 生命周期见 [profiles.md](profiles.md)。

package/skills/wowdump/references/disassemble.md

@@ -0,0 +1,18 @@
+# 反汇编与 IDA Pro 分支
+
+静态分析是按需使用的证据放大器，不是每个查询的必经步骤。运行时 text、字节样本、Hook 调用记录或返回值都可以作为输入。先检查当前 Agent 是否能调用本机 IDA Pro MCP：
+
+- 能调用时，让 MCP 只分析当前字段相关样本附近的函数、字符串、调用关系和结构，把结果保存为 JSON。随后回到 dynamic Hook 验证候选函数，不要直接把静态候选当成可读字段。
+- 不能调用时执行：
+
+```powershell
+wowdump analyze disassemble `
+  --exe "C:\Games\World of Warcraft\_retail_\Wow.exe" `
+  --build "retail@VERSION" `
+  --runtime-export "$HOME\.wowdump\runtime\SESSION\text.json" `
+  --output "$HOME\.wowdump\runtime\SESSION\candidate.profile.json"
+```
+
+CLI 使用 `iced-x86` 解码 runtime 样本，返回模块基址、RVA、指令文本、PE sections 和证据。Agent 负责把这些线索与运行时字段对应起来，再用 dynamic 验证 `root`、`pointerChain`、`layout/type`、计数上限和停止条件。不要把一次运行的绝对地址写进持久化 profile。
+
+输出中的 `readerStatus: "reader_ready"` 只适用于每个字段都有可验证 RVA/地址、类型和边界，并且 reader 实际读成功的情况；否则保持 `candidate`，回到 dynamic 或继续局部静态分析。只做一次性查询时可以不生成持久化 profile。