wowdump 0.2.1 → 0.3.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Follenfang
+Copyright (c) 2026 Follen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,132 +1,38 @@
 # wowdump
 
-`wowdump` is a build-aware World of Warcraft runtime analysis MCP server. It exposes Frida process control, focused Lua/C++ tracing, bounded data watches, build profile validation, and verified data readers over the MCP `2026-07-28` protocol.
+WoW 原生内存分析 CLI。用 Frida 运行时证据和 IDA Pro/iced-x86 局部反汇编定位字段，生成可复核的 Reader profile。
 
-The package supports multiple WoW flavors and builds. `retail` is a flavor in a build key such as `retail@12.0.7.68974`; it is not part of the product name.
-
-## Install
-
-Run directly from an MCP client:
-
-```json
-{
-  "mcpServers": {
-    "wowdump": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "wowdump",
-        "--game-root",
-        "D:\\Game\\World of Warcraft"
-      ]
-    }
-  }
-}
-```
-
-Or install it globally:
+## 安装
 
 ```powershell
 npm install --global wowdump
-wowdump --game-root "D:\Game\World of Warcraft"
-```
-
-The `wowdump` executable only starts the stdio MCP server. It is not a separate interactive CLI.
-
-## Game Directories
-
-Game directories are resolved once when the MCP server starts. The first non-empty source wins:
-
-1. Repeatable `--game-root <path>` arguments.
-2. `WOWDUMP_GAME_ROOTS` as a semicolon-separated list on Windows.
-3. `game_roots` in the TOML file selected by `--config <path>`.
-4. `%LOCALAPPDATA%\wowdump\config.toml`.
-5. Automatic detection from verified Battle.net Agent installation metadata, followed by common Windows installation locations.
-
-Example persistent configuration:
-
-```toml
-game_roots = [
-  "D:/Game/World of Warcraft",
-  "E:/World of Warcraft"
-]
-
-broker_idle_ms = 1200000
+wowdump init
 ```
 
-`WOW_ROOT` remains a deprecated compatibility fallback. Invalid selected paths are reported on stderr and are not silently replaced by a lower-priority source.
-
-PID, build, module base, Frida sessions, Hook IDs, and runtime addresses are never persisted in TOML. They are discovered and validated for the current process.
-
-## Selecting A Target
-
-Use these read-only tools before starting a dynamic session:
-
-- `wow_install_list`: installed game directories and flavors.
-- `wow_build_list`: detected build keys and versions.
-- `wow_target_list`: running Wow.exe PIDs matched to an installation and build.
-
-Focused and trace operations accept an explicit `pid` and `buildKey`. The server rejects PID/build mismatches and does not reuse a historical PID or module base.
+安装脚本会初始化 `~/.wowdump`，并把 Skill 与 references 参考文档安装到 `~/.agents/skills/wowdump`。反汇编保底使用 npm 内置的 `iced-x86`。
 
-## MCP Tools
+## 基本流程
 
-The primary tool groups are:
-
-- `frida_command`: generic Frida read, write, script, Hook, process, and session operations.
-- `wow_lua_trace_*` and `wow_cpp_trace_*`: build-aware bounded trace sessions.
-- `wow_focus_*`, `wow_watch_*`, and `wow_session_checkpoint`: explicit before/during/after analysis windows.
-- `wow_data_source_*`, `wow_data_read`, and `wow_build_profile_validate`: verified build data and readers.
-- `wow_broker_*`: Broker status, start, reconnect, and stop.
-- `wow_analysis_coverage` and `wow_analysis_checkpoint`: static profile coverage and checkpoints.
-
-The server rejects legacy MCP handshakes. Protocol output is written only to stdout; diagnostics are written to stderr.
-
-## Runtime Layout
-
-Production uses three distinct directory roles:
-
-- Package `resources/builds`: read-only, build-specific profiles and signatures.
-- `%LOCALAPPDATA%\wowdump`: writable Broker ledgers, focused sessions, logs, and cache.
-- Repository `analyze/vm`: offline analysis inputs and intermediate evidence; it is not required by the installed package.
+```powershell
+# 1. 导出运行时模块或 provider
+wowdump analyze runtime --pid 1234 --build "retail@VERSION" --kind text --duration-ms 5000 --max-events 100 --confirm > runtime.json
 
-Stable overrides can be placed in TOML:
+# 2. 通过 IDA Pro MCP（若可用）或 iced-x86 局部反汇编生成 profile
+wowdump analyze disassemble --exe "C:\Games\World of Warcraft\_retail_\Wow.exe" --build "retail@VERSION" --runtime-export "$HOME\.wowdump\runtime\<session-id>\text.json" --output "$HOME\.wowdump\runtime\<session-id>\candidate.profile.json"
 
-```toml
-profile_root = "D:/wowdump-profiles"
-runtime_root = "C:/Users/ACCOUNT/AppData/Local/wowdump"
-log_level = "info"
-broker_idle_ms = 1200000
+# 3. 用户确认后，把 profile 保存到当前 build 的 profile 目录，再读取
+wowdump memory read --pid 1234 --profile "$HOME\.wowdump\retail@VERSION\profile\player-state.json" --field playerAuras
 ```
 
-The MCP process does not own Frida sessions. A single per-user `wowdump-broker` process owns attach/detach, scripts, Hooks, Interceptors, request forwarding, and cleanup. Requests refresh its idle timer; the default idle timeout is 20 minutes.
-
-## Packaged Builds
-
-This release includes a verified profile for:
-
-- `retail@12.0.7.68974`
+Windows reader 首次使用时由 Node 请求 UAC 启动 broker，后续调用复用同一 broker，空闲 20 分钟后退出。Frida 运行时导出需要显式 `--confirm`；高开销 Stalker 默认关闭。
 
-Every build has its own RVA profile, entry signatures, data sources, and manifest hashes. A new build must be relocated and validated; old RVAs are not automatically reused.
+当前 build 的持久化 profile 放在 `~/.wowdump/<buildKey>/profile/`；动态导出、静态候选和验证报告放在 runtime 会话临时目录。完整字段和 JSON 约定见 `~/.agents/skills/wowdump/references/commands.md`、`references/request-schema.md` 与 `references/profiles.md`；短时 Hook 示例见 `~/.agents/skills/wowdump/scripts/dynamic-session.js`。
 
-## Development
+## 开发验证
 
 ```powershell
-npm install
 npm run typecheck
-npm test
 npm run build
-npm run bundle:verify
-npm run package:verify
-```
-
-To regenerate the packaged bundle from the repository-only analysis workspace:
-
-```powershell
-npm run bundle:build
+npm test
+npm pack --dry-run
 ```
-
-`npm run package:verify` enforces the npm file whitelist, creates a real tarball, installs it in a temporary directory, starts the installed `wowdump` bin, and performs an MCP `2026-07-28` handshake.
-
-## License
-
-MIT

package/dist/adapters/reader.js

@@ -0,0 +1,33 @@
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+/** Adapts the elevated reader broker to ProfileEngine's minimal memory API. */
+export class ReaderProfileAdapter {
+    invoke;
+    constructor(invoke) {
+        this.invoke = invoke;
+    }
+    async modules(pid) {
+        const response = record(await this.invoke({ command: "modules", payload: { pid } }));
+        if (response.ok !== true)
+            throw new Error(String(record(response.error).message ?? "module enumeration failed"));
+        const values = Array.isArray(response.modules) ? response.modules : [];
+        return values.filter(value => value && typeof value === "object").map(value => {
+            const item = value;
+            return { name: String(item.name ?? ""), base: String(item.base ?? "0x0"), ...(item.size !== undefined ? { size: Number(item.size) } : {}), ...(item.path !== undefined ? { path: String(item.path) } : {}) };
+        });
+    }
+    async read(pid, address, size) {
+        const response = record(await this.invoke({ command: "read", payload: { pid, address, size } }));
+        const error = response.error;
+        return {
+            ok: response.ok === true,
+            address: typeof response.address === "string" ? response.address : address,
+            requestedSize: Number(response.requestedSize ?? size),
+            bytesRead: Number(response.bytesRead ?? 0),
+            dataHex: typeof response.dataHex === "string" ? response.dataHex : undefined,
+            complete: response.complete === true,
+            ...(error !== undefined ? { error } : {})
+        };
+    }
+}

package/dist/analysis/disassemble.js

@@ -0,0 +1,77 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { resolve } from "node:path";
+import { Decoder, DecoderOptions, Formatter, FormatterSyntax } from "iced-x86";
+import { inspectPeSections, sha256File } from "../toolchain.js";
+function record(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; }
+function array(value) { return Array.isArray(value) ? value.filter(item => item && typeof item === "object" && !Array.isArray(item)) : []; }
+function hex(value) { if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+    return BigInt(value); if (typeof value === "string" && /^0x[0-9a-f]+$/i.test(value.trim()))
+    return BigInt(value); return undefined; }
+function hexText(value) { return `0x${value.toString(16)}`; }
+function moduleInfo(runtime) { const module = record(runtime.module); const base = hex(module.moduleBase ?? module.base ?? runtime.moduleBase) ?? 0n; const size = Number(module.moduleSize ?? module.size ?? runtime.moduleSize ?? 0); return { base, size: Number.isFinite(size) ? size : 0, name: String(module.name ?? "Wow.exe") }; }
+function sampleBytes(item) { const value = item.bytesHex ?? item.dataHex; if (typeof value !== "string" || !/^[0-9a-f]*$/i.test(value) || value.length % 2 !== 0)
+    return undefined; return Buffer.from(value, "hex"); }
+function sampleRva(item) { return hex(item.rva) ?? (hex(item.address) !== undefined ? hex(item.address) : undefined); }
+function decodeSamples(runtime, maxInstructions) {
+    const info = moduleInfo(runtime);
+    const samples = [...array(runtime.samples), ...array(runtime.records)];
+    const formatter = new Formatter(FormatterSyntax.Masm);
+    const output = [];
+    let remaining = maxInstructions;
+    for (const sample of samples) {
+        if (remaining <= 0)
+            break;
+        const bytes = sampleBytes(sample);
+        const raw = sampleRva(sample);
+        if (!bytes || raw === undefined)
+            continue;
+        const rva = raw >= info.base && info.base > 0n ? raw - info.base : raw;
+        const ip = info.base + rva;
+        const decoder = new Decoder(64, bytes, DecoderOptions.None);
+        decoder.ip = ip;
+        const instructions = [];
+        while (remaining > 0 && decoder.canDecode) {
+            const instruction = decoder.decode();
+            if (instruction.code === 0)
+                break;
+            instructions.push(formatter.format(instruction));
+            remaining--;
+        }
+        output.push({ rva: hexText(rva), address: hexText(ip), bytesHex: bytes.toString("hex"), instructions, source: "frida-text" });
+    }
+    return output;
+}
+function fieldCandidates(runtime, ida) {
+    const candidates = {};
+    const source = { ...record(runtime.fields), ...record(ida.fields) };
+    for (const [name, value] of Object.entries(source)) {
+        const item = record(value);
+        const rva = item.rva ?? record(item.root).rva;
+        const type = item.type ?? (record(item.layout).type);
+        const layout = item.layout;
+        if (rva !== undefined && (typeof type === "string" || (layout && typeof layout === "object" && !Array.isArray(layout))))
+            candidates[name] = { ...item, root: item.root ?? { rva }, ...(type ? { type } : {}), evidence: [...array(item.evidence), { source: ida && Object.keys(ida).length ? "ida-pro-mcp" : "iced-x86", kind: "runtime-guided" }] };
+    }
+    return candidates;
+}
+export async function runDisassembly(options) {
+    const executable = resolve(options.exe);
+    await access(executable, constants.R_OK);
+    if (!options.buildKey?.trim())
+        throw new Error("buildKey is required");
+    const runtime = record(JSON.parse(await readFile(resolve(options.runtimeExport), "utf8")));
+    const ida = options.idaEvidence ? record(JSON.parse(await readFile(resolve(options.idaEvidence), "utf8"))) : {};
+    const info = moduleInfo(runtime);
+    const decoded = decodeSamples(runtime, Math.min(Math.max(options.maxInstructions ?? 256, 1), 10_000));
+    const sections = inspectPeSections(await readFile(executable));
+    const fields = fieldCandidates(runtime, ida);
+    const ready = Object.keys(fields).length > 0 && Object.values(fields).every(field => { const value = record(field); return value.root !== undefined && (value.type !== undefined || value.layout !== undefined); });
+    const outputFile = resolve(options.output ?? `${executable}.${options.buildKey.replace(/[^A-Za-z0-9_.@-]+/g, "-")}.profile.json`);
+    const profile = { schema: "wowdump.profile.v1", id: `${options.buildKey}-runtime`, buildKey: options.buildKey, readerStatus: ready ? "reader_ready" : "candidate", confidence: ready ? "confirmed" : "candidate", module: { name: info.name, rvaBase: "0x0" }, executable: { path: executable, sha256: await sha256File(executable) }, sections, fields, evidence: [{ source: "frida", kind: "runtime-text", samples: decoded.length }, { source: options.idaEvidence ? "ida-pro-mcp" : "iced-x86", kind: "disassembly", instructions: decoded.length }], analysis: { engine: options.idaEvidence ? "ida-pro-mcp+iced-x86" : "iced-x86", generatedAt: new Date().toISOString() } };
+    const disassembly = { module: { name: info.name, moduleBase: hexText(info.base), moduleSize: info.size }, sections, instructions: decoded, idaEvidence: options.idaEvidence ?? null };
+    if (!options.dryRun)
+        await writeFile(outputFile, `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+    return { ok: true, command: "analyze.disassemble", engine: options.idaEvidence ? "ida-pro-mcp" : "iced-x86", buildKey: options.buildKey, executable, outputFile, profile, disassembly };
+}

package/dist/{frida-runtime.js → analysis/frida-runtime.js}

@@ -1,16 +1,6 @@
 import { createHash } from "node:crypto";
 import { appendFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-export const BROKER_MANAGED_COMMAND = Symbol("wowdump.broker-managed-command");
-export function brokerManagedCommand(request, purpose) {
-    Object.defineProperty(request, BROKER_MANAGED_COMMAND, {
-        value: { purpose, irreversibleReason: "Broker-managed observation instrumentation is cleaned through the owned resource graph." },
-        enumerable: false,
-        configurable: false,
-        writable: false
-    });
-    return request;
-}
 const DEFAULT_MAX_SOURCE_BYTES = 4 * 1024 * 1024;
 const DEFAULT_MAX_MEMORY_BYTES = 16 * 1024 * 1024;
 const DEFAULT_SCRIPT_TIMEOUT_MS = 150;
@@ -196,9 +186,6 @@ function buildPrelude(context) {
         buildKey: context?.buildKey,
         flavor: context?.flavor,
         executable: context?.executable,
-        processStartTime: context?.processStartTime,
-        moduleBase: context?.moduleBase,
-        moduleIdentity: context?.moduleIdentity,
         adapter: context?.adapter
     });
     const verifiedPrelude = context?.adapter?.adapter?.fridaPrelude ?? "";
@@ -213,10 +200,7 @@ function requestContext(request, context, existing) {
         ...(request.buildKey === undefined ? {} : { buildKey: request.buildKey }),
         ...(request.flavor === undefined ? {} : { flavor: request.flavor }),
         ...(request.adapter === undefined ? {} : { adapter: request.adapter }),
-        ...(request.executable === undefined ? {} : { executable: request.executable }),
-        ...(request.processStartTime === undefined ? {} : { processStartTime: request.processStartTime }),
-        ...(request.moduleBase === undefined ? {} : { moduleBase: request.moduleBase }),
-        ...(request.moduleIdentity === undefined ? {} : { moduleIdentity: request.moduleIdentity })
+        ...(request.executable === undefined ? {} : { executable: request.executable })
     };
 }
 function sessionContext(record) {
@@ -226,10 +210,7 @@ function sessionContext(record) {
         ...(context.buildKey === undefined ? {} : { buildKey: context.buildKey }),
         ...(context.flavor === undefined ? {} : { flavor: context.flavor }),
         ...(context.adapter === undefined ? {} : { adapter: context.adapter }),
-        ...(context.executable === undefined ? {} : { executable: context.executable }),
-        ...(context.processStartTime === undefined ? {} : { processStartTime: context.processStartTime }),
-        ...(context.moduleBase === undefined ? {} : { moduleBase: context.moduleBase }),
-        ...(context.moduleIdentity === undefined ? {} : { moduleIdentity: context.moduleIdentity })
+        ...(context.executable === undefined ? {} : { executable: context.executable })
     };
 }
 function serializeDevice(device) {
@@ -514,10 +495,6 @@ export class FridaCommandRuntime {
         const record = this.sessions.get(id);
         if (!record)
             throw new Error(`session ${id} was not found`);
-        // Detach is an at-most-once terminal transition. Frida may report an
-        // error after teardown has already started, so retaining the record would
-        // let Broker cleanup call detach again on a half-destroyed agent.
-        this.sessions.delete(id);
         for (const scriptId of [...record.scripts.keys()])
             await this.unloadScript(scriptId).catch(() => undefined);
         try {
@@ -525,6 +502,7 @@ export class FridaCommandRuntime {
         }
         catch { /* bridge cleanup is best effort */ }
         await record.session.detach();
+        this.sessions.delete(id);
     }
     async resume(request, context) {
         const pid = this.requirePid(request, context);

package/dist/analysis/runtime-script.js

@@ -0,0 +1,36 @@
+/** Built-in bounded sampler used by `analyze runtime`; dynamic stays caller-owned. */
+export const RUNTIME_EXPORT_SCRIPT = String.raw `
+"use strict";
+const input = globalThis.__WOWDUMP_INPUT__ || {};
+const moduleName = typeof input.module === "string" && input.module ? input.module : "Wow.exe";
+const module = Process.findModuleByName(moduleName);
+const limit = Math.min(Math.max(Number(input.maxEvents || 16), 1), 256);
+const sampleBytes = Math.min(Math.max(Number(input.sampleBytes || 64), 1), 256);
+function bytes(address, size) { const value = address.readByteArray(size); return value ? Array.from(new Uint8Array(value), byte => byte.toString(16).padStart(2, "0")).join("") : ""; }
+function collect() {
+  if (!module) return { ok: false, module: { name: moduleName }, records: [], evidence: [{ source: "frida", kind: "module-missing" }] };
+  if (input.kind === "text") {
+    const ranges = Process.enumerateRanges("r-x").filter(range => range.base.compare(module.base) >= 0 && range.base.compare(module.base.add(module.size)) < 0);
+    const textRanges = ranges.map(range => ({ base: range.base.toString(), rva: range.base.sub(module.base).toString(), size: range.size, protection: range.protection }));
+    const records = [];
+    for (const range of ranges) {
+      if (records.length >= limit) break;
+      const rva = range.base.sub(module.base);
+      const offset = rva.isNull() && range.size > 0x1000 ? 0x1000 : 0;
+      const address = range.base.add(offset);
+      records.push({ address: address.toString(), rva: address.sub(module.base).toString(), size: Math.min(sampleBytes, range.size - offset), bytesHex: bytes(address, Math.min(sampleBytes, range.size - offset)) });
+    }
+    return { ok: true, kind: "text", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, textRanges, samples: records, records, evidence: [{ source: "frida", kind: "frida-runtime-text", samples: records.length }] };
+  }
+  const profile = input.profile && typeof input.profile === "object" ? input.profile : {};
+  const candidates = Array.isArray(profile.providers) ? profile.providers : [];
+  const records = [];
+  for (const candidate of candidates.slice(0, limit)) {
+    if (!candidate || typeof candidate.rva !== "string") continue;
+    const address = module.base.add(ptr(candidate.rva));
+    records.push({ name: candidate.name || "candidate", rva: candidate.rva, runtimeAddress: address.toString(), bytesHex: bytes(address, Math.min(Number(candidate.size || 16), 256)), source: "frida" });
+  }
+  return { ok: true, module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, records, evidence: [{ source: "frida", kind: "frida-runtime-read", count: records.length }] };
+}
+rpc.exports = { collect };
+`;